CFBinaryHeap Reference

CFBinaryHeap implements a container that stores values sorted using a binary search algorithm. All binary heaps are mutable; there is not a separate immutable variety. Binary heaps can be useful as priority queues.

Declaration

Parameters

heap

The binary heap to search.

value

The value for which to find matches in the binary heap. The compare callback provided in the CFBinaryHeapCallBacks structure when the binary heap was created is used to compare values. If value, or any of the values in the binary heap, are not understood by the compare callback, the behavior is undefined.

Parameters

allocator

The allocator to use to allocate memory for the new object. Pass NULL or kCFAllocatorDefault to use the current default allocator.

capacity

The maximum number of values that can be contained by the binary heap. The binary heap starts empty and can grow to this number of values. If this parameter is 0, the binary heap's maximum capacity is limited only by memory.

callBacks

A pointer to a CFBinaryHeapCallBacks structure initialized with the callbacks that operate on the values placed into the binary heap. If the binary heap will be holding CFString objects, pass the kCFStringBinaryHeapCallBacks constant. This functions makes a copy of the contents of the callbacks structure, so that a pointer to a structure on the stack can be passed in, or can be reused for multiple binary heap creations. This callbacks parameter may not be NULL.

Parameters

allocator

The allocator to use to allocate memory for the new object. Pass NULL or kCFAllocatorDefault to use the current default allocator.

capacity

The maximum number of values that can be contained by the binary heap. The binary heap starts with the same number of values as heap and can grow to this number of values. If this parameter is 0, the binary heap's maximum capacity is limited only by memory. If nonzero, capacity must be large enough to hold all the values in heap.

heap

The binary heap which is to be copied. The values from the binary heap are copied as pointers into the new binary heap (that is, the values themselves are copied, not that to which the values point, if anything). However, the values are also retained by the new binary heap.

Return Value

A new CFBinaryHeap object holding the same values as heap. The new binary heap uses the same callbacks as heap. Ownership follows the Create Rule.

Declaration

Parameters

heap

The binary heap to search.

value

The value for which to find matches in the binary heap. The compare callback provided in the CFBinaryHeapCallBacks structure when the binary heap was created is used to compare. If value, or any of the values in the binary heap, are not understood by the compare callback, the behavior is undefined.

Declaration

Parameters

heap

The binary heap to use.

Return Value

The minimum value in heap as determined by the binary heap’s compare callback. If heap contains several equal minimum values, any one may be returned. If the value is a Core Foundation object, ownership follows the Get Rule.

Parameters

heap

The binary heap to use.

value

On return, the minimum value in heap as determined by the binary heap’s compare callback. If heap contains several equal minimum values, any one may be returned. If the value is a Core Foundation object, ownership follows the Get Rule.

Return Value

true if a minimum value exists in heap, false otherwise. false is returned only if heap is empty.

Declaration

Parameters

heap

The binary heap to use.

values

On return, the memory pointed to by this argument holds a C array of all the values in heap, sorted from minimum to maximum values. You must allocate sufficient memory to hold all the values in heap before calling this function. If the values are Core Foundation objects, ownership follows the Get Rule.

Fields

version

The version number of the structure type being passed in as a parameter to the CFBinaryHeap creation functions. This structure is version 0.

retain

The callback used to add a retain for the binary heap on values as they are put into the binary heap. This callback returns the value to use as the value in the binary heap, which is usually the value parameter passed to this callback, but may be a different value if a different value should be added to the binary heap. If this field is NULL, the binary heap does nothing to retain a value being added.

release

The callback used to remove a retain previously added for the binary heap from values as they are removed from the binary heap. If this field is NULL, the binary heap does nothing to release a value being removed.

copyDescription

The callback used to create a descriptive string representation of each value in the binary heap. This is used by the CFCopyDescription function. If this field is NULL, the binary heap constructs a CFString object describing the value based on its pointer value.

compare

The callback used to compare values in the binary heap in some operations. This field cannot be NULL.