CFDictionary

Overview

CFDictionary and its derived mutable type, CFMutableDictionary, manage associations of key-value pairs. CFDictionary creates static dictionaries where you set the key-value pairs when first creating a dictionary and cannot modify them afterward; CFMutableDictionary creates dynamic dictionaries where you can add or delete key-value pairs at any time, and the dictionary automatically allocates memory as needed.

A key-value pair within a dictionary is called an entry. Each entry consists of one object that represents the key and a second object that is that key’s value. Within a dictionary, the keys are unique. That is, no two keys in a single dictionary are equal (as determined by the equal callback). Internally, a dictionary uses a hash table to organize its storage and to provide rapid access to a value given the corresponding key.

Keys for a CFDictionary may be of any C type, however note that if you want to convert a CFPropertyList to XML, any dictionary’s keys must be CFString objects.

You create static dictionaries using either the CFDictionaryCreate or CFDictionaryCreateCopy function. Key-value pairs are passed as parameters to CFDictionaryCreate. When adding key-value pairs to a dictionary, the keys and values are not copied—they are retained so they are not invalidated before the dictionary is deallocated.

CFDictionary provides functions for querying the values of a dictionary. The function CFDictionaryGetCount returns the number of key-value pairs in a dictionary; the CFDictionaryContainsValue function checks if a value is in a dictionary; and CFDictionaryGetKeysAndValues returns a C array containing all the values and a C array containing all the keys in a dictionary.

The CFDictionaryApplyFunction function lets you apply a function to all key-value pairs in a dictionary.

CFDictionary is “toll-free bridged” with its Cocoa Foundation counterpart, NSDictionary. 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 NSDictionary * parameter, you can pass in a CFDictionaryRef, and in a function where you see a CFDictionaryRef parameter, you can pass in an NSDictionary instance. This also applies to concrete subclasses of NSDictionary. See Toll-Free Bridged Types for more information on toll-free bridging.

Topics

Creating a dictionary

CFDictionaryCreate

Creates an immutable dictionary containing the specified key-value pairs.

CFDictionaryCreateCopy

Creates and returns a new immutable dictionary with the key-value pairs of another dictionary.

Examining a dictionary

CFDictionaryContainsKey

Returns a Boolean value that indicates whether a given key is in a dictionary.

CFDictionaryContainsValue

Returns a Boolean value that indicates whether a given value is in a dictionary.

CFDictionaryGetCount

Returns the number of key-value pairs in a dictionary.

CFDictionaryGetCountOfKey

Returns the number of times a key occurs in a dictionary.

CFDictionaryGetCountOfValue

Counts the number of times a given value occurs in the dictionary.

CFDictionaryGetKeysAndValues

Fills two buffers with the keys and values from a dictionary.

CFDictionaryGetValue

Returns the value associated with a given key.

CFDictionaryGetValueIfPresent

Returns a Boolean value that indicates whether a given value for a given key is in a dictionary, and returns that value indirectly if it exists.

Applying a function to a dictionary

CFDictionaryApplyFunction

Calls a function once for each key-value pair in a dictionary.

Getting the CFDictionary type ID

CFDictionaryGetTypeID

Returns the type identifier for the CFDictionary opaque type.

Callbacks

CFDictionaryApplierFunction

Prototype of a callback function that may be applied to every key-value pair in a dictionary.

CFDictionaryCopyDescriptionCallBack

Prototype of a callback function used to get a description of a value or key in a dictionary.

CFDictionaryEqualCallBack

Prototype of a callback function used to determine if two values or keys in a dictionary are equal.

CFDictionaryHashCallBack

Prototype of a callback function invoked to compute a hash code for a key. Hash codes are used when key-value pairs are accessed, added, or removed from a collection.

CFDictionaryReleaseCallBack

Prototype of a callback function used to release a key-value pair before it’s removed from a dictionary.

CFDictionaryRetainCallBack

Prototype of a callback function used to retain a value or key being added to a dictionary.

Data Types

CFDictionaryKeyCallBacks

This structure contains the callbacks used to retain, release, describe, and compare the keys in a dictionary.

CFDictionaryRef

A reference to an immutable dictionary object.

CFDictionaryValueCallBacks

This structure contains the callbacks used to retain, release, describe, and compare the values in a dictionary.

Constants

Predefined Callback Structures

CFDictionary provides some predefined callbacks for your convenience.

See Also

Opaque Types

CFFileDescriptor

The CFFileDescriptor provides an opaque type to monitor file descriptors for read and write activity via CFRunLoop.

CFStringTokenizer

CFStringTokenizer allows you to tokenize strings into words, sentences or paragraphs in a language-neutral way. It supports languages such as Japanese and Chinese that do not delimit words by spaces, as well as de-compounding German compounds. You can obtain Latin transcription for tokens. It also provides language identification API.