CFBinaryHeap Reference

Overview

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.

Functions

CFBinaryHeapAddValue

Adds a value to a binary heap.

void CFBinaryHeapAddValue (
   CFBinaryHeapRef heap,
   const void *value
);

CFBinaryHeapApplyFunction

Iteratively applies a function to all the values in a binary heap.

void CFBinaryHeapApplyFunction (
   CFBinaryHeapRef heap,
   CFBinaryHeapApplierFunction applier,
   void *context
);

CFBinaryHeapContainsValue

Returns whether a given value is in a binary heap.

Boolean CFBinaryHeapContainsValue (
   CFBinaryHeapRef heap,
   const void *value
);

CFBinaryHeapCreate

Creates a new mutable or fixed-mutable binary heap.

CFBinaryHeapRef CFBinaryHeapCreate (
   CFAllocatorRef allocator,
   CFIndex capacity,
   const CFBinaryHeapCallBacks *callBacks,
   const CFBinaryHeapCompareContext *compareContext
);

CFBinaryHeapCreateCopy

Creates a new mutable or fixed-mutable binary heap with the values from a pre-existing binary heap.

CFBinaryHeapRef CFBinaryHeapCreateCopy (
   CFAllocatorRef allocator,
   CFIndex capacity,
   CFBinaryHeapRef heap
);

CFBinaryHeapGetCount

Returns the number of values currently in a binary heap.

CFIndex CFBinaryHeapGetCount (
   CFBinaryHeapRef heap
);

CFBinaryHeapGetCountOfValue

Counts the number of times a given value occurs in a binary heap.

CFIndex CFBinaryHeapGetCountOfValue (
   CFBinaryHeapRef heap,
   const void *value
);

CFBinaryHeapGetMinimum

Returns the minimum value in a binary heap.

const void * CFBinaryHeapGetMinimum (
   CFBinaryHeapRef heap
);

CFBinaryHeapGetMinimumIfPresent

Returns the minimum value in a binary heap, if present.

Boolean CFBinaryHeapGetMinimumIfPresent (
   CFBinaryHeapRef heap,
   const void **value
);

CFBinaryHeapGetTypeID

Returns the type identifier of the CFBinaryHeap opaque type.

CFTypeID CFBinaryHeapGetTypeID (
   void
);

CFBinaryHeapGetValues

Copies all the values from a binary heap into a sorted C array.

void CFBinaryHeapGetValues (
   CFBinaryHeapRef heap,
   const void **values
);

CFBinaryHeapRemoveAllValues

Removes all values from a binary heap, making it empty.

void CFBinaryHeapRemoveAllValues (
   CFBinaryHeapRef heap
);

CFBinaryHeapRemoveMinimumValue

Removes the minimum value from a binary heap.

void CFBinaryHeapRemoveMinimumValue (
   CFBinaryHeapRef heap
);

Callbacks

CFBinaryHeapApplierFunction

Callback function used to apply a function to all members of a binary heap.

typedef void (*CFBinaryHeapApplierFunction) (
   const void *val,
   void *context
);

If you name your function MyCallBack, you would declare it like this:

void MyCallBack (
   const void *val,
   void *context
);

CFBinaryHeapCompareCallBack

Callback function used to compare two members of a binary heap.

typedef CFComparisonResult (*CFBinaryHeapCompareCallBack) (
   const void *ptr1,
   const void *ptr2,
   void *info
);

If you name your function MyCallBack, you would declare it like this:

CFComparisonResult MyCallBack (
   const void *ptr1,
   const void *ptr2,
   void *info
);

CFBinaryHeapCopyDescriptionCallBack

Callback function used to get a description of a value in a binary heap.

typedef CFStringRef (*CFBinaryHeapCopyDescriptionCallBack) (
   const void *ptr
);

If you name your function MyCallBack, you would declare it like this:

CFStringRef MyCallBack (
   const void *ptr
);

CFBinaryHeapReleaseCallBack

Callback function used to release a value before it is removed from a binary heap.

typedef void (*CFBinaryHeapReleaseCallBack) (
   CFAllocatorRef allocator,
   const void *ptr
);

If you name your function MyCallBack, you would declare it like this:

void MyCallBack (
   CFAllocatorRef allocator,
   const void *ptr
);

CFBinaryHeapRetainCallBack

Callback function used to retain a value being added to a binary heap.

typedef const void *(*CFBinaryHeapRetainCallBack) (
   CFAllocatorRef allocator,
   const void *ptr
);

If you name your function MyCallBack, you would declare it like this:

const void *MyCallBack (
   CFAllocatorRef allocator,
   const void *ptr
);

Data Types

CFBinaryHeapCallBacks

Structure containing the callbacks for values for a CFBinaryHeap object.

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 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.

CFBinaryHeapCompareContext

Not used.

struct CFBinaryHeapCompareContext {
   CFIndex version;
   void *info;
   CFAllocatorRetainCallBack retain;
   CFAllocatorReleaseCallBack release;
   CFAllocatorCopyDescriptionCallBack copyDescription;
};
typedef struct CFBinaryHeapCompareContext CFBinaryHeapCompareContext;

CFBinaryHeapRef

A reference to a binary heap object.

typedef struct __CFBinaryHeap *CFBinaryHeapRef;

Constants

Predefined Callback Structures

CFBinaryHeap provides some predefined callbacks for your convenience.

const CFBinaryHeapCallBacks kCFStringBinaryHeapCallBacks;

Constants

kCFStringBinaryHeapCallBacks

Predefined CFBinaryHeapCallBacks structure containing a set of callbacks appropriate for use when the values in a binary heap are all CFString objects.

Available in iOS 2.0 and later.

Declared in CFBinaryHeap.h.