Searching Collections
Core Foundation includes several programming interfaces for
finding values (and, in the case of CFDictionary, keys) in collection
objects. The CF
TypeGetValueIfPresent
functions, described
in Getting the Values of Collections, report on the existence
of values in dictionaries, sets, and bags. You can also use functions
with “Contains” in their names to determine whether a collection
holds a value or key. Listing 1 illustrates how the CFDictionaryContainsKey
function
might be used.
Listing 1 Searching a CFDictionary object for a key
if (CFDictionaryContainsKey(mappingTable, (const void*)lowerCharsetName)) { |
result = (CFStringEncoding)CFDictionaryGetValue(mappingTable, (const void*)lowerCharsetName); |
} |
For CFArray objects, the CFArrayBSearchValues
function
offers a more sophisticated search option. This function searches
for a specified value in a sorted array using a binary search algorithm.
If the value doesn’t exist in the collection, the function tells
you where it should go; the CFArrayBSearchValues
function
thus helps you to keep a sorted mutable array sorted. Listing 2 shows
how this function might be called.
Listing 2 Searching for a value in a CFArray object
CFIndex position = CFArrayBSearchValues(aMutArray, CFRangeMake(0,CFArrayGetCount(anArray)), (const void *)CFSTR("String Three"), CFStringCompare, 0); |
The fourth parameter of the CFArrayBSearchValues
function
must be a pointer to a function that conforms to the CFComparatorFunction
type.
This comparator function is supposed to know how to compare values
in the array. In the given example CFStringCompare
is
used because it conforms to CFComparatorFunction
and
it knows how to compare CFString values. There are other predefined
Core Foundation comparator functions that you can use, such as CFNumberCompare
and CFDateCompare
.
Upon return of the above call, the function’s CFIndex
result
can indicate one of the following:
If the value exists, its index in the array
An index greater than or equal to the end point of the range if the specified value is greater than all the values in the rangeThe index of the value greater than the specified value if the value lies between two of (or less than all of) the values in the range.
You can use the CFArrayContainsValue
to
determine whether the result is the first of the listed alternatives.
The CFTree type defines a different group of functions for locating contained values (that is, subtrees). See Creating and Copying Collections for more information.
Copyright © 2011 Apple Inc. All Rights Reserved. Terms of Use | Privacy Policy | Updated: 2011-01-18