Go to the previous, next section.
#include <nihcl/Dictionary.h>
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.
Dictionary(unsigned
capacity
=DEFAULT_CAPACITY)
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.
virtual Object* add(Object&
ob)
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)
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
Dictionary
to
cltn
and returns a reference to
cltn.
virtual Collection& addKeysTo(Collection&
cltn) const
virtual Collection& addValuesTo(Collection&
cltn) const
Dictionary
to
cltn
and returns a reference to
cltn
.
virtual Object* remove(const Object&
asc)
virtual LookupKey* removeAssoc(const LookupKey&
asc)
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)
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.
virtual LookupKey* assocAt(const Object&
key) const
Dictionary
with a key object equal to
key. If
key
is not found,
assocAt()
returns 0.
virtual Object* atKey(const Object&
key) const
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)
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
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
Dictionary
.
bool operator==(const Dictionary&) const
bool operator!=(const Dictionary&) const
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.
virtual bool includesAssoc(const LookupKey&
asc) const
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
YES
if there is an association in this
Dictionary
with a key object equal to
key.
virtual bool isEqual(const Object&
a) const
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==()
.
virtual const Class* species() const
Dictionary
.
virtual int compare(const Object&) const
These functions are implemented as
shouldNotImplement()
.
NIHCL_DUPKEY
,
NIHCL_KEYNOTFOUND
Go to the previous, next section.