CFArrayBSearchValues

Header: CFArray.h Carbon status: Supported

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

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

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

range

The range within the array to search. If the range location or end point (defined by the location plus 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

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

comparator

The function with the comparator function type signature which 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.

function result

The return value is either 1) the index of a value that matched, if the target value matches one or more in the range, 2) greater than or equal to the end point of the range, if the value is greater than all the values in the range, or 3) 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.

AVAILABILITY

Supported in Carbon. Available in Carbon 1.0.2 and later.


© 2000 Apple Computer, Inc. (Last Updated 6/30/2000)