CTCLHashTableIterator

DESCRIPTION

CTCLHashTableIterator objects are created and returned by CTCLHashTableIterator::begin and CTCLHashTableIterator::end. These objects are pointer like objects to CTCLHashTableItem objects within the hash table.

If you imagine that all containers can have an ordering defined on them, iterators are like pointers to elements of this ordering. Dereference operators yield an element of the container, and increment operators make the iterator 'point' to the next element in the container according to the ordering.

For more information on both hash tables and iterators see the REFERENCES. For information about the classes that are related to this, consult manpages pointed to by the SEE ALSO section.

METHODS

  CTCLHashTableIterator (Tcl_HashTable* pTable);
  CTCLHashTableIterator(const CTCLHashTableIterator& rhs);
        

Construct a hash table iterator. Normally you will not need to use these constructors directly. They will be created, instead by CTCLHashTable::begin() or CTCLHashTable::end(). pTable is a pointer to an existing Tcl_HashTable created via Tcl_InitHashTable. rhs is an existing CTCLHashTableIterator object whose state will be used to initialize the object under construction.

  CTCLHashTableIterator operator=
                     (const CTCLHashTableIterator& rhs);
  int operator==(const CTCLHashTableIterator& rhs);
        

operator= allows you to assign the state of one CTCLHashTableIterator to another. When the assignment is complete, the left hand side object will be 'pointing' to the same object as the right hand side object but be separately incrementable.

operator== allows you to compare two iterators for equality. equality is defined as the two iterators being defined on the same underlying hash table, pointing to the same element, and having the same increment context (e.g. an increment of both iterators will leave them both pointing to the same hash table item (different from the one prior to the increment).

CTCLHashTableItem<T>* getCurrentEntry() const;
Tcl_HashTable* getHashTable() const;
        

These two functions get at the information the iterator is encapsulating. getCurrentEntry returns a pointer to the entry that the iterator si currently 'pointing' at. This is identical to the operator-> function. getHashTable returns a pointer to the underlying Tcl_HashTable created by Tcl_InitHashTable.

CTCLHashTableIterator& operator++ ();
CTCLHashTableIterator operator++ (int i);
            

These two function support both pre and post increment operations on an iterator. There are slight differences in semantics between these operators best illustrated with a sample code fragment. In the fragment below, i is an CTCLHashTableIterator

CTCLHashTableItem item1 = *i++;   // item 1 is the item pointed to prior to increment
CTCLHashTableItem item2 = *++i;   // item 2 is the item pointed to after increment.
            

CTCLHashTableItem<T>& operator* ();
CTCLHashTableItem<T>* operator->();
        

These operators allow CTCLHashTableIterator objects to be treated like pointers to CTCLHashTableItem objects. operator* provides 'pointer' dereferencing that allows code like:

                (*i).getItem();
            

operator-> provides a pointer to struct like semantics allowing code like:

                i->getItem();
            

SEE ALSO

CTCLHashTable(3), CTCLHashTableItem(3), Tcl_InitHashTable(3tcl), Tcl_FirstHashEntry(3tcl), Tcl_NextHashEntry(3tcl)

REFERENCES

Niklaus Wirth Algorithms + Data Structures = Programs
Prentice Hall Series in Automatic Computation 1976 See section 4.6

Musser, Derge, Saini: STL Tutorial and Reference Guide
Addison-Wesley Professional Computing Series; 2001 ISBN 0-201-37923-6