WWC snapshot of http://www.alw.nih.gov/Docs/NIHCL/nihcl_19.html taken on Sat Jun 10 19:13:43 1995

Go to the previous, next section.

Iterator--Collection Iterator

DESCRIPTION

Instances of class Iterator are used to iterate over (i.e. sequence through) the objects contained in a Collection. For example:

OrderedCltn c;
c.add(*new Point(0,0));
c.add(*new Point(1,1));
// ...
Iterator i(c);
Object* p;
while (p = i++) cout << *p;

will print all the Point objects in the OrderedCltn c in the same order in which they were added.

You may use an Iterator on any derived class of Collection, and more than one Iterator may be active on the same Collection at the same time without interference.

Class Iterator also provides a preprocessor macro for iterating over the objects in a Collection:

DO(collection, classname, p) ... OD;: The argument collection is the collection to be iterated over, classname is the class of the objects in collection, and p is the variable to be used to point to each object in turn.

The DO preprocessor macro expands into:

{
    classname* p;
    Iterator DO_pos(collection);
    while (p = classname::castdown(DO_pos++)) {

The OD preprocessor macro expands into:

}
}

Thus, the previous example may be written using the DO ... OD as:

OrderedCltn c;
c.add(*new Point(0,0));
c.add(*new Point(1,1));
// ...
DO(c, Object, p) cout << *p; OD

Iterator implements the usual Object functionality with the following restriction: deepCopy() and storeOn() work only for Iterators bound to classes derived from SeqCltn.

Class Iterator has the following public member variables:

public:
    int index;          // index of next Object
    Object* ptr;        // pointer to current Object or NULL
    unsigned num;       // object number, used by Bags
    Object* state;      // additional state, e.g., a Stack

Derived classes of Collection define the virtual member functions doReset(), doNext(), and doFinish() to record and update the current position of an iteration in these member variables. Simple container classes such as OrderedCltn need to use only the member variable index to record a position, but more complex container classes also use the other member variables. For example, class LinkedList uses ptr to save the address of the current Link. Class Bag uses num to determine when all the occurrences of an object at a particular index have been visited. Class Heap uses state to point to a shallow copy of the bound Heap made by doReset(), and Heap::doNext() applies removeFirst() to this copy to obtain the next object during an iteration.

CONSTRUCTORS

Iterator(const Collection& cltn): Constructs an Iterator for the Collection cltn. The Iterator is reset to the beginning of the Collection; i.e., the next call to Iterator::operator++() will return a pointer to the first object, if any.

POSITIONING ITERATORS

void reset(): Resets this Iterator to the beginning of the Collection it was bound to when constructed. The next call to Iterator::operator++() will return a pointer to the first object, if any.
Object* operator++(): Returns a pointer to the next Object in the Collection this Iterator was bound to when constructed, or a NULL (0) pointer when the end of the Collection is reached. This is the prefix operator so it adjusts the Iterator position before referencing it.
Object* operator++(int): Returns a pointer to the next Object in the Collection this Iterator was bound to when constructed, or a NULL (0) pointer when the end of the Collection is reached. This is the postfix operator so it adjusts the Iterator position after referencing it.

ACCESSING ITERATORS

Object* operator()() const: Returns a pointer to the current object this Iterator is positioned at in the Collection it was bound to when constructed, or a NULL (0) pointer if this Iterator has just been reset(), or if at the end of the Collection.
const Collection* collection() const: Returns a pointer to the Collection this Iterator was bound to when constructed.

SEARCHING

virtual unsigned hash() const: Returns a number suitable for use as a hash table probe, computed from the address of the bound collection, the member variables index, and num, and the hash() of the object pointed to by the member variable state.

RELATIONAL OPERATORS

bool operator==(const Iterator&) const
bool operator!=(const Iterator&) const: Returns YES if this Iterator is equal to (not equal to) the right operand Iterator. Two Iterators are equal if they are bound to the same Collection and they are at the same position within that Collection.

TESTING ITERATORS

virtual bool isEqual(const Object& ob) const: Returns YES if ob is of species Iterator and equals this Iterator. See operator==() for the definition of Iterator equality.

COPYING ITERATORS

virtual void deepenShallowCopy(): Creates a deep copy of this Iterator and the SeqCltn to which it is bound. Raises an NIHCL_BADCLASS exception if this Iterator is not bound to a derived class of SeqCltn.

READING AND PRINTING ITERATORS

virtual void dumpOn(ostream& strm =cerr) const: Prints the internal state of this Iterator on output stream strm.
virtual void printOn(ostream& strm =cout) const: Prints the object that this Iterator is currently positioned at on output stream strm. Does nothing if there is no current object.

ITERATOR SPECIES

virtual const Class* species() const: Returns a pointer to the class descriptor for class Iterator.

PROTECTED MEMBERS

Object I/O

virtual void storer(OIOofd& fd) const
virtual void storer(OIOout& strm) const: Stores the SeqCltn that this Iterator is bound to and the current position on strm or fd. If the bound collection is not a derived class of SeqCltn, an NIHCL_BADCLASS exception results.

DISABLED MEMBER FUNCTIONS

virtual int compare(const Object&) const: These functions are implemented as shouldNotImplement().

EXCEPTIONS RAISED

None