pfList(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfList(3pf)NAME
pfNewList, pfGetListClassType, pfAdd, pfCombineLists, pfFastRemove,
pfFastRemoveIndex, pfGet, pfGetListArray, pfGetListArrayLen,
pfGetListEltSize, pfGetNum, pfInsert, pfMove, pfListArrayLen, pfNum,
pfRemove, pfRemoveIndex, pfReplace, pfResetList, pfSearch, pfSet -
Dynamically-sized list utility
FUNCTION SPECIFICATION
#include <Performer/pr.h>
pfList * pfNewList(int eltSize, int listLength, void* arena);
pfType * pfGetListClassType(void);
void pfAdd(pfList* list, void* elt);
void pfCombineLists(pfList* dst, const pfList *a,
const pfList *b);
int pfFastRemove(pfList* list, void* elt);
void pfFastRemoveIndex(pfList* list, int index);
void * pfGet(const pfList* list, int index);
const void ** pfGetListArray(const pfList* list);
int pfGetListArrayLen(const pfList* len);
int pfGetListEltSize(const pfList* list);
int pfGetNum(const pfList* list);
void pfInsert(pfList* list, int index, void* elt);
int pfMove(pfList* lists, int index, void *elt);
void pfListArrayLen(pfList* list, int len);
void pfNum(pfList *list, int num);
int pfRemove(pfList* list, void* elt);
void pfRemoveIndex(pfList* list, int index);
int pfReplace(pfList* list, void* old, void* new);
void pfResetList(pfList* list);
int pfSearch(const pfList* list, void* elt);
Page 1
pfList(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfList(3pf)
void pfSet(pfList* list, int index, void *elt);
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. Casting an object of class
pfList to an object of class pfObject is taken care of automatically.
This is also true for casts to objects of ancestor classes of class
pfObject.
void pfUserDataSlot(pfObject *obj, int slot, void *data);
void pfUserData(pfObject *obj, void *data);
void* pfGetUserDataSlot(pfObject *obj, int slot);
void* pfGetUserData(pfObject *obj);
int pfGetNumUserData(pfObject *obj);
int pfGetNamedUserDataSlot(const char *name);
const char* pfGetUserDataSlotName(int slot);
int pfGetNumNamedUserDataSlots(void);
int pfGetGLHandle(pfObject *obj);
int pfDeleteGLHandle(pfObject *obj);
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.
pfType * pfGetType(const void *ptr);
int pfIsOfType(const void *ptr, pfType *type);
int pfIsExactType(const void *ptr, pfType *type);
const char * pfGetTypeName(const void *ptr);
int pfRef(void *ptr);
int pfUnref(void *ptr);
int pfUnrefDelete(void *ptr);
int pfUnrefGetRef(void *ptr);
int pfGetRef(const void *ptr);
int pfCopy(void *dst, void *src);
int pfDelete(void *ptr);
int pfIsFluxed(void *ptr);
int pfCompare(const void *ptr1, const void *ptr2);
void pfPrint(const void *ptr, uint which, uint verbose,
FILE *file);
void * pfGetArena(void *ptr);
PARAMETERS
list identifies a pfList.
DESCRIPTION
A pfList is a dynamically-sized array of arbitrary, but homogeneously-
sized, elements.
pfNewList creates and returns a handle to a new pfList. eltSize
specifies the size in bytes of an individual list element. The element
Page 2
pfList(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfList(3pf)
size is fixed at creation time and cannot be later changed. listLength
is the initial length of the list; listLength * eltSize bytes will be
allocated for the list array. The argument arena specifies a malloc
arena out of which the pfList is to be allocated or NULL for allocation
from the process heap. pfLists can be deleted with pfDelete.
pfGetListClassType returns the pfType* for the class pfList. The pfType*
returned by pfGetListClassType is the same as the pfType* returned by
invoking pfGetType 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 pfIsOfType 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 pfNewList) or with
pfListArrayLen. pfGetListArrayLen returns the current array length of
list.
Example 1:
/* Fit list's array to its current number of elements */
pfListArrayLen(list, pfGetNum(list));
pfSet sets the indexth element of list to elt. The list is automatically
grown if index is beyond the current array length.
pfGet returns the element of list at index index or 0 if index is out of
bounds.
pfAdd appends elt to list and automatically grows list if necessary.
pfRemove removes elt from list 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. pfRemove returns the index of elt if elt was
actually removed and -1 if it was not found in the list. pfRemoveIndex
removes the indexth element of list, and like pfRemove, shifts the array
down over the vacant spot.
pfFastRemove removes elt from list 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. pfFastRemoveIndex replaces the
indexth element with the last element of list.
Note that both pfRemove and pfFastRemove linearly search the array for
Page 3
pfList(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfList(3pf)
elt and remove only the first matching element. To remove all
occurrences of elt do the following:
while (pfRemove(list, elt) >= 0)
/* empty */ ;
pfSearch returns the index of elt if elt was found in list and -1
otherwise.
pfInsert inserts elt before the array element with index index. index
must be within the range [0 .. pfGetNum(list)].
pfMove deletes elt from its current location and inserts before the array
element with index index. index must be within the range [0 ..
pfGetNum(list)] or else (-1) is returned and no move is executed. If elt
is not already in list, (-1) is returned and elt is not inserted into the
list. Otherwise, index is returned to indicate success.
pfReplace replaces the first instance of old with new and returns the
index of old if it was found in list and -1 otherwise.
pfGetNum returns the number of elements in list. (Actually, list may have
holes in its array so pfGetNum technically should be considered as
returning the maximum index of all elements in list.)
pfResetList zeros list's array and resets the number of elements to 0.
It does not resize the array.
pfCombineLists sets dst to a appended with b. dst may be the same as a
or b. Lists must have equal element sizes to be combined.
For quick access to the list array, pfGetListArray returns a pointer to
the internal array of list. Care should be taken with this routine since
out of bounds range checking provided by pfList API is bypassed. If you
add elements to list then use pfNum to set the number of elements of
list.
BUGS
pfLists currently only support an element size of sizeof(void*).
SEE ALSO
pfDelete
Page 4
