void CFDictionaryAddValue(CFMutableDictionaryRef dict, const void * key, const void * value);
Adds the key-value pair to a mutable CFDictionary object if no such key already exists in the object.
Name Description dict Pass a reference to the CFDictionary object to which the value is to be added. If this parameter is not a valid reference to a mutable CFDictionary object, the behavior is undefined. If the object is a fixed-capacity dictionary and it is full before this operation, the behavior is undefined. key Pass the key of the value to add to the dictionary dict. The dictonary retains the key using the retain callback provided when the dictionary was created. If the key is not of the type expected by the retain callback, the behavior is undefined. If there is an identical key already in the dictionary, this function does nothing.. value Pass value to add to the dictionary dict. The dictionary retains the value using the retain callback provided when the dictionary was created. If the value is not of the type expected by the retain callback, the behavior is undefined.
void CFDictionaryApplyFunction(CFDictionaryRef dict, CFDictionaryApplierFunction applier, void * context);
Calls a function once for each value in a CFDictionary object.
Name Description dict Pass a reference to the CFDictionary object to be queried. If this parameter is not a valid reference to a CFDictionary object, the behavior is undefined. applier Pass a pointer to the callback function to call once for each value in the dictionary dict. If this parameter is not a pointer to a function of type CFDictionaryApplierFunction, the behavior is undefined. If there are keys or values which the applier function does not expect or cannot properly apply behavior to, the behavior of CFDictionaryApplyFunction is undefined. context Pass a pointer-sized user-defined value, which is passed as the third 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.
Boolean CFDictionaryContainsKey(CFDictionaryRef dict, const void * key);
Reports whether the specified key is in the dictionary.
Result: TRUE if the key is in the CFDictionary object, otherwise FALSE.
Name Description dict Pass a reference to the CFDictionary object to be queried. If this parameter is not a valid reference to a CFDictionary object, the behavior is undefined. key Pass the key for which to find matches in the dictionary. The hash and equal key callbacks provided when the CFDictionary object was created are used to compute matches. If the hash key callback is NULL, the key is treated as a pointer and converted to an integer. If the equal key callback is NULL, pointer equality is used. If key or any of the keys in dict are not understood by the equal callback, the behavior is undefined.
Boolean CFDictionaryContainsValue(CFDictionaryRef dict, const void * value);
Reports whether a value is in the CFDictionary object.
Result: TRUE if the value is in the dictionary, otherwise FALSE.
Name Description dict Pass a reference to the CFDictionary object to be queried. If this parameter is not a valid reference to a CFDictionary object, the behavior is undefined. value Pass the value for which to find matches in the dictionary. The equal callback provided when the CFDictionary object was created are used to compare. If the equal key callback is NULL, pointer equality is used. If value or any of the values in dict are not understood by the equal callback, the behavior is undefined.
CFDictionaryRef CFDictionaryCreate(CFAllocatorRef allocator, const void ** keys, const void ** values, CFIndex numValues, const CFDictionaryKeyCallBacks * keyCallBacks, const CFDictionaryValueCallBacks * valueCallBacks);
Creates an immutable CFDictionary object containing the provided keys and values.
Result: A reference to an immutable CFDictionary object or NULL if there was a problem creating the object.
Name Description allocator Pass a reference to a CFAllocator object used to allocate memory for the created CFDictionary 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. keys Pass a pointer to a C array containing pointer-sized keys to put into the created CFDictionary object. The keys in this C array (and in the CFDictionary object) are positionally paired with the items in the values array. This C array is not changed or freed by this function. This parameter may be NULL if the numValues parameter is 0. If this parameter is not a valid pointer to a C array of at least numValues pointers, the behavior is undefined. values Pass a pointer to a C array containing pointer-sized values to put into the created CFDictionary object. The values in this C array (and in the CFDictionary object) are positionally paired with the items in the keys array. This C array is not changed or freed by this function. This parameter may be NULL if the numValues parameter is 0. 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 keys and values C arrays into the CFDictionary object. This number is the count of the dictionary. If this parameter is negative, or greater than the number of values actually in the keys or values C arrays, the behavior is undefined. keyCallBacks Pass a pointer to a structure of type CFDictionaryKeyCallBacks that is initialized with the callbacks for the CFDictionary object to use on each of its keys. The retain callback is used within this function, for example, to retain all of the new keys from the keys C array. The 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 dictionary creations. If the version field of this callbacks structure is not one of the defined ones for CFDictionary, the behavior is undefined. The retain member may be initialized with NULL, in which case the CFDictionary object does nothing to the keys of the contained values. The release field may be initialized to NULL, in which case the CFDictionary object does nothing to reverse the dictionary's retain callback (if any) on the keys when the dictionary is destroyed or a key-value pair is removed. If the copyDescription field is NULL, the CFDictionary object creates a simple description for a key. If the equal field is NULL, the dictionary uses pointer equality to test for equality of keys. If the hash field is NULL, a key is converted from a pointer to an integer to compute the hash code. If this callback parameter itself is NULL, the function behaves as if a valid CFDictionaryKeyCallBacks structure initialized with version 0 and with all function-pointer fields set to 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 CFDictionaryKeyCallBacks structure, the behavior is undefined. If any of the keys put into the dictionary is not one understood by any callback function, the behavior when that callback function is used is undefined. valueCallBacks Pass a pointer to a CFDictionaryValueCallBacks structure initialized with the callbacks for the created CFDictionary object to use on each of its values. The 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 dictionary creations. If the version field of this callbacks structure is not one of the defined ones for CFDictionary, the behavior is undefined. The retain member may be initialized with NULL, in which case the CFDictionary object does nothing to added values. The release field may be initialized to NULL, in which case the CFDictionary object does nothing to reverse the dictionary's retain callback (if any) on the values when the dictionary is destroyed or a key-value pair is removed. If the copyDescription field is NULL, the CFDictionary object creates a simple description for a value. If the equal field is NULL, the dictionary uses pointer equality to test for equality of values. If this callback parameter itself is NULL, the function behaves as if a valid CFDictionaryValueCallBacks structure initialized with version 0 and with all function-pointer fields set to 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 CFDictionaryValueCallBacks structure, the behavior is undefined. If any value put into the dictionary is not one understood by any of the callback functions, the behavior when that callback function is used is undefined.
CFDictionaryRef CFDictionaryCreateCopy(CFAllocatorRef allocator, CFDictionaryRef dict);
Creates an immutable CFDictionary object with the key-value pairs from another CFDictionary object.
Result: A reference to the new immutable CFDictionary object or NULL if there was a problem creating the object.
Name Description allocator Pass the CFAllocator object used which to allocate memory for the created CFDictionary and for its storage of 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. dict Pass a reference to the CFDictionary object to be copied. The keys and values from this source CFDictionary object are copied as pointers into the new CFDictionary object (that is, the values themselves are copied, not that which the values point to, if anything). However, the new CFDictionary object also retains the keys and values using the retain function of the source CFDictionary object. The count of the new CFDictionary object is the same as the source CFDictionary object. The new CFDictionary object uses the same callbacks as the source dictionary. If this parameter is not a valid reference to a CFDictionary object, the behavior is undefined.
CFMutableDictionaryRef CFDictionaryCreateMutable(CFAllocatorRef allocator, CFIndex capacity, const CFDictionaryKeyCallBacks * keyCallBacks, const CFDictionaryValueCallBacks * valueCallBacks);
Creates a mutable CFDictionary object.
Result: A reference to the new mutable CFDictionary object or NULL if there was a problem creating the object.
Name Description allocator Pass a reference to the CFAllocator object used to allocate memory for the dictionary and for its storage of 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 an integer specifying the maximum number of values that can be contained by the CFDictionary object. The object starts empty, and can grow to capacity number of values (and it can have less). If this parameter is 0, the dictionary'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. keyCallBacks Pass a pointer to a CFDictionaryKeyCallBacks structure initialized with the callbacks for dictionary to use on each of its keys. The 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 CFDictionary creations. If the version field of this callbacks structure is not one of the defined ones for CFDictionary, the behavior is undefined. The retain field may be NULL, in which case the CFDictionary object does nothing to retain the keys of the contained values. The release field may be NULL, in which case the CFDictionary object does nothing to reverse the effects of retain (if any) on the keys when the dictionary is destroyed or a key-value pair is removed. If the copyDescription field is NULL, the CFDictionary object creates a simple description for a key. If the equal field is NULL, the dictionary uses pointer equality to test for equality of keys. If the hash field is NULL, CFDictionary converts a key from a pointer to an integer to compute the hash code. This parameter itself may be NULL; the function treats this value as if it were a valid CFDictionaryKeyCallBacks structure with version 0 and with all function-pointer fields NULL. 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 CFDictionaryKeyCallBacks structure, the behavior is undefined. If any of the keys put into the dictionary is not one understood by one of the callback functions the behavior when that callback function is invoked is undefined. valueCallBacks Pass a pointer to a CFDictionaryValueCallBacks structure initialized with the callbacks for dictionary to use on each of its values. The 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 CFDictionary creations. If the version field of this callbacks structure is not one of the defined ones for CFDictionary, the behavior is undefined. The retain field may be NULL, in which case the CFDictionary object does nothing to retain the contained values. The release field may be NULL, in which case the CFDictionary object does nothing to reverse the effects of retain (if any) on the values when the dictionary is destroyed or a key-value pair is removed. If the copyDescription field is NULL, the CFDictionary object creates a simple description for a value. If the equal field is NULL, the dictionary uses pointer equality to test for equality of values. This parameter itself may be NULL; the function treats this value as if it were a valid CFDictionaryValueCallBacks structure with version 0 and with all function-pointer fields NULL. 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 CFDictionaryValueCallBacks structure, the behavior is undefined. If any of the values put into the dictionary is not one understood by one of the callback functions the behavior when that callback function is invoked is undefined.
CFMutableDictionaryRef CFDictionaryCreateMutableCopy(CFAllocatorRef allocator, CFIndex capacity, CFDictionaryRef dict);
Creates a mutable CFDictionary object with the key-value pairs from another CFDictionary object.
Result: A reference to the new mutable CFDictionary object or NULL if there was a problem creating the object.
Name Description allocator Pass a reference to the CFAllocator object used to allocate memory for the dictionary and for its storage of 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 an integer specifying the maximum number of values that can be contained by the CFDictionary object. The object starts empty, and can grow to capacity number of values (and it can have less). If this parameter is 0, the dictionary'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. dict Pass a reference to the CFDictionary object to be copied. The keys and values from this source CFDictionary object are copied as pointers into the new CFDictionary object (that is, the values themselves are copied, not that which the values point to, if anything). However, the new CFDictionary object also retains the keys and values using the retain function of the source CFDictionary object. The count of the new CFDictionary object is the same as the source CFDictionary object. The new CFDictionary object uses the same callbacks as the source dictionary. If this parameter is not a valid reference to a CFDictionary object, the behavior is undefined.
CFIndex CFDictionaryGetCount(CFDictionaryRef dict);
Obtains the number of values currently in the dictionary.
Result: The number of values in the dictionary.
Name Description dict Pass a reference to the CFDictionary object to be queried. If this parameter is not a valid reference to a CFDictionary object, the behavior is undefined.
CFIndex CFDictionaryGetCountOfKey(CFDictionaryRef dict, const void * key);
Obtains the number of times the specified key occurs in the dictionary.
Result: Returns 1 if a matching key is used by the CFDictionary object, 0 otherwise.
Name Description dict Pass a reference to the CFDictionary object to be queried. If this parameter is not a valid reference to a CFDictionary object, the behavior is undefined. key Pass the key for which to find matches in dict. The hash and equal key callbacks provided when the CFDictionary object was created are used to compute matches. If the hash key callback is NULL, the key is treated as a pointer and converted to an integer. If the equal key callback is NULL, pointer equality is used. If key or any of the keys in the dictionary are not understood by the equal callback, the behavior is undefined.
CFIndex CFDictionaryGetCountOfValue(CFDictionaryRef dict, const void * value);
Obtains the number of times the specified value occurs in the CFDictionary object.
Result: The number of times the specified value occurs in the CFDictionary object.
Name Description dict Pass a reference to the CFDictionary object to be queried. If this parameter is not a valid reference to a CFDictionary object, the behavior is undefined. value Pass the value for which to find matches in dict. The equal value callbacks provided when the CFDictionary object was created are used to compare values. IIf the equal key callback is NULL, pointer equality is used. If value or any of the values in the dictionary are not understood by the equal callback, the behavior is undefined.
void CFDictionaryGetKeysAndValues(CFDictionaryRef dict, void ** keys, void ** values);
Fills two user-supplied buffers with the keys and values from a CFDictionary object.
Name Description dict Pass a reference to the CFDictionary object to be queried. If this parameter is not a valid reference to a CFDictionary object, the behavior is undefined. keys Pass a pointer to a C array of pointer-sized values, Upon return, keys is filled with keys from the dictionary dict. When filled, the keys and values C arrays are parallel to each other; that is, the items at the same indices form a key-value pair from the dictionary. If this parameter is not a valid pointer to a C array of at least CFDictionaryGetCount pointers, the behavior is undefined. values Pass a pointer to a C array of pointer-sized values. Upon return, values is filled with values from the dictionary. When filled, the keys and values C arrays are parallel to each other; that is, the items at the same indices form a key-value pair from the dictionary. If this parameter is not a valid pointer to a C array of at least CFDictionaryGetCount pointers, the behavior is undefined.
CFTypeID CFDictionaryGetTypeID(void);
Obtains the type identifier for all CFDictionary objects.
_C( void *) CFDictionaryGetValue(CFDictionaryRef dict, const void * key);
Retrieves the value associated with the specified key from a CFDictionary object.
Result: The value paired with the specified key in the CFDictionary or NULL if no key-value pair with a matching key exists. Because NULL can be a valid value in some dictionaries, use the function CFDictionaryGetValueIfPresent to determine whether NULL is the value or NULL means "not found.".
Name Description dict Pass a reference to the CFDictionary object to be queried. If this parameter is not a valid reference to a CFDictionary object, the behavior is undefined. key Pass the key for which to find a match in the dictionary. The hash and equal key callbacks provided when the CFDictionary object was created are used to compute matches. If the hash key callback is NULL, the key is treated as a pointer and converted to an integer. If the equal key callback is NULL, pointer equality is used. If key or any of the keys in dict are not understood by the equal callback, the behavior is undefined.
Boolean CFDictionaryGetValueIfPresent(CFDictionaryRef dict, const void * key, void ** value);
Retrieves the value associated with a specified key if it exists in a CFDictionary object.
Result: TRUE if a matching key was found, FALSE otherwise.
Name Description dict Pass a reference to the CFDictionary object to be queried. If this parameter is not a valid reference to a CFDictionary object, the behavior is undefined. key Pass the key for which to find a match in the dictionary. The hash and equal key callbacks provided when the CFDictionary object was created are used to compute matches. If the hash key callback is NULL, the key is treated as a pointer and converted to an integer. If the equal key callback is NULL, pointer equality is used. If key or any of the keys in dict are not understood by the equal callback, the behavior is undefined. value Pass an untyped pointer to memory. Upon return, value is filled with the pointer-sized value if a matching key is found in dict. If no matching key is found, the contents of the storage pointed to by this parameter are undefined. This parameter may be NULL, in which case the value from the dictionary is not returned (but the return value of this function still indicates whether the key-value pair was present in dict).
void CFDictionaryRemoveAllValues(CFMutableDictionaryRef dict);
Removes all key-values paris from a mutable CFDictionary object, making it empty.
Name Description dict Pass a reference to the CFDictionary object in which the value is to be set. If this parameter is not a valid reference to a mutable CFDictionary object, the behavior is undefined.
void CFDictionaryRemoveValue(CFMutableDictionaryRef dict, const void * key);
Removes a key-value pair, specified by key, from a mutable CFDictionary object.
Name Description dict Pass a reference to the CFDictionary object in which the value is to be set. If this parameter is not a valid reference to a mutable CFDictionary object, the behavior is undefined. key Pass the key of the value to remove from the dictionary dict. If a key matching the specified key is present in the dictionary, the key-value pair is removed from the dictionary; otherwise, this function does nothing.
void CFDictionaryReplaceValue(CFMutableDictionaryRef dict, const void * key, const void * value);
Replaces the value paired with a specified key in a mutable CFDictionary object.
Name Description dict Pass a reference to the CFDictionary object in which the value is to be set. If this parameter is not a valid reference to a mutable CFDictionary object, the behavior is undefined. key Pass the key of the value to replace in the dictionary dict. If a key which matches this key is present in the dictionary, the value is changed to the given value; otherwise, this function does nothing. value Pass value to replace another value in the dictionary dict. The value is retained by the dictionary using the retain callback provided when the dictionary was created, and the previous value is released. If the value is not of the type expected by the retain or release callbacks, the behavior is undefined.
void CFDictionarySetValue(CFMutableDictionaryRef dict, const void * key, const void * value);
Sets the value of the specified key in a mutable CFDictionary object.
Name Description dict Pass a reference to the CFDictionary object in which the value is to be set. If this parameter is not a valid reference to a mutable CFDictionary object, the behavior is undefined. If the object is a fixed-capacity dictionary and it is full before this operation, and the key does not exist in the dictionary, the behavior is undefined. key Pass the key of the value to set in the dictionary dict. If a key which matches this key is already present in the dictionary, only the value is changed. If no key in the dictionary matches the specified key, the key-value pair is added to the dictionary. If the key is added, the CFDictionary object retains it using the retain callback provided when the object was created. If the key is not of the type expected by the key retain callback, the behavior is undefined. value Pass the value to add to or replace another value in the dictionary dict. The dictionary retains the value using the retain callback provided when the dictionary was created, and the previous value if any is released. If the value is not of the type expected by the retain or release callbacks, the behavior is undefined.
© 1999 Apple Computer, Inc. (Last Updated 9/17/99)