NAME
OTC_LinkIterator -
Iterator over a range of objects in a doubly linked list.
SYNOPSIS
#include <OTC/collctn/linkiter.hh>
class OTC_LinkIterator : public OTC_MPObject
{
public:
~OTC_LinkIterator();
static os_typespec* get_os_typespec();
OTC_LinkIterator(
OTC_Linkable* theStart,
OTC_Linkable* theEnd,
OTC_Protection theProtection=OTCLIB_SAFE
);
OTC_LinkIterator(OTC_LinkIterator const& theIter);
OTC_LinkIterator& operator=(OTC_LinkIterator const& theIter);
inline OTC_Boolean isStart() const;
inline OTC_Boolean isEnd() const;
inline OTC_Boolean isLink() const;
inline void resetStart();
inline void resetEnd();
inline void resetFirst();
inline void resetLast();
void next();
void prev();
inline OTC_Link* link() const;
};
CLASS TYPE
Concrete
DESCRIPTION
The class OTC_LinkIterator, implements an iterator over a range
of objects in a doubly linked list. The iterator provides the
ability to move back and forth along the list of objects, and
provides the ability to know when the iterator is located over a
valid link, or on an end anchor point. By default, the iterator
also transparently increments and decrements reference counts on
the objects, to ensure that removal of a link from the list will
not corrupt the iterator. This feature can be disabled if
necessary.
INITIALISATION
OTC_LinkIterator(
OTC_Linkable* theStart,
OTC_Linkable* theEnd,
OTC_Protection theProtection=OTCLIB_SAFE
);
theStart and theEnd should be anchor
points inserted into the list to mark
the boundaries of the range over which
the iterator can traverse. Both anchor
points should be in the same list, and
theStart should appear prior to theEnd
in the list. If theStart and theEnd
are not correctly placed into the list,
an exception will be raised at the time
that the condition is detected. Link
objects in the list, may also be used
as end points of iteration. In this
case, the endpoints are not included in
the iteration, and references are
maintained on the link objects for the
whole life of the iterator, meaning that
deletion of items will be delayed.
The argument theProtection determines
if reference counting will actually be
performed on object in the list. The
default of OTCLIB_SAFE will result in
reference counting being performed. A
value of OTCLIB_UNSAFE will turn of
reference counting. In this later case,
the list should not be modified while
the iterator exists as the state of the
iterator will be corrupted.
OTC_LinkIterator(OTC_LinkIterator const& theIter);
Creates an iterator which operates in the
same range as theIter, that is
initially located over the same object as
theIter.
OTC_LinkIterator& operator=(OTC_LinkIterator const& theIter);
Initialises this iterator to operate in
the same range as theIter, and to be
initially located over the same object as
theIter.
LOCATION
inline OTC_Boolean isStart() const;
Returns OTCLIB_TRUE if the iterator is
situated on the start anchor point, of the
valid range for this iterator.
inline OTC_Boolean isEnd() const;
Returns OTCLIB_TRUE if the iterator is
situated on the end anchor point, of the
valid range for this iterator.
inline OTC_Boolean isLink() const;
Returns OTCLIB_TRUE if the iterator is
located on a real link, ie., a link for
which a derived class may contain actual
data. Note though, that the link may be
dead; thus it is the user's responsibility
to only access data in a derived class if
it is still valid. If OTCLIB_FALSE is
returned then it implies that we are
located over either the start or end
anchor points.
ITERATION
inline void resetStart();
Reset the iterator back to the start
anchor point.
inline void resetEnd();
Reset the iterator to point at the end
anchor point.
inline void resetFirst();
Resets the iterator to the first real
link. If there are no links, the iterator
is reset to the end anchor point.
inline void resetLast();
Resets the iterator to the last real
link. If there are no links, the iterator
is reset to the start anchor point.
void next();
Moves the iterator to the next real link
occurring after the current link, or if
there are no real links between the
current link and the end link for this
range, to the end of the list.
void prev();
Moves the iterator to the next real
link occurring before the current link,
or if there are no real links between the
current link and the start link for this
range, to the start of the list.
RETRIEVAL
inline OTC_Link* link() const;
Returns the link on which the iterator is
located, if it is a real link. If the
iterator is not located on a real link,
then 0 is returned. Note that although a
non zero value may be returned, it does
not mean that the link is alive. To find
out if a link is alive, it should be
queried directly using the isDead()
member function.
SEE ALSO
OTC_Link, OTC_Anchor, OTC_Linkable
LIBRARY
OTC
AUTHOR(S)
Graham Dumpleton
COPYRIGHT
Copyright 1992 1993 OTC LIMITED
Copyright 1994 DUMPLETON SOFTWARE CONSULTING PTY LIMITED