pfList(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfList(3pf)NAMEpfList - Dynamically-sized list utility
FUNCTION SPECIFICATION
#include <Performer/pr/pfList.h>
pfList::pfList();
pfList::pfList(int eltSize, int listLength);
static pfType * pfList::getClassType(void);
void pfList::add(void* elt);
void pfList::combine(const pfList *a, const pfList *b);
int pfList::fastRemove(void* elt);
void pfList::fastRemoveIndex(int index);
void * pfList::get(int index);
const void ** pfList::getArray(void);
int pfList::getArrayLen(void);
int pfList::getEltSize(void);
int pfList::getNum(void);
void pfList::insert(int index, void* elt);
void pfList::move(int index, void *elt);
void pfList::setArrayLen(int len);
void pfList::setNum(int num);
int pfList::remove(void* elt);
void pfList::removeIndex(int index);
int pfList::replace(void* old, void* new);
void pfList::reset(void);
int pfList::search(void* elt);
void pfList::set(int index, void *elt);
Page 1
pfList(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfList(3pf)PARENT CLASS FUNCTIONS
The OpenGL Performer class pfList is derived from the parent class
pfObject, so each of these member functions of class pfObject are also
directly usable with objects of class pfList. This is also true for
ancestor classes of class pfObject.
void* pfObject::operator new(size_t);
void* pfObject::operator new(size_t, void *arena);
void* pfObject::operator new(size_t, pfFluxMemory *fmem);
void pfObject::setUserData(void *data);
void pfObject::setUserData(int slot, void *data);
void* pfObject::getUserData(pfObject *obj);
void* pfObject::getUserData(pfObject *obj, int slot);
int pfObject::getNumUserData();
Since the class pfObject is itself derived from the parent class
pfMemory, objects of class pfList can also be used with these functions
designed for objects of class pfMemory.
void* pfMemory::getData(const void *ptr);
pfType * pfMemory::getType();
int pfMemory::isOfType(pfType *type);
int pfMemory::isExactType(pfType *type);
const char * pfMemory::getTypeName();
int pfMemory::copy(pfMemory *src);
int pfMemory::compare(const pfMemory *mem);
void pfMemory::print(uint which, uint verbose, char *prefix,
FILE *file);
int pfMemory::getArena(void *ptr);
void* pfMemory::getArena();
int pfMemory::ref();
int pfMemory::unref();
int pfMemory::unrefDelete();
int pfMemory::unrefGetRef();
int pfMemory::getRef();
int pfMemory::checkDelete();
int pfMemory::isFluxed();
void * pfMemory::getArena();
int pfMemory::getSize();
DESCRIPTION
A pfList is a dynamically-sized array of arbitrary, but homogeneously-
sized, elements.
The default constructor pfList creates a list with an element size of
sizeof(void *) bytes. The element size is fixed at creation time and
cannot be later changed. Another constructor is provided that allows the
element size eltSize and initial allocated length listLength for the
pfList. new(arena) allocates a pfList from the specified memory arena,
or from the process heap if arena is NULL. new allocates a pfList from
the default memory arena (see pfGetSharedArena). Like other pfObjects,
Page 2
pfList(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfList(3pf)
pfLists cannot be created statically, automatically on the stack or in
arrays. pfLists should be deleted with pfDelete rather than the delete
operator.
pfList::getClassType returns the pfType* for the class pfList. The
pfType* returned by pfList::getClassType is the same as the pfType*
returned by invoking the virtual function getType on any instance of
class pfList. Because OpenGL Performer allows subclassing of built-in
types, when decisions are made based on the type of an object, it is
usually better to use the member function isOfType to test if an object
is of a type derived from a Performer type rather than to test for strict
equality of the pfType*'s.
A pfList dynamically increases its array size by a factor of 2 and zeros
the additional memory whenever it runs out of array memory. This way the
array size quickly reaches its final size without many reallocations of
memory. However, some memory (up to one half of the total allocation) at
the end of the array may be wasted. If you know the exact number of
elements in the array, you can specify the pfList array length either
when creating it (the listLength argument to new pfList) or with
pfList::setArrayLen. pfList::getArrayLen returns the current array
length of the pfList.
Example 1:
/* Fit list's array to its current number of elements */
list->setArrayLen(list->getNum());
pfList::set sets the indexth element of the pfList to elt. The list is
automatically grown if index is beyond the current array length.
pfList::get returns the element of the pfList at index index or 0 if
index is out of bounds.
pfList::add appends elt to the pfList and automatically grows the pfList
if necessary.
pfList::remove removes elt from the pfList and shifts the array down over
the vacant spot, e.g. - if elt had index 0, then index 1 becomes index 0,
index 2 becomes index 1 and so on. pfList::remove returns the index of
elt if elt was actually removed and -1 if it was not found in the list.
pfList::removeIndex removes the indexth element of the pfList, and like
pfList::remove, shifts the array down over the vacant spot.
pfList::fastRemove removes elt from the pfList but does not shift the
array; instead it places the last element of the array into the vacated
location so it does not preserve the list ordering.
pfList::fastRemoveIndex replaces the indexth element with the last
element of the pfList.
Page 3
pfList(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfList(3pf)
Note that both pfList::remove and pfList::fastRemove linearly search the
array for elt and remove only the first matching element. To remove all
occurrences of elt do the following:
while (list->remove(elt) >= 0)
/* empty */ ;
pfList::search returns the index of elt if elt was found in the pfList
and -1 otherwise.
pfList::insert inserts elt before the array element with index index.
index must be within the range [0 .. list->getNum()].
pfList::move deletes elt from its current location and inserts before the
array element with index index. index must be within the range [0 ..
list->getNum()] or else (-1) is returned and no move is executed. If elt
is not already in the pfList, (-1) is returned and elt is not inserted
into the list. Otherwise, index is returned to indicate success.
pfList::replace replaces the first instance of old with new and returns
the index of old if it was found in the pfList and -1 otherwise.
pfList::getNum returns the number of elements in the pfList. (Actually,
list may have holes in its array so pfList::getNum technically should be
considered as returning the maximum index of all elements in the pfList.)
pfList::reset zeros the pfList's array and resets the number of elements
to 0. It does not resize the array.
pfList::combine sets the pfList to a appended with b. the pfList may be
the same as a or b. Lists must have equal element sizes to be combined.
For quick access to the list array, pfList::getArray returns a pointer to
the internal array of the pfList. Care should be taken with this routine
since out of bounds range checking provided by pfList API is bypassed.
If you add elements to the pfList then use pfList::setNum to set the
number of elements of the pfList.
BUGS
pfLists currently only support an element size of sizeof(void*).
SEE ALSO
pfDelete
Page 4
