Traditional Essential Tools Module Iterators
Traditional Essential Tools Module iterators have a number of unique features. You recall that the state of the iterator is undefined immediately following construction or the calling of reset(). You also trigger the undefined state if you change the collection class directly by adding or deleting objects while an iterator is active. Using an iterator at that point can bring unpredictable results. You must then use the member function reset() to restart the iterator, as if it has just been constructed. It's OK to change a collection via the iterator itself.
At any given moment, the iterator marks an object in the collection class—think of it as the current object. There are various methods for moving this mark. For example, most of the time you will probably be using member function operator(). In the Essential Tools Module, it is designed to always advance to the next object, then return either true or a pointer to the next object, depending on whether the associated collection class is value-based or reference-based, respectively. It always returns false (i.e., zero) when the end of the collection class is reached. Hence, a simple canonical form for using an iterator is:
RWSlistCollectable list;
.
.
.
RWSlistCollectableIterator iterator(list);
RWCollectable* next;
while (next = iterator()) {
.
. // (use next)
.
}
As an alternative, you can also use the prefix increment operator ++X. Some iterators have other member functions for manipulating the mark, such as findNext() or removeNext().
Member function key() always returns either the current object or a pointer to the current object, again depending on whether the collection class is value-based or reference-based, respectively. For most collection classes, using member function apply() to access every member is much faster than using an iterator. This is particularly true for the sorted collection classes; usually a tree must be traversed, requiring that the parent of a node be stored on a stack. Function apply() uses the program’s stack, while the sorted collection class iterator must maintain its own. The former is much faster.
The Essential Tools Module provides const versions of every traditional iterator. Const iterators have the same capabilities as traditional iterators, but also maintain const correctness by not allowing the modification of a container via that iterator. If you attempt to modify a container with a const iterator, a compilation error will occur.
