Mac Developer Library

Developer

OSDictionary Class Reference

Options
Deployment Target:

On This Page
Language:

OSDictionary

OSDictionary provides an associative store using strings for keys. More...

Inheritance


Not Applicable

Conforms To


Not Applicable

Import Statement


Not Applicable @import Kernel;

Availability


Available in OS X v10.0 and later.
  • Creates a deep copy of the dictionary and its child collections.

    Declaration

    C++

    OSCollection * copyCollection( OSDictionary *cycleDict = 0);

    Parameters

    cycleDict

    A dictionary of all of the collections that have been copied so far, which is used to track circular references. To start the copy at the top level, pass NULL.

    Return Value

    The newly copied dictionary, with a retain count of 1, or NULL if there is insufficient memory to do the copy.

    Discussion

    The receiving dictionary, and any collections it contains, recursively, are copied. Objects that are not derived from OSCollection are retained rather than copied.

    Import Statement

  • Ensures the dictionary has enough space to store the requested number of key/object pairs.

    Declaration

    C++

    virtual unsigned int ensureCapacity( unsigned intnewCapacity);

    Parameters

    newCapacity

    The total number of key/object pairs the dictionary should be able to store.

    Return Value

    The new capacity of the dictionary, which may be different from the number requested (if smaller, reallocation of storage failed).

    Discussion

    This function immediately resizes the dictionary, if necessary, to accommodate at least newCapacity key/object pairs. If newCapacity is not greater than the current capacity, or if an allocation error occurs, the original capacity is returned.

    There is no way to reduce the capacity of an OSDictionary.

    Import Statement

  • Removes and releases all keys and objects within the dictionary.

    Declaration

    C++

    virtual void flushCollection();

    Discussion

    The dictionary's capacity (and therefore direct memory consumption) is not reduced by this function.

    Import Statement

  • Deallocates or releases any resources used by the OSDictionary instance.

    Declaration

    C++

    virtual void free();

    Discussion

    This function should not be called directly, use release instead.

    Import Statement

  • Returns the number of objects the dictionary can store without reallocating.

    Declaration

    C++

    virtual unsigned int getCapacity() const;

    Return Value

    The number objects the dictionary can store without reallocating.

    Discussion

    OSDictionary objects grow when full to accommodate additional key/object pairs. See getCapacityIncrement and ensureCapacity.

    Import Statement

  • Returns the storage increment of the dictionary.

    Declaration

    C++

    virtual unsigned int getCapacityIncrement() const;

    Return Value

    The storage increment of the dictionary.

    Discussion

    An OSDictionary allocates storage for key/object pairs in multiples of the capacity increment.

    Import Statement

  • Returns the current number of key/object pairs contained within the dictionary.

    Declaration

    C++

    virtual unsigned int getCount() const;

    Return Value

    The current number of key/object pairs contained within the dictionary.

    Import Statement

  • Returns the object stored under a given key.

    Declaration

    C++

    virtual OSObject * getObject( const char *aKey) const;

    Parameters

    aKey

    A C string key identifying the object to be returned to caller.

    Return Value

    The object stored under aKey, or NULL if the key does not exist in the dictionary.

    Discussion

    The returned object will be released if removed from the dictionary; if you plan to store the reference, you should call retain on that object.

    Import Statement

  • Returns the object stored under a given key.

    Declaration

    C++

    virtual OSObject * getObject( const OSString *aKey) const;

    Parameters

    aKey

    An OSString key identifying the object to be returned to caller.

    Return Value

    The object stored under aKey, or NULL if the key does not exist in the dictionary.

    Discussion

    The returned object will be released if removed from the dictionary; if you plan to store the reference, you should call retain on that object.

    Import Statement

  • Returns the object stored under a given key.

    Declaration

    C++

    virtual OSObject * getObject( const OSSymbol *aKey) const;

    Parameters

    aKey

    An OSSymbol key identifying the object to be returned to the caller.

    Return Value

    The object stored under aKey, or NULL if the key does not exist in the dictionary.

    Discussion

    The returned object will be released if removed from the dictionary; if you plan to store the reference, you should call retain on that object.

    Import Statement

  • Initializes a new instance of OSDictionary.

    Declaration

    C++

    virtual bool initWithCapacity( unsigned intcapacity);

    Parameters

    capacity

    The initial storage capacity of the new dictionary object.

    Return Value

    true on success, false on failure.

    Discussion

    Not for general use. Use the static instance creation method withCapacity instead.

    capacity must be nonzero. The new dictionary will grow as needed to accommodate more key/object pairs (unlike CFMutableDictionary, for which the initial capacity is a hard limit).

    Import Statement

  • Initializes a new OSDictionary with the contents of another dictionary.

    Declaration

    C++

    virtual bool initWithDictionary( const OSDictionary *dict, unsigned int capacity = 0);

    Parameters

    dict

    A dictionary whose contents will be placed in the new instance.

    capacity

    The initial storage capacity of the new dictionary object. If 0, the capacity is set to the number of key/value pairs in dict; otherwise capacity must be greater than or equal to the number of key/value pairs in dict.

    Return Value

    true on success, false on failure.

    Discussion

    Not for general use. Use the static instance creation method withDictionary instead.

    dict must be non-NULL. If capacity is nonzero, it must be greater than or equal to count. The new dictionary will grow as needed to accommodate more key/object pairs (unlike CFMutableDictionary, for which the initial capacity is a hard limit).

    The keys and objects in dict are retained for storage in the new OSDictionary, not copied.

    Import Statement

  • Initializes a new OSDictionary with keys and objects provided.

    Declaration

    C++

    virtual bool initWithObjects( const OSObject *objects[], const OSString *keys[], unsigned int count, unsigned int capacity = 0);

    Parameters

    objects

    A C array of OSMetaClassBase-derived objects.

    keys

    A C array of OSString keys for the corresponding objects in objects.

    count

    The number of keys and objects to be placed into the dictionary.

    capacity

    The initial storage capacity of the new dictionary object. If 0, count is used; otherwise this value must be greater than or equal to count.

    Return Value

    true on success, false on failure.

    Discussion

    Not for general use. Use the static instance creation method withObjects instead.

    objects and keys must be non-NULL, and count must be nonzero. If capacity is nonzero, it must be greater than or equal to count. The new dictionary will grow as needed to accommodate more key/object pairs (unlike CFMutableDictionary, for which the initial capacity is a hard limit).

    Import Statement

  • Initializes a new OSDictionary with keys and objects provided.

    Declaration

    C++

    virtual bool initWithObjects( const OSObject *objects[], const OSSymbol *keys[], unsigned int count, unsigned int capacity = 0);

    Parameters

    objects

    A C array of OSMetaClassBase-derived objects.

    keys

    A C array of OSSymbol keys for the corresponding objects in objects.

    count

    The number of keys and objects to be placed into the dictionary.

    capacity

    The initial storage capacity of the new dictionary object. If 0, count is used; otherwise this value must be greater than or equal to count.

    Return Value

    true on success, false on failure.

    Discussion

    Not for general use. Use the static instance creation method withObjects instead.

    objects and keys must be non-NULL, and count must be nonzero. If capacity is nonzero, it must be greater than or equal to count. The new dictionary will grow as neede to accommodate more key/object pairs (unlike CFMutableDictionary, for which the initial capacity is a hard limit).

    Import Statement

  • Tests the equality of an OSDictionary to an arbitrary object.

    Declaration

    C++

    virtual bool isEqualTo( const OSMetaClassBase *anObject) const;

    Parameters

    anObject

    An object to be compared against the receiver.

    Return Value

    true if the objects are equal.

    Discussion

    An OSDictionary is considered equal to another object if that object is derived from OSDictionary and contains the same or equivalent objects.

    Import Statement

  • Tests the equality of two OSDictionary objects.

    Declaration

    C++

    virtual bool isEqualTo( const OSDictionary *aDictionary) const;

    Parameters

    aDictionary

    The dictionary to be compared against the receiver.

    Return Value

    true if the dictionaries are equal, false if not.

    Discussion

    Two OSDictionary objects are considered equal if they have same count, the same keys, and if the objects stored in each under a given key compare as equal using isEqualTo.

    Import Statement

  • Tests the equality of two OSDictionary objects over a subset of keys.

    Declaration

    C++

    virtual bool isEqualTo( const OSDictionary *aDictionary, const OSCollection *keys) const;

    Parameters

    aDictionary

    The dictionary to be compared against the receiver.

    keys

    An OSArray or OSDictionary containing the keys (as OSStrings in OSString Class Reference or OSSymbols in OSSymbol Class Reference) describing the intersection for the comparison.

    Return Value

    true if the intersections of the two dictionaries are equal.

    Discussion

    Two OSDictionary objects are considered equal by this function if both have objects stored for all keys provided, and if the objects stored in each under a given key compare as equal using isEqualTo.

    Import Statement

  • Merges the contents of a dictionary into the receiver.

    Declaration

    C++

    virtual bool merge( const OSDictionary *aDictionary);

    Parameters

    aDictionary

    The dictionary whose contents are to be merged with the receiver.

    Return Value

    true if the merge succeeds, false otherwise.

    Discussion

    If there are keys in aDictionary that match keys in the receiving dictionary, then the objects in the receiver are replaced by those from aDictionary, and the replaced objects are released.

    Import Statement

  • Removes a key/object pair from the dictionary.

    Declaration

    C++

    virtual void removeObject( const char *aKey);

    Parameters

    aKey

    A C string identifying the object to be removed from the dictionary.

    Discussion

    The removed key (internally an OSSymbol) and object are automatically released.

    Import Statement

  • Removes a key/object pair from the dictionary.

    Declaration

    C++

    virtual void removeObject( const OSString *aKey);

    Parameters

    aKey

    A OSString identifying the object to be removed from the dictionary.

    Discussion

    The removed key (not necessarily aKey itself) and object are automatically released.

    Import Statement

  • Removes a key/object pair from the dictionary.

    Declaration

    C++

    virtual void removeObject( const OSSymbol *aKey);

    Parameters

    aKey

    An OSSymbol identifying the object to be removed from the dictionary.

    Discussion

    The removed key (not necessarily aKey itself) and object are automatically released.

    Import Statement

  • Archives the receiver into the provided OSSerialize object.

    Declaration

    C++

    virtual bool serialize( OSSerialize *serializer) const;

    Parameters

    serializer

    The OSSerialize object.

    Return Value

    true if serialization succeeds, false if not.

    Import Statement

  • Sets the storage increment of the dictionary.

    Declaration

    C++

    virtual unsigned int setCapacityIncrement( unsigned increment);

    Return Value

    The new storage increment of the dictionary, which may be different from the number requested.

    Discussion

    An OSDictionary allocates storage for key/object pairs in multiples of the capacity increment. Calling this function does not immediately reallocate storage.

    Import Statement

  • Stores an object in the dictionary under a key.

    Declaration

    C++

    virtual bool setObject( const char *aKey, const OSMetaClassBase *anObject);

    Parameters

    aKey

    A C string identifying the object placed within the dictionary.

    anObject

    The object to be stored in the dictionary. It is automatically retained.

    Return Value

    true if the addition was successful, false otherwise.

    Discussion

    An OSSymbol for aKey is created internally. An object already stored under aKey is released.

    Import Statement

  • Stores an object in the dictionary under a key.

    Declaration

    C++

    virtual bool setObject( const OSString *aKey, const OSMetaClassBase *anObject);

    Parameters

    aKey

    An OSString identifying the object placed within the dictionary.

    anObject

    The object to be stored in the dictionary. It is automatically retained.

    Return Value

    true if the addition was successful, false otherwise.

    Discussion

    An OSSymbol for aKey is created internally. An object already stored under aKey is released.

    Import Statement

  • Stores an object in the dictionary under a key.

    Declaration

    C++

    virtual bool setObject( const OSSymbol *aKey, const OSMetaClassBase *anObject);

    Parameters

    aKey

    An OSSymbol identifying the object placed within the dictionary. It is automatically retained.

    anObject

    The object to be stored in the dictionary. It is automatically retained.

    Return Value

    true if the addition was successful, false otherwise.

    Discussion

    An object already stored under aKey is released.

    Import Statement

  • Recursively sets option bits in the dictionary and all child collections.

    Declaration

    C++

    virtual unsigned setOptions( unsigned options, unsigned mask, void *context = 0);

    Parameters

    options

    A bitfield whose values turn the options on (1) or off (0).

    mask

    A mask indicating which bits in options to change. Pass 0 to get the whole current options bitfield without changing any settings.

    context

    Unused.

    Return Value

    The options bitfield as it was before the set operation.

    Discussion

    Kernel extensions should not call this function.

    Child collections' options are changed only if the receiving dictionary's options actually change.

    Import Statement

  • Creates and initializes an empty OSDictionary.

    Declaration

    C++

    static OSDictionary * withCapacity( unsigned intcapacity);

    Parameters

    capacity

    The initial storage capacity of the new dictionary object.

    Return Value

    An empty instance of OSDictionary with a retain count of 1; NULL on failure.

    Discussion

    capacity must be nonzero. The new dictionary will grow as needed to accommodate more key/object pairs (unlike CFMutableDictionary, for which the initial capacity is a hard limit).

    Import Statement

  • Creates and initializes an OSDictionary populated with the contents of another dictionary.

    Declaration

    C++

    static OSDictionary * withDictionary( const OSDictionary *dict, unsigned int capacity = 0);

    Parameters

    dict

    A dictionary whose contents will be stored in the new instance.

    capacity

    The initial storage capacity of the new dictionary object. If 0, the capacity is set to the number of key/value pairs in dict; otherwise capacity must be greater than or equal to the number of key/value pairs in dict.

    Return Value

    An instance of OSDictionary containing the key/value pairs of dict, with a retain count of 1; NULL on failure.

    Discussion

    dict must be non-NULL. If capacity is nonzero, it must be greater than or equal to count. The new dictionary will grow as needed to accommodate more key/object pairs (unlike CFMutableDictionary, for which the initial capacity is a hard limit).

    The keys and objects in dict are retained for storage in the new OSDictionary, not copied.

    Import Statement

  • Creates and initializes an OSDictionary populated with keys and objects provided.

    Declaration

    C++

    static OSDictionary * withObjects( const OSObject *objects[], const OSString *keys[], unsigned int count, unsigned int capacity = 0);

    Parameters

    objects

    A C array of OSMetaClassBase-derived objects.

    keys

    A C array of OSString keys for the corresponding objects in objects.

    count

    The number of keys and objects to be placed into the dictionary.

    capacity

    The initial storage capacity of the new dictionary object. If 0, count is used; otherwise this value must be greater than or equal to count.

    Return Value

    An instance of OSDictionary containing the key/object pairs provided, with a retain count of 1; NULL on failure.

    Discussion

    objects and keys must be non-NULL, and count must be nonzero. If capacity is nonzero, it must be greater than or equal to count. The new dictionary will grow as needed to accommodate more key/object pairs (unlike CFMutableDictionary, for which the initial capacity is a hard limit).

    Import Statement

  • Creates and initializes an OSDictionary populated with keys and objects provided.

    Declaration

    C++

    static OSDictionary * withObjects( const OSObject *objects[], const OSSymbol *keys[], unsigned int count, unsigned int capacity = 0);

    Parameters

    objects

    A C array of OSMetaClassBase-derived objects.

    keys

    A C array of OSSymbol keys for the corresponding objects in objects.

    count

    The number of keys and objects to be placed into the dictionary.

    capacity

    The initial storage capacity of the new dictionary object. If 0, count is used; otherwise this value must be greater than or equal to count.

    Return Value

    An instance of OSDictionary containing the key/object pairs provided, with a retain count of 1; NULL on failure.

    Discussion

    objects and keys must be non-NULL, and count must be nonzero. If capacity is nonzero, it must be greater than or equal to count. The new dictionary will grow as needed to accommodate more key/object pairs (unlike CFMutableDictionary, for which the initial capacity is a hard limit).

    Import Statement