ADC Home > Reference Library > Reference > Darwin > Kernel Framework Reference

OSDictionary

Inherits from:	OSCollection
Declared In:	OSDictionary.h

Overview

A collection class whose instances maintain a list of object references.

Discussion

An instance of OSDictionary is a mutable container which contains a list of OSMetaClassBase-derived object references and these objects are identified and acquired by unique associative keys. When an object is placed into a dictionary, a unique identifier or key must provided to identify the object within the collection. The key then must be provided to find the object within the collection. If an object is not found within the collection, a 0 is returned. Placing an object into a dictionary for a key that already identifies an object within that dictionary, will replace the current object with the new object.

Objects placed into a dictionary are automatically retained and objects removed or replaced are automatically released. All objects are released when the collection is freed.

Functions

ensureCapacity: Grows the size of the dictionary.
flushCollection: Removes and releases all objects within the dictionary.
free: Deallocates and releases all resources used by the OSDictionary instance.
getCapacity: Returns the storage capacity of the dictionary.
getCapacityIncrement: Returns the growth size for the dictionary.
getCount: Returns the current number of objects within the dictionary.
getObject: Finds an object in the dictionary identified by the given key.
getObject(const OSString *): Finds an object in the dictionary identified by the given key.
getObject(const OSSymbol *): Finds an object in the dictionary identified by the given key.
initWithCapacity: Initializes an instance of OSDictionary.
initWithDictionary: Initializes an instance of OSDictionary and populates it with the contents of another dictionary.
initWithObjects(const OSObject *, const OSString *, unsigned int, unsigned int): Initializes an instance of OSDictionary and populates it with the provided objects and keys.
initWithObjects(const OSObject *, const OSSymbol *, unsigned int, unsigned int): Initializes an instance of OSDictionary and populates it with the provided objects and keys.
isEqualTo: Tests the equality of the receiver and an unknown object.
isEqualTo(const OSDictionary *): Tests the equality of two dictionaries.
isEqualTo(const OSDictionary *, const OSCollection *): Tests the equality of the intersections of two dictionaries.
merge: Merges the contents of a dictionary into the receiver.
removeObject: Removes an object from the dictionary.
removeObject(const OSString *): Removes an object from the dictionary.
removeObject(const OSSymbol *): Removes an object from the dictionary.
serialize: Archives the receiver.
setCapacityIncrement: Sets the growth size of the dictionary.
setObject: Places an object into the dictionary and identifies it by a unique key.
setObject(const OSString *, const OSMetaClassBase *): Places an object into the dictionary and identifies it by a unique key.
setObject(const OSSymbol *, const OSMetaClassBase *): Places an object into the dictionary and identifies it by a unique key.
withCapacity: Creates and initializes an instance of OSDictionary.
withDictionary: Creates and initializes an instance of OSDictionary and populates it with objects from another dictionary.
withObjects(const OSObject *, const OSString *, unsigned int, unsigned int): Creates and initializes an instance of OSDictionary and populates it with the objects provided.
withObjects(const OSObject *, const OSSymbol *, unsigned int, unsigned int): Creates and initializes an instance of OSDictionary and populates it with the objects provided.

ensureCapacity

Grows the size of the dictionary.

public

virtual unsigned int ensureCapacity(
    unsigned int newCapacity);

Parameters

newCapacity: The new capacity for the dictionary to expand to.

Return Value

Returns the new capacity of the dictionary or the previous capacity upon error.

flushCollection

Removes and releases all objects within the dictionary.

public

virtual void flushCollection();

free

Deallocates and releases all resources used by the OSDictionary instance.

public

virtual void free();

Discussion

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

getCapacity

Returns the storage capacity of the dictionary.

public

virtual unsigned int getCapacity() const;

Return Value

Returns the storage capacity of the dictionary.

getCapacityIncrement

Returns the growth size for the dictionary.

public

virtual unsigned int getCapacityIncrement() const;

getCount

Returns the current number of objects within the dictionary.

public

virtual unsigned int getCount() const;

Return Value

Returns the number of objects contained within the dictionary.

getObject

Finds an object in the dictionary identified by the given key.

public

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

Parameters

aKey: The unique string identifying the object to be returned to caller.

Return Value

Returns a reference to the object corresponding to the given key, or 0 if the key does not exist in the dictionary.

getObject(const OSString *)

Finds an object in the dictionary identified by the given key.

public

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

Parameters

aKey: The unique OSString key identifying the object to be returned to caller.

Return Value

Returns a reference to the object corresponding to the given key, or 0 if the key does not exist in the dictionary.

getObject(const OSSymbol *)

Finds an object in the dictionary identified by the given key.

public

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

Parameters

aKey: The unique OSSymbol key identifying the object to be returned to caller.

Return Value

Returns a reference to the object corresponding to the given key, or 0 if the key does not exist in the dictionary.

initWithCapacity

Initializes an instance of OSDictionary.

public

virtual bool initWithCapacity(
    unsigned int capacity);

Parameters

capacity: The initial storage capacity of the dictionary object.

Return Value

Returns true if initialization succeeded or false on failure.

initWithDictionary

Initializes an instance of OSDictionary and populates it with the contents of another dictionary.

public

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

Parameters

dict: The dictionary containing the objects to be used to populate the receiving dictionary.
capacity: The initial storage capacity of the dictionary. If 0, the value of capacity will be set to the number of elements in the dictionary object, else the value of capacity must be greater than or equal to the number of elements in the dictionary object.

Return Value

Returns true if initialization succeeded or false on failure.

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

Initializes an instance of OSDictionary and populates it with the provided objects and keys.

public

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

Parameters

objects: A static array of OSMetaClassBase-derived objects to be placed into the dictionary.
keys: A static array of OSString keys which identify the corresponding objects provided in the 'objects' parameter.
count: The number of objects provided to the dictionary.
capacity: The initial storage capacity of the dictionary object. If 0, the capacity will be set to the size of 'count', else the capacity must be greater than or equal to the value of 'count'.

Return Value

Returns true if initialization succeeded or false on failure.

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

Initializes an instance of OSDictionary and populates it with the provided objects and keys.

public

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

Parameters

objects: A static array of OSMetaClassBase-derived objects to be placed into the dictionary.
keys: A static array of OSSymbol keys which identify the corresponding objects provided in the 'objects' parameter.
count: The number of objects provided to the dictionary.
capacity: The initial storage capacity of the dictionary object. If 0, the capacity will be set to the size of 'count', else the capacity must be greater than or equal to the value of 'count'.

Return Value

Returns true if initialization succeeded or false on failure.

isEqualTo

Tests the equality of the receiver and an unknown object.

public

virtual bool isEqualTo(
    const OSMetaClassBase *anObject) const;

Parameters

anObject: An object to be compared against the receiver.

Return Value

Returns true if the objects are equal.

isEqualTo(const OSDictionary *)

Tests the equality of two dictionaries.

public

virtual bool isEqualTo(
    const OSDictionary *aDictionary) const;

Parameters

aDictionary: The dictionary to be compared against the receiver.

Return Value

Returns true if the dictionaries are equal.

isEqualTo(const OSDictionary , const OSCollection )

Tests the equality of the intersections of two dictionaries.

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 describing the intersection for the comparison.

Return Value

Returns true if the intersections of the two dictionaries are equal.

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

Returns true if the merge is successful, 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'; the replaced objects are released.

removeObject

Removes an object from the dictionary.

public

virtual void removeObject(
    const char *aKey);

Parameters

aKey: A unique string identifying the object to be removed from the dictionary.

Discussion

Note that the removed object is automatically released.

removeObject(const OSString *)

Removes an object from the dictionary.

public

virtual void removeObject(
    const OSString *aKey);

Parameters

aKey: A unique OSString identifying the object to be removed from the dictionary.

Discussion

Note that the removed object is automatically released.

removeObject(const OSSymbol *)

Removes an object from the dictionary.

public

virtual void removeObject(
    const OSSymbol *aKey);

Parameters

aKey: A unique OSSymbol identifying the object to be removed from the dictionary.

Discussion

Note that the removed object is automatically released.

serialize

Archives the receiver.

public

virtual bool serialize(
    OSSerialize *s) const;

Parameters

s: The OSSerialize object.

Return Value

Returns true if serialization was successful, false if not.

setCapacityIncrement

Sets the growth size of the dictionary.

public

virtual unsigned int setCapacityIncrement(
    unsigned increment);

Parameters

increment: The new growth size.

Return Value

Returns the new capacity increment.

setObject

Places an object into the dictionary and identifies it by a unique key.

public

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

Parameters

aKey: A unique string identifying the object placed within the dictionary.
anObject: The object to be stored in the dictionary. It is automatically retained.

Return Value

Returns true if the addition of an object was successful, false otherwise.

setObject(const OSString , const OSMetaClassBase )

Places an object into the dictionary and identifies it by a unique key.

public

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

Parameters

aKey: A unique OSString identifying the object placed within the collection.
anObject: The object to be stored in the dictionary. It is automatically retained.

Return Value

Returns true if the addition of an object was successful, false otherwise.

setObject(const OSSymbol , const OSMetaClassBase )

Places an object into the dictionary and identifies it by a unique key.

public

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

Parameters

aKey: A unique OSSymbol identifying the object placed within the collection.
anObject: The object to be stored in the dictionary. It is automatically retained.

Return Value

Returns true if the addition of an object was successful, false otherwise.

withCapacity

Creates and initializes an instance of OSDictionary.

public

static OSDictionary *withCapacity(
    unsigned int capacity);

Parameters

capacity: The initial storage capacity of the dictionary object.

Return Value

Returns an instance of OSDictionary or 0 on failure.

withDictionary

Creates and initializes an instance of OSDictionary and populates it with objects from another dictionary.

public

static OSDictionary *withDictionary(
    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 dictionary object. If 0, the capacity will be set to the number of elements in the dictionary object, else the capacity must be greater than or equal to the number of elements in the dictionary.

Return Value

Returns an instance of OSDictionary or 0 on failure.

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

Creates and initializes an instance of OSDictionary and populates it with the objects provided.

public

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

Parameters

objects: A static array of OSMetaClassBase-derived objects.
keys: A static array of OSString keys.
count: The number of items to be placed into the dictionary.
capacity: The initial storage capacity of the dictionary object. If 0, the capacity will be set to the size of 'count', else this value must be greater or equal to 'count'.

Return Value

Returns an instance of OSDictionary or 0 on failure.

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

Creates and initializes an instance of OSDictionary and populates it with the objects provided.

public

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

Parameters

objects: A static array of OSMetaClassBase-derived objects.
keys: A static array of OSSymbol keys.
count: The number of items to be placed into the dictionary.
capacity: The initial storage capacity of the dictionary object. If 0, the capacity will be set to the size of 'count', else this value must be greater or equal to 'count'.

Return Value

Returns an instance of OSDictionary or 0 on failure.

Member Data

reserved

protected

ExpansionData *reserved;

Discussion

Reserved for future use. (Internal use only)

Did this document help you?

Yes: Tell us what works for you.

It’s good, but: Report typos, inaccuracies, and so forth.

It wasn’t helpful: Tell us what would have helped.

Last Updated: 2008-12-19