RWGSlistIterator(3C++)

Name
     RWGSlistIterator(type) - Rogue Wave library class

Synopsis
              #include <rw/gslist.h>



              declare(RWGSlist, type)
          RWGSlist(type) a ;
          RWGSlistIterator(type) I(a);




Description
     Iterator for class RWGSlist(type), which allows sequential access to all
     the elements of a singly-linked list.  Elements are accessed in order,
     first to last.  As with all Rogue Wave iterators, the "current item" is
     undefined immediately after construction -- you must define it by using
     operator() or some other (valid) operation.  Once the iterator has
     advanced beyond the end of the collection it is no longer valid --
     continuing to use it will bring undefined results.  In order to simplify
     the documentation below, an imaginary typedef

              typedef RWBoolean (*yourTester)(const type*, const void*);





     has been used.  See the documentation for class RWGSlist(type) for an
     explanation of this function.

Persistence
     None

Public Constructor
              RWGSlistIterator(type)( RWGSlist(type)& list);


     Constructs an iterator for the RWGSlist(type) list.  Immediately after
     construction, the position of the iterator is undefined.

Public Member Operators
              type*
          operator()();


     Advances the iterator to the next item and returns it.  Returns nil if it
     is at the end of the collection.
              void
          operator++();


     Advances the iterator one item.

              void
          operator+=(size_t n);


     Advances the iterator n items.

Public Member Functions
              RWBoolean
          atFirst() const;


     Returns TRUE if the iterator is at the start of the list, FALSE
     otherwise;

              RWBoolean
          atLast() const;


     Returns TRUE if the iterator is at the end of the list, FALSE otherwise;

              type*
          findNext(yourTester t,const type* d);


     Moves the iterator to the next item for which the function pointed to by
     t finds a match with d and returns it.  Returns nil if no match is found,
     in which case the position of the iterator will be undefined.

              type*
          findNextReference(const type* e);


     Moves the iterator to the next item with the address e and returns it.
     Returns nil if no match is found, in which case the position of the
     iterator will be undefined.

              type*
          insertAfterPoint(type* a);


     Adds item a after the current iterator position and return the item.  The
     position of the iterator is left unchanged.

              type*
          key() const;
     Returns the item at the current iterator position.

              type*
          remove();


     Removes and returns the item at the current cursor position.  Afterwards,
     the iterator will be positioned at the previous item in the list.  In a
     singly-linked list, this function is an inefficient operation because the
     entire list must be traversed, looking for the link before the link to be
     removed.

              type*
          removeNext(yourTester t, const type* d);


     Moves the iterator to the next item for which the function pointed to by
     t finds a "match" with d and removes and returns it.  Returns nil if no
     match is found, in which case the position of the iterator will be
     undefined.

              type*
          removeNextReference(const type* e);


     Moves the iterator to the next item with the address e and removes and
     returns it.  Returns nil if no match is found, in which case the position
     of the iterator will be undefined.

              void
          reset();


     Resets the iterator to its initial state.

              void
          toFirst();


     Moves the iterator to the start of the list.

              void
          toLast();


     Moves the iterator to the end of the list.