Contents

CFDictionary

Declaration

class 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

Examining a dictionary

Applying a function to a dictionary

Getting the CFDictionary type ID

Callbacks

Data Types

Constants

See Also

Related Documentation

  • Property List Programming Topics for Core Foundation
  • Collections Programming Topics for Core Foundation

Opaque Types