pfuAutoList(3pfu) OpenGL Performer 3.2.2 libpfutil C++ Reference Pages
NAMEpfuAutoList - Dynamically-sized resource owning list
FUNCTION SPECIFICATION
#include <Performer/pfutil/pfuAutoList.h>
pfuAutoList::pfuAutoList();
pfuAutoList::pfuAutoList(int listLength);
static pfType* pfuAutoList::getClassType(void);
void pfuAutoList::add(pfMemory* elt);
void* pfuAutoList::get(int index);
int pfuAutoList::getNum(void);
void pfuAutoList::insert(int index, pfMemory* elt);
void pfuAutoList::move(int index, pfMemory* elt);
int pfuAutoList::remove(pfMemory* elt);
void pfuAutoList::removeIndex(int index);
int pfuAutoList::replace(pfMemory* old, pfMemory* new);
void pfuAutoList::reset(void);
int pfuAutoList::search(pfMemory* elt);
int pfuAutoList::search(pfType* type);
void pfuAutoList::set(int index, pfMemory* elt);
PARENT CLASS FUNCTIONS
The OpenGL Performer class pfuAutoList is derived from the parent class
pfObject, so each of these member functions of class pfObject are also
directly usable with objects of class pfuAutoList. This is also true for
ancestor classes of class pfObject.
void* pfObject::operator new(size_t);
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();
Page 1
pfuAutoList(3pfu) OpenGL Performer 3.2.2 libpfutil C++ Reference Pages
Since the class pfObject is itself derived from the parent class
pfMemory, objects of class pfuAutoList 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 pfuAutoList is a dynamically-sized list of elements. Elements must be
of type pointer to pfMemory (or a derived class). pfuAutoList increments
the reference count of elements that are added or inserted into the list.
It decrements the reference count of elements that are removed from the
list. In this way, pfuAutoList takes ownership of its elements.
The default constructor pfuAutoList creates a list with an element size
of sizeof( pfMemory* ). The element size is fixed and cannot be changed.
Another constructor is provided that allows the initial allocated length
listLength for the pfuAutoList. new(arena) allocates a pfuAutoList from
the specified memory arena, or from the process heap if arena is NULL.
new allocates a pfuAutoList from the default memory arena (see
pfGetSharedArena). Like other pfObjects, pfuAutoLists cannot be created
statically, automatically on the stack or in arrays.
pfuAutoLists should be deleted with pfDelete rather than the delete
operator. When a list is deleted, it calls pfMemory::unrefDelete() on
all elements in the list.
pfuAutoList::getClassType returns the pfType* for the class pfuAutoList.
The pfType* returned by pfuAutoList::getClassType is the same as the
pfType* returned by invoking the virtual function getType on any instance
of class pfuAutoList. 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
Page 2
pfuAutoList(3pfu) OpenGL Performer 3.2.2 libpfutil C++ Reference Pages
strict equality of the pfType*'s.
A pfuAutoList dynamically increases its list size by a factor of 2 and
zeros the additional memory whenever it runs out of memory. This way the
list 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 list may be wasted. If you know the exact number of
elements in the list, you can specify the pfuAutoList list length when
creating it (the listLength argument to new pfuAutoList).
pfList::set sets the indexth element of the pfList to elt. The list is
automatically grown if index is beyond the current list length. If the
list already contains an element at indexth then pfMemory::unref() is
called on that element, before elt is inserted into the list.
pfMemory::ref() is called on elt.
pfuAutoList::get returns the element of the pfuAutoList at index index or
0 if index is out of bounds.
pfuAutoList::add appends elt to the pfuAutoList and automatically grows
the pfuAutoList if necessary. pfMemory::ref() is called on elt.
pfuAutoList::remove removes elt from the pfuAutoList and shifts the
elements 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.
pfuAutoList::remove returns the index of elt if elt was actually removed
and -1 if it was not found in the list. pfuAutoList::removeIndex removes
the indexth element of the pfuAutoList, and like pfuAutoList::remove,
shifts the elements down over the vacant spot.
Note that if the requested element was removed from the list then
pfMemory::unref() is called on that element. In this way, the list
disowns the removed element.
Note that pfuAutoList::remove linearly searches the list for elt and
removes only the first matching element. To remove all occurrences of
elt do the following:
while (list->remove(elt) >= 0)
/* empty */ ;
pfuAutoList::search( pfMemory* ) returns the index of elt if elt was
found in the pfuAutoList and -1 otherwise.
pfuAutoList::search( pfType* ) returns the index of type, if an element
was found in the pfuAutoList that returns TRUE for pfMemory::isOfType(),
and returns -1 otherwise.
pfuAutoList::insert inserts elt before the list element with index index.
index must be within the range [0 .. list->getNum()]. pfMemory::ref() is
Page 3
pfuAutoList(3pfu) OpenGL Performer 3.2.2 libpfutil C++ Reference Pages
called on elt.
pfuAutoList::move deletes elt from its current location and inserts
before the list 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 pfuAutoList, (-1) is returned and elt is not
inserted into the list. Otherwise, index is returned to indicate success.
pfuAutoList::replace replaces the first instance of old with new and
returns the index of old if it was found in the pfuAutoList and -1
otherwise. pfMemory::unref() is called on old if it was found in the
list.
pfuAutoList::getNum returns the number of elements in the pfuAutoList.
pfuAutoList::reset calls pfMemory::unrefDelete() on all the elements in
list and resets the number of elements to 0.
NOTES
Any attempt to add or insert non-pfMemory objects into a pfuAutoList will
fail. If an error status cannot be returned then a warning will be
issued. The list will remain unchanged.
SEE ALSO
pfList, pfMemory
Page 4
