NAME
OTC_Map -
Class implementing a one way map between two objects.
SYNOPSIS
#include <OTC/collctn/map.hh>
template<class T1, class T2>
class OTC_Map
{
public:
static os_typespec* get_os_typespec();
typedef OTC_Modifier<T2> type1;
type1 dummy1();
typedef OTC_PairModifier<T1,T2> type2;
type2 dummy2();
~OTC_Map();
OTC_Map(int (*theRankFn)(T1 const&,T1 const&)=0);
OTC_Map(OTC_Map<T1,T2> const& theMap);
void removeAll();
OTC_Map<T1,T2>& operator=(OTC_Map<T1,T2> const& theMap);
void add(T1 const& theKey, T2 const& theItem);
void remove(T1 const& theKey);
OTC_Boolean contains(T1 const& theKey) const;
inline T2& item(T1 const& theKey);
inline T2 const& item(T1 const& theKey) const;
T1 const& pickKey() const;
T2 const& pickItem() const;
inline u_int population() const;
inline OTC_Boolean isEmpty() const;
OTC_Iterator<T1> keys(
OTC_Direction theDirection=OTCLIB_FORWARD,
OTC_Protection theProtection=OTCLIB_SAFE
) const;
inline OTC_Iterator<T2> items(
OTC_Direction theDirection=OTCLIB_FORWARD,
OTC_Protection theProtection=OTCLIB_SAFE
) const;
inline OTC_Modifier<T2> items(
OTC_Direction theDirection=OTCLIB_FORWARD,
OTC_Protection theProtection=OTCLIB_SAFE
);
inline OTC_PairIterator<T1,T2> pairs(
OTC_Direction theDirection=OTCLIB_FORWARD,
OTC_Protection theProtection=OTCLIB_SAFE
) const;
inline OTC_PairModifier<T1,T2> pairs(
OTC_Direction theDirection=OTCLIB_FORWARD,
OTC_Protection theProtection=OTCLIB_SAFE
);
};
CLASS TYPE
Concrete
DESCRIPTION
This class implements a one way mapping between two objects. The
first of these objects, the key, must be unique and must be able
to have a hash value generated for it using the OTC_HashActions
class. It must also be possible to compare the keys. The method
of comparing keys can be determined by providing a template
override version of OTC_RankActions for the type of the key.
INITIALISATION
OTC_Map(int (*theRankFn)(T1 const&,T1 const&)=0);
Creates an empty map. theRankFn is an
optional comparison function to be used in
place of OTC_RankActions for the key.
OTC_Map(OTC_Map<T1,T2> const& theMap);
Creates a copy of theMap.
DESTRUCTION
void removeAll();
Removes all key/item pairs in this map.
INSERTION
OTC_Map<T1,T2>& operator=(OTC_Map<T1,T2> const& theMap);
Replaces the contents of this map with
the contents of theMap.
void add(T1 const& theKey, T2 const& theItem);
If an item corresponding to theKey does
not exist in this map, then theItem will
be entered into this map. If an item
corresponding to theKey already exists,
an exception will be raised.
RETRIEVAL/SEARCH
void remove(T1 const& theKey);
If an item corresponding to theKey
exists in this map, it will be removed
and deleted. If an item corresponding to
theKey does not exist, an exception
will be raised.
OTC_Boolean contains(T1 const& theKey) const;
Returns OTCLIB_TRUE if this map contains
a item corresponding to theKey.
inline T2& item(T1 const& theKey);
If an item corresponding to theKey
exists in this map, a reference to it will
be returned. If an item corresponding to
theKey does not exist, an exception will
be raised.
inline T2 const& item(T1 const& theKey) const;
If an item corresponding to theKey
exists in this map, a reference to it will
be returned. If an item corresponding to
theKey does not exist, an exception will
be raised.
T1 const& pickKey() const;
Returns a key from the collection. If
the map is empty, an exception is raised.
The function is not guaranteed to
return a different key on each call.
T2 const& pickItem() const;
Returns an item from the collection. If
the map is empty, an exception is raised.
The function is not guaranteed to
return a different item on each call.
QUERY
inline u_int population() const;
Returns the number of key/item mappings
contained in this map.
inline OTC_Boolean isEmpty() const;
Returns OTCLIB_TRUE if the collection
is empty.
ITERATION
By default, iterators will perform reference counts on the
buckets in the collection as the iterator moves over the items.
Performing the reference counts ensures that the iterator
is not corrupted by additions or removals to the collection.
If an unsafe iterator is required, for example, to avoid
grabbing a write lock when using ObjectStore, a second
argument can be passed to the following functions. The value
of this argument is either OTCLIB_SAFE or OTCLIB_UNSAFE.
To get an unsafe iterator, the OTCLIB_UNSAFE argument should
be used.
The first argument to the following functions indicates the
direction of traversal of the iterator. Traversal in the
direction of first to last item is indicated by a value of
OTCLIB_FORWARD. Traversal in the reverse direction is
indicated by a value of OTCLIB_BACKWARD. The default value
is OTCLIB_FORWARD. In the OTC_Map class, traversal in
the forward direction will result in the first key/item being
accessible being the oldest key/item in the set. Moving the
iterator will result in successively newer key/items in the set
being accessible.
When iterating over items, in the order in which they were
inserted, be very careful about inserting new items into the set.
This is because any new items inserted, will also be seen by the
iterator. If you were inserting a new item for every item seen,
you would end up with an infinite loop.
OTC_Iterator<T1> keys(
OTC_Direction theDirection=OTCLIB_FORWARD,
OTC_Protection theProtection=OTCLIB_SAFE
) const;
Returns an iterator over the keys.
inline OTC_Iterator<T2> items(
OTC_Direction theDirection=OTCLIB_FORWARD,
OTC_Protection theProtection=OTCLIB_SAFE
) const;
Returns an iterator over the items.
inline OTC_Modifier<T2> items(
OTC_Direction theDirection=OTCLIB_FORWARD,
OTC_Protection theProtection=OTCLIB_SAFE
);
Returns an iterator over the items.
inline OTC_PairIterator<T1,T2> pairs(
OTC_Direction theDirection=OTCLIB_FORWARD,
OTC_Protection theProtection=OTCLIB_SAFE
) const;
Returns an iterator over the key/item
pairs in this map.
inline OTC_PairModifier<T1,T2> pairs(
OTC_Direction theDirection=OTCLIB_FORWARD,
OTC_Protection theProtection=OTCLIB_SAFE
);
Returns an iterator over the key/item
pairs in this map.
NOTES
When a pointer type is used as a key and the hash value generated
from it, is based not on the pointer, but on some part of the
object being pointed at, then it is important that the pointer be
of type pointer to const object. In other words you should define
the map as OTC_Map<EX_Foo const*,EX_Bar*> and not just
OTC_Map<EX_Foo*,EX_Bar*>. If this is not done, it would be
possible for a user to modify parts of the key from which the hash
value is generated. If the hash value of an object changes, it
will no longer be accessible.
The OTC_Bucket class is used internally to hold both key and
items. Thus the OTC_BaseActions class may be used to provide
actions to be performed, when items are inserted or removed from
the map.
Since an attempt to access or remove an item from the map, which
isn't there, will raise an exception, it is important to first
check that an item is actually in the map by calling the
contains() function.
SEE ALSO
OTC_Iterator, OTC_Modifier, OTC_HashActions, OTC_Bucket,
OTC_BaseActions, OTC_RankActions, OTC_PairIterator,
OTC_PairModifier
LIBRARY
OTC
AUTHOR(S)
Graham Dumpleton
COPYRIGHT
Copyright 1991 1992 1993 OTC LIMITED
Copyright 1994 DUMPLETON SOFTWARE CONSULTING PTY LIMITED