CFDictionaryCreate

Header: CFDictionary.h Carbon status: Supported

Creates a new immutable dictionary with the given values.

CFDictionaryRef CFDictionaryCreate (
    CFAllocatorRef allocator, 
    void **keys, 
    void **values, 
    CFIndex numValues, 
    const CFDictionaryKeyCallBacks *keyCallBacks, 
    const CFDictionaryValueCallBacks *valueCallBacks
);
Parameter descriptions
allocator

The CFAllocator which should be used to allocate memory for the dictionary and its storage for values. This parameter may be NULL in which case the current default CFAllocator is used. If this reference is not a valid CFAllocator, the behavior is undefined.

keys

A C array of the pointer-sized keys to be used for the parallel C array of values to be put into the dictionary. This parameter may be NULL if the numValues parameter is 0. This C array is not changed or freed by this function. If this parameter is not a valid pointer to a C array of at least numValues pointers, the behavior is undefined.

values

A C array of the pointer-sized values to be in the dictionary. This parameter may be NULL if the numValues parameter is 0. This C array is not changed or freed by this function. If this parameter is not a valid pointer to a C array of at least numValues pointers, the behavior is undefined.

numValues

The number of values to copy from the keys and values C arrays into the CFDictionary. This number will be 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

A pointer to a CFDictionaryKeyCallBacks structure initialized with the callbacks for the dictionary to use on each key in the dictionary. The retain callback will be used within this function, for example, to retain all of the new keys from the keys C array. A copy of the contents of the callbacks structure is made, 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 field may be NULL, in which case the CFDictionary will do nothing to add a retain to the keys of the contained values. The release field may be NULL, in which case the CFDictionary will do nothing to remove the dictionary's 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 dictionary will create a simple description for a key. If the equal field is NULL, the dictionary will use pointer equality to test for equality of keys. If the hash field is NULL, a key will be converted from a pointer to an integer to compute the hash code. This callbacks parameter itself may be NULL, which is treated as if a valid structure of version 0 with all fields 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 callbacks 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 used is undefined.

valueCallBacks

A pointer to a CFDictionaryValueCallBacks structure initialized with the callbacks for the dictionary to use on each value in the dictionary. The retain callback will be used within this function, for example, to retain all of the new values from the values C array. A copy of the contents of the callbacks structure is made, 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 field may be NULL, in which case the CFDictionary will do nothing to add a retain to values as they are put into the dictionary. The release field may be NULL, in which case the CFDictionary will do nothing to remove the dictionary's 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 dictionary will create a simple description for a value. If the equal field is NULL, the dictionary will use pointer equality to test for equality of values. This callbacks parameter itself may be NULL, which is treated as if a valid structure of version 0 with all fields 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 callbacks 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 used is undefined.

function result

A reference to the new immutable CFDictionary.

AVAILABILITY

Supported in Carbon. Available in Carbon 1.0.2 and later.


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