Mac Developer Library

Developer

OSDictionary Class Reference

Options
Deployment Target:

On This Page
Language:

OSDictionary

OSDictionary provides an associative store using strings for keys.

OSDictionary is a container for Libkern C++ objects (those derived from OSMetaClassBase, in particular OSObject). Storage and access are associative, based on string-valued keys (C string, OSString, or OSSymbol). When adding an object to an OSDictionary, you provide a string identifier, which can then used to retrieve that object or remove it from the dictionary. Setting an object with a key that already has an associated object replaces the original object.

You must generally cast retrieved objects from OSObject to the desired class using OSDynamicCast. This macro returns the object cast to the desired class, or NULL if the object isn't derived from that class.

When iterating an OSDictionary using OSCollectionIterator, the objects returned from getNextObject are dictionary keys (not the object values for those keys). You can use the keys to retrieve their associated object values.

As with all Libkern collection classes, OSDictionary retains keys and objects added to it, and releases keys and objects removed from it (or replaced). An OSDictionary also grows as necessary to accommodate new key/value pairs, unlike Core Foundation collections (it does not, however, shrink).

Note: OSDictionary currently uses a linear search algorithm, and is not designed for high-performance access of many values. It is intended as a simple associative-storage mechanism only.

Use Restrictions

With very few exceptions in the I/O Kit, all Libkern-based C++ classes, functions, and macros are unsafe to use in a primary interrupt context. Consult the I/O Kit documentation related to primary interrupts for more information.

OSDictionary provides no concurrency protection; it's up to the usage context to provide any protection necessary. Some portions of the I/O Kit, such as IORegistryEntry, handle synchronization via defined member functions for setting properties.

Inheritance


Not Applicable

Conforms To


Not Applicable

Import Statement


Not Applicable

Objective-C

@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.

  • 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.

  • 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.

  • 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.

  • 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.

  • 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.

  • 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.

  • 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.

  • 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.

  • 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.

  • 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).

  • 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.

  • 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).

  • 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).

  • 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.

  • 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.

  • 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 or OSSymbols) 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.

  • 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.

  • 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.

  • 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.

  • 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.

  • 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.

  • 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.

  • 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.

  • 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.

  • 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.

  • 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.

  • 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).

  • 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.

  • 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).

  • 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).