PCLObject -- Universal Base Class

The PCLObject class serves as a base class for all but the most lightweight of classes in the PCI Class Library (PCL). It provides a standard set of services including run time class identification, a virtual destructor, standard debug methods, and a method for associating keys with objects for sorting and searching purposes.

Perhaps more importantly, sharing the PCLObject base class gives a convenient base class by which item may be placed in placed in container objects. Only classes derived from PCLObject may be placed in PCLContainer classes.

See Also: PCLContainer

GetClassName()

const char  *GetClassName();
The GetClassName() method returns a pointer to the name of the class of the object on which it is invoked. This string may be used in debug messages, and may be checked to perform run time time checking, and run time type based operations.

It is guarenteed that all objects of a particular type will return a pointer to the same string, meaning that in many situations it is sufficient to compare the pointers returned by GetClassName() rather than doing a character by character string comparison.

The class name returned should always be exactly the same as the name by which the class is defined in the "class" statement.

The following example will remove all objects of the class PCLString from the container poArray. 

    int         i;

    for( i = 0; i < poArray->GetMaxIndex(); i++ )
    {
        if( poArray[i] != NULL 
            && EQUAL(poArray[i]->GetClassName(),"PCLString") )
            poArray->SetAt( i, NULL );
    }

Validate()

TBool   Validate();
This function provides a virtual method for PCObject's to perform a diagnositic self check, and return TRUE if things are OK and FALSE if there is a problem.

The following assertion verifies that the PCLTree object is in a valid state. If Validate() returns FALSE, the assertion will be triggered and an error reported. 

    IMPAssert( poTree->Validate() );

Dump()

void    Dump( fp );

FILE    *fp;
           The text file to write the dump information to.  This
           is often stdout or stderr.
Dump() a textual representation of the object to this text file. This method is primarily used for debugging purposes.

The following statement invokes the Dump() method on a container. The Dump() method on containers dumps some general information about the container, and then invokes the Dump() method on each of the PCLObject's in the container. 

    oTree.Dump( stdout  );

Deriving from PCLObject

To write a class derived from PCLObject the one service that is absolutely required is a GetClassName() method. As well, it is suggested that a Dump() method be provided, and if appropriate a Validate() method.

Also ensure that the class destructor is virtual so that a generic PCLObject * can be used to delete any derived class properly.

The PCLIndexedData class is a fairly trivial PCLObject class used primarily for testing. It provides all the required methods. Note that the GetClassName() should not be declared as an inline function in the include file, or else a seperate copy of the string constant may be instantiated for each module the include is included in. Not only is this a waste of space, it also makes it impossible to compare the pointer to the classnames of different objects to see if they are of the same class. 

 class PCLIndexedData : public PCLObject
 {
   public:
     int        iIndex;
     void       *pData;

                PCLIndexedData( int iIndex, void *pData )
                { this->iIndex = iIndex; this->pData = pData; }
     virtual const char *GetClassName() const; 
     virtual void       Dump( FILE *fp ) const
              { fprintf(fp,"PCLIndexedData:%d:%lx\n",iIndex,pData); }
 };

 const char * PCLIndexedData::GetClassName()

 {
         return( "PCLIndexedData" );
 }
About PCI Help Gateway