OSDictionary

Inherits from:	OSCollection
Declared In:	OSDictionary.h

Overview

OSDictionary provides an associative store using strings for keys.

Discussion

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.

Functions

copyCollection: Creates a deep copy of the dictionary and its child collections.
ensureCapacity: Ensures the dictionary has enough space to store the requested number of key/object pairs.
flushCollection: Removes and releases all keys and objects within the dictionary.
free: Deallocates or releases any resources used by the OSDictionary instance.
getCapacity: Returns the number of objects the dictionary can store without reallocating.
getCapacityIncrement: Returns the storage increment of the dictionary.
getCount: Returns the current number of key/object pairs contained within the dictionary.
getObject: Returns the object stored under a given key.
getObject(const OSString *): Returns the object stored under a given key.
getObject(const OSSymbol *): Returns the object stored under a given key.
initWithCapacity: Initializes a new instance of OSDictionary.
initWithDictionary: Initializes a new OSDictionary with the contents of another dictionary.
initWithObjects(const OSObject *, const OSString *, unsigned int, unsigned int): Initializes a new OSDictionary with keys and objects provided.
initWithObjects(const OSObject *, const OSSymbol *, unsigned int, unsigned int): Initializes a new OSDictionary with keys and objects provided.
isEqualTo: Tests the equality of an OSDictionary to an arbitrary object.
isEqualTo(const OSDictionary *): Tests the equality of two OSDictionary objects.
isEqualTo(const OSDictionary *, const OSCollection *): Tests the equality of two OSDictionary objects over a subset of keys.
merge: Merges the contents of a dictionary into the receiver.
removeObject: Removes a key/object pair from the dictionary.
removeObject(const OSString *): Removes a key/object pair from the dictionary.
removeObject(const OSSymbol *): Removes a key/object pair from the dictionary.
serialize: Archives the receiver into the provided OSSerialize object.
setCapacityIncrement: Sets the storage increment of the dictionary.
setObject: Stores an object in the dictionary under a key.
setObject(const OSString *, const OSMetaClassBase *): Stores an object in the dictionary under a key.
setObject(const OSSymbol *, const OSMetaClassBase *): Stores an object in the dictionary under a key.
setOptions: Recursively sets option bits in the dictionary and all child collections.
withCapacity: Creates and initializes an empty OSDictionary.
withDictionary: Creates and initializes an OSDictionary populated with the contents of another dictionary.
withObjects(const OSObject *, const OSString *, unsigned int, unsigned int): Creates and initializes an OSDictionary populated with keys and objects provided.
withObjects(const OSObject *, const OSSymbol *, unsigned int, unsigned int): Creates and initializes an OSDictionary populated with keys and objects provided.

copyCollection

Creates a deep copy of the dictionary and its child collections.

public

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.

ensureCapacity

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

public

virtual unsigned int ensureCapacity(
    unsigned int newCapacity);

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.

flushCollection

Removes and releases all keys and objects within the dictionary.

public

virtual void flushCollection();

Discussion

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

free

Deallocates or releases any resources used by the OSDictionary instance.

public

virtual void free();

Discussion

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

getCapacity

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

public

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.

getCapacityIncrement

Returns the storage increment of the dictionary.

public

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.

getCount

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

public

virtual unsigned int getCount() const;

Return Value

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

getObject

Returns the object stored under a given key.

public

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.

getObject(const OSString *)

Returns the object stored under a given key.

public

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.

getObject(const OSSymbol *)

Returns the object stored under a given key.

public

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.

initWithCapacity

Initializes a new instance of OSDictionary.

public

virtual bool initWithCapacity(
    unsigned int capacity);

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

initWithDictionary

Initializes a new OSDictionary with the contents of another dictionary.

public

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.

initWithObjects(const OSObject , const OSString , unsigned int, unsigned int)

Initializes a new OSDictionary with keys and objects provided.

public

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

initWithObjects(const OSObject , const OSSymbol , unsigned int, unsigned int)

Initializes a new OSDictionary with keys and objects provided.

public

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

isEqualTo

Tests the equality of an OSDictionary to an arbitrary object.

public

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.

isEqualTo(const OSDictionary *)

Tests the equality of two OSDictionary objects.

public

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.

isEqualTo(const OSDictionary , const OSCollection )

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

public

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.

merge

Merges the contents of a dictionary into the receiver.

public

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.

removeObject

Removes a key/object pair from the dictionary.

public

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.

removeObject(const OSString *)

Removes a key/object pair from the dictionary.

public

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.

removeObject(const OSSymbol *)

Removes a key/object pair from the dictionary.

public

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.

serialize

Archives the receiver into the provided OSSerialize object.

public

virtual bool serialize(
    OSSerialize *serializer) const;

Parameters

serializer: The OSSerialize object.

Return Value

true if serialization succeeds, false if not.

setCapacityIncrement

Sets the storage increment of the dictionary.

public

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.

setObject

Stores an object in the dictionary under a key.

public

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.

setObject(const OSString , const OSMetaClassBase )

Stores an object in the dictionary under a key.

public

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.

setObject(const OSSymbol , const OSMetaClassBase )

Stores an object in the dictionary under a key.

public

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.

setOptions

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

public

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.

withCapacity

Creates and initializes an empty OSDictionary.

public

static OSDictionary * withCapacity(
    unsigned int capacity);

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

withDictionary

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

public

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

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

withObjects(const OSObject , const OSString , unsigned int, unsigned int)

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

public

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

withObjects(const OSObject , const OSSymbol , unsigned int, unsigned int)

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

public

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

Mac Dev Center Mac OS X Reference Library Drivers, Kernel, & Hardware: Kernel Device Drivers Kernel Framework Reference

Did this document help you?

Shop the Apple Online Store (1-800-MY-APPLE), visit an Apple Retail Store, or find a reseller.

Last Updated: 2010-07-29