Functions

Beta documentation : This document has not received a full technical review and therefore might contain inaccuracies.

CFArrayAppendValue

void CFArrayAppendValue(CFMutableArrayRef theArray, const void * value);

Adds a value to a mutable CFArray object and gives it the largest index of the array.

Parameters

Name Description

array Pass a reference to a CFArray object to which the value is to be added. If this parameter is not a valid reference to a mutable CFArray object, the behavior is undefined. If the object is a fixed-capacity array and it is full before this operation, the behavior is undefined.

value The value to add to the array. The value is retained by the array using the retain callback provided when the array was created. If the value is not of the sort expected by the retain callback, the behavior is undefined. The value is assigned to the index one larger than the previous largest index, and the count of the array is increased by one.

Name	Description
`array`	Pass a reference to a CFArray object to which the value is to be added. If this parameter is not a valid reference to a mutable CFArray object, the behavior is undefined. If the object is a fixed-capacity array and it is full before this operation, the behavior is undefined.
`value`	The value to add to the array. The value is retained by the array using the retain callback provided when the array was created. If the value is not of the sort expected by the retain callback, the behavior is undefined. The value is assigned to the index one larger than the previous largest index, and the count of the array is increased by one.

CFArrayApplyFunction

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

Calls a function once for each value in the array.

Parameters

Name Description

array Pass a reference to the CFArray object to be operated upon. If this parameter is not a valid reference to a CFArray object, the behavior is undefined..

range Pass a structure of type CFRange that specifies the range of values within the array to apply the function to. If the range location or end point (defined as the range location plus the range length minus 1) are outside the index space of the array (0 to N-1 inclusive, where N is the count of the array), the behavior is undefined. If the range length is negative, the behavior is undefined. The range may be empty (length 0).

applier Pass a pointer to the callback applier function to call once for each array value in the specified range. If this parameter is not a pointer to a function of the correct prototype (CFArrayApplierFunction), the behavior is undefined. If there are array values in the specified range which the applier function does not expect or cannot properly apply behavior to, the behavior of CFArrayApplyFunction is undefined.

context A pointer-sized user-defined value, which is passed as the second parameter to the applier function, but is otherwise unused by this function. If the context is not what is expected by the applier function, the behavior is undefined.

Name	Description
`array`	Pass a reference to the CFArray object to be operated upon. If this parameter is not a valid reference to a CFArray object, the behavior is undefined..
`range`	Pass a structure of type `CFRange` that specifies the range of values within the array to apply the function to. If the range location or end point (defined as the range location plus the range length minus 1) are outside the index space of the array (0 to N-1 inclusive, where N is the count of the array), the behavior is undefined. If the range length is negative, the behavior is undefined. The range may be empty (length 0).
`applier`	Pass a pointer to the callback applier function to call once for each array value in the specified range. If this parameter is not a pointer to a function of the correct prototype (`CFArrayApplierFunction`), the behavior is undefined. If there are array values in the specified range which the applier function does not expect or cannot properly apply behavior to, the behavior of `CFArrayApplyFunction` is undefined.
`context`	A pointer-sized user-defined value, which is passed as the second parameter to the applier function, but is otherwise unused by this function. If the context is not what is expected by the applier function, the behavior is undefined.

CFArrayBSearchValues

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

Searches a CFArray object for a specified value using a binary search algorithm.

Parameters

Name Description

array Pass a reference to the CFArray object to be searched. If this parameter is not a valid reference to a CFArray object, the behavior is undefined. If array is not sorted from least to greatest according to the comparator function, the behavior is undefined.

range Pass a structure of type CFRange that specifies the range of values within array to search. If the range location or end point (defined as the range location plus the range length minus 1) are outside the index space of the array (0 to N-1 inclusive, where N is the count of the array), the behavior is undefined. If the range length is negative, the behavior is undefined. The range may be empty (length 0).

value Pass the value for which to find a match in array. If value, or any of the values in the array, are not understood by the comparator callback, the behavior is undefined.

comparator Pass a pointer to a function conforming to the CFComparatorFunction type signature. This function is used in the binary search operation to compare values in the array with the given value. If this parameter is not a pointer to a function of the correct prototype, the behavior is undefined. If there are values in the range which the comparator function does not expect or cannot properly compare, the behavior is undefined.

context A pointer-sized user-defined value, which is passed as the third parameter to the comparator function, but is otherwise unused by this function. If the context is not what is expected by the comparator function, the behavior is undefined.

Name	Description
`array`	Pass a reference to the CFArray object to be searched. If this parameter is not a valid reference to a CFArray object, the behavior is undefined. If `array` is not sorted from least to greatest according to the comparator function, the behavior is undefined.
`range`	Pass a structure of type `CFRange` that specifies the range of values within `array` to search. If the range location or end point (defined as the range location plus the range length minus 1) are outside the index space of the array (0 to N-1 inclusive, where N is the count of the array), the behavior is undefined. If the range length is negative, the behavior is undefined. The range may be empty (length 0).
`value`	Pass the value for which to find a match in `array`. If `value`, or any of the values in the array, are not understood by the comparator callback, the behavior is undefined.
`comparator`	Pass a pointer to a function conforming to the `CFComparatorFunction` type signature. This function is used in the binary search operation to compare values in the array with the given value. If this parameter is not a pointer to a function of the correct prototype, the behavior is undefined. If there are values in the range which the comparator function does not expect or cannot properly compare, the behavior is undefined.
`context`	A pointer-sized user-defined value, which is passed as the third parameter to the comparator function, but is otherwise unused by this function. If the context is not what is expected by the comparator function, the behavior is undefined.

Result: The returned value is one of the following:

The index of a value that matched, if the given value matches one or more in the range
An index greater than or equal to the end point of the range if the value is greater than all the values in the range
The index of the value greater than the target value if the value lies between two of (or less than all of) the values in the range.

CFArrayContainsValue

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

Reports whether a specified value is in a CFArray object.

Parameters

Name Description

array Pass a reference to the CFArray object to be searched. If this parameter is not a valid reference to a CFArray object, the behavior is undefined.

range Pass a structure of type CFRange that specifies the range of values within the array to search. If the range location or end point (defined as the range location plus the range length minus 1) are outside the index space of the array (0 to N-1 inclusive, where N is the count of the array), the behavior is undefined. If the range length is negative, the behavior is undefined. The range may be empty (that is, have a length of 0).

value Pass the value for which to find matches in the array. The equal callback specified when the array was created is used to compare values. If the equal callback was initialized to NULL, pointer equality (the C operator ==) is used. If value, or any of the values in the array, are not understood by the equal callback, the behavior is undefined.

Name	Description
`array`	Pass a reference to the CFArray object to be searched. If this parameter is not a valid reference to a CFArray object, the behavior is undefined.
`range`	Pass a structure of type `CFRange` that specifies the range of values within the `array` to search. If the range location or end point (defined as the range location plus the range length minus 1) are outside the index space of the array (0 to N-1 inclusive, where N is the count of the array), the behavior is undefined. If the range length is negative, the behavior is undefined. The range may be empty (that is, have a length of 0).
`value`	Pass the value for which to find matches in the array. The `equal` callback specified when the array was created is used to compare values. If the `equal` callback was initialized to `NULL`, pointer equality (the C operator `==`) is used. If `value`, or any of the values in the array, are not understood by the `equal` callback, the behavior is undefined.

Result: TRUE if the value is in the specified range of the CFArray object, otherwise FALSE.

CFArrayCreate

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

Creates an immutable CFArray object with the given values.

Parameters

Name Description

allocator Pass a reference to a CFAllocator object used to allocate memory for the created CFArray object and its storage for values. This parameter may be NULL in which case the current default CFAllocator object is used. If this reference is not to a valid CFAllocator, the behavior is undefined.

values Pass a pointer to a C array containing pointer-sized values, or pointers to values, to be stored in the created CFArray object. The values in the array are in the same order in which they appear in the C array. This parameter may be NULL if the numValues parameter is 0. This C array is not changed or freed by this function. If this parameter is not a valid pointer to a C array of at least numValues pointers, the behavior is undefined.

numValues Pass the number of values to copy from the C array pointed to by the values parameter into the created CFArray object. This number is the count of values in the array. If this parameter is negative or is greater than the number of values actually in the values C array, the behavior is undefined.

callBacks Pass a pointer to a CFArrayCallBacks structure initialized with the callbacks for the CFArray object to use on each of its values. The retain callback is used within this function, for example, to retain all of the new values from the values C array. The CFArrayCreate function 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 CFArray creations. If the version field of this callbacks structure is not one of the defined ones for CFArray, the behavior is undefined. The retain field may be NULL, in which case the CFArray object does nothing to retain the values contained by the array. The release field may be NULL, in which case the CFArray object does nothing to reverse the effect of the retain callback (if any) on the values when the array is destroyed. If the copyDescription field is NULL, the array creates a simple description for the value. If the equal field is NULL, the array will use pointer equality to test for equality of values. The parameter itself may be NULL. In this case the function behaves as if a valid structure of version 0 with all fields NULL had been passed in. Otherwise, if any of the fields are not valid pointers to functions of the correct type, or this parameter is not a valid pointer to a CFArrayCallBacks structure, the behavior is undefined. If any of the values put into the array is not understood by a callback function, the behavior when that callback function is invoked is undefined.

Name	Description
`allocator`	Pass a reference to a CFAllocator object used to allocate memory for the created CFArray object and its storage for values. This parameter may be `NULL` in which case the current default CFAllocator object is used. If this reference is not to a valid CFAllocator, the behavior is undefined.
`values`	Pass a pointer to a C array containing pointer-sized values, or pointers to values, to be stored in the created CFArray object. The values in the array are in the same order in which they appear in the C array. This parameter may be `NULL` if the `numValues` parameter is 0. This C array is not changed or freed by this function. If this parameter is not a valid pointer to a C array of at least `numValues` pointers, the behavior is undefined.
`numValues`	Pass the number of values to copy from the C array pointed to by the `values` parameter into the created CFArray object. This number is the count of values in the array. If this parameter is negative or is greater than the number of values actually in the `values` C array, the behavior is undefined.
`callBacks`	Pass a pointer to a `CFArrayCallBacks` structure initialized with the callbacks for the CFArray object to use on each of its values. The `retain` callback is used within this function, for example, to retain all of the new values from the values C array. The `CFArrayCreate` function 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 CFArray creations. If the version field of this callbacks structure is not one of the defined ones for CFArray, the behavior is undefined. The `retain` field may be `NULL`, in which case the CFArray object does nothing to retain the values contained by the array. The `release` field may be `NULL`, in which case the CFArray object does nothing to reverse the effect of the retain callback (if any) on the values when the array is destroyed. If the `copyDescription` field is `NULL`, the array creates a simple description for the value. If the `equal` field is `NULL`, the array will use pointer equality to test for equality of values. The parameter itself may be `NULL`. In this case the function behaves as if a valid structure of version 0 with all fields `NULL` had been passed in. Otherwise, if any of the fields are not valid pointers to functions of the correct type, or this parameter is not a valid pointer to a `CFArrayCallBacks` structure, the behavior is undefined. If any of the values put into the array is not understood by a callback function, the behavior when that callback function is invoked is undefined.

Result: A reference to the new immutable CFArray object or NULL if there was a problem creating the object.

CFArrayCreateCopy

CFArrayRef CFArrayCreateCopy(CFAllocatorRef allocator, CFArrayRef srcArray);

Creates an immutable CFArray object from the values contained by another CFArray object.

Parameters

Name Description

allocator Pass reference to a CFAllocator to be used to allocate memory for the CFArray object and for the storage of its values. This parameter may be NULL in which case the current default CFAllocator object is used. If this reference is not to a valid CFAllocator, the behavior is undefined.

array Pass reference to the CFArray object which is to be copied. The values from the array are copied as pointers into the new array (that is, the values themselves are copied, not that which the values point to, if anything). However, the values are also retained by the new array. The count of the new array will be the same as the source array and the new array uses the same callbacks as the source array. If this parameter is not a valid reference to a CFArray, the behavior is undefined.

Name	Description
`allocator`	Pass reference to a CFAllocator to be used to allocate memory for the CFArray object and for the storage of its values. This parameter may be `NULL` in which case the current default CFAllocator object is used. If this reference is not to a valid CFAllocator, the behavior is undefined.
`array`	Pass reference to the CFArray object which is to be copied. The values from the array are copied as pointers into the new array (that is, the values themselves are copied, not that which the values point to, if anything). However, the values are also retained by the new array. The count of the new array will be the same as the source array and the new array uses the same callbacks as the source array. If this parameter is not a valid reference to a CFArray, the behavior is undefined.

Result: A reference to the new immutable CFArray object or NULL if there was a problem creating the object.

CFArrayCreateMutable

CFMutableArrayRef CFArrayCreateMutable(CFAllocatorRef allocator, CFIndex capacity, const CFArrayCallBacks * callBacks);

Creates an empty mutable CFArray object.

Parameters

Name Description

allocator Pass a reference to a CFAllocator to be used to allocate memory for the CFArray object and for the storage of its values. This parameter may be NULL in which case the current default CFAllocator object is used. If this reference is not to a valid CFAllocator, the behavior is undefined.

capacity Pass the maximum number of values that can be contained by the CFArray object. The array starts empty, and can grow to this number of values (and it can have less). Adding values exceeding the capacity limit can result in undefined behavior. If this parameter is 0, the array's maximum capacity is unlimited (or rather, only limited by address space and available memory constraints). If this parameter is negative, the behavior is undefined.

callBacks Pass a pointer to a CFArrayCallBacks structure initialized with the callbacks for the CFArray object to use on each of its values. The retain callback is used within this function, for example, to retain all of the new values from the values C array. The CFArrayCreate function 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 array creations. If the version field of this callbacks structure is not one of the defined ones for CFArray, the behavior is undefined. The retain field may be NULL, in which case the CFArray object does nothing to retain the values contained by the array. The release field may be NULL, in which case the CFArray object does nothing to reverse the effect of the retain callback (if any) on the values when the array is destroyed. If the copyDescription field is NULL, the array creates a simple description for the value. If the equal field is NULL, the array will use pointer equality to test for equality of values. The parameter itself may be NULL. In this case the function behaves as if a valid structure of version 0 with all fields NULL had been passed in. Otherwise, if any of the fields are not valid pointers to functions of the correct type, or this parameter is not a valid pointer to a CFArrayCallBacks structure, the behavior is undefined. If any of the values put into the array is not understood by a callback function, the behavior when that callback function is invoked is undefined.

Name	Description
`allocator`	Pass a reference to a CFAllocator to be used to allocate memory for the CFArray object and for the storage of its values. This parameter may be `NULL` in which case the current default CFAllocator object is used. If this reference is not to a valid CFAllocator, the behavior is undefined.
`capacity`	Pass the maximum number of values that can be contained by the CFArray object. The array starts empty, and can grow to this number of values (and it can have less). Adding values exceeding the capacity limit can result in undefined behavior. If this parameter is 0, the array's maximum capacity is unlimited (or rather, only limited by address space and available memory constraints). If this parameter is negative, the behavior is undefined.
`callBacks`	Pass a pointer to a `CFArrayCallBacks` structure initialized with the callbacks for the CFArray object to use on each of its values. The `retain` callback is used within this function, for example, to retain all of the new values from the values C array. The CFArrayCreate function 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 array creations. If the version field of this callbacks structure is not one of the defined ones for CFArray, the behavior is undefined. The `retain` field may be `NULL`, in which case the CFArray object does nothing to retain the values contained by the array. The `release` field may be `NULL`, in which case the CFArray object does nothing to reverse the effect of the retain callback (if any) on the values when the array is destroyed. If the `copyDescription` field is `NULL`, the array creates a simple description for the value. If the `equal` field is `NULL`, the array will use pointer equality to test for equality of values. The parameter itself may be `NULL`. In this case the function behaves as if a valid structure of version 0 with all fields `NULL` had been passed in. Otherwise, if any of the fields are not valid pointers to functions of the correct type, or this parameter is not a valid pointer to a `CFArrayCallBacks` structure, the behavior is undefined. If any of the values put into the array is not understood by a callback function, the behavior when that callback function is invoked is undefined.

Result: A reference to the new mutable CFArray or NULL if there was a problem creating the object.

CFArrayCreateMutableCopy

CFMutableArrayRef CFArrayCreateMutableCopy(CFAllocatorRef allocator, CFIndex capacity, CFArrayRef srcArray);

Creates a mutable CFArray object from the values of another CFArray object.

Parameters

Name Description

allocator Pass a reference to a CFAllocator object used to allocate memory for the array and for the storage of its values. This parameter may be NULL in which case the current default CFAllocator object is used. If this reference is not to a valid CFAllocator object, the behavior is undefined.

capacity Pass the maximum number of values that can be contained by the CFArray object. The array starts empty, and can grow to this number of values (and it can have less). Adding values exceeding the capacity limit can result in undefined behavior. If this parameter is 0, the array's maximum capacity is unlimited (or rather, only limited by address space and available memory constraints). If this parameter is negative, the behavior is undefined

array Pass a reference to the CFArray object to be copied. The values from the array are copied as pointers into the new CFArray object (that is, the values themselves are copied, not that which the values point to, if anything). However, the values are also retained by the new array. The count of the new CFArray object is be the same as the source CFArray object and the new object uses the same callbacks as the source object. If this parameter is not a reference to a valid CFArray object, the behavior is undefined.

Name	Description
`allocator`	Pass a reference to a CFAllocator object used to allocate memory for the array and for the storage of its values. This parameter may be `NULL` in which case the current default CFAllocator object is used. If this reference is not to a valid CFAllocator object, the behavior is undefined.
`capacity`	Pass the maximum number of values that can be contained by the CFArray object. The array starts empty, and can grow to this number of values (and it can have less). Adding values exceeding the capacity limit can result in undefined behavior. If this parameter is 0, the array's maximum capacity is unlimited (or rather, only limited by address space and available memory constraints). If this parameter is negative, the behavior is undefined
`array`	Pass a reference to the CFArray object to be copied. The values from the array are copied as pointers into the new CFArray object (that is, the values themselves are copied, not that which the values point to, if anything). However, the values are also retained by the new array. The count of the new CFArray object is be the same as the source CFArray object and the new object uses the same callbacks as the source object. If this parameter is not a reference to a valid CFArray object, the behavior is undefined.

Result: A reference to the new mutable CFArray object or NULL if there was a problem creating the object.

CFArrayExchangeValuesAtIndices

void CFArrayExchangeValuesAtIndices(CFMutableArrayRef theArray, CFIndex idx1, CFIndex idx2);

Exchanges the values at two indices of a mutable CFArray object.

Parameters

Name Description

array Pass a reference to a mutable CFArray object in which the values are to be swapped. If this parameter is not a valid mutable CFArray object, the behavior is undefined.

idx1 Pass the index of the first value to be swapped. If the index is outside the index space of the array (0 to N-1 inclusive, where N is the count of the array before the operation), the behavior is undefined.

idx2 Pass the index of the second value to be swapped. If the index is outside the index space of the array (0 to N-1 inclusive, where N is the count of the array before the operation), the behavior is undefined.

Name	Description
`array`	Pass a reference to a mutable CFArray object in which the values are to be swapped. If this parameter is not a valid mutable CFArray object, the behavior is undefined.
`idx1`	Pass the index of the first value to be swapped. If the index is outside the index space of the array (0 to `N`-1 inclusive, where `N` is the count of the array before the operation), the behavior is undefined.
`idx2`	Pass the index of the second value to be swapped. If the index is outside the index space of the array (0 to `N`-1 inclusive, where `N` is the count of the array before the operation), the behavior is undefined.

CFArrayGetCount

CFIndex CFArrayGetCount(CFArrayRef theArray);

Obtains the number of values currently in a CFArray object.

Parameters

Name Description

array A reference to the CFArray object to be queried. If this parameter is not a valid reference to a CFArray object, the behavior is undefined.

Name	Description
`array`	A reference to the CFArray object to be queried. If this parameter is not a valid reference to a CFArray object, the behavior is undefined.

Result: The number of values in the array.

CFArrayGetCountOfValue

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

Obtains the number of times a given value occurs in a CFArray object.

Parameters

Name Description

array Pass a reference to the CFArray object to be searched. If this parameter is not a valid reference to a CFArray object, the behavior is undefined.

range Pass the range of values within the array to search. If the range location or end point (defined as the range location plus the range length minus 1) are outside the index space of the array (0 to N-1 inclusive, where N is the count of the array), the behavior is undefined. If the range length is negative, the behavior is undefined. The range may be empty (that is, have a length of 0).

value Pass the value for which to find matches in the array. The equal callback specified when the array was created is used to compare values. If the equal callback was initialized to NULL, pointer equality (the C operator ==) is used. If value, or any of the values in the array, are not understood by the equal callback, the behavior is undefined.

Name	Description
`array`	Pass a reference to the CFArray object to be searched. If this parameter is not a valid reference to a CFArray object, the behavior is undefined.
`range`	Pass the range of values within the array to search. If the range location or end point (defined as the range location plus the range length minus 1) are outside the index space of the array (0 to N-1 inclusive, where N is the count of the array), the behavior is undefined. If the range length is negative, the behavior is undefined. The range may be empty (that is, have a length of 0).
`value`	Pass the value for which to find matches in the array. The `equal` callback specified when the array was created is used to compare values. If the `equal` callback was initialized to `NULL`, pointer equality (the C operator `==`) is used. If `value`, or any of the values in the array, are not understood by the `equal` callback, the behavior is undefined.

Result: The number of times the given value occurs in the array within the specified range.

CFArrayGetFirstIndexOfValue

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

Obtains the first index of a specified value in a CFArray object.

Parameters

Name Description

array Pass a reference to the CFArray object to be searched. If this parameter is not a valid reference to a CFArray object, the behavior is undefined.

range Pass a structure of type CFRange that specifies the range of values within array to search. If the range location or end point (defined as the range location plus the range length minus 1) are outside the index space of the array (0 to N-1 inclusive, where N is the count of the array), the behavior is undefined. If the range length is negative, the behavior is undefined. The range may be empty (length 0).. The search progresses from the smallest index defined by the range to the largest.

value Pass the value for which to find a match in array. The equal callback provided when the array was created is used to compare values. If the equal callback was NULL, pointer equality (with the C operator ==) is used. If value, or any of the values in the array, are not understood by the equal callback, the behavior is undefined.

Name	Description
`array`	Pass a reference to the CFArray object to be searched. If this parameter is not a valid reference to a CFArray object, the behavior is undefined.
`range`	Pass a structure of type `CFRange` that specifies the range of values within `array` to search. If the range location or end point (defined as the range location plus the range length minus 1) are outside the index space of the array (0 to N-1 inclusive, where N is the count of the array), the behavior is undefined. If the range length is negative, the behavior is undefined. The range may be empty (length 0).. The search progresses from the smallest index defined by the range to the largest.
`value`	Pass the value for which to find a match in `array`. The `equal` callback provided when the array was created is used to compare values. If the `equal` callback was `NULL`, pointer equality (with the C operator `==`) is used. If `value`, or any of the values in the array, are not understood by the `equal` callback, the behavior is undefined.

Result: The lowest index of the matching values in the specified range of array, or -1 if no value in the range matched the given value.

CFArrayGetLastIndexOfValue

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

Searches the array for the value.

Parameters

Name Description

array Pass a reference to the CFArray object to be searched. If this parameter is not a valid reference to a CFArray object, the behavior is undefined.

range Pass a structure of type CFRange that specifies the range of values within array to search. If the range location or end point (defined as the range location plus the range length minus 1) are outside the index space of the array (0 to N-1 inclusive, where N is the count of the array), the behavior is undefined. If the range length is negative, the behavior is undefined. The range may be empty (length 0). The search progresses from the largest index defined by the range to the smallest.

value Pass the value for which to find a match in array. The equal callback provided when the array was created is used to compare values. If the equal callback was NULL, pointer equality (with the C operator ==) is used. If value, or any of the values in the array, are not understood by the equal callback, the behavior is undefined.

Name	Description
`array`	Pass a reference to the CFArray object to be searched. If this parameter is not a valid reference to a CFArray object, the behavior is undefined.
`range`	Pass a structure of type `CFRange` that specifies the range of values within `array` to search. If the range location or end point (defined as the range location plus the range length minus 1) are outside the index space of the array (0 to N-1 inclusive, where N is the count of the array), the behavior is undefined. If the range length is negative, the behavior is undefined. The range may be empty (length 0). The search progresses from the largest index defined by the range to the smallest.
`value`	Pass the value for which to find a match in `array`. The `equal` callback provided when the array was created is used to compare values. If the `equal` callback was `NULL`, pointer equality (with the C operator `==`) is used. If `value`, or any of the values in the array, are not understood by the `equal` callback, the behavior is undefined.

Result: The highest index of the matching values in the specified range of array, or -1 if no array value in the range matched the given value.

CFArrayGetTypeID

CFTypeID CFArrayGetTypeID(void);

Obtains the type identifier of all CFArray objects.

CFArrayGetValueAtIndex

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

Retrieves the value at a specified index in a CFArray object.

Parameters

Name Description

array Pass a reference to the CFArray to be queried. If this parameter is not a valid reference to a CFArray object, the behavior is undefined.

idx Pass an integer identifying the index of the value to retrieve. If the index is outside the index space of the array (0 to N-1 inclusive, where N is the count of the array), the behavior is undefined.

Name	Description
`array`	Pass a reference to the CFArray to be queried. If this parameter is not a valid reference to a CFArray object, the behavior is undefined.
`idx`	Pass an integer identifying the index of the value to retrieve. If the index is outside the index space of the array (0 to N-1 inclusive, where N is the count of the array), the behavior is undefined.

Result: The value with the specified index in the array.

CFArrayGetValues

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

Fills a user-supplied buffer with values from the array.

Parameters

Name Description

array Pass a reference to the CFArray to be queried. If this parameter is not a valid reference to a CFArray object, the behavior is undefined.

range Pass a structure of type CFRange that specifies the range of values within the array to retrieve. If the range location or end point (defined as the range location plus the range length minus 1) are outside the index space of the array (0 to N-1 inclusive, where N is the count of the array), the behavior is undefined. If the range length is negative, the behavior is undefined. The range may be empty (length 0), in which case no values are put into the buffer.

values Pass a pointer to a C array of pointer-sized values to be filled with values from the CFArray object. The values in the C array are in the same order in which they appear in the CFArray object. If this parameter is not a valid pointer to a C array of at least range.length pointers, the behavior is undefined.

Name	Description
`array`	Pass a reference to the CFArray to be queried. If this parameter is not a valid reference to a CFArray object, the behavior is undefined.
`range`	Pass a structure of type `CFRange` that specifies the range of values within the `array` to retrieve. If the range location or end point (defined as the range location plus the range length minus 1) are outside the index space of the array (0 to N-1 inclusive, where N is the count of the array), the behavior is undefined. If the range length is negative, the behavior is undefined. The range may be empty (length 0), in which case no values are put into the buffer.
`values`	Pass a pointer to a C array of pointer-sized values to be filled with values from the CFArray object. The values in the C array are in the same order in which they appear in the CFArray object. If this parameter is not a valid pointer to a C array of at least `range.length` pointers, the behavior is undefined.

CFArrayInsertValueAtIndex

void CFArrayInsertValueAtIndex(CFMutableArrayRef theArray, CFIndex idx, const void * value);

Adds a value to a mutable CFArray object, assigning it the given index.

Parameters

Name Description

array Pass a reference to a mutable CFArray object to which the value is to be inserted. If this parameter is not a valid reference to a mutable CFArray object, the behavior is undefined. If the object is a fixed-capacity array and it is full before this operation, the behavior is undefined.

idx The index to which to add the new value. If the index is outside the index space of the array (0 to N inclusive, where N is the count of the array before the operation), the behavior is undefined. If the index is the same as N, this function has the same effect as CFArrayAppendValue().

value Pass the value to add to array. The value is retained by the array using the retain callback provided when the array was created. If the value is not of the sort expected by the retain callback, the behavior is undefined. The value is assigned to the given index, and all values with equal and larger indices have their indexes increased by one.

Name	Description
`array`	Pass a reference to a mutable CFArray object to which the value is to be inserted. If this parameter is not a valid reference to a mutable CFArray object, the behavior is undefined. If the object is a fixed-capacity array and it is full before this operation, the behavior is undefined.
`idx`	The index to which to add the new value. If the index is outside the index space of the array (0 to N inclusive, where N is the count of the array before the operation), the behavior is undefined. If the index is the same as N, this function has the same effect as CFArrayAppendValue().
`value`	Pass the value to add to `array`. The value is retained by the array using the `retain` callback provided when the array was created. If the value is not of the sort expected by the `retain` callback, the behavior is undefined. The value is assigned to the given index, and all values with equal and larger indices have their indexes increased by one.

CFArrayRemoveAllValues

void CFArrayRemoveAllValues(CFMutableArrayRef theArray);

Removes all the values from a mutable CFArray object, making it empty.

Parameters

Name Description

array Pass a reference to a mutable CFArray object from which values are to be removed. If this parameter is not a valid reference to a mutable CFArray object, the behavior is undefined.

Name	Description
`array`	Pass a reference to a mutable CFArray object from which values are to be removed. If this parameter is not a valid reference to a mutable CFArray object, the behavior is undefined.

CFArrayRemoveValueAtIndex

void CFArrayRemoveValueAtIndex(CFMutableArrayRef theArray, CFIndex idx);

Removes the value at the given index in a mutable CFArray object.

Parameters

Name Description

array Pass a reference to a mutable CFArray object from which the value is to be removed. If this parameter is not a valid reference to a mutable CFArray object, the behavior is undefined.

idx Pass the index identifying the value to remove from the CFArray object. If the index is outside the index space of the array (0 to N-1 inclusive, where N is the count of the array before the operation), the behavior is undefined.

Name	Description
`array`	Pass a reference to a mutable CFArray object from which the value is to be removed. If this parameter is not a valid reference to a mutable CFArray object, the behavior is undefined.
`idx`	Pass the index identifying the value to remove from the CFArray object. If the index is outside the index space of the array (0 to `N`-1 inclusive, where `N` is the count of the array before the operation), the behavior is undefined.

CFArrayReplaceValues

void CFArrayReplaceValues(CFMutableArrayRef theArray, CFRange range, const void ** newValues, CFIndex newCount);

Replaces a range of values in a mutable CFArray object.

Parameters

Name Description

array Pass a reference to a mutable CFArray object in which values are to be replaced. If this parameter is not a valid reference to a mutable CFArray object, the behavior is undefined

range Pass a structure of type CFRange that specifies the range of values within array to replace. If the range location or end point (defined as the range location plus the range length minus 1) are outside the index space of the array (0 to N-1 inclusive, where N is the count of the array), the behavior is undefined. If the range length is negative, the behavior is undefined. The range may be empty (length 0), in which case the new values are merely inserted at the range location.

newValues Pass a pointer to a C array containing the pointer-sized values to be put into the array. The order of the values in the C array is the same order in which they are put into the CFArray object. This parameter may be NULL if the newCount parameter is 0. The C array is not changed or freed by this function. If this parameter is not a valid pointer to a C array of at least newCount pointers, the behavior is undefined.

newCount Pass the number of values to copy from the newValues C array into the CFArray object. If this parameter is different than the range length, the values in excess of newCount are inserted after the range, or the excess range values will be deleted. This parameter may be 0, in which case no new values are replaced into the array and the values in the range are simply removed. If this parameter is negative, or greater than the number of values actually in the newValues C array, the behavior is undefined.

Name	Description
`array`	Pass a reference to a mutable CFArray object in which values are to be replaced. If this parameter is not a valid reference to a mutable CFArray object, the behavior is undefined
`range`	Pass a structure of type `CFRange` that specifies the range of values within `array` to replace. If the range location or end point (defined as the range location plus the range length minus 1) are outside the index space of the array (0 to N-1 inclusive, where N is the count of the array), the behavior is undefined. If the range length is negative, the behavior is undefined. The range may be empty (length 0), in which case the new values are merely inserted at the range location.
`newValues`	Pass a pointer to a C array containing the pointer-sized values to be put into the array. The order of the values in the C array is the same order in which they are put into the CFArray object. This parameter may be `NULL` if the `newCount` parameter is 0. The C array is not changed or freed by this function. If this parameter is not a valid pointer to a C array of at least `newCount` pointers, the behavior is undefined.
`newCount`	Pass the number of values to copy from the `newValues` C array into the CFArray object. If this parameter is different than the range length, the values in excess of `newCount` are inserted after the range, or the excess range values will be deleted. This parameter may be 0, in which case no new values are replaced into the array and the values in the range are simply removed. If this parameter is negative, or greater than the number of values actually in the `newValues` C array, the behavior is undefined.

CFArraySetValueAtIndex

void CFArraySetValueAtIndex(CFMutableArrayRef theArray, CFIndex idx, const void * value);

Changes a value at a given index in a CFArray object.

Parameters

Name Description

array Pass a reference to a mutable CFArray object in which the value is to be set. If this parameter is not a valid reference to a mutable CFArray object, the behavior is undefined. If the object is a fixed-capacity array and it is full before this operation, and the index is the same as idx, the behavior is undefined.

idx The index to which to set the new value to. If the index is outside the index space of the array (0 to N inclusive, where N is the count of the array before the operation), the behavior is undefined. If the index is the same as N, this function has the same effect as the CFArrayAppendValue function.

value Pass the value to set in the array. The value is retained by the array using the retain callback provided when the array was created, and the previous value with that index is released. If the value is not of the sort expected by the retain callback, the behavior is undefined. The indices of other values are not affected.

Name	Description
`array`	Pass a reference to a mutable CFArray object in which the value is to be set. If this parameter is not a valid reference to a mutable CFArray object, the behavior is undefined. If the object is a fixed-capacity array and it is full before this operation, and the index is the same as `idx`, the behavior is undefined.
`idx`	The index to which to set the new value to. If the index is outside the index space of the array (0 to `N` inclusive, where `N` is the count of the array before the operation), the behavior is undefined. If the index is the same as `N`, this function has the same effect as the `CFArrayAppendValue` function.
`value`	Pass the value to set in the array. The value is retained by the array using the `retain` callback provided when the array was created, and the previous value with that index is released. If the value is not of the sort expected by the `retain` callback, the behavior is undefined. The indices of other values are not affected.

CFArraySortValues

void CFArraySortValues(CFMutableArrayRef theArray, CFRange range, CFComparatorFunction comparator, void * context);

Sorts the values in a mutable CFArray object using the given comparison function.

Parameters

Name Description

array Pass a reference to a mutable CFArray object to be sorted. If this parameter is not a valid reference to a mutable CFArray object, the behavior is undefined

range Pass a structure of type CFRange that specifies the range of values within array to sort. If the range location or end point (defined as the range location plus the range length minus 1) are outside the index space of the array (0 to N-1 inclusive, where N is the count of the array), the behavior is undefined. If the range length is negative, the behavior is undefined. The range may be empty (length 0).

comparator Pass a pointer to a function conforming to the signature of the comparator function type CFComparatorFunction. This function is used in the sort operation to compare values in the array. If this parameter is not a pointer to a function of the correct prototype, the the behavior is undefined. If there are values in the array which the comparator function does not expect or cannot properly compare, the behavior is undefined. The values in the range are sorted from least to greatest according to this function.

context A pointer-sized user-defined value, which is passed as the third parameter to the comparator function, but is otherwise unused by this function. If the context is not what is expected by the comparator function, the behavior is undefined.