Go to the previous, next section.
#include <nihcl/Iterator.h>
Collection
and its descendants.
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
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
Iterator
s 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.
Iterator(const Collection&
cltn)
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.
void reset()
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++()
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)
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.
Object* operator()() const
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
Collection
this
Iterator
was bound to when constructed.
virtual unsigned hash() const
hash()
of the object pointed to by the member variable
state.
bool operator==(const Iterator&) const
bool operator!=(const Iterator&) const
YES
if this
Iterator
is equal to (not equal to) the right operand
Iterator
. Two
Iterator
s are equal if they are bound to the same
Collection
and they are at the same position within that
Collection
.
virtual bool isEqual(const Object&
ob) const
YES
if
ob
is of species
Iterator
and equals this
Iterator
. See
operator==()
for the definition of
Iterator
equality.
virtual void deepenShallowCopy()
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
.
virtual void dumpOn(ostream&
strm
=cerr) const
Iterator
on output stream
strm.
virtual void printOn(ostream&
strm
=cout) const
Iterator
is currently positioned at on output stream
strm. Does nothing if there is no current object.
virtual const Class* species() const
Iterator
.
virtual void storer(OIOofd&
fd) const
virtual void storer(OIOout&
strm) const
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.
virtual int compare(const Object&) const
shouldNotImplement()
.
Go to the previous, next section.