PblIterator* pblMapIteratorNew

( PblMap* map )

Returns an iterator over the map entries in this map in proper sequence.

Documentation

Returns an iterator over the map entries in this map in proper sequence.

The iterator starts the iteration at the beginning of the map.

The elements returned by the pblIteratorNext() and pblIteratorPrevious() calls to this iterator are of type 'PblMapEntry *'. Use the methods pblMapEntryKeyLength(), pblMapEntryKey(), pblMapEntryValueLength() and pblMapEntryValue() to retrieve the attributes of the map entries.

Note: The memory allocated by this method for the iterator returned needs to be released by calling pblIteratorFree() once the iterator is no longer needed.

The iterators returned by the this method are fail-fast: if the map is structurally modified at any time after the iterator is created, in any way, the iterator will return a PBL_ERROR_CONCURRENT_MODIFICATION error.

Thus, in the face of concurrent modification, the iterator fails quickly and cleanly, rather than risking arbitrary, non-deterministic behavior at an undetermined time in the future.

This method has a time complexity of O(1).

Parameters:

map - The map to create the iterator for

Returns:

void * retptr != NULL: The iterator.
void * retptr == NULL: An error, see pbl_errno:
PBL_ERROR_OUT_OF_MEMORY - Out of memory.
PBL_ERROR_PARAM_COLLECTION - The map cannot be iterated.

Alphabetic index