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.

Adds a value to a binary heap.
Declaration
Swift
func CFBinaryHeapAddValue(_
heap
: CFBinaryHeap!, _value
: UnsafePointer<Void>)ObjectiveC
void CFBinaryHeapAddValue ( CFBinaryHeapRef heap, const void *value );
Parameters
heap
The binary heap to use.
value
The value to add to the binary heap. The value is retained by the binary heap using the retain callback provided in the
CFBinaryHeapCallBacks
structure when the binary heap was created.Availability
Available in OS X v10.0 and later.

Iteratively applies a function to all the values in a binary heap.
Declaration
Swift
func CFBinaryHeapApplyFunction(_
heap
: CFBinaryHeap!, _applier
: CFBinaryHeapApplierFunction!, _context
: UnsafeMutablePointer<Void>)ObjectiveC
void CFBinaryHeapApplyFunction ( CFBinaryHeapRef heap, CFBinaryHeapApplierFunction applier, void *context );
Parameters
heap
The binary heap to use.
applier
The callback function to call once for each value in
heap
.context
A programdefined value that is passed to the
applier
callback function, but is otherwise unused by this function.Availability
Available in OS X v10.0 and later.

Returns whether a given value is in a binary heap.
Declaration
Swift
func CFBinaryHeapContainsValue(_
heap
: CFBinaryHeap!, _value
: UnsafePointer<Void>) > BoolObjectiveC
Boolean CFBinaryHeapContainsValue ( CFBinaryHeapRef heap, const void *value );
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. Ifvalue
, or any of the values in the binary heap, are not understood by the compare callback, the behavior is undefined.Return Value
true
ifvalue
is a member ofheap
,false
otherwise.Availability
Available in OS X v10.0 and later.

Creates a new mutable or fixedmutable binary heap.
Declaration
Swift
func CFBinaryHeapCreate(_
allocator
: CFAllocator!, _capacity
: CFIndex, _callBacks
: UnsafePointer<CFBinaryHeapCallBacks>, _compareContext
: UnsafePointer<CFBinaryHeapCompareContext>) > CFBinaryHeap!ObjectiveC
CFBinaryHeapRef CFBinaryHeapCreate ( CFAllocatorRef allocator, CFIndex capacity, const CFBinaryHeapCallBacks *callBacks, const CFBinaryHeapCompareContext *compareContext );
Parameters
allocator
The allocator to use to allocate memory for the new object. Pass
NULL
orkCFAllocatorDefault
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 holdingCFString
objects, pass thekCFStringBinaryHeapCallBacks
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 beNULL
.compareContext
Not used. Pass
NULL
.Return Value
A new
CFBinaryHeap
object. Ownership follows the Create Rule.Availability
Available in OS X v10.0 and later.

Creates a new mutable or fixedmutable binary heap with the values from a preexisting binary heap.
Declaration
Swift
func CFBinaryHeapCreateCopy(_
allocator
: CFAllocator!, _capacity
: CFIndex, _heap
: CFBinaryHeap!) > CFBinaryHeap!ObjectiveC
CFBinaryHeapRef CFBinaryHeapCreateCopy ( CFAllocatorRef allocator, CFIndex capacity, CFBinaryHeapRef heap );
Parameters
allocator
The allocator to use to allocate memory for the new object. Pass
NULL
orkCFAllocatorDefault
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 is0
, the binary heap's maximum capacity is limited only by memory. If nonzero,capacity
must be large enough to hold all the values inheap
.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 asheap
. The new binary heap uses the same callbacks asheap
. Ownership follows the Create Rule.Availability
Available in OS X v10.0 and later.

Returns the number of values currently in a binary heap.
Declaration
Swift
func CFBinaryHeapGetCount(_
heap
: CFBinaryHeap!) > CFIndexObjectiveC
CFIndex CFBinaryHeapGetCount ( CFBinaryHeapRef heap );
Parameters
heap
The binary heap to use.
Return Value
The number of values in
heap
.Availability
Available in OS X v10.0 and later.

Counts the number of times a given value occurs in a binary heap.
Declaration
Swift
func CFBinaryHeapGetCountOfValue(_
heap
: CFBinaryHeap!, _value
: UnsafePointer<Void>) > CFIndexObjectiveC
CFIndex CFBinaryHeapGetCountOfValue ( CFBinaryHeapRef heap, const void *value );
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. Ifvalue
, or any of the values in the binary heap, are not understood by the compare callback, the behavior is undefined.Return Value
The number of times
value
occurs inheap
.Availability
Available in OS X v10.0 and later.

Returns the minimum value in a binary heap.
Declaration
Swift
func CFBinaryHeapGetMinimum(_
heap
: CFBinaryHeap!) > UnsafePointer<Void>ObjectiveC
const void * CFBinaryHeapGetMinimum ( CFBinaryHeapRef heap );
Parameters
heap
The binary heap to use.
Return Value
The minimum value in
heap
as determined by the binary heap’s compare callback. Ifheap
contains several equal minimum values, any one may be returned. If the value is a Core Foundation object, ownership follows the Get Rule.Availability
Available in OS X v10.0 and later.

Returns the minimum value in a binary heap, if present.
Declaration
Swift
func CFBinaryHeapGetMinimumIfPresent(_
heap
: CFBinaryHeap!, _value
: UnsafeMutablePointer<UnsafePointer<Void>>) > BoolObjectiveC
Boolean CFBinaryHeapGetMinimumIfPresent ( CFBinaryHeapRef heap, const void **value );
Parameters
heap
The binary heap to use.
value
On return, the minimum value in
heap
as determined by the binary heap’s compare callback. Ifheap
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 inheap
,false
otherwise.false
is returned only ifheap
is empty.Availability
Available in OS X v10.0 and later.

Copies all the values from a binary heap into a sorted C array.
Declaration
Swift
func CFBinaryHeapGetValues(_
heap
: CFBinaryHeap!, _values
: UnsafeMutablePointer<UnsafePointer<Void>>)ObjectiveC
void CFBinaryHeapGetValues ( CFBinaryHeapRef heap, const void **values );
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.Availability
Available in OS X v10.0 and later.

Removes all values from a binary heap, making it empty.
Declaration
Swift
func CFBinaryHeapRemoveAllValues(_
heap
: CFBinaryHeap!)ObjectiveC
void CFBinaryHeapRemoveAllValues ( CFBinaryHeapRef heap );
Parameters
heap
The binary heap to use.
Availability
Available in OS X v10.0 and later.

Removes the minimum value from a binary heap.
Declaration
Swift
func CFBinaryHeapRemoveMinimumValue(_
heap
: CFBinaryHeap!)ObjectiveC
void CFBinaryHeapRemoveMinimumValue ( CFBinaryHeapRef heap );
Parameters
heap
The binary heap to use.
Discussion
If
heap
contains several equal minimum values, only one of them is removed. Ifheap
is empty, this function does nothing.Availability
Available in OS X v10.0 and later.

Callback function used to apply a function to all members of a binary heap.
Declaration
Swift
typealias CFBinaryHeapApplierFunction = (UnsafePointer<Void>, UnsafeMutablePointer<Void>) > Void
ObjectiveC
typedef void (*CFBinaryHeapApplierFunction) ( const void *val, void *context );
Parameters
val
The current value from the binary heap.
context
The programdefined context parameter given to the
CFBinaryHeapApplyFunction
function.Availability
Available in OS X v10.0 and later.

Callback function used to compare two members of a binary heap.
Declaration
ObjectiveC
typedef CFComparisonResult (*CFBinaryHeapCompareCallBack) ( const void *ptr1, const void *ptr2, void *info );
Parameters
ptr1
First value to compare.
ptr2
Second value to compare.
info
Not used. Should always be
NULL
.Return Value
kCFCompareLessThan
ifptr1
is less thanptr2
,kCFCompareEqualTo
ifptr1
andptr2
are equal, orkCFCompareGreaterThan
ifptr1
is greater thanptr2
. 
Callback function used to get a description of a value in a binary heap.
Declaration
ObjectiveC
typedef CFStringRef (*CFBinaryHeapCopyDescriptionCallBack) ( const void *ptr );
Parameters
ptr
The value to be described.

Callback function used to release a value before it is removed from a binary heap.
Declaration
ObjectiveC
typedef void (*CFBinaryHeapReleaseCallBack) ( CFAllocatorRef allocator, const void *ptr );
Parameters
allocator
The binary heap’s allocator.
ptr
The value to release.

Callback function used to retain a value being added to a binary heap.
Declaration
ObjectiveC
typedef const void *(*CFBinaryHeapRetainCallBack) ( CFAllocatorRef allocator, const void *ptr );
Parameters
allocator
The binary heap’s allocator.
ptr
The value to retain.
Return Value
The value to store in the binary heap, which is usually the
ptr
parameter passed to this callback, but may be a different value if a different value should be stored in the binary heap.

Structure containing the callbacks for values for a
CFBinaryHeap
object.Declaration
Swift
struct CFBinaryHeapCallBacks { var version: CFIndex var retain: ((CFAllocator!, UnsafePointer<Void>) > UnsafePointer<Void>)! var release: ((CFAllocator!, UnsafePointer<Void>) > Void)! var copyDescription: ((UnsafePointer<Void>) > Unmanaged<CFString>!)! var compare: ((UnsafePointer<Void>, UnsafePointer<Void>, UnsafeMutablePointer<Void>) > CFComparisonResult)! init() init(version
version
: CFIndex, retainretain
: ((CFAllocator!, UnsafePointer<Void>) > UnsafePointer<Void>)!, releaserelease
: ((CFAllocator!, UnsafePointer<Void>) > Void)!, copyDescriptioncopyDescription
: ((UnsafePointer<Void>) > Unmanaged<CFString>!)!, comparecompare
: ((UnsafePointer<Void>, UnsafePointer<Void>, UnsafeMutablePointer<Void>) > CFComparisonResult)!) }ObjectiveC
struct CFBinaryHeapCallBacks { CFIndex version; CFBinaryHeapRetainCallBack retain; CFBinaryHeapReleaseCallBack release; CFAllocatorCopyDescriptionCallBack copyDescription; CFBinaryHeapCompareCallBack compare; }; typedef struct CFBinaryHeapCallBacks CFBinaryHeapCallBacks;
Fields
version
The version number of the structure type being passed in as a parameter to the
CFBinaryHeap
creation functions. This structure is version0
.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 isNULL
, the binary heap constructs aCFString
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
.Availability
Available in OS X v10.0 and later.

Not used.
Declaration
Swift
struct CFBinaryHeapCompareContext { var version: CFIndex var info: UnsafeMutablePointer<Void> var retain: ((UnsafePointer<Void>) > UnsafePointer<Void>)! var release: ((UnsafePointer<Void>) > Void)! var copyDescription: ((UnsafePointer<Void>) > Unmanaged<CFString>!)! init() init(version
version
: CFIndex, infoinfo
: UnsafeMutablePointer<Void>, retainretain
: ((UnsafePointer<Void>) > UnsafePointer<Void>)!, releaserelease
: ((UnsafePointer<Void>) > Void)!, copyDescriptioncopyDescription
: ((UnsafePointer<Void>) > Unmanaged<CFString>!)!) }ObjectiveC
struct CFBinaryHeapCompareContext { CFIndex version; void *info; CFAllocatorRetainCallBack retain; CFAllocatorReleaseCallBack release; CFAllocatorCopyDescriptionCallBack copyDescription; }; typedef struct CFBinaryHeapCompareContext CFBinaryHeapCompareContext;
Availability
Available in OS X v10.0 and later.

A reference to a binary heap object.
Declaration
Swift
class CFBinaryHeap { }
ObjectiveC
typedef struct __CFBinaryHeap *CFBinaryHeapRef;
Import Statement
ObjectiveC
@import CoreFoundation;
Swift
import CoreFoundation
Availability
Available in OS X v10.0 and later.

CFBinaryHeap
provides some predefined callbacks for your convenience.Declaration
Swift
let kCFStringBinaryHeapCallBacks: CFBinaryHeapCallBacks
ObjectiveC
const CFBinaryHeapCallBacks kCFStringBinaryHeapCallBacks;
Constants

kCFStringBinaryHeapCallBacks
kCFStringBinaryHeapCallBacks
Predefined
CFBinaryHeapCallBacks
structure containing a set of callbacks appropriate for use when the values in a binary heap are allCFString
objects.Available in OS X v10.0 and later.

Copyright © 2016 Apple Inc. All rights reserved. Terms of Use  Privacy Policy  Updated: 20060110