PCLArray -- Automatic Array Container

The PCLArray is a container class implemented in the form required for classes derived from PCLContainer. In addition to standard PCLContainer semantics it also provides the SetAt() and operator[] methods that offer array like access.

The PCLArray is implemented such as Add(), SetAt() and operator[] are O(1) while Remove is O(n). PCLArray is not an efficient way of representing very sparse arrays, as it creates space for all unused entries which are initialized as NULL pointers.

As is normal, the PCLIter will visit every non-NULL entry in the PCLArray starting at index zero and moving up. The GetCount() method also returns the number of non-NULL entries.

SetAt()

void    SetAt( nIndex, poObject );

int     nIndex;
           The array index at which an entry is to be set.
           This must be greater than or equal to zero.

PCLObject *poObject;
           The object pointer to assign.  This may be NULL to
           clear the entry in the array.

The SetAt() method is used to directly assign a PCLObject * to an entry in the array. It is an O(1) operation, and thus much more efficient for removing an entry from a large array than the O(n) Remove() method but presumes that the index in the array is known.

If the nIndex value is beyond the existing `end' of the array the array will automatically be extended and all new entries set to NULL.

InsertAt()

void    InsertAt( nIndex, poObject );

int     nIndex;
           The array index at which the entry is to be set.
           This must be greater than or equal to zero.

PCLObject *poObject;
           The object pointer to insert.

The InsertAt() method is used to assign a PCLObject * to an index in the array. Room is made for it.

If the nIndex value is beyond the existing `end' of the array the array will automatically be extended and all new entries set to NULL.

Indexing

PCLObject *     operator[]( nIndex );

int     nIndex;
           The index in the array from which to fetch an item.

The operator[] method is used to fetch the PCLObject * from a location in the PCLArray. If the entry is empty or the passed index is out of bounds a NULL is returned.

Pack()

void    Pack();

The Pack() method will compact all the items in the PCLArray to be in the positions 0 to n-1 where n is the number of entries in the array.

Example

 poArray->Pack();
 for( i = 0; i < poArray->GetCount(); i++ )
    poArray[i]->Dump();

Sort()

void    Sort(QSCMP);

QSCMP   pfnCompFunc;
       A function of the type QSCMP (see pci.h). It is a comparison
       function used by qsort.

The sort() method will sort the array using the comparison function that is passed in. The comparison function should be the same type used by qsort.

Example

 int ObjectCompare QSANSICMPFUNC (pObject1, pObject2)
 {
     PCLObject**   ppoObject1 = (PCLObject**) pObject1;
     PCLObject**   ppoObject2 = (PCLObject**) pObject2;
 
 
     if (*ppoObject1 > *ppoObject2);
        return(1);
     else if (*ppoObject1 < *ppoObject2)
        return(-1);
     else 
        return(0);
 }

GetMaxIndex()

int     GetMaxIndex();

The GetMaxIndex() method is used to fetch the index of the last entry used in the PCLArray. This can be used as an upper bound for scans of the array. Note that the returned value may be slightly higher than the real maximum index, so it should not be assumed that oArray[oArray.GetMaxIndex()] is not NULL.

Example

The following example shows looping over the occupied portion of a PCLArray and deleting all elements with a class name of PCLString.

    int         i;

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

Reverse()

void Reverse( void );

The Reverse() method takes all of the objects in the array and places them in reverse order. It also packs the array in the reverse order. Reverse() is not friendly with iterators so perform the reverse before or after iteration.

About PCI Help Gateway