Parent Topic: PCLCONTA

PCLIter

PCLIter is a class associated with the PCLContainer class. It is used to iterate through all the elements in a container. A PCLIter is a light weight object that represent a "cursor" or pointer into a list. It may be placed back at the beginning of the list with the Start() method, moved ahead to the next item with the Next() method and the Current() method may be used to fetch the currently indicated item.

PCLIter objects should be restarted with Start() before further access if an object is added to, or deleted from the container class being scanned.

The PCLIter is derived from PCLObject, and so can be stored in containers and so forth.

Methods

The PCLIter() constructor takes one argument, the PCLContainer for which it will be an iterator.

PCLIter( poContainer );

const PCLContainer *    poContainer;
           Pointer to the container for which an iterator is
           to be created.  It can be NULL if the selection of
           container is to be deferred till the call to Start().

The Start() method is position the iterator at the first item in a container. It will return the pointer to the first object. It is also optionally possible to pass a container to retarget the iterator on a new container.

PCLObject * Start( poNewContainer );

const PCLContainer      *poNewContainer;
       Optional new container which defaults to NULL to indicate
       that the current container should containue to be used.

The Next() method is used to advance an iterator to the next item in a container. Calling this method repeatedly will advance the iterator through each of the elements in the container till all have been visited, at which point NULL will be returned.

PCLObject * Next();

The Current() method is used to fetch the PCLObject currently refered to by the iterator. This will be the same value as the most recent call to Start() or Next() returned. Invoking the Current() method does not affect the PCLIter object.

PCLObject * Current();

Example

The following example creates an iterator on the stack, uses it to loop over all the elements in a container and Dump()s them each in turn.

 {
    PCLIter     oIter( poStack );

    for( oIter.Start(); oIter.Current() != NULL; oIter.Next() )
    {
        oIter.Current()->Dump( stdout );
    }
 }

Parent Topic: PCLCONTA
About PCI Help Gateway