PblIterator* pblHeapIterator

( PblHeap* heap )

Returns an iterator over the elements in the heap.

Documentation

Returns an iterator over the elements in the heap.

The iterator starts the iteration at the biggest element.

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.

Modifying the heap via the Iterator's own remove or add methods does not maintain the heap property of the heap. In this case the heap property has to be restored by a call to pblHeapConstruct().

The iterators returned by the this method are fail-fast: if the heap is structurally modified at any time after the iterator is created, in any way except through the Iterator's own remove or add methods, 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:

heap - The heap to use

Returns:

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

Alphabetic index