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);
OTC_Map(OTC_Map<T1,T2> const& theMap);

DESTRUCTION

void removeAll();

INSERTION

OTC_Map<T1,T2>& operator=(OTC_Map<T1,T2> const& theMap);
void add(T1 const& theKey, T2 const& theItem);

RETRIEVAL/SEARCH

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;

QUERY

inline u_int population() const;
inline OTC_Boolean isEmpty() const;

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;
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
);

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