NAME

cp_hashlist_iterator - an iterator for cp_hashlist structures

SYNOPSIS

#include <cprops/hashlist.h>

cp_hashlist_iterator * cp_hashlist_create_iterator(cp_hashlist *list, int lock_mode);
int cp_hashlist_iterator_init(cp_hashlist_iterator *iterator, cp_hashlist *list, int lock_mode);
int cp_hashlist_iterator_init_tail(cp_hashlist_iterator *iterator, cp_hashlist *list, int lock_mode);
int cp_hashlist_iterator_release(cp_hashlist_iterator *iterator);
void cp_hashlist_iterator_destroy(cp_hashlist_iterator *iterator);

void cp_hashlist_iterator_head(cp_hashlist_iterator *iterator);
void cp_hashlist_iterator_tail(cp_hashlist_iterator *iterator);
int cp_hashlist_iterator_to_key(cp_hashlist_iterator *iterator, void *key);

cp_hashlist_entry * cp_hashlist_iterator_next(cp_hashlist_iterator *iterator);
void *cp_hashlist_iterator_next_key(cp_hashlist_iterator *iterator);
void *cp_hashlist_iterator_next_value(cp_hashlist_iterator *iterator);

cp_hashlist_entry * cp_hashlist_iterator_prev(cp_hashlist_iterator *iterator);
void *cp_hashlist_iterator_prev_key(cp_hashlist_iterator *iterator);
void *cp_hashlist_iterator_prev_value(cp_hashlist_iterator *iterator);

cp_hashlist_entry * cp_hashlist_iterator_curr(cp_hashlist_iterator *iterator);
void *cp_hashlist_iterator_curr_key(cp_hashlist_iterator *iterator);
void *cp_hashlist_iterator_curr_value(cp_hashlist_iterator *iterator);

void *cp_hashlist_entry_get_key(cp_hashlist_entry *entry);
void *cp_hashlist_entry_get_value(cp_hashlist_entry *entry);

cp_hashlist_entry * cp_hashlist_iterator_insert(cp_hashlist_iterator *iterator, void *key, void *value);
cp_hashlist_entry * cp_hashlist_iterator_append(cp_hashlist_iterator *iterator, void *key, void *value);
cp_hashlist_entry * cp_hashlist_iterator_remove(cp_hashlist_iterator *iterator);

DESCRIPTION

cp_hashlist_iterator is an iterator for cp_hashlist structures. <cprops/hashlist.h> provides functions for list traversal and for making structural changes to lists.

ITERATOR INITIALIZATION / FINALIZATION

cp_hashlist_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. Unless the list was created with the COLLECTION_MODE_NOSYNC mode bit set, iterator functions may only perform structural changes with write-lock iterators.
cp_hashlist_iterator_init initializes an existing iterator by associating it with hashlist list, setting it at the head position and performing the locking specified by lock_mode. cp_hashlist_iterator_init_tail is similar but sets the iterator at the tail position.

cp_hashlist_iterator_release unlocks the list, but need not be called explicitly if calling cp_hashlist_iterator_destroy. If you allocate the iterator with cp_hashlist_create_iterator, call cp_hashlist_iterator_destroy to perform cleanup. If you declare an iterator instance on the stack, perform cleanup with cp_hashlist_iterator_release. Iterators that are created or initialized in a mode other than COLLECTION_LOCK_NONE must be released or destroyed to prevent deadlocks.

ITERATOR POSITIONING AND ITEM RETRIEVAL

cp_hashlist_iterator_head and cp_hashlist_iterator_tail position the iterator at the first and last positions in the list respectively.
cp_hashlist_iterator_to_key positions the iterator at the first occurence of key in the list if it exists.
cp_hashlist_iterator_next and cp_hashlist_iterator_prev return the internal entry structure at the current iterator position and move the iterator to the next or previous entry respectively. cp_hashlist_iterator_curr returns the internal entry structure at the current iterator position but does not advance the iterator position. cp_hashlist_entry_get_key and cp_hashlist_entry_get_value may be used to retrieve key and value from the returned structure.
cp_hashlist_iterator_next_key, cp_hashlist_iterator_next_value, cp_hashlist_iterator_curr_key, cp_hashlist_iterator_curr_value, cp_hashlist_iterator_prev_key and cp_hashlist_iterator_prev_value do not return an internal entry structure but the mapping key as indicated by their names.

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 created or initialized with COLLECTION_LOCK_WRITE. cp_hashlist_iterator_insert and cp_hashlist_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_hashlist_iterator_remove removes the item from the current iterator position and advances the iterator one step towards the end of the list if possible, or one step towards the beginning if not.

RETURN VALUE

cp_hashlist_create_iterator returns the newly allocated iterator or NULL if memory allocation failed or if the requested lock could not be obtained.
cp_hashlist_iterator_init and cp_hashlist_iterator_init_tail return 0 on success or non-zero if the requested lock could not be obtained.
cp_hashlist_iterator_to_key returns 0 if the requested key could be found or -1 if not.
cp_hashlist_iterator_next, cp_hashlist_iterator_prev and cp_hashlist_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.
cp_hashlist_iterator_insert and cp_hashlist_iterator_append return the newly created cp_hashlist_entry on success or NULL on error.

ERRORS

cp_hashlist_iterator_insert and cp_hashlist_iterator_append may set EINVAL or ENOMEM. cp_hashlist_iterator_create may set ENOMEM.

EINVAL

the iterator does not own the required lock type for inserting or appending.

ENOMEM

an internal memory allocation failed.

SEE ALSO

cp_hashlist(3)