OSDictionary



Member Functions

ensureCapacity

Abstract: Member function to grow the size of the collection.
public:

virtual unsigned int ensureCapacity(unsigned int newCapacity);

Parameters

NameDescription
newCapacityThe new capacity for the dictionary to expand to.
Result: Returns the new capacity of the dictionary or the previous capacity upon error.

flushCollection

Abstract: A member function which removes and releases all objects within the collection.
public:

virtual void flushCollection();


free

Abstract: A member functions to deallocate and release all resources used by the OSDictionary instance.
public:

virtual void free();

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


getCapacity

Abstract: A member function which returns the storage capacity of the collection.
public:

virtual unsigned int getCapacity() const;

Result: Returns the storage capacity of the dictionary.

getCapacityIncrement

Abstract: A member function which returns the growth size for the collection.
public:

virtual unsigned int getCapacityIncrement() const;


getCount

Abstract: A member function which returns the current number of objects within the collection.
public:

virtual unsigned int getCount() const;

Result: Returns the number of objects contained within the dictionary.

getObject

Abstract: A member function to find an object in the dictionary associated by a given key.
public:

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

Parameters

NameDescription
aKeyThe unique string identifying the object to be returned to caller.
Result: Returns a reference to the object corresponding to the given key, or 0 if the key does not exist in the dictionary.

getObject

Abstract: A member function to find an object in the dictionary associated by a given key.
public:

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

Parameters

NameDescription
aKeyThe unique OSString key identifying the object to be returned to caller.
Result: Returns a reference to the object corresponding to the given key, or 0 if the key does not exist in the dictionary.

getObject

Abstract: A member function to find an object in the dictionary associated by a given key.
public:

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

Parameters

NameDescription
aKeyThe unique OSSymbol key identifying the object to be returned to caller.
Result: Returns a reference to the object corresponding to the given key, or 0 if the key does not exist in the dictionary.

initWithCapacity

Abstract: A member function to initialize an instance of OSDictionary.
public:

virtual bool initWithCapacity(unsigned int capacity);

Parameters

NameDescription
capacityThe initial storage capacity of the dictionary object.
Result: Returns true if intialization succeeded or false on failure.

initWithDictionary

Abstract: A member function to initialize an instance of OSDictionary and populate it with the contents of another dictionary.
public:

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

Parameters

NameDescription
dictThe dictionary contining the objects to be used to populate the receiving dictionary.
capacityThe 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.
Result: Returns true if intialization succeeded or false on failure.

initWithObjects

Abstract: A member function to initialize an instance of OSDictionary and populate it with the provided objects and keys.
public:

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

Parameters

NameDescription
objectsA static array of OSObject derived objects to be placed into the dictionary.
keysA static array of OSString keys which identify the correspoding objects provided in the 'objects' parameter.
countThe number of objects provided to the dictionary.
capacityThe 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'.
Result: Returns true if intialization succeeded or false on failure.

initWithObjects

Abstract: A member function to initialize an instance of OSDictionary and populate it with the provided objects and keys.
public:

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

Parameters

NameDescription
objectsA static array of OSObject derived objects to be placed into the dictionary.
keysA static array of OSSymbol keys which identify the correspoding objects provided in the 'objects' parameter.
countThe number of objects provided to the dictionary.
capacityThe 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'.
Result: Returns true if intialization succeeded or false on failure.

isEqualTo

Abstract: A member function to test the equality of two dictionaries.
public:

virtual bool isEqualTo(OSDictionary *aDictionary) const;

Parameters

NameDescription
aDictionaryThe dictionary to be compared against the receiver.
Result: Returns true if the dictionaries are equal.

isEqualTo

Abstract: A member function to test the equality of the intersections of two dictionaries.
public:

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

Parameters

NameDescription
aDictionaryThe dictionary to be compared against the receiver.
keysAn OSArray or OSDictionary containing the keys describing the intersecion for the comparison.
Result: Returns true if the intersections of the two dictionaries are equal.

isEqualTo

Abstract: A member function to test the equality between the receiver and an unknown object.
public:

virtual bool isEqualTo(const OSObject *anObject) const;

Parameters

NameDescription
anObjectAn object to be compared against the receiver.
Result: Returns true if the objects are equal.

merge

Abstract: A member function which merges the contents of a dictionary into the receiver.
public:

virtual bool merge(const OSDictionary *aDictionary);

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

Parameters

NameDescription
aDictionaryThe dictionary whose contents are to be merged with the receiver.
Result: Returns true if the merger is successful, false otherwise.

removeObject

Abstract: A member function which removes an object from the dictionary. The removed object is automatically released.
public:

virtual void removeObject(const char *aKey);

Parameters

NameDescription
aKeyA unique string identifying the object to be removed from the dictionary.

removeObject

Abstract: A member function which removes an object from the dictionary. The removed object is automatically released.
public:

virtual void removeObject(const OSString *aKey);

Parameters

NameDescription
aKeyA unique OSString identifying the object to be removed from the dictionary.

removeObject

Abstract: A member function which removes an object from the dictionary. The removed object is automatically released.
public:

virtual void removeObject(const OSSymbol *aKey);

Parameters

NameDescription
aKeyA unique OSSymbol identifying the object to be removed from the dictionary.

serialize

Abstract: A member function which archives the receiver.
public:

virtual bool serialize(OSSerialize *s) const;

Parameters

NameDescription
sThe OSSerialize object.
Result: Returns true if serialization was successful, false if not.

setCapacityIncrement

Abstract: A member function to set the growth size of the collection.
public:

virtual unsigned int setCapacityIncrement(unsigned increment);

Parameters

NameDescription
incrementThe new growth size.
Result: Returns the new capacity increment.

setObject

Abstract: A member function which places an object into the dictionary and identifed by a unique key.
public:

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

Parameters

NameDescription
aKeyA unique OSString identifying the object placed within the collection.
anObjectThe object to be stored in the dictionary. It is automatically retained.
Result: Returns true if the addition of an object was successful, false otherwise.

setObject

Abstract: A member function which places an object into the dictionary and identifed by a unique key.
public:

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

Parameters

NameDescription
aKeyA unique string identifying the object placed within the collection.
anObjectThe object to be stored in the dictionary. It is automatically retained.
Result: Returns true if the addition of an object was successful, false otherwise.

setObject

Abstract: A member function which places an object into the dictionary and identifed by a unique key.
public:

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

Parameters

NameDescription
aKeyA unique OSSymbol identifying the object placed within the collection.
anObjectThe object to be stored in the dictionary. It is automatically retained.
Result: Returns true if the addition of an object was successful, false otherwise.

withCapacity

Abstract: A static constructor function to create and initialize an instance of OSDictionary.
public:

static OSDictionary *withCapacity(unsigned int capacity);

Parameters

NameDescription
capacityThe initial storage capacity of the dictionary object.
Result: Returns an instance of OSDictionary or 0 on failure.

withDictionary

Abstract: A static constructor function to create and initialize an instance of OSDictionary and populate it with objects from another dictionary.
public:

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

Parameters

NameDescription
dictA dictionary whose contents will be placed in the new instance.
capacityThe 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.
Result: Returns an instance of OSDictionary or 0 on failure.

withObjects

Abstract: A static constructor function to create and initialize an instance of OSDictionary and populate it with objects provided.
public:

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

Parameters

NameDescription
objectsA static array of OSObject derived objects.
keysA static array of OSString keys.
countThe number of items to be placed into the dictionary.
capacityThe 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'.
Result: Returns an instance of OSDictionary or 0 on failure.

withObjects

Abstract: A static constructor function to create and initialize an instance of OSDictionary and populate it with objects provided.
public:

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

Parameters

NameDescription
objectsA static array of OSObject derived objects.
keysA static array of OSSymbol keys.
countThe number of items to be placed into the dictionary.
capacityThe 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'.
Result: Returns an instance of OSDictionary or 0 on failure.

© 2000 Apple Computer, Inc. — (Last Updated 2/23/2000)