PCLContainer -- Container Base Class

The PCLContainer class is an abstract base class for a variety of container classes which may hold any object derived from PCLObject. The PCLContainer is itself derived from PCLObject implying that a PCLContainer can itself contain references to PCLContainers.

See Also: PCLArray, PCLTree, PCLBag, PCLObject, PCLIter

Constructor

The PCLContainer has two constructors. One with no arguments for creating a empty container, and one taking another PCLContainer * as an argument from which to initialize the container (a copy constructor).

IsEmpty()

This method function returns TRUE if the PCLContainer contains no PCLObjects, otherwise it returns FALSE.

TBool   IsEmpty() const;

This function is equivelent to testing if GetCount() == 0 on the same object. The following example is used to report an error if no items are passed to a processing function.

    if( poBag->IsEmpty() )
        IMPError( 11, ERRTYP_PFATAL,
                  "No objects passed to function PCLDoIt()\n");

GetCount()

The GetCount() method returns the number of elements in the container on which it is invoked.

int     GetCount() const;

Verify that a modest number of elements are in the group to be processed.

    IMPAssert( poBag->GetCount() < 1000 );

IsMember()

The IsMember() function is used to test if a particular PCLObject is in the provided container.

int     IsMember( poTestObject );

PCLObject * poTestObject;
           The object to test for in the container.

The following adds a new vector to the list if it is not already present.

    if( !poWin->poVectorList->IsMember( poThisLayer ) )
    {
        poWin->poVectorList->Add( poThisLayer );
    }

Add()

The Add() method is used to add a single PCLObject to a container. Whether multiple copies of an object can be kept in a container, and concepts of ordering are specific to the derived container implementation.

void    Add( poObject );

PCLObject * poObject;
           The PCLObject to be added to the container.

The following adds a new vector to the list if it is not already present.

    if( !poWin->poVectorList->IsMember( poThisLayer ) )
    {
        poWin->poVectorList->Add( poThisLayer );
    }

Remove()

The Remove() method is used to remove one reference to the indicated object from a container. If the object is not found the call returns FALSE, otherwise TRUE is returned. Note this only removes a reference from the container, and does not destroy the object.

TBool   Remove( poObject );

PCLObject * poObject;
           The object to search for, and remove if found.

Remove an object, and emit a debug message if it is not found.

    if( !poBag->Remove( poThisLayer ) )
        Debug( "Unable to remove layer %s in display list\n",
               poThisLayer->GetName() );

AddContainer()

This method will add a reference to all PCLObjects in the passed container to the container on which the function is invoked. This does not remove the object references from the source container.

void    AddContainer( poBag );

PCLContainer * poBag;
           The container from which object references are to be
           copied.

DestroyContents()

The DestroyContents() method is used to delete all objects for which a reference is contained in the given container. As well the object references are removed from the container. The objects are destroyed by invoking the destructor with the delete operator.

void    DestroyContents();

The DestroyMatchingEvents() function uses the FetchMatchingEvents() method to get a container of events matching a given criteria. DestroyContents is used to destroy all the events, and then the container itself is destroyed.

 PCLContainer * poEvents;

 IMPAssert( gpoDispatcher != NULL );

 poEvents = 
  gpoDispatcher->FetchMatchingEvents( ePriority, nCode, 
                                      poObject, poRequestor,
                                      pfnCBProc, pCBData );
 poEvents->DestroyContents();

 delete poEvents;

Empty()

The Empty() method re-initializes a container to be empty.

void    Empty();

Validate()

TBool   Validate() const;

The validate method is inherited from PCLObject. The default PCLContainer implementation does do much with the container itself, but it does also attempt to validate each of the objects in the container.

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 );
    }
 }

Writing a Container Class

New container classes must be derived from PCLContainer, and must implement the following methods.

a copy constructor taking a PCLContainer *.
IsMember()
Add()
Remove()
Start(): Initialize information related to a PCLIter
Next(): Move PCLIter to next item
GetClassName() (because it is a PCLObject)

The container class may also implement some of the other PCLObject related methods such as Validate(), Dump(), Compare() and Key() though this is not required. The Empty() method may be implemented if the default iterator based solution is judged to be too slow. As well, some container classes will want to add some methods related to semantics specific to that class. For instance an "array" might implement the index operator, and a tree might want to offer

The IsMember(), Add() and Remove() methods are adequately described above; however the Start() and Next() methods require further elaboration.

These are used to implement support for the PCLIter friend class. The Start() and Next() method take a (PCLIter *) as an argument. These methods are permitted to update the public pState data item in the PCLIter to keep track of the location of that iterator. The Start() method should return the "first" object in the container, while the Next() method should return the object after the Current() one in the iterator.

Maintaining the protected nCount data item inheirited from the PCLContainer class is also a reponsibility of each derived container class. The nCount field is expected to contain the current number of items in the container and is used to implement the IsEmpty() and GetCount() methods on the container. This field is automatically initialized to zero on container construction.

About PCI Help Gateway