Class: TDictionaryOf

Declaration: DictionaryOf.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

MCollectible

Inherited By:

None.

Purpose:

TDictionaryOf is a class that you can use to create collections that hold unordered key-value pairs. TDictionaryOf provides operators for adding and removing objects as well as searching for objects by either their key or value. The collection automatically grows in size, as needed, when objects are added.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

Do not derive any classes from TDictionaryOf.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Other Considerations:

The TKeyValuePair objects returned by the Add, Remove and Member operators must not be deleted. In future releases, these operators will be replaced by methods that require a TKeyValuePair argument that will be filled in. It is recommended that you, when possible, use the AddMember, RemoveByKey and MemberByKey operators instead. Iterators created for TDictionaryOf return objects of class TKeyValuePair. When iterating on a class of TDictionaryOf, the objects are returned in a random fashion because the collection is unordered.

Member Function: TDictionaryOf::~TDictionaryOf

virtual ~ TDictionaryOf ()

Interface Category:

API.

Purpose:

Destructor.

Calling Context:

Call this function directly to destroy an object.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TDictionaryOf::operator=

const TDictionaryOf < AKey , AValue >& operator =(const TDictionaryOf < AKey, AValue >&)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Call this function directly when an object is assigned to another compatible object.

Parameters:

const TDictionaryOf < AKey, AValue >& -The collection to be copied.

Return Value:

A reference to the left-hand side object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TDictionaryOf::ValueAt

AValue * ValueAt (const AKey & key) const

Interface Category:

API.

Purpose:

Returns the value associated with the supplied key.

Calling Context:

Call this function directly to retrieve the value associated with a key-value pair.

Parameters:

const AKey & key -The key.

Return Value:

A reference to the value.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TDictionaryOf::KeyAt

AKey * KeyAt (const AValue & val) const

Interface Category:

API.

Purpose:

Returns the key associated with the supplied value.

Calling Context:

Call this function directly to retrieve the key associated with a key-value pair.

Parameters:

const AValue & val -The value associated with the pair.

Return Value:

A reference to the key associated with the pair.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TDictionaryOf::AddKeyValuePair

AValue * AddKeyValuePair (const AKey * key, AValue * val, bool replace =true)

Interface Category:

API.

Purpose:

Adds a key-value pair to the collection.

Calling Context:

Call this function directly to add a key-value pair to the collection.

Parameters:

const AKey * key -The key associated with the pair.
AValue * val -The value associated with the pair.
bool replace =true -Indicates what action to take if a pair is found in the collection with the same key as the pair to be added.

Return Value:

If a matching key is already in the collection it will return the value already in the collection. If no matching key is in the collection it will return NIL.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This operation will automatically attempt to grow the size of the collection, as needed, to accommodate the new pair.

Member Function: TDictionaryOf::MemberByKey

AKey * MemberByKey (const AKey & key) const

Interface Category:

API.

Purpose:

Searches the collection for a key-value pair.

Calling Context:

Call this function directly to retrieve the pair with a key that matches the key supplied.

Parameters:

const AKey & key -The search key.

Return Value:

A reference to the pair with a the matching key. A NIL reference is returned if no matching key is found.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TDictionaryOf::RemoveByKey

AValue * RemoveByKey (const AKey & key)

Interface Category:

API.

Purpose:

Removes a key-value pair from the collection. The destructor for the pair is not called.

Calling Context:

Call this function directly to search the collection for a key-value pair and remove the pair from the collection, if found.

Parameters:

const AKey & key -The search key.

Return Value:

A reference to the pair removed from the collection. If there was no pair with a matching key, a NIL reference is returned.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TDictionaryOf::RemoveAll

void RemoveAll ()

Interface Category:

API.

Purpose:

Removes all objects from the collection. The destructors for each object are not called.

Calling Context:

Call this function directly to remove all key-value pairs from the collection.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TDictionaryOf::IsEmpty

bool IsEmpty () const

Interface Category:

API.

Purpose:

Determines if the collection is empty.

Calling Context:

Call this function directly to determine if the collection is empty.

Parameters:

Takes no parameters.

Return Value:

Returns true if the collection contains no objects.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TDictionaryOf::Count

CollectionCount Count () const

Interface Category:

API.

Purpose:

Returns the number of pairs in the collection.

Calling Context:

Call this function directly to get the number of key-value pairs currently in the collection.

Parameters:

Takes no parameters.

Return Value:

The number of pairs in the collection.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TDictionaryOf::AddCollection

void AddCollection (const TDictionaryOf < AKey, AValue >* col)

Interface Category:

API.

Purpose:

Adds the objects from another collection to this collection.

Calling Context:

Call this function directly to add the key-value pairs from another collection to this collection.

Parameters:

const TDictionaryOf < AKey, AValue >* col -The collection to be added.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

If a pair from the collection to be added has a key that matches a key in this collection, the value in this collection will be replaced with the value from the other collection.

Member Function: TDictionaryOf::operator==

bool operator ==(const TDictionaryOf < AKey, AValue >& dictionaryOf) const

Interface Category:

API.

Purpose:

Tests whether the objects in this collection are equivalent to the objects in another collection.

Calling Context:

Call this function directly to test the equivalence of two collections.

Parameters:

const TDictionaryOf < AKey, AValue >& dictionaryOf -The collection to compare to this collection.

Return Value:

Returns true if the collections are equivalent.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TDictionaryOf::operator!=

bool operator != (const TDictionaryOf < AKey, AValue >& dictionaryOf) const

Interface Category:

API.

Purpose:

Tests whether the objects in this collection differ from the objects in another collection.

Calling Context:

Call this function directly to test the equivalence of two collections.

Parameters:

const TDictionaryOf < AKey, AValue >& dictionaryOf -The collection to compare to this collection.

Return Value:

Returns true if the collections are not equivalent.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TDictionaryOf::operator>>=

TStream & operator >>=(TStream & towhere) const

Interface Category:

API.

Purpose:

Stream-out operator.

Calling Context:

Call this function directly to stream out data.

Parameters:

TStream & towhere -The stream to which the object streams itself.

Return Value:

Returns a reference to the stream the object streams itself out to.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TDictionaryOf::operator<<=

TStream & operator <<= (TStream & fromwhere)

Interface Category:

API.

Purpose:

Stream-in operator.

Calling Context:

Call this function directly to stream in data.

Parameters:

TStream & fromwhere -The stream from which the object streams itself.

Return Value:

Returns a reference to the stream the object streams itself in from.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TDictionaryOf::Hash

CollectionHash Hash () const

Interface Category:

API.

Purpose:

Returns the hash value for the collection.

Calling Context:

Call this function directly to return the number of objects in the collection.

Parameters:

Takes no parameters.

Return Value:

Number of objects in the collection.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TDictionaryOf::Remove

TKeyValuePair < AKey , AValue >* Remove (const TKeyValuePair < AKey, AValue >& keyValPair)

Interface Category:

API.

Purpose:

Removes an object from the collection.

Calling Context:

Call this function directly to remove a key-value pair from the collection.

Parameters:

const TKeyValuePair < AKey, AValue >& keyValPair -The pair to be removed from the collection.

Return Value:

A reference to the pair removed. If the pair was not found in the collection, a NIL reference is returned.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Avoid using this operation. It will be replaced in future releases with an operator that requires a TKeyValuePair as an argument. Use RemoveByKey instead. If you choose to use this operation, you should not delete the reference it returns.

Member Function: TDictionaryOf::Member

TKeyValuePair < AKey , AValue >* Member (const TKeyValuePair < AKey, AValue >& pair) const

Interface Category:

API.

Purpose:

Searches the collection for an object.

Calling Context:

Call this function directly to retrieve a key-value pair from the collection that matches the pair supplied.

Parameters:

const TKeyValuePair < AKey, AValue >& pair -The pair to search the collection for.

Return Value:

A reference to the pair. If the pair was not found in the collection, a NIL reference is returned.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Member Function: TDictionaryOf::Add

TKeyValuePair < AKey , AValue >* Add (TKeyValuePair < AKey, AValue

* anAssocOfKeyValue)

Interface Category:

API.

Purpose:

Adds key value to the collection. If a matching key is found in the collection, the value is replaced with the new value.

Calling Context:

Call this function directly to add a key-value pair to the collection.

Parameters:

TKeyValuePair < AKey, AValue >* anAssocOfKeyValue -The pair to add.

Return Value:

A reference to the pair added.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Member Function: TDictionaryOf::Delete

AValue * Delete (AKey * key)

Interface Category:

API.

Purpose:

Deletes the current key-value pair from the collection. The destructor for the key is called. The value is returned.

Calling Context:

Call this function directly to delete the current key-value pair.

Parameters:

AKey * key -The key to lookup and find key-value pair.

Return Value:

A pointer to the value.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TDictionaryOf::DeleteAll

void DeleteAll ()

Interface Category:

API.

Purpose:

Deletes all key-value pairs from the collection. Destructors for all key and value objects are called.

Calling Context:

Call this function directly to deleted all key-value pairs.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TDictionaryOf::DeleteAllValues

void DeleteAllValues ()

Interface Category:

API.

Purpose:

Deletes all the values from the collection. Destructors for all value objects are called.

Calling Context:

Call this function directly to delete all values.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TDictionaryOf::DeleteAllKeys

void DeleteAllKeys ()

Interface Category:

API.

Purpose:

Deletes all keys from the collection. Destructors for all key objects are called.

Calling Context:

Call this function directly to delete all keys.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TDictionaryOf::CreateIterator

TIteratorOver < TKeyValuePair < AKey , AValue >>* CreateIterator () const

Interface Category:

API.

Purpose:

Creates an iterator for this collection.

Calling Context:

Call this function directly to create an iterator for this collection.

Parameters:

Takes no parameters.

Return Value:

A pointer to the iterator created for this collection.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

When iterating on TDictionaryOf, objects will appear to be returned in a random fashion because the collection is not ordered.

Member Function: TDictionaryOf::TDictionaryOf

TDictionaryOf ()
TDictionaryOf (const TDictionaryOf < AKey, AValue >&)
TDictionaryOf (TKeyValuePairComparator < AKey, AValue >* adoptedComparator, TStreamer < TKeyValuePair < AKey, AValue >>* adoptedPairStreamer, CollectionIndex sizeHint =kCollectionSizeHint, CollectionIndex growthRate =kCollectionSizeHint)

Interface Category:

API.

Purpose:

Default constructor.
Copy constructor.
Creates a TDictionaryOf, setting the adoptedComparator, adoptedPairStreamer, sizeHint and growthRate to the passed values.

Calling Context:

Call this function directly anytime that creation of on empty TDictionaryOf is desired.
Call this function directly to create a TDictionaryOf initialized to the contents of the specified collection.
Call this function directly to create a TDictionaryOf with the adoptedComparator, adoptedPairStreamer, sizeHint and growthRate initialized to the supplied values.

Parameters:

Takes no parameters.
const TDictionaryOf < AKey, AValue >& -The TDictionaryOf to be copied.
TKeyValuePairComparator < AKey, AValue >* adoptedComparator -The comparator to use for this collection.
TStreamer < TKeyValuePair < AKey, AValue >>* adoptedPairStreamer -The streamer to use for this collection.
CollectionIndex sizeHint =kCollectionSizeHint -The sizeHint to use for this collection.
CollectionIndex growthRate =kCollectionSizeHint -The growthRate to use for this collection.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Click the icon to mail questions or corrections about this material to Taligent personnel.