CFArray Reference

Overview

CFArray and its derived mutable type, CFMutableArray Reference, manage ordered collections of values called arrays. CFArray creates static arrays and CFMutableArray creates dynamic arrays.

You create a static array object using either the CFArrayCreate or CFArrayCreateCopy function. These functions return an array containing the values you pass in as arguments. (Note that arrays can’t contain NULL pointers; in most cases, though, you can use the kCFNull constant instead.) Values are not copied but retained using the retain callback provided when an array was created. Similarly, when a value is removed from an array, it is released using the release callback.

CFArray’s two primitive functions CFArrayGetCount and CFArrayGetValueAtIndex provide the basis for all other functions in its interface. The CFArrayGetCount function returns the number of elements in an array; CFArrayGetValueAtIndex gives you access to an array’s elements by index, with index values starting at 0.

A number of CFArray functions allow you to operate over a range of values in an array, for example CFArrayApplyFunction lets you apply a function to values in an array, and CFArrayBSearchValues searches an array for the value that matches its parameter. Recall that a range is defined as {start, length}, therefore to operate over the entire array the range you supply should be {0, N} (where N is the count of the array).

CFArray is “toll-free bridged” with its Cocoa Foundation counterpart, NSArray. This means that the Core Foundation type is interchangeable in function or method calls with the bridged Foundation object. Therefore, in a method where you see an NSArray * parameter, you can pass in a CFArrayRef, and in a function where you see a CFArrayRef parameter, you can pass in an NSArray instance. This also applies to concrete subclasses of NSArray. See “Toll-Free Bridged Types” for more information on toll-free bridging.

Functions by Task

Creating an Array

• CFArrayCreate
• CFArrayCreateCopy

Examining an Array

• CFArrayBSearchValues
• CFArrayContainsValue
• CFArrayGetCount
• CFArrayGetCountOfValue
• CFArrayGetFirstIndexOfValue
• CFArrayGetLastIndexOfValue
• CFArrayGetValues
• CFArrayGetValueAtIndex

Applying a Function to Elements

• CFArrayApplyFunction

Getting the CFArray Type ID

• CFArrayGetTypeID

Functions

CFArrayApplyFunction

Calls a function once for each element in range in an array.

void CFArrayApplyFunction (
   CFArrayRef theArray,
   CFRange range,
   CFArrayApplierFunction applier,
   void *context
);

CFArrayBSearchValues

Searches an array for a value using a binary search algorithm.

CFIndex CFArrayBSearchValues (
   CFArrayRef theArray,
   CFRange range,
   const void *value,
   CFComparatorFunction comparator,
   void *context
);

CFArrayContainsValue

Reports whether or not a value is in an array.

Boolean CFArrayContainsValue (
   CFArrayRef theArray,
   CFRange range,
   const void *value
);

CFArrayCreate

Creates a new immutable array with the given values.

CFArrayRef CFArrayCreate (
   CFAllocatorRef allocator,
   const void **values,
   CFIndex numValues,
   const CFArrayCallBacks *callBacks
);

CFArrayCreateCopy

Creates a new immutable array with the values from another array.

CFArrayRef CFArrayCreateCopy (
   CFAllocatorRef allocator,
   CFArrayRef theArray
);

CFArrayGetCount

Returns the number of values currently in an array.

CFIndex CFArrayGetCount (
   CFArrayRef theArray
);

CFArrayGetCountOfValue

Counts the number of times a given value occurs in an array.

CFIndex CFArrayGetCountOfValue (
   CFArrayRef theArray,
   CFRange range,
   const void *value
);

CFArrayGetFirstIndexOfValue

Searches an array forward for a value.

CFIndex CFArrayGetFirstIndexOfValue (
   CFArrayRef theArray,
   CFRange range,
   const void *value
);

CFArrayGetLastIndexOfValue

Searches an array backward for a value.

CFIndex CFArrayGetLastIndexOfValue (
   CFArrayRef theArray,
   CFRange range,
   const void *value
);

CFArrayGetTypeID

Returns the type identifier for the CFArray opaque type.

CFTypeID CFArrayGetTypeID (
   void
);

CFArrayGetValueAtIndex

Retrieves a value at a given index.

const void * CFArrayGetValueAtIndex (
   CFArrayRef theArray,
   CFIndex idx
);

CFArrayGetValues

Fills a buffer with values from an array.

void CFArrayGetValues (
   CFArrayRef theArray,
   CFRange range,
   const void **values
);

Callbacks

CFArrayApplierFunction

Prototype of a callback function that may be applied to every value in an array.

typedef void (*CFArrayApplierFunction) (
   const void *value,
   void *context
);

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

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

CFArrayCopyDescriptionCallBack

Prototype of a callback function used to get a description of a value in an array.

typedef CFStringRef (*CFArrayCopyDescriptionCallBack) (
   const void *value
);

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

CFStringRef MyCallBack (
   const void *value
);

CFArrayEqualCallBack

Prototype of a callback function used to determine if two values in an array are equal.

typedef Boolean (*CFArrayEqualCallBack) (
   const void *value1,
   const void *value2
);

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

Boolean MyCallBack (
   const void *value1,
   const void *value2
);

CFArrayReleaseCallBack

Prototype of a callback function used to release a value before it’s removed from an array.

typedef void (*CFArrayReleaseCallBack) (
   CFAllocatorRef allocator,
   const void *value
);

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

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

CFArrayRetainCallBack

Prototype of a callback function used to retain a value being added to an array.

typedef const void *(*CFArrayRetainCallBack) (
   CFAllocatorRef allocator,
   const void *value
);

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

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

Data Types

CFArrayCallBacks

Structure containing the callbacks of a CFArray.

struct CFArrayCallBacks {
   CFIndex version;
   CFArrayRetainCallBack retain;
   CFArrayReleaseCallBack release;
   CFArrayCopyDescriptionCallBack copyDescription;
   CFArrayEqualCallBack equal;
};
typedef struct CFArrayCallBacks CFArrayCallBacks;

Fields

version

The version number of this structure. If not one of the defined version numbers for this opaque type, the behavior is undefined. The current version of this structure is 0.

retain

The callback used to retain each value as they are added to the collection. If NULL, values are not retained. See CFArrayRetainCallBack for a description of this callback.

release

The callback used to release values as they are removed from the collection. If NULL, values are not released. See CFArrayReleaseCallBack for a description of this callback.

copyDescription

The callback used to create a descriptive string representation of each value in the collection. If NULL, the collection will create a simple description of each value. See CFArrayCopyDescriptionCallBack for a description of this callback.

equal

The callback used to compare values in the array for equality for some operations. If NULL, the collection will use pointer equality to compare values in the collection. See CFArrayEqualCallBack for a description of this callback.

CFArrayRef

A reference to an immutable array object.

typedef const struct __CFArray *CFArrayRef;

Constants

Predefined Callback Structures

CFArray provides a predefined callback structure appropriate for use when the values in a CFArray are all CFType-derived objects.

const CFArrayCallBacks kCFTypeArrayCallBacks;

Constants

kCFTypeArrayCallBacks

Predefined CFArrayCallBacks structure containing a set of callbacks appropriate for use when the values in a CFArray are all CFType-derived objects. The retain callback is CFRetain, the release callback is CFRelease, the copy callback is CFCopyDescription, and the equal callback is CFEqual. Therefore, if you use this constant when creating the collection, items are automatically retained when added to the collection, and released when removed from the collection.

Available in OS X v10.0 and later.

Declared in CFArray.h.