Dictionary--Set of Associations

A Dictionary is a set of associations (i.e., instances of classes that are descendants of class LookupKey, such as Assoc) between key and value object pairs. Given a key object, a Dictionary permits the associated value object to be retrieved efficiently.

Class Dictionary determines whether or not two key objects are equal by applying the virtual function isEqual() to them.

CONSTRUCTORS

Dictionary(unsigned capacity =DEFAULT_CAPACITY): Constructs an empty Dictionary that can hold up to capacity associations (instances of classes derived from LookupKey). An NIHCL_ALLOCSIZE error is raised if capacity is not greater than 0. If an attempt is made to add more than capacity associations to a Dictionary, reSize() is called to increase its capacity. Since this is an expensive operation, it is wise to supply a reasonable estimate for capacity.

ADDING OBJECTS

virtual Object* add(Object& ob): Adds the object ob, which must be a kind of LookupKey, to this Dictionary and returns a pointer to either a LookupKey with a duplicate (i.e., isEqual()) key object in the Dictionary, or to ob if there was not already a duplicate key in the Dictionary.
virtual Assoc* addAssoc(Object& key, Object& value): Constructs an association (an instance of class Assoc) with the specified key and value objects, adds it to this Dictionary, and returns a pointer to the newly constructed association. The caller is responsible for deleting this association when no longer needed. If an association with a duplicate (i.e., isEqual()) key is already in the Dictionary, addAssoc() raises an NIHCL_DUPKEY exception.
virtual Collection& addContentsTo(Collection& cltn) const: Adds the value objects of all of the associations in this Dictionary to cltn and returns a reference to cltn.
virtual Collection& addKeysTo(Collection& cltn) const
virtual Collection& addValuesTo(Collection& cltn) const: Adds the key or value objects, respectively, of all of the associations in this Dictionary to cltn and returns a reference to cltn.

REMOVING OBJECTS

virtual Object* remove(const Object& asc)
virtual LookupKey* removeAssoc(const LookupKey& asc): Removes the association whose key object is equal to that of asc, which must be a kind of LookupKey, from this Dictionary and returns a pointer to the association removed. If no equal key is found an NIHCL_REMOVEERR exception is raised.
virtual LookupKey* removeKey(const Object& key): Removes the association whose key object is equal to key from this Dictionary and returns a pointer to the association removed. If an association for key does not occur in this Dictionary, Dictionary::removeKey() raises an NIHCL_REMOVEERR exception.

SEARCHING

virtual LookupKey* assocAt(const Object& key) const: Returns a reference to the association in this Dictionary with a key object equal to key. If key is not found, assocAt() returns 0.
virtual Object* atKey(const Object& key) const: Returns a pointer to the value object of the association in this Dictionary whose key object is equal to key. If key is not found, atKey() raises an NIHCL_KEYNOTFOUND exception.
virtual Object* atKey(const Object& key, Object& newValue): Changes the value object of the association in this Dictionary with key object isEqual() to key to newValue and returns a pointer to the old value object. If key is not found, atKey() raises an NIHCL_KEYNOTFOUND exception.
virtual Object* keyAtValue(const Object& val) const: Returns a pointer to the key object of the first association found in this Dictionary with a value object that equals val. If there is no equal value object, nil is returned. This function does a sequential search of the hash table, so it is not particularly efficient, and the order of the associations in the table is unpredictable.
virtual unsigned occurrencesOf(const Object& val) const: Returns the number of occurrences of value objects equal to val in this Dictionary.

RELATIONAL OPERATORS

bool operator==(const Dictionary&) const
bool operator!=(const Dictionary&) const: Returns YES if the right Dictionary is equal to (or not equal to) the left Dictionary operand. Two Dictionaries a and b are equal if they contain the same number of associations and if, for each association in a, there is an association in b with equal (i.e., isEqual()) key and value objects.

TESTING DICTIONARIES

virtual bool includesAssoc(const LookupKey& asc) const: Returns YES is there is an association in the Dictionary with a key object and value object equal to those of asc.
virtual bool includesKey(const Object& key) const: Returns YES if there is an association in this Dictionary with a key object equal to key.
virtual bool isEqual(const Object& a) const: Returns YES if this Dictionary and the argument object are comparable and they have equal values. The argument object a is comparable if it returns the address of class Dictionary's class descriptor for its species(). Class Dictionary implements isEqual() using Dictionary::operator==().

DICTIONARY SPECIES

virtual const Class* species() const: Returns a pointer to the class descriptor for class Dictionary.

DISABLED MEMBER FUNCTIONS

virtual int compare(const Object&) const

These functions are implemented as shouldNotImplement().

EXCEPTIONS RAISED

NIHCL_DUPKEY, NIHCL_KEYNOTFOUND

Go to the previous, next section.

Dictionary--Set of Associations

SYNOPSIS

BASE CLASS

DERIVED CLASSES

RELATED CLASSES

DESCRIPTION