List iterators operate on singly or doubly linked lists. They're used to step through a list one or more elements at a time. The choice of which type of iterator to use is determined by the list you wish to iterate over. For example, to iterate over a non-constant WCIsvDList<Type> object, use the WCIsvDListIter<Type> class. A constant WCValSList<Type> object can be iterated over using the WCValConstSListIter<Type> class.
The iterators that correspond to the singly link list containers have some functionality inhibited. If backward traversal is required, the doubly linked containers and corresponding iterators must be used.
Like all WATCOM iterators, newly constructed and reset iterators are positioned before the first element in the list. The list may be traversed one element at a time using the pre-increment or call operator. An increment operation causing the iterator to be positioned after the end of the list returns zero. Further increments cause the undef_iter exception to be thrown, if it's enabled. This behaviour allows lists to be traversed simply using a while loop, and is demonstrated in the examples for the iterator classes.
The classes are presented in alphabetical order:
The WCIterExcept class provides the common exception handling control interface for all of the iterators.
Since the iterator classes are all template classes, deriving most of the functionality from common base classes was used. In the listing of class member functions, those public member functions that appear to be in the iterator class but are actually defined in the common base class are identified as if they were explicitly specified in the iterator class.
wclistit.h
The WCIsvConstDListIter<Type> and WCIsvConstSListIter<Type> classes are the templated classes used to create iterator objects for constant singly and doubly linked list objects. These classes may be used to iterate over non-constant lists, but the WCIsvDListIter<Type> and WCIsvSListIter<Type> classes provide additional functionality for only non-constant lists.
In the description of each member function, the text Type is used to indicate the list element type specified as the template parameter.
The WCIterExcept class is a base class of the WCIsvConstDListIter<Type> and WCIsvConstSListIter<Type> classes, and provides the exceptions() member function. This member function controls the exceptions that can be thrown by the WCIsvConstDListIter<Type> and WCIsvConstSListIter<Type> objects. No exceptions are enabled unless they're set by the exceptions() member function.
Some functionality supported by base classes of the iterator isn't appropriate for the constant list iterator classes. Setting those functions as private members in the derived class is the standard mechanism to prevent them from being invoked.
int append( Type * ); int insert( Type * );
The following member functions are declared in the public interface:
WCIsvConstSListIter();
WCIsvConstSListIter( const WCIsvSList<Type> & );
~WCIsvConstSListIter();
WCIsvConstDListIter();
WCIsvConstDListIter( const WCIsvDList<Type> & );
~WCIsvConstDListIter();
const WCIsvSList<Type> *
WCIsvConstSListIter<Type>::container() const;
const WCIsvDList<Type> *
WCIsvConstDListIter<Type>::container() const;
Type * current() const;
void reset();
void WCIsvConstSListIter<Type>::reset(
const WCIsvSList<Type> & );
void WCIsvConstDListIter<Type>::reset(
const WCIsvDList<Type> & );
The following member operators are declared in the public interface:
Type * operator ()(); Type * operator ++(); Type * operator +=( int );
In the iterators for doubly linked lists only:
Type * operator --(); Type * operator -=( int );
WCIsvSList::forAll(), WCIsvDList::forAll()
create a WCIsvConstSListIter<Type> object
#include <wclistit.h> public: WCIsvConstSListIter(); WCIsvConstSListIter( const WCIsvSList<Type> & );
There are two forms of the public WCIsvConstSListIter<Type> constructor:
The public WCIsvConstSListIter<Type> constructor creates an initialized WCIsvConstSListIter object.
WCIsvConstSListIter<Type>::~WCIsvConstSListIter(), WCIsvConstSListIter<Type>::operator ()(), WCIsvConstSListIter<Type>::operator ++(), WCIsvConstSListIter<Type>::operator +=(), WCIsvConstSListIter<Type>::reset()
destroy a WCIsvConstSListIter<Type> object
#include <wclistit.h> public: ~WCIsvConstSListIter();
This public member function is the destructor for the WCIsvConstSListIter<Type> class. The call to it is inserted implicitly by the compiler at the point where the WCIsvConstSListIter object goes out of scope.
The WCIsvConstSListIter object is destroyed.
WCIsvConstSListIter<Type>::WCIsvConstSListIter()
create a WCIsvConstDListIter<Type> object
#include <wclistit.h> public: WCIsvConstDListIter(); WCIsvConstDListIter( const WCIsvDList<Type> & );
There are two forms of the public WCIsvConstDListIter<Type> constructor:
The public WCIsvConstDListIter<Type> constructor creates an initialized WCIsvConstDListIter object.
WCIsvConstDListIter<Type>::~WCIsvConstDListIter(), WCIsvConstDListIter<Type>::operator ()(), WCIsvConstDListIter<Type>::operator ++(), WCIsvConstDListIter<Type>::operator +=(), WCIsvConstDListIter<Type>::reset()
destroy a WCIsvConstDListIter<Type> object
#include <wclistit.h> public: ~WCIsvConstDListIter();
This public member function is the destructor for the class WCIsvConstDListIter<Type>. The call to it is inserted implicitly by the compiler at the point where the WCIsvConstDListIter object goes out of scope.
The WCIsvConstDListIter object is destroyed.
WCIsvConstDListIter<Type>::WCIsvConstDListIter()
return a pointer to the list container object
#include <wclistit.h>
public:
const WCIsvSList<Type> *
WCIsvSListIter<Type>::container() const;
const WCIsvDList<Type> *
WCIsvDListIter<Type>::container() const;
The container() public member function returns a pointer to the list container object. If the iterator hasn't been initialized with a list object, and the undef_iter exception is enabled, the exception is thrown.
A pointer to the list object associated with the iterator is returned, or NULL(0) if the iterator hasn't been initialized with a list.
WCIterExcept::undef_iter, WCIsvConstSListIter<Type>::WCIsvConstSListIter(), WCIsvConstDListIter<Type>::WCIsvConstDListIter(), WCIsvConstDListIter<Type>::reset(), WCIsvConstSListIter<Type>::reset()
get the current list element
#include <wclistit.h> public: Type * current();
The current() public member function returns a pointer to the list element at the current iterator position.
If the iterator isn't associated with a list, or the iterator position is either before the first element or past the last element in the list, the current iterator position is undefined. In this case the undef_item exception is thrown, if enabled.
A pointer to the current list element is returned. If the current element is undefined, NULL(0) is returned.
WCIterExcept::undef_item, WCIsvConstDListIter<Type>::operator ()(), WCIsvConstSListIter<Type>::operator ()(), WCIsvConstDListIter<Type>::operator ++(), WCIsvConstSListIter<Type>::operator ++(), WCIsvConstDListIter<Type>::operator +=(), WCIsvConstSListIter<Type>::operator +=(), WCIsvConstDListIter<Type>::operator --(), WCIsvConstDListIter<Type>::operator -=(), WCIsvConstDListIter<Type>::reset(), WCIsvConstSListIter<Type>::reset()
advance the iterator to the next element in the list
#include <wclistit.h> public: Type * operator ()();
The operator ()() public member function is the call operator for the class. The list element that follows the current item is set to be the new current item. If the previous current item was the last element in the list, the iterator is positioned after the end of the list.
The operator ()() public member function has the same semantics as the pre-increment operator, operator ++().
If the iterator was positioned before the first list element, the current item is set to the first element. If the list is empty, the iterator is positioned after the end of the list.
If the iterator isn't associated with a list, or the iterator position before the increment was past the last element in the list, the undef_iter exception is thrown, if enabled.
The operator ()() public member function returns a pointer to the new current item. NULL(0) is returned when the iterator is incremented past the end of the list.
WCIterExcept::undef_iter, WCIsvConstDListIter<Type>::operator ++(), WCIsvConstSListIter<Type>::operator ++(), WCIsvConstDListIter<Type>::operator +=(), WCIsvConstSListIter<Type>::operator +=(), WCIsvConstDListIter<Type>::operator --(), WCIsvConstDListIter<Type>::operator -=(), WCIsvConstDListIter<Type>::reset(), WCIsvConstSListIter<Type>::reset()
advance the iterator to the next element in the list
#include <wclistit.h> public: Type * operator ++();
The operator ++() public member function is the pre-increment operator for the class. The list element that follows the current item is set to be the new current item. If the previous current item was the last element in the list, the iterator is positioned after the end of the list.
The operator ++() public member function has the same semantics as the call operator, operator ()().
The current item is set to the first list element if the iterator was positioned before the first element in the list. If the list is empty, the iterator is positioned after the end of the list.
If the iterator isn't associated with a list, or the iterator position before the increment was past the last element in the list, the undef_iter exception is thrown, if enabled.
The operator ++() public member function returns a pointer to the new current item. NULL(0) is returned when the iterator is incremented past the end of the list.
WCIterExcept::undef_iter, WCIsvConstDListIter<Type>::current(), WCIsvConstSListIter<Type>::current(), WCIsvConstDListIter<Type>::operator ()(), WCIsvConstSListIter<Type>::operator ()(), WCIsvConstDListIter<Type>::operator +=(), WCIsvConstSListIter<Type>::operator +=(), WCIsvConstDListIter<Type>::operator --(), WCIsvConstDListIter<Type>::operator -=(), WCIsvConstDListIter<Type>::reset(), WCIsvConstSListIter<Type>::reset()
move the iterator forward a number of times
#include <wclistit.h> public: Type * operator +=( int );
The operator +=() public member function accepts an integer value that causes the iterator to move that many elements after the current item. If the iterator was positioned before the first element in the list, the operation sets the current item to be the given element in the list.
If the current item was after the last element in the list previous to the iteration, and the undef_iter exception is enabled, the exception is thrown. Attempting to increment the iterator position more than one element after the end of the list, or by less than one element causes the iter_range exception to be thrown, if enabled.
The operator +=() public member function returns a pointer to the new current item. NULL(0) is returned when the iterator is incremented past the end of the list.
WCIterExcept::iter_range, WCIterExcept::undef_iter, WCIsvConstDListIter<Type>::current(), WCIsvConstSListIter<Type>::current(), WCIsvConstDListIter<Type>::operator ()(), WCIsvConstSListIter<Type>::operator ()(), WCIsvConstDListIter<Type>::operator ++(), WCIsvConstSListIter<Type>::operator ++(), WCIsvConstDListIter<Type>::operator --(), WCIsvConstDListIter<Type>::operator -=(), WCIsvConstDListIter<Type>::reset(), WCIsvConstSListIter<Type>::reset()
move the iterator backward in the list
#include <wclistit.h> public: Type * operator --();
The operator --() public member function is the pre-decrement operator for the WCIsvConstDListIter<Type> class. The list element previous to the current item is set to be the new current item:
If the iterator isn't associated with a list or the iterator position previous to the decrement was before the first element in the list, the undef_iter exception is thrown, if enabled.
The operator --() public member function returns a pointer to the new current item. NULL(0) is returned when the iterator is decremented past the first element of the list.
WCIterExcept::undef_iter, WCIsvConstDListIter<Type>::current(), WCIsvConstDListIter<Type>::operator ()(), WCIsvConstDListIter<Type>::operator ++(), WCIsvConstDListIter<Type>::operator +=(), WCIsvConstDListIter<Type>::operator -=(), WCIsvConstDListIter<Type>::reset()
move the iterator backward a number of times
#include <wclistit.h> public: Type * operator -=( int );
The operator -=() public member function accepts an integer value that causes the iterator to move that many elements before the current item. If the iterator was positioned after the last element in the list, the operation sets the current item to be the given number of elements from the end of the list.
If the current item was before the first element in the list previous to the iteration, and the undef_iter exception is enabled, the exception is thrown. Attempting to decrement the iterator position more than one element before the beginning of the list, or by less than one element causes the iter_range exception to be thrown, if enabled.
The operator -=() public member function returns a pointer to the new current item. NULL(0) is returned when the iterator is decremented past the first element in the list.
WCIterExcept::iter_range, WCIterExcept::undef_iter, WCIsvConstDListIter<Type>::current(), WCIsvConstDListIter<Type>::operator ()(), WCIsvConstDListIter<Type>::operator ++(), WCIsvConstDListIter<Type>::operator +=(), WCIsvConstDListIter<Type>::operator --(), WCIsvConstDListIter<Type>::reset()
position the iterator before the first element in a list
#include <wclistit.h>
public:
void reset();
void WCIsvSListIter<Type>::reset(
const WCIsvSList<Type> & );
void WCIsvDListIter<Type>::reset(
const WCIsvDList<Type> & );
The first form of the reset() public member function resets the iterator to the initial state, positioning the iterator before the first element in the associated list.
The second and third forms reset the iterator to operate on the specified list. The iterator is positioned before the first element in the list.
The iterator is positioned before the first list element.
WCIsvConstSListIter<Type>::WCIsvConstSListIter(), WCIsvConstDListIter<Type>::WCIsvConstDListIter(), WCIsvConstDListIter<Type>::container(), WCIsvConstSListIter<Type>::container()
wclistit.h
The WCIsvDListIter<Type> and WCIsvSListIter<Type> classes are the templated classes used to create iterator objects for singly and doubly linked list objects. These classes can be used only for non-constant lists. The WCIsvConstDListIter<Type> and WCIsvConstSListIter<Type> classes are provided to iterate over constant lists.
In the description of each member function, the text Type is used to indicate the list element type specified as the template parameter.
The WCIterExcept class is a base class of the WCIsvDListIter<Type> and WCIsvSListIter<Type> classes, and provides the exceptions() member function. This member function controls the exceptions that can be thrown by the WCIsvDListIter<Type> and WCIsvSListIter<Type> objects. No exceptions are enabled unless they're set by the exceptions() member function.
Some functionality supported by base classes of the iterator isn't appropriate in the singly linked list iterator classes. Setting those functions as private members in the derived class is the standard mechanism to prevent them from being invoked. The following member functions are declared in the singly linked list iterator private interface:
Type * operator --(); Type * operator -=( int ); int insert( Type * );
The following member functions are declared in the public interface:
WCIsvSListIter();
WCIsvSListIter( WCIsvSList<Type> & );
~WCIsvSListIter();
WCIsvDListIter();
WCIsvDListIter( WCIsvDList<Type> & );
~WCIsvDListIter();
int append( Type * );
WCIsvSList<Type> *
WCIsvSListIter<Type>::container() const;
WCIsvDList<Type> *
WCIsvDListIter<Type>::container() const;
Type * current() const;
void reset();
void WCIsvSListIter<Type>::reset( WCIsvSList<Type> & );
void WCIsvDListIter<Type>::reset( WCIsvDList<Type> & );
In the iterators for doubly linked lists only:
int insert( Type * );
The following member operators are declared in the public interface:
Type * operator ()(); Type * operator ++(); Type * operator +=( int );
In the iterators for doubly linked lists only:
Type * operator --(); Type * operator -=( int );
WCIsvSList::forAll(), WCIsvDList::forAll()
create a WCIsvSListIter<Type> object
#include <wclistit.h> public: WCIsvSListIter(); WCIsvSListIter( WCIsvSList<Type> & );
There are two forms of the public WCIsvSListIter<Type> constructor:
The public WCIsvSListIter<Type> constructor creates an initialized WCIsvSListIter object.
WCIsvSListIter<Type>::~WCIsvSListIter(), WCIsvSListIter<Type>::operator ()(), WCIsvSListIter<Type>::operator ++(), WCIsvSListIter<Type>::operator +=(), WCIsvSListIter<Type>::reset()
destroy a WCIsvSListIter<Type> object
#include <wclistit.h> public: ~WCIsvSListIter();
The WCIsvSListIter<Type> public member function is the destructor for the class. The call to it is inserted implicitly by the compiler at the point where the WCIsvSListIter object goes out of scope.
The WCIsvSListIter object is destroyed.
WCIsvSListIter<Type>::WCIsvSListIter()
create a WCIsvDListIter<Type> object
#include <wclistit.h> public: WCIsvDListIter(); WCIsvDListIter( WCIsvDList<Type> & );
There are two forms of the public WCIsvDListIter<Type> constructor:
The public WCIsvDListIter<Type> constructor creates an initialized WCIsvDListIter object.
WCIsvDListIter<Type>::~WCIsvDListIter(), WCIsvDListIter<Type>::operator ()(), WCIsvDListIter<Type>::operator ++(), WCIsvDListIter<Type>::operator +=(), WCIsvDListIter<Type>::reset()
destroy a WCIsvDListIter<Type> object
#include <wclistit.h> public: ~WCIsvDListIter();
The WCIsvDListIter<Type> public member function is the destructor for the class. The call to it is inserted implicitly by the compiler at the point where the WCIsvDListIter object goes out of scope.
The WCIsvDListIter object is destroyed.
WCIsvDListIter<Type>::WCIsvDListIter()
add an element after the current iterator position
#include <wclistit.h> public: int append( Type * );
The append() public member function inserts a new element into the list container object. The new element is inserted after the current iterator item.
If the iterator isn't associated with a list, or the iterator position is either before the first element or past the last element in the list, the current iterator position is undefined. The element isn't appended. If the undef_iter exception is enabled, it's thrown.
The new element is inserted after the current iterator item. A TRUE value (non-zero) is returned if the append is successful; FALSE (zero) result is returned if it fails.
WCExcept::out_of_memory, WCIterExcept::undef_iter, WCIsvDListIter<Type>::insert(), WCIsvSListIter<Type>::insert()
get a pointer to the list container object
#include <wclistit.h>
public:
WCIsvSList<Type> *
WCIsvSListIter<Type>::container() const;
WCIsvDList<Type> *
WCIsvDListIter<Type>::container() const;
The container() public member function returns a pointer to the list container object. If the iterator hasn't been initialized with a list object, and the undef_iter exception is enabled, the exception is thrown.
A pointer to the list object associated with the iterator is returned, or NULL(0) if the iterator hasn't been initialized with a list.
WCIterExcept::undef_iter, WCIsvSListIter<Type>::WCIsvSListIter(), WCIsvDListIter<Type>::WCIsvDListIter(), WCIsvDListIter<Type>::reset(), WCIsvSListIter<Type>::reset()
get the element at the current iterator position
#include <wclistit.h> public: Type * current();
The current() public member function returns a pointer to the list element at the current iterator position.
If the iterator isn't associated with a list, or the iterator position is either before the first element or past the last element in the list, the current iterator position is undefined. In this case the undef_item exception is thrown, if enabled.
A pointer to the current list element is returned. If the current element is undefined, NULL(0) is returned.
WCIterExcept::undef_item, WCIsvDListIter<Type>::operator ()(), WCIsvSListIter<Type>::operator ()(), WCIsvDListIter<Type>::operator ++(), WCIsvSListIter<Type>::operator ++(), WCIsvDListIter<Type>::operator +=(), WCIsvSListIter<Type>::operator +=(), WCIsvDListIter<Type>::operator --(), WCIsvDListIter<Type>::operator -=(), WCIsvDListIter<Type>::reset(), WCIsvSListIter<Type>::reset()
insert a new element into the list
#include <wclistit.h> public: int insert( Type * );
The insert() public member function inserts a new element into the list container object. The new element is inserted before the current iterator item. This process uses the previous link in the doubly linked list, so the insert() public member function isn't allowed with singly linked lists.
If the iterator isn't associated with a list, or the iterator position is either before the first element or past the last element in the list, the current iterator position is undefined. The element isn't inserted. If the undef_iter exception is enabled, it's thrown.
The new element is inserted before the current iterator item. A TRUE value (non-zero) is returned if the insertion is successful; FALSE (zero) result is returned if it fails.
WCExcept::out_of_memory, WCIterExcept::undef_iter, WCIsvDListIter<Type>::append()
advance the iterator to the next element in the list
#include <wclistit.h> public: Type * operator ()();
The operator ()() public member function is the call operator for the class. The list element that follows the current item is set to be the new current item. If the previous current item was the last element in the list, the iterator is positioned after the end of the list.
The operator ()() public member function has the same semantics as the pre-increment operator, operator ++().
If the iterator was positioned before the first list element, the current item is set to the first element. If the list is empty, the iterator is positioned after the end of the list.
If the iterator isn't associated with a list or the iterator position before the increment was past the last element in the list, the undef_iter exception is thrown, if enabled.
The operator ()() public member function returns a pointer to the new current item. NULL(0) is returned when the iterator is incremented past the end of the list.
WCIterExcept::undef_iter, WCIsvDListIter<Type>::operator ++(), WCIsvSListIter<Type>::operator ++(), WCIsvDListIter<Type>::operator +=(), WCIsvSListIter<Type>::operator +=(), WCIsvDListIter<Type>::operator --(), WCIsvDListIter<Type>::operator -=(), WCIsvDListIter<Type>::reset(), WCIsvSListIter<Type>::reset()
advance the iterator to the next element in the list
#include <wclistit.h> public: Type * operator ++();
The operator ++() public member function is the pre-increment operator for the class. The list element that follows the current item is set to be the new current item. If the previous current item was the last element in the list, the iterator is positioned after the end of the list.
The operator ++() public member function has the same semantics as the call operator, operator ()().
The current item is set to the first list element if the iterator was positioned before the first element in the list. If the list is empty, the iterator is positioned after the end of the list.
If the iterator isn't associated with a list or the iterator position before the increment was past the last element in the list, the undef_iter exception is thrown, if enabled.
The operator ++() public member function returns a pointer to the new current item. NULL(0) is returned when the iterator is incremented past the end of the list.
WCIterExcept::undef_iter, WCIsvDListIter<Type>::current(), WCIsvSListIter<Type>::current(), WCIsvDListIter<Type>::operator ()(), WCIsvSListIter<Type>::operator ()(), WCIsvDListIter<Type>::operator +=(), WCIsvSListIter<Type>::operator +=(), WCIsvDListIter<Type>::operator --(), WCIsvDListIter<Type>::operator -=(), WCIsvDListIter<Type>::reset(), WCIsvSListIter<Type>::reset()
move the iterator forward in the list a number of times
#include <wclistit.h> public: Type * operator +=( int );
The operator +=() public member function accepts an integer value that causes the iterator to move that many elements after the current item. If the iterator was positioned before the first element in the list, the operation sets the current item to be the given element in the list.
If the current item was after the last element in the list previous to the iteration, and the undef_iter exception is enabled, the exception is thrown. Attempting to increment the iterator position more than one element after the end of the list, or by less than one element causes the iter_range exception to be thrown, if enabled.
The operator +=() public member function returns a pointer to the new current item. NULL(0) is returned when the iterator is incremented past the end of the list.
WCIterExcept::iter_range, WCIterExcept::undef_iter, WCIsvDListIter<Type>::current(), WCIsvSListIter<Type>::current(), WCIsvDListIter<Type>::operator ()(), WCIsvSListIter<Type>::operator ()(), WCIsvDListIter<Type>::operator ++(), WCIsvSListIter<Type>::operator ++(), WCIsvDListIter<Type>::operator --(), WCIsvDListIter<Type>::operator -=(), WCIsvDListIter<Type>::reset(), WCIsvSListIter<Type>::reset()
move the iterator one element back in the list
#include <wclistit.h> public: Type * operator --();
The operator --() public member function is the pre-decrement operator for the WCIsvDListIter<Type> class. The list element previous to the current item is set to be the new current item:
If the iterator isn't associated with a list or the iterator position previous to the decrement was before the first element in the list, the undef_iter exception is thrown, if enabled.
The operator --() public member function returns a pointer to the new current item. NULL(0) is returned when the iterator is decremented past the first element of the list.
WCIterExcept::undef_iter, WCIsvDListIter<Type>::current(), WCIsvDListIter<Type>::operator ()(), WCIsvDListIter<Type>::operator ++(), WCIsvDListIter<Type>::operator +=(), WCIsvDListIter<Type>::operator -=(), WCIsvDListIter<Type>::reset()
move the iterator backward in the list a number of times
#include <wclistit.h> public: Type * operator -=( int );
The operator -=() public member function accepts an integer value that causes the iterator to move that many elements before the current item. If the iterator was positioned after the last element in the list, the operation sets the current item to be the given number of elements from the end of the list.
If the current item was before the first element in the list previous to the iteration, and the undef_iter exception is enabled, the exception is thrown. Attempting to decrement the iterator position more than one element before the beginning of the list, or by less than one element causes the iter_range exception to be thrown, if enabled.
The operator -=() public member function returns a pointer to the new current item. NULL(0) is returned when the iterator is decremented past the first element in the list.
WCIterExcept::iter_range, WCIterExcept::undef_iter, WCIsvDListIter<Type>::current(), WCIsvDListIter<Type>::operator ()(), WCIsvDListIter<Type>::operator ++(), WCIsvDListIter<Type>::operator +=(), WCIsvDListIter<Type>::operator --(), WCIsvDListIter<Type>::reset()
move the iterator before the first element in the list
#include <wclistit.h>
public:
void reset();
void WCIsvSListIter<Type>::reset(
WCIsvSList<Type> & );
void WCIsvDListIter<Type>::reset(
WCIsvDList<Type> & );
The first form of the reset() public member function resets the iterator to the initial state, positioning the iterator before the first element in the associated list.
The second and third forms reset the iterator to operate on the specified list. The iterator is positioned before the first element in the list.
The iterator is positioned before the first list element.
WCIsvSListIter<Type>::WCIsvSListIter(), WCIsvDListIter<Type>::WCIsvDListIter(), WCIsvDListIter<Type>::container(), WCIsvSListIter<Type>::container()
wclistit.h
The WCPtrConstSListIter<Type> and WCPtrConstDListIter<Type> classes are the templated classes used to create iterator objects for constant singly and doubly linked list objects. These classes may be used to iterate over non-constant lists, but the WCPtrDListIter<Type> and WCPtrSListIter<Type> classes provide additional functionality for only non-constant lists.
In the description of each member function, the text Type is used to indicate the list element type specified as the template parameter.
The WCIterExcept class is a base class of the WCPtrConstDListIter<Type> and WCPtrConstSListIter<Type> classes, and provides the exceptions() member function. This member function controls the exceptions that can be thrown by the WCPtrConstDListIter<Type> and WCPtrConstSListIter<Type> objects. No exceptions are enabled unless they're set by the exceptions() member function.
Some functionality supported by base classes of the iterator isn't appropriate for the constant list iterator classes. Setting those functions as private members in the derived class is the standard mechanism to prevent them from being invoked.
int append( Type * ); int insert( Type * );
The following member functions are declared in the public interface:
WCPtrConstSListIter();
WCPtrConstSListIter( const WCPtrSList<Type> & );
~WCPtrConstSListIter();
WCPtrConstDListIter();
WCPtrConstDListIter( const WCPtrDList<Type> & );
~WCPtrConstDListIter();
const WCPtrSList<Type> *
WCPtrConstSListIter<Type>::container() const;
const WCPtrDList<Type> *
WCPtrConstDListIter<Type>::container() const;
Type * current() const;
void reset();
void WCPtrConstSListIter<Type>::reset(
const WCPtrSList<Type> & );
void WCPtrConstDListIter<Type>::reset(
const WCPtrDList<Type> & );
The following member operators are declared in the public interface:
int operator ()(); int operator ++(); int operator +=( int );
In the iterators for doubly linked lists only:
int operator --(); int operator -=( int );
WCPtrSList::forAll(), WCPtrDList::forAll()
create a WCPtrConstSListIter<Type> object
#include <wclistit.h> public: WCPtrConstSListIter(); WCPtrConstSListIter( const WCPtrSList<Type> & );
There are two forms of the public WCPtrConstSListIter<Type> constructor:
The public WCPtrConstSListIter<Type> constructor creates an initialized WCPtrConstSListIter object.
WCPtrConstSListIter<Type>::~WCPtrConstSListIter(), WCPtrConstSListIter<Type>::operator ()(), WCPtrConstSListIter<Type>::operator ++(), WCPtrConstSListIter<Type>::operator +=(), WCPtrConstSListIter<Type>::reset()
destroy a WCPtrConstSListIter<Type> object
#include <wclistit.h> public: ~WCPtrConstSListIter();
This public member function is the destructor for the WCPtrConstSListIter<Type> class. The call to it is inserted implicitly by the compiler at the point where the WCPtrConstSListIter object goes out of scope.
The WCPtrConstSListIter object is destroyed.
WCPtrConstSListIter<Type>::WCPtrConstSListIter()
create a WCPtrConstDListIter<Type> object
#include <wclistit.h> public: WCPtrConstDListIter(); WCPtrConstDListIter( const WCPtrDList<Type> & );
There are two forms of the public WCPtrConstDListIter<Type> constructor:
The public WCPtrConstDListIter<Type> constructor creates an initialized WCPtrConstDListIter object.
WCPtrConstDListIter<Type>::~WCPtrConstDListIter(), WCPtrConstDListIter<Type>::operator ()(), WCPtrConstDListIter<Type>::operator ++(), WCPtrConstDListIter<Type>::operator +=(), WCPtrConstDListIter<Type>::reset()
destroy a WCPtrConstDListIter<Type> object
#include <wclistit.h> public: ~WCPtrConstDListIter();
This public member functions is the destructor for the WCPtrConstDListIter<Type> class. The call to it is inserted implicitly by the compiler at the point where the WCPtrConstDListIter object goes out of scope.
The WCPtrConstDListIter object is destroyed.
WCPtrConstDListIter<Type>::WCPtrConstDListIter()
return a pointer to the list container object
#include <wclistit.h>
public:
const WCPtrSList<Type> *
WCPtrSListIter<Type>::container() const;
const WCPtrDList<Type> *
WCPtrDListIter<Type>::container() const;
The container() public member function returns a pointer to the list container object. If the iterator hasn't been initialized with a list object, and the undef_iter exception is enabled, the exception is thrown.
A pointer to the list object associated with the iterator is returned, or NULL(0) if the iterator hasn't been initialized with a list.
WCIterExcept::undef_iter, WCPtrConstSListIter<Type>::WCPtrConstSListIter(), WCPtrConstDListIter<Type>::WCPtrConstDListIter(), WCPtrConstDListIter<Type>::reset(), WCPtrConstSListIter<Type>::reset()
get the element at the current iterator position
#include <wclistit.h> public: Type * current() const;
The current() public member function returns a pointer to the list element at the current iterator position.
If the iterator isn't associated with a list, or the iterator position is either before the first element or past the last element in the list, the current iterator position is undefined. In this case the undef_item exception is thrown, if enabled.
A pointer to the current list element is returned. If the current element is undefined, an uninitialized pointer is returned.
WCIterExcept::undef_item, WCPtrConstDListIter<Type>::operator ()(), WCPtrConstSListIter<Type>::operator ()(), WCPtrConstDListIter<Type>::operator ++(), WCPtrConstSListIter<Type>::operator ++(), WCPtrConstDListIter<Type>::operator +=(), WCPtrConstSListIter<Type>::operator +=(), WCPtrConstDListIter<Type>::operator --(), WCPtrConstDListIter<Type>::operator -=(), WCPtrConstDListIter<Type>::reset(), WCPtrConstSListIter<Type>::reset()
advance the iterator in the list
#include <wclistit.h> public: int operator ()();
The operator ()() public member function is the call operator for the class. The list element that follows the current item is set to be the new current item. If the previous current item was the last element in the list, the iterator is positioned after the end of the list.
The operator ()() public member function has the same semantics as the pre-increment operator, operator ++().
If the iterator was positioned before the first list element, the current item is set to the first element. If the list is empty, the iterator is positioned after the end of the list.
If the iterator isn't associated with a list or the iterator position before the increment was past the last element in the list, the undef_iter exception is thrown, if enabled.
The operator ()() public member function returns a non-zero value if the iterator is positioned on a list item. Zero(0) is returned when the iterator is incremented past the end of the list.
WCIterExcept::undef_iter, WCPtrConstDListIter<Type>::operator ++(), WCPtrConstSListIter<Type>::operator ++(), WCPtrConstDListIter<Type>::operator +=(), WCPtrConstSListIter<Type>::operator +=(), WCPtrConstDListIter<Type>::operator --(), WCPtrConstDListIter<Type>::operator -=(), WCPtrConstDListIter<Type>::reset(), WCPtrConstSListIter<Type>::reset()
advance the iterator in the list
#include <wclistit.h> public: int operator ++();
The operator ++() public member function is the pre-increment operator for the class. The list element that follows the current item is set to be the new current item. If the previous current item was the last element in the list, the iterator is positioned after the end of the list.
The operator ++() public member function has the same semantics as the call operator, operator ()().
The current item is set to the first list element if the iterator was positioned before the first element in the list. If the list is empty, the iterator is positioned after the end of the list.
If the iterator isn't associated with a list or the iterator position before the increment was past the last element in the list, the undef_iter exception is thrown, if enabled.
The operator ++() public member function returns a non-zero value if the iterator is positioned on a list item. Zero(0) is returned when the iterator is incremented past the end of the list.
WCIterExcept::undef_iter, WCPtrConstDListIter<Type>::current(), WCPtrConstSListIter<Type>::current(), WCPtrConstDListIter<Type>::operator ()(), WCPtrConstSListIter<Type>::operator ()(), WCPtrConstDListIter<Type>::operator +=(), WCPtrConstSListIter<Type>::operator +=(), WCPtrConstDListIter<Type>::operator --(), WCPtrConstDListIter<Type>::operator -=(), WCPtrConstDListIter<Type>::reset(), WCPtrConstSListIter<Type>::reset()
move the iterator forward a number of times in the list
#include <wclistit.h> public: int operator +=( int );
The operator +=() public member function accepts an integer value that causes the iterator to move that many elements after the current item. If the iterator was positioned before the first element in the list, the operation sets the current item to be the given element in the list.
If the current item was after the last element in the list previous to the iteration, and the undef_iter exception is enabled, the exception is thrown. Attempting to increment the iterator position more than one element after the end of the list, or by less than one element causes the iter_range exception to be thrown, if enabled.
The operator +=() public member function returns a non-zero value if the iterator is positioned on a list item. Zero(0) is returned when the iterator is incremented past the end of the list.
WCIterExcept::iter_range, WCIterExcept::undef_iter, WCPtrConstDListIter<Type>::current(), WCPtrConstSListIter<Type>::current(), WCPtrConstDListIter<Type>::operator ()(), WCPtrConstSListIter<Type>::operator ()(), WCPtrConstDListIter<Type>::operator ++(), WCPtrConstSListIter<Type>::operator ++(), WCPtrConstDListIter<Type>::operator --(), WCPtrConstDListIter<Type>::operator -=(), WCPtrConstDListIter<Type>::reset(), WCPtrConstSListIter<Type>::reset()
move the iterator backward in the list
#include <wclistit.h> public: int operator --();
The operator --() public member function is the pre-decrement operator for the class. The list element previous to the current item is set to be the new current item:
If the iterator isn't associated with a list or the iterator position previous to the decrement was before the first element in the list, the undef_iter exception is thrown, if enabled.
The operator --() public member function returns a non-zero value if the iterator is positioned on a list item. Zero(0) is returned when the iterator is decremented past the first element of the list.
WCIterExcept::undef_iter, WCPtrConstDListIter<Type>::current(), WCPtrConstDListIter<Type>::operator ()(), WCPtrConstDListIter<Type>::operator ++(), WCPtrConstDListIter<Type>::operator +=(), WCPtrConstDListIter<Type>::operator -=(), WCPtrConstDListIter<Type>::reset()
move the iterator backward in the list a number of times
#include <wclistit.h> public: int operator -=( int );
The operator -=() public member function accepts an integer value that causes the iterator to move that many elements before the current item. If the iterator was positioned after the last element in the list, the operation sets the current item to be the given number of elements from the end of the list.
If the current item was before the first element in the list previous to the iteration, and the undef_iter exception is enabled, the exception is thrown. Attempting to decrement the iterator position more than one element before the beginning of the list, or by less than one element causes the iter_range exception to be thrown, if enabled.
The operator -=() public member function returns a non-zero value if the iterator is positioned on a list item. Zero(0) is returned when the iterator is decremented past the first element in the list.
WCIterExcept::iter_range, WCIterExcept::undef_iter, WCPtrConstDListIter<Type>::current(), WCPtrConstDListIter<Type>::operator ()(), WCPtrConstDListIter<Type>::operator ++(), WCPtrConstDListIter<Type>::operator +=(), WCPtrConstDListIter<Type>::operator --(), WCPtrConstDListIter<Type>::reset()
move the iterator before the first element in the list
#include <wclistit.h>
public:
void reset();
void WCPtrSListIter<Type>::reset(
const WCPtrSList<Type> & );
void WCPtrDListIter<Type>::reset(
const WCPtrDList<Type> & );
The first form of the reset() public member function resets the iterator to the initial state, positioning the iterator before the first element in the associated list.
The second and third forms reset the iterator to operate on the specified list. The iterator is positioned before the first element in the list.
The iterator is positioned before the first list element.
WCPtrConstSListIter<Type>::WCPtrConstSListIter(), WCPtrConstDListIter<Type>::WCPtrConstDListIter(), WCPtrConstDListIter<Type>::container(), WCPtrConstSListIter<Type>::container()
wclistit.h
The WCPtrSListIter<Type> and WCPtrDListIter<Type> classes are the templated classes used to create iterator objects for singly and doubly linked list objects. These classes can be used only for non-constant lists. The WCPtrConstDListIter<Type> and WCPtrConstSListIter<Type> classes are provided to iterate over constant lists.
In the description of each member function, the text Type is used to indicate the list element type specified as the template parameter.
The WCIterExcept class is a base class of the WCPtrDListIter<Type> and WCPtrSListIter<Type> classes, and provides the exceptions() member function. This member function controls the exceptions that can be thrown by the WCPtrConstDListIter<Type> and WCPtrConstSListIter<Type> objects. No exceptions are enabled unless they're set by the exceptions() member function.
Some functionality supported by base classes of the iterator isn't appropriate in the singly linked list iterator classes. Setting those functions as private members in the derived class is the standard mechanism to prevent them from being invoked. The following member functions are declared in the singly linked list iterator private interface:
int operator --(); int operator -=( int ); int insert( Type * );
The following member functions are declared in the public interface:
WCPtrSListIter(); WCPtrSListIter( WCPtrSList<Type> & ); ~WCPtrSListIter(); WCPtrDListIter(); WCPtrDListIter( WCPtrDList<Type> & ); ~WCPtrDListIter(); int append( Type * ); WCPtrSList<Type> * WCPtrSListIter<Type>::container() const; WCPtrDList<Type> * WCPtrDListIter<Type>::container() const; Type * current() const; void reset(); void WCPtrSListIter<Type>::reset( WCPtrSList<Type> & ); void WCPtrDListIter<Type>::reset( WCPtrDList<Type> & );
In the iterators for doubly linked lists only:
int insert( Type * );
The following member operators are declared in the public interface:
int operator ()(); int operator ++(); int operator +=( int );
In the iterators for doubly linked lists only:
int operator --(); int operator -=( int );
WCPtrSList::forAll(), WCPtrDList::forAll()
create a WCPtrSListIter<Type> object
#include <wclistit.h> public: WCPtrSListIter(); WCPtrSListIter( WCPtrSList<Type> & );
There are two forms of the public WCPtrSListIter<Type> constructor:
The public WCPtrSListIter<Type> constructor creates an initialized WCPtrSListIter object.
WCPtrSListIter<Type>::~WCPtrSListIter(), WCPtrSListIter<Type>::operator ()(), WCPtrSListIter<Type>::operator ++(), WCPtrSListIter<Type>::operator +=(), WCPtrSListIter<Type>::reset()
destroy a WCPtrSListIter<Type> object
#include <wclistit.h> public: ~WCPtrSListIter();
This public member function is the destructor for the WCPtrSListIter<Type> class. The call to it is inserted implicitly by the compiler at the point where the WCPtrSListIter object goes out of scope.
The WCPtrSListIter object is destroyed.
WCPtrSListIter<Type>::WCPtrSListIter()
create a WCPtrDListIter<Type> object
#include <wclistit.h> public: WCPtrDListIter(); WCPtrDListIter( WCPtrDList<Type> & );
There are two forms of the public WCPtrDListIter<Type> constructor:
The public WCPtrDListIter<Type> constructor creates an initialized WCPtrDListIter object.
WCPtrDListIter<Type>::~WCPtrDListIter(), WCPtrDListIter<Type>::operator ()(), WCPtrDListIter<Type>::operator ++(), WCPtrDListIter<Type>::operator +=(), WCPtrDListIter<Type>::reset()
destroy a WCPtrDListIter<Type> object
#include <wclistit.h> public: ~WCPtrDListIter();
This public member function is the destructor for the WCPtrDListIter<Type> class. The call to it is inserted implicitly by the compiler at the point where the WCPtrDListIter object goes out of scope.
The WCPtrDListIter object is destroyed.
WCPtrDListIter<Type>::WCPtrDListIter()
add a new element after the current iterator item
#include <wclistit.h> public: int append( Type * );
The append() public member function inserts a new element into the list container object. The new element is inserted after the current iterator item.
If the iterator isn't associated with a list or the iterator position is either before the first element or past the last element in the list, the current iterator position is undefined. The element isn't appended. If the undef_iter exception is enabled, it's thrown.
If the append fails, the out_of_memory exception is thrown, if it's enabled in the list being iterated over. The list remains unchanged.
The new element is inserted after the current iterator item. A TRUE value (non-zero) is returned if the append is successful; FALSE (zero) is returned if it fails.
WCExcept::out_of_memory, WCIterExcept::undef_iter, WCPtrDListIter<Type>::insert(), WCPtrSListIter<Type>::insert()
return a pointer to the list container object
#include <wclistit.h>
public:
WCPtrSList<Type> *
WCPtrSListIter<Type>::container() const;
WCPtrDList<Type> *
WCPtrDListIter<Type>::container() const;
The container() public member function returns a pointer to the list container object. If the iterator hasn't been initialized with a list object, and the undef_iter exception is enabled, the exception is thrown.
A pointer to the list object associated with the iterator is returned, or NULL(0) if the iterator hasn't been initialized with a list.
WCIterExcept::undef_iter, WCPtrSListIter<Type>::WCPtrSListIter(), WCPtrDListIter<Type>::WCPtrDListIter(), WCPtrDListIter<Type>::reset(), WCPtrSListIter<Type>::reset()
get the element at the current iterator position
#include <wclistit.h> public: Type * current();
The current() public member function returns a pointer to the list element at the current iterator position.
If the iterator isn't associated with a list or the iterator position is either before the first element or past the last element in the list, the current iterator position is undefined. In this case the undef_item exception is thrown, if enabled.
A pointer to the current list element is returned. If the current element is undefined, an uninitialized pointer is returned.
WCIterExcept::undef_item, WCPtrDListIter<Type>::operator ()(), WCPtrSListIter<Type>::operator ()(), WCPtrDListIter<Type>::operator ++(), WCPtrSListIter<Type>::operator ++(), WCPtrDListIter<Type>::operator +=(), WCPtrSListIter<Type>::operator +=(), WCPtrDListIter<Type>::operator --(), WCPtrDListIter<Type>::operator -=(), WCPtrDListIter<Type>::reset(), WCPtrSListIter<Type>::reset()
insert a new element in the list
#include <wclistit.h> public: int insert( Type * );
The insert() public member function inserts a new element into the list container object. The new element is inserted before the current iterator item. This process uses the previous link in the doubly linked list, so the insert() public member function isn't allowed with singly linked lists.
If the iterator isn't associated with a list or the iterator position is either before the first element or past the last element in the list, the current iterator position is undefined. The element isn't inserted. If the undef_iter exception is enabled, the exception is thrown.
If the insertion fails and the out_of_memory exception is enabled in the list being iterated over, the exception is thrown. The list remains unchanged.
The new element is inserted before the current iterator item. A TRUE value (non-zero) is returned if the insertion is successful; FALSE (zero) is returned if it fails.
WCExcept::out_of_memory, WCIterExcept::undef_iter, WCPtrDListIter<Type>::append()
advance the iterator in the list
#include <wclistit.h> public: int operator ()();
The operator ()() public member function is the call operator for the class. The list element that follows the current item is set to be the new current item. If the previous current item was the last element in the list, the iterator is positioned after the end of the list.
The operator ()() public member function has the same semantics as the pre-increment operator, operator ++().
If the iterator was positioned before the first list element, the current item is set to the first element. If the list is empty, the iterator is positioned after the end of the list.
If the iterator isn't associated with a list or the iterator position before the increment was past the last element in the list, the undef_iter exception is thrown, if enabled.
The operator ()() public member function returns a non-zero value if the iterator is positioned on a list item. Zero(0) is returned when the iterator is incremented past the end of the list.
WCIterExcept::undef_iter, WCPtrDListIter<Type>::operator ++(), WCPtrSListIter<Type>::operator ++(), WCPtrDListIter<Type>::operator +=(), WCPtrSListIter<Type>::operator +=(), WCPtrDListIter<Type>::operator --(), WCPtrDListIter<Type>::operator -=(), WCPtrDListIter<Type>::reset(), WCPtrSListIter<Type>::reset()
advance the iterator in the list
#include <wclistit.h> public: int operator ++();
The operator ++() public member function is the pre-increment operator for the class. The list element that follows the current item is set to be the new current item. If the previous current item was the last element in the list, the iterator is positioned after the end of the list.
The operator ++() public member function has the same semantics as the call operator, operator ()().
The current item is set to the first list element if the iterator was positioned before the first element in the list. If the list is empty, the iterator is positioned after the end of the list.
If the iterator isn't associated with a list or the iterator position before the increment was past the last element in the list, the undef_iter exception is thrown, if enabled.
The operator ++() public member function returns a non-zero value if the iterator is positioned on a list item. Zero(0) is returned when the iterator is incremented past the end of the list.
WCIterExcept::undef_iter, WCPtrDListIter<Type>::current(), WCPtrSListIter<Type>::current(), WCPtrDListIter<Type>::operator ()(), WCPtrSListIter<Type>::operator ()(), WCPtrDListIter<Type>::operator +=(), WCPtrSListIter<Type>::operator +=(), WCPtrDListIter<Type>::operator --(), WCPtrDListIter<Type>::operator -=(), WCPtrDListIter<Type>::reset(), WCPtrSListIter<Type>::reset()
advance the iterator a number of times in the list
#include <wclistit.h> public: int operator +=( int );
The operator +=() public member function accepts an integer value that causes the iterator to move that many elements after the current item. If the iterator was positioned before the first element in the list, the operation sets the current item to be the given element in the list.
If the current item was after the last element in the list previous to the iteration, and the undef_iter exception is enabled, the exception is thrown. Attempting to increment the iterator position more than one element after the end of the list or by less than one element causes the iter_range exception to be thrown, if enabled.
The operator +=() public member function returns a non-zero value if the iterator is positioned on a list item. Zero(0) is returned when the iterator is incremented past the end of the list.
WCIterExcept::iter_range, WCIterExcept::undef_iter, WCPtrDListIter<Type>::current(), WCPtrSListIter<Type>::current(), WCPtrDListIter<Type>::operator ()(), WCPtrSListIter<Type>::operator ()(), WCPtrDListIter<Type>::operator ++(), WCPtrSListIter<Type>::operator ++(), WCPtrDListIter<Type>::operator --(), WCPtrDListIter<Type>::operator -=(), WCPtrDListIter<Type>::reset(), WCPtrSListIter<Type>::reset()
move the iterator backward in the list
#include <wclistit.h> public: int operator --();
The operator --() public member function is the pre-decrement operator for the class. The list element previous to the current item is set to be the new current item:
If the iterator isn't associated with a list or the iterator position previous to the decrement was before the first element in the list, the undef_iter exception is thrown, if enabled.
The operator --() public member function returns a non-zero value if the iterator is positioned on a list item. Zero(0) is returned when the iterator is decremented past the first element of the list.
WCIterExcept::undef_iter, WCPtrDListIter<Type>::current(), WCPtrDListIter<Type>::operator ()(), WCPtrDListIter<Type>::operator ++(), WCPtrDListIter<Type>::operator +=(), WCPtrDListIter<Type>::operator -=(), WCPtrDListIter<Type>::reset()
move the iterator backward a number of times in the list
#include <wclistit.h> public: int operator -=( int );
The operator -=() public member function accepts an integer value that causes the iterator to move that many elements before the current item. If the iterator was positioned after the last element in the list, the operation sets the current item to be the given number of elements from the end of the list.
If the current item was before the first element in the list previous to the iteration, and the undef_iter exception is enabled, the exception is thrown. Attempting to decrement the iterator position more than one element before the beginning of the list or by less than one element causes the iter_range exception to be thrown, if enabled.
The operator -=() public member function returns a non-zero value if the iterator is positioned on a list item. Zero(0) is returned when the iterator is decremented past the first element in the list.
WCIterExcept::iter_range, WCIterExcept::undef_iter, WCPtrDListIter<Type>::current(), WCPtrDListIter<Type>::operator ()(), WCPtrDListIter<Type>::operator ++(), WCPtrDListIter<Type>::operator +=(), WCPtrDListIter<Type>::operator --(), WCPtrDListIter<Type>::reset()
position the iterator before the first element in the list
#include <wclistit.h>
public:
void reset();
void WCPtrSListIter<Type>::reset(
WCPtrSList<Type> & );
void WCPtrDListIter<Type>::reset(
WCPtrDList<Type> & );
The first form of the reset() public member function resets the iterator to the initial state, positioning the iterator before the first element in the associated list.
The second and third forms reset the iterator to operate on the specified list. The iterator is positioned before the first element in the list.
The iterator is positioned before the first list element.
WCPtrSListIter<Type>::WCPtrSListIter(), WCPtrDListIter<Type>::WCPtrDListIter(), WCPtrDListIter<Type>::container(), WCPtrSListIter<Type>::container()
wclistit.h
The WCValConstSListIter<Type> and WCValConstDListIter<Type> classes are the templated classes used to create iterator objects for constant singly and doubly linked list objects. These classes may be used to iterate over non-constant lists, but the WCValDListIter<Type> and WCValSListIter<Type> classes provide additional functionality for only non-constant lists.
In the description of each member function, the text Type is used to indicate the list element type specified as the template parameter.
The WCIterExcept class is a base class of the WCValConstDListIter<Type> and WCValConstSListIter<Type> classes, and provides the exceptions() member function. This member function controls the exceptions that can be thrown by the WCValConstDListIter<Type> and WCValConstSListIter<Type> objects. No exceptions are enabled unless they're set by the exceptions() member function.
Some functionality supported by base classes of the iterator isn't appropriate for the constant list iterator classes. Setting those functions as private members in the derived class is the standard mechanism to prevent them from being invoked.
int append( Type & ); int insert( Type & );
The following member functions are declared in the public interface:
WCValConstSListIter();
WCValConstSListIter( const WCValSList<Type> & );
~WCValConstSListIter();
WCValConstDListIter();
WCValConstDListIter( const WCValDList<Type> & );
~WCValConstDListIter();
const WCValSList<Type> *
WCValConstSListIter<Type>::container() const;
const WCValDList<Type> *
WCValConstDListIter<Type>::container() const;
Type current() const;
void reset();
void WCValConstSListIter<Type>::reset(
const WCValSList<Type> & );
void WCValConstDListIter<Type>::reset(
const WCValDList<Type> & );
The following member operators are declared in the public interface:
int operator ()(); int operator ++(); int operator +=( int );
In the iterators for doubly linked lists only:
int operator --(); int operator -=( int );
WCValSList::forAll(), WCValDList::forAll()
create a WCValConstSListIter<Type> object
#include <wclistit.h> public: WCValConstSListIter(); WCValConstSListIter( const WCValSList<Type> & );
There are two forms of the public WCValConstSListIter<Type> constructor:
The public WCValConstSListIter<Type> constructor creates an initialized WCValConstSListIter object.
WCValConstSListIter<Type>::~WCValConstSListIter(), WCValConstSListIter<Type>::operator ()(), WCValConstSListIter<Type>::operator ++(), WCValConstSListIter<Type>::operator +=(), WCValConstSListIter<Type>::reset()
destroy a WCValConstSListIter<Type> object
#include <wclistit.h> public: ~WCValConstSListIter();
This public member function is the destructor for the WCValConstSListIter<Type> class. The call to it is inserted implicitly by the compiler at the point where the WCValConstSListIter object goes out of scope.
The WCValConstSListIter object is destroyed.
WCValConstSListIter<Type>::WCValConstSListIter()
create a WCValConstDListIter<Type> object
#include <wclistit.h> public: WCValConstDListIter(); WCValConstDListIter( const WCValDList<Type> & );
There are two forms of the public WCValConstDListIter<Type> constructor:
The public WCValConstDListIter<Type> constructor creates an initialized WCValConstDListIter object.
WCValConstDListIter<Type>::~WCValConstDListIter(), WCValConstDListIter<Type>::operator ()(), WCValConstDListIter<Type>::operator ++(), WCValConstDListIter<Type>::operator +=(), WCValConstDListIter<Type>::reset()
destroy a WCValConstDListIter<Type> object
#include <wclistit.h> public: ~WCValConstDListIter();
This public member function is the destructor for the WCValConstDListIter<Type> class. The call to it is inserted implicitly by the compiler at the point where the WCValConstDListIter object goes out of scope.
The WCValConstDListIter object is destroyed.
WCValConstDListIter<Type>::WCValConstDListIter()
return a pointer to the list container object
#include <wclistit.h>
public:
const WCValSList<Type> *
WCValSListIter<Type>::container() const;
const WCValDList<Type> *
WCValDListIter<Type>::container() const;
The container() public member function returns a pointer to the list container object. If the iterator hasn't been initialized with a list object, and the undef_iter exception is enabled, the exception is thrown.
A pointer to the list object associated with the iterator is returned, or NULL(0) if the iterator hasn't been initialized with a list.
WCIterExcept::undef_iter, WCValConstSListIter<Type>::WCValConstSListIter(), WCValConstDListIter<Type>::WCValConstDListIter(), WCValConstDListIter<Type>::reset(), WCValConstSListIter<Type>::reset()
get the element at the current iterator position
#include <wclistit.h> public: Type current();
The current() public member function returns the value of the list element at the current iterator position.
If the iterator isn't associated with a list, or the iterator position is either before the first element or past the last element in the list, the current iterator position is undefined. In this case the undef_item exception is thrown, if enabled.
The value at the current iterator element is returned. If the current element is undefined, a default initialized object is returned.
WCIterExcept::undef_item, WCValConstDListIter<Type>::operator ()(), WCValConstSListIter<Type>::operator ()(), WCValConstDListIter<Type>::operator ++(), WCValConstSListIter<Type>::operator ++(), WCValConstDListIter<Type>::operator +=(), WCValConstSListIter<Type>::operator +=(), WCValConstDListIter<Type>::operator --(), WCValConstDListIter<Type>::operator -=(), WCValConstDListIter<Type>::reset(), WCValConstSListIter<Type>::reset()
advance the iterator in the list
#include <wclistit.h> public: int operator ()();
The operator ()() public member function is the call operator for the class. The list element that follows the current item is set to be the new current item. If the previous current item was the last element in the list, the iterator is positioned after the end of the list.
The operator ()() public member function has the same semantics as the pre-increment operator, operator ++().
If the iterator was positioned before the first list element, the current item is set to the first element. If the list is empty, the iterator is positioned after the end of the list.
If the iterator isn't associated with a list or the iterator position before the increment was past the last element in the list, the undef_iter exception is thrown, if enabled.
The operator ()() public member function returns a non-zero value if the iterator is positioned on a list item. Zero(0) is returned when the iterator is incremented past the end of the list.
WCIterExcept::undef_iter, WCValConstDListIter<Type>::operator ++(), WCValConstSListIter<Type>::operator ++(), WCValConstDListIter<Type>::operator +=(), WCValConstSListIter<Type>::operator +=(), WCValConstDListIter<Type>::operator --(), WCValConstDListIter<Type>::operator -=(), WCValConstDListIter<Type>::reset(), WCValConstSListIter<Type>::reset()
advance the iterator in the list
#include <wclistit.h> public: int operator ++();
The operator ++() public member function is the pre-increment operator for the class. The list element that follows the current item is set to be the new current item. If the previous current item was the last element in the list, the iterator is positioned after the end of the list.
The operator ++() public member function has the same semantics as the call operator, operator ()().
The current item is set to the first list element if the iterator was positioned before the first element in the list. If the list is empty, the iterator is positioned after the end of the list.
If the iterator isn't associated with a list or the iterator position before the increment was past the last element in the list, the undef_iter exception is thrown, if enabled.
The operator ++() public member function returns a non-zero value if the iterator is positioned on a list item. Zero(0) is returned when the iterator is incremented past the end of the list.
WCIterExcept::undef_iter, WCValConstDListIter<Type>::current(), WCValConstSListIter<Type>::current(), WCValConstDListIter<Type>::operator ()(), WCValConstSListIter<Type>::operator ()(), WCValConstDListIter<Type>::operator +=(), WCValConstSListIter<Type>::operator +=(), WCValConstDListIter<Type>::operator --(), WCValConstDListIter<Type>::operator -=(), WCValConstDListIter<Type>::reset(), WCValConstSListIter<Type>::reset()
advance the iterator in the list a number of times
#include <wclistit.h> public: int operator +=( int );
The operator +=() public member function accepts an integer value that causes the iterator to move that many elements after the current item. If the iterator was positioned before the first element in the list, the operation sets the current item to be the given element in the list.
If the current item was after the last element in the list previous to the iteration, and the undef_iter exception is enabled, the exception is thrown. Attempting to increment the iterator position more than one element after the end of the list, or by less than one element causes the iter_range exception to be thrown, if enabled.
The operator +=() public member function returns a non-zero value if the iterator is positioned on a list item. Zero(0) is returned when the iterator is incremented past the end of the list.
WCIterExcept::iter_range, WCIterExcept::undef_iter, WCValConstDListIter<Type>::current(), WCValConstSListIter<Type>::current(), WCValConstDListIter<Type>::operator ()(), WCValConstSListIter<Type>::operator ()(), WCValConstDListIter<Type>::operator ++(), WCValConstSListIter<Type>::operator ++(), WCValConstDListIter<Type>::operator --(), WCValConstDListIter<Type>::operator -=(), WCValConstDListIter<Type>::reset(), WCValConstSListIter<Type>::reset()
move the iterator backward in the list
#include <wclistit.h> public: int operator --();
The operator --() public member function is the pre-decrement operator for the class. The list element previous to the current item is set to be the new current item:
If the iterator isn't associated with a list or the iterator position previous to the decrement was before the first element in the list, the undef_iter exception is thrown, if enabled.
The operator --() public member function returns a non-zero value if the iterator is positioned on a list item. Zero(0) is returned when the iterator is decremented past the first element of the list.
WCIterExcept::undef_iter, WCValConstDListIter<Type>::current(), WCValConstDListIter<Type>::operator ()(), WCValConstDListIter<Type>::operator ++(), WCValConstDListIter<Type>::operator +=(), WCValConstDListIter<Type>::operator -=(), WCValConstDListIter<Type>::reset()
move the iterator backward in the list a number of times
#include <wclistit.h> public: int operator -=( int );
The operator -=() public member function accepts an integer value that causes the iterator to move that many elements before the current item. If the iterator was positioned after the last element in the list, the operation sets the current item to be the given number of elements from the end of the list.
If the current item was before the first element in the list previous to the iteration, and the undef_iter exception is enabled, the exception is thrown. Attempting to decrement the iterator position more than one element before the beginning of the list, or by less than one element causes the iter_range exception to be thrown, if enabled.
The operator -=() public member function returns a non-zero value if the iterator is positioned on a list item. Zero(0) is returned when the iterator is decremented past the first element in the list.
WCIterExcept::iter_range, WCIterExcept::undef_iter, WCValConstDListIter<Type>::current(), WCValConstDListIter<Type>::operator ()(), WCValConstDListIter<Type>::operator ++(), WCValConstDListIter<Type>::operator +=(), WCValConstDListIter<Type>::operator --(), WCValConstDListIter<Type>::reset()
position the iterator before the first element in the list
#include <wclistit.h>
public:
void reset();
void WCValSListIter<Type>::reset(
const WCValSList<Type> & );
void WCValDListIter<Type>::reset(
const WCValDList<Type> & );
The first form of the reset() public member function resets the iterator to the initial state, positioning the iterator before the first element in the associated list.
The second and third forms reset the iterator to operate on the specified list. The iterator is positioned before the first element in the list.
The iterator is positioned before the first list element.
WCValConstSListIter<Type>::WCValConstSListIter(), WCValConstDListIter<Type>::WCValConstDListIter(), WCValConstDListIter<Type>::container(), WCValConstSListIter<Type>::container()
wclistit.h
The WCValDListIter<Type> and WCValSListIter<Type> classes are the templated classes used to create iterator objects for singly and doubly linked list objects. These classes can be used only for non-constant lists. The WCValConstDListIter<Type> and WCValConstSListIter<Type> classes are provided to iterate over constant lists.
In the description of each member function, the text Type is used to indicate the list element type specified as the template parameter.
The WCIterExcept class is a base class of the WCValConstDListIter<Type> and WCValConstSListIter<Type> classes, and provides the exceptions() member function. This member function controls the exceptions that can be thrown by the WCValConstDListIter<Type> and WCValConstSListIter<Type> objects. No exceptions are enabled unless they're set by the exceptions() member function.
Some functionality supported by base classes of the iterator isn't appropriate in the singly linked list iterator classes. Setting those functions as private members in the derived class is the standard mechanism to prevent them from being invoked. The following member functions are declared in the singly linked list iterator private interface:
int operator --(); int operator -=( int ); int insert( Type & );
The following member functions are declared in the public interface:
WCValSListIter(); WCValSListIter( WCValSList<Type> & ); ~WCValSListIter(); WCValDListIter(); WCValDListIter( WCValDList<Type> & ); ~WCValDListIter(); int append( Type & ); WCValSList<Type> * WCValSListIter<Type>::container() const; WCValDList<Type> * WCValDListIter<Type>::container() const; Type current() const; void reset(); void WCValSListIter<Type>::reset( WCValSList<Type> & ); void WCValDListIter<Type>::reset( WCValDList<Type> & );
In the iterators for doubly linked lists only:
int insert( Type & );
The following member operators are declared in the public interface:
int operator ()(); int operator ++(); int operator +=( int );
In the iterators for doubly linked lists only:
int operator --(); int operator -=( int );
WCValSList::forAll(), WCValDList::forAll()
#include <wclistit.h>
#include <iostream.h>
//
// insert elem after all elements in the list less than
// or equal to elem
//
void insert_in_order( WCValDList<int> &list, int elem ) {
if( list.entries() == 0 ) {
// cannot insert in an empty list using a iterator
list.insert( elem );
} else {
WCValDListIter<int> iter( list );
while( ++iter ) {
if( iter.current() > elem ) {
// insert elem before first element in list
// greater than elem
iter.insert( elem );
return;
}
}
// iterated past the end of the list
// append elem to the end of the list
list.append( elem );
}
}
void main() {
WCValDList<int> list;
insert_in_order( list, 5 );
insert_in_order( list, 20 );
insert_in_order( list, 1 );
insert_in_order( list, 25 );
cout << "List elements in ascending order:\n";
WCValDListIter<int> iter( list );
while( ++iter ) {
cout << iter.current() << "\n";
}
cout << "List elements in descending order\n";
// iterator is past the end of the list
while( --iter ) {
cout << iter.current() << "\n";
}
}
create a WCValSListIter<Type> object
#include <wclistit.h> public: WCValSListIter(); WCValSListIter( WCValSList<Type> & );
There are two forms of the public WCValSListIter<Type> constructor:
The public WCValSListIter<Type> constructor creates an initialized WCValSListIter object.
WCValSListIter<Type>::~WCValSListIter(), WCValSListIter<Type>::operator ()(), WCValSListIter<Type>::operator ++(), WCValSListIter<Type>::operator +=(), WCValSListIter<Type>::reset()
destroy a WCValSListIter<Type> object
#include <wclistit.h> public: ~WCValSListIter();
This public member function is the destructor for the WCValSListIter<Type> class. The call to it is inserted implicitly by the compiler at the point where the WCValSListIter object goes out of scope.
The WCValSListIter object is destroyed.
WCValSListIter<Type>::WCValSListIter()
create a WCValDListIter<Type> object
#include <wclistit.h> public: WCValDListIter(); WCValDListIter( WCValDList<Type> & );
There are two forms of the public WCValDListIter<Type> constructor:
The public WCValDListIter<Type> constructor creates an initialized WCValDListIter object.
WCValDListIter<Type>::~WCValDListIter(), WCValDListIter<Type>::operator ()(), WCValDListIter<Type>::operator ++(), WCValDListIter<Type>::operator +=(), WCValDListIter<Type>::reset()
destroy a WCValDListIter<Type> object
#include <wclistit.h> public: ~WCValDListIter();
This public member function is the destructor for the WCValDListIter<Type> class. The call to it is inserted implicitly by the compiler at the point where the WCValDListIter object goes out of scope.
The WCValDListIter object is destroyed.
WCValDListIter<Type>::WCValDListIter()
insert an element after the current iterator item
#include <wclistit.h> public: int append( Type & );
The append() public member function inserts a new element into the list container object. The new element is inserted after the current iterator item.
If the iterator isn't associated with a list, or the iterator position is either before the first element or past the last element in the list, the current iterator position is undefined. The element isn't appended. If the undef_iter exception is enabled, it's thrown.
If the append fails, the out_of_memory exception is thrown, if enabled in the list being iterated over. The list remains unchanged.
The new element is inserted after the current iterator item. A TRUE value (non-zero) is returned if the append is successful; FALSE (zero) is returned if it fails.
WCExcept::out_of_memory, WCIterExcept::undef_iter, WCValDListIter<Type>::insert(), WCValSListIter<Type>::insert()
return a pointer to the list container object
#include <wclistit.h>
public:
WCValSList<Type> *
WCValSListIter<Type>::container() const;
WCValDList<Type> *
WCValDListIter<Type>::container() const;
The container() public member function returns a pointer to the list container object. If the iterator hasn't been initialized with a list object, and the undef_iter exception is enabled, the exception is thrown.
A pointer to the list object associated with the iterator is returned, or NULL(0) if the iterator hasn't been initialized with a list.
WCIterExcept::undef_iter, WCValSListIter<Type>::WCValSListIter(), WCValDListIter<Type>::WCValDListIter(), WCValDListIter<Type>::reset(), WCValSListIter<Type>::reset()
get the element at the current iterator position
#include <wclistit.h> public: Type current();
The current() public member function returns the value of the list element at the current iterator position.
If the iterator isn't associated with a list, or the iterator position is either before the first element or past the last element in the list, the current iterator position is undefined. In this case the undef_item exception is thrown, if enabled.
The value at the current iterator element is returned. If the current element is undefined, a default initialized object is returned.
WCIterExcept::undef_item, WCValDListIter<Type>::operator ()(), WCValSListIter<Type>::operator ()(), WCValDListIter<Type>::operator ++(), WCValSListIter<Type>::operator ++(), WCValDListIter<Type>::operator +=(), WCValSListIter<Type>::operator +=(), WCValDListIter<Type>::operator --(), WCValDListIter<Type>::operator -=(), WCValDListIter<Type>::reset(), WCValSListIter<Type>::reset()
insert an element before the iterator
#include <wclistit.h> public: int insert( Type & );
The insert() public member function inserts a new element into the list container object. The new element is inserted before the current iterator item. This process uses the previous link in the doubly linked list, so the insert() public member function isn't allowed with singly linked lists.
If the iterator isn't associated with a list, or the iterator position is either before the first element or past the last element in the list, the current iterator position is undefined. The element isn't inserted. If the undef_iter exception is enabled, the exception is thrown.
If the insertion fails and the out_of_memory exception is enabled in the list being iterated over, the exception is thrown. The list remains unchanged.
The new element is inserted before the current iterator item. A TRUE value (non-zero) is returned if the insertion is successful; FALSE (zero) is returned if it fails.
WCExcept::out_of_memory, WCIterExcept::undef_iter, WCValDListIter<Type>::append()
advance the iterator in the list
#include <wclistit.h> public: int operator ()();
The operator ()() public member function is the call operator for the class. The list element that follows the current item is set to be the new current item. If the previous current item was the last element in the list, the iterator is positioned after the end of the list.
The operator ()() public member function has the same semantics as the pre-increment operator, operator ++().
If the iterator was positioned before the first list element, the current item is set to the first element. If the list is empty, the iterator is positioned after the end of the list.
If the iterator isn't associated with a list or the iterator position before the increment was past the last element in the list, the undef_iter exception is thrown, if enabled.
The operator ()() public member function returns a non-zero value if the iterator is positioned on a list item. Zero(0) is returned when the iterator is incremented past the end of the list.
WCIterExcept::undef_iter, WCValDListIter<Type>::operator ++(), WCValSListIter<Type>::operator ++(), WCValDListIter<Type>::operator +=(), WCValSListIter<Type>::operator +=(), WCValDListIter<Type>::operator --(), WCValDListIter<Type>::operator -=(), WCValDListIter<Type>::reset(), WCValSListIter<Type>::reset()
advance the iterator in the list
#include <wclistit.h> public: int operator ++();
The operator ++() public member function is the pre-increment operator for the class. The list element that follows the current item is set to be the new current item. If the previous current item was the last element in the list, the iterator is positioned after the end of the list.
The operator ++() public member function has the same semantics as the call operator, operator ()().
The current item is set to the first list element if the iterator was positioned before the first element in the list. If the list is empty, the iterator is positioned after the end of the list.
If the iterator isn't associated with a list or the iterator position before the increment was past the last element in the list, the undef_iter exception is thrown, if enabled.
The operator ++() public member function returns a non-zero value if the iterator is positioned on a list item. Zero(0) is returned when the iterator is incremented past the end of the list.
WCIterExcept::undef_iter, WCValDListIter<Type>::current(), WCValSListIter<Type>::current(), WCValDListIter<Type>::operator ()(), WCValSListIter<Type>::operator ()(), WCValDListIter<Type>::operator +=(), WCValSListIter<Type>::operator +=(), WCValDListIter<Type>::operator --(), WCValDListIter<Type>::operator -=(), WCValDListIter<Type>::reset(), WCValSListIter<Type>::reset()
advance the iterator in the list a number of times
#include <wclistit.h> public: int operator +=( int );
The operator +=() public member function accepts an integer value that causes the iterator to move that many elements after the current item. If the iterator was positioned before the first element in the list, the operation sets the current item to be the given element in the list.
If the current item was after the last element in the list previous to the iteration, and the undef_iter exception is enabled, the exception is thrown. Attempting to increment the iterator position more than one element after the end of the list, or by less than one element causes the iter_range exception to be thrown, if it's enabled.
The operator +=() public member function returns a non-zero value if the iterator is positioned on a list item. Zero(0) is returned when the iterator is incremented past the end of the list.
WCIterExcept::iter_range, WCIterExcept::undef_iter, WCValDListIter<Type>::current(), WCValSListIter<Type>::current(), WCValDListIter<Type>::operator ()(), WCValSListIter<Type>::operator ()(), WCValDListIter<Type>::operator ++(), WCValSListIter<Type>::operator ++(), WCValDListIter<Type>::operator --(), WCValDListIter<Type>::operator -=(), WCValDListIter<Type>::reset(), WCValSListIter<Type>::reset()
move the iterator backward in the list
#include <wclistit.h> public: int operator --();
The operator --() public member function is the pre-decrement operator for the class. The list element previous to the current item is set to be the new current item:
If the iterator isn't associated with a list or the iterator position previous to the decrement was before the first element in the list, the undef_iter exception is thrown, if enabled.
The operator --() public member function returns a non-zero value if the iterator is positioned on a list item. Zero(0) is returned when the iterator is decremented past the first element of the list.
WCIterExcept::undef_iter, WCValDListIter<Type>::current(), WCValDListIter<Type>::operator ()(), WCValDListIter<Type>::operator ++(), WCValDListIter<Type>::operator +=(), WCValDListIter<Type>::operator -=(), WCValDListIter<Type>::reset()
move the iterator backward in the list a number of times
#include <wclistit.h> public: int operator -=( int );
The operator -=() public member function accepts an integer value that causes the iterator to move that many elements before the current item. If the iterator was positioned after the last element in the list, the operation sets the current item to be the given number of elements from the end of the list.
If the current item was before the first element in the list previous to the iteration, and the undef_iter exception is enabled, the exception is thrown. Attempting to decrement the iterator position more than one element before the beginning of the list, or by less than one element causes the iter_range exception to be thrown, if enabled.
The operator -=() public member function returns a non-zero value if the iterator is positioned on a list item. Zero(0) is returned when the iterator is decremented past the first element in the list.
WCIterExcept::iter_range, WCIterExcept::undef_iter, WCValDListIter<Type>::current(), WCValDListIter<Type>::operator ()(), WCValDListIter<Type>::operator ++(), WCValDListIter<Type>::operator +=(), WCValDListIter<Type>::operator --(), WCValDListIter<Type>::reset()
position the iterator before the first element in the list
#include <wclistit.h>
public:
void reset();
void WCValSListIter<Type>::reset(
WCValSList<Type> & );
void WCValDListIter<Type>::reset(
WCValDList<Type> & );
The first form of the reset() public member function resets the iterator to the initial state, positioning the iterator before the first element in the associated list.
The second and third forms reset the iterator to operate on the specified list. The iterator is positioned before the first element in the list.
The iterator is positioned before the first list element.
WCValSListIter<Type>::WCValSListIter(), WCValDListIter<Type>::WCValDListIter(), WCValDListIter<Type>::container(), WCValSListIter<Type>::container()