cp_list_iterator

Section: libcprops - cp_list (3)
Updated: OCTOBER 2005
Index Return to Main Contents

NAME

cp_list_iterator - an iterator for cp_list structures

SYNOPSIS

cp_list_iterator *cp_list_create_iterator(cp_list *list,
int lock_mode);
int cp_list_iterator_release(cp_list_iterator *iterator);
int cp_list_iterator_destroy(cp_list_iterator *iterator);

int cp_list_iterator_init(cp_list_iterator *iterator, cp_list *list,
int lock_mode);
int cp_list_iterator_init_tail(cp_list_iterator *iterator,
cp_list *list, int lock_mode);

int cp_list_iterator_head(cp_list_iterator *iterator);
int cp_list_iterator_tail(cp_list_iterator *iterator);
void *cp_list_iterator_next(cp_list_iterator *iterator);
void *cp_list_iterator_prev(cp_list_iterator *iterator);
void *cp_list_iterator_curr(cp_list_iterator *iterator);

void *cp_list_iterator_insert(cp_list_iterator *iterator,
void *item);
void *cp_list_iterator_append(cp_list_iterator *iterator,
void *item);
void *cp_list_iterator_remove(cp_list_iterator *iterator);

DESCRIPTION

cp_list_iterator is an iterator for cp_list structures.

ITERATOR INITIALIZATION / FINALIZATION

cp_list_create_iterator returns a pointer to a newly allocated iterator pointing to the head of the list. If called with lock_mode set to COLLECTION_LOCK_READ the list will be locked for reading. If called with COLLECTION_LOCK_WRITE the list will be locked for writing.

cp_list_iterator_release unlocks the list, but need not be called explicitly if calling cp_list_iterator_destroy. If you allocate the iterator with cp_list_create_iterator, call cp_list_iterator_destroy to perform cleanup. If you declare an iterator instance on the stack, perform cleanup with cp_list_iterator_release.

ITERATOR POSITIONING AND ITEM RETRIEVAL

cp_list_iterator_init initializes an iterator by performing the requested locking and positioning the iterator at the first position in the list. cp_list_iterator_init_tail does the same but positions the iterator at the last position in the list. cp_list_iterator_head and cp_list_iterator_tail position the iterator at the first and last positions in the list respectively. cp_list_iterator_next and cp_list_iterator_prev return the entry at the current iterator position and move the iterator to the next or previous entry respectively. cp_list_iterator_curr returns the entry at the current iterator position but does not advance the iterator position.

LIST MANIPULATION

unless the underlying list mode has the COLLECTION_MODE_NOSYNC bit set, iterator functions that structurally change a list require the iterator to have been initialized with COLLECTION_LOCK_WRITE. cp_list_iterator_insert and cp_list_iterator_append add the item specified by the item parameter to the list before or after the current iterator position respectively. An exception is when inserting an item at the beginning of the list or appending an item at the end after the iterator has been moved beyond list limits, in which cases the item will still be added to the list in the extreme position.
cp_list_iterator_remove removes the item from the current iterator position and advances the iterator one step towards the bottom of the list if possible, or one step towards the top if not.

RETURN VALUE

cp_list_create_iterator returns the newly allocated iterator or NULL if memory allocation failed or if the requested lock could not be obtained. cp_list_iterator_init and cp_list_iterator_init_tail return 0 on success or non-zero if the requested lock could not be obtained. cp_list_iterator_next, cp_list_iterator_prev and cp_list_iterator_curr return the list item at the current iterator position or NULL if the list is empty or if the iterator has been positioned beyond list limits by a previous call.

Index

NAME
SYNOPSIS
DESCRIPTION
ITERATOR INITIALIZATION / FINALIZATION
ITERATOR POSITIONING AND ITEM RETRIEVAL
LIST MANIPULATION
RETURN VALUE
SEE ALSO

This document was created by man2html, using the manual pages.
Time: 18:37:21 GMT, December 27, 2005