Introduction | Initialization | Closing | Adding | Deleting | Fetching | Parameters | Advanced | Obscure

PARRAY

This data structure is an abstraction of the simple C array data type, only the array is dynamic, i.e. it grows and shrinks as the data is added or removed. Growing and shrinking happens in user-defined steps, to minimize memory management.

Always useful.

Introduction

A PARRAY is LibDS's name for a variable length array. It is nothing more than that, only, in keeping with the design of LibDS, it also supports different fetching operations, and currency. (PARRAY is a rather contrived name, but it stands for Pointer Array, since it actually stores void pointers).

Initialization

PARRAY paMake(int size,int grow_by)

Make a new PARRAY of initial size size. The array will grow and shrink as necessary, each time by the number of elements given by grow_by.

Closing

void paClose(PARRAY pa)
void paCloseWithFunction(PARRAY pa,void (*fun)(void*))

Close the parray, releasing any memory it was using. The second function applies the provided fun to each element in the array prior to closing it.

Adding

int paAdd(PARRAY pa,void *data)

Adds the given data to the array. Returns the number of items in the array afterwards, -1 if something went wrong.

Deleting

void* paRemove(PARRAY pa,int idx)

Remove the element at index idx. The data stored at idx is returned on success, NULL otherwise (most likely because the index was smaller than 0, or larger than the number of items in the array).

Fetching

void* paFirst(PARRAY pa)

Returns the first element found in the array. If the array contains no elements, NULL is returned. Upon success the currency is set to the first element.

void* paLast(PARRAY pa)

Returns the last element found in the array. If the array is empty, NULL is returned. Upon success, the currency is set to the last element.

void* paNext(PARRAY pa)

Returns the next element in the array. Next is defined as the element after the current element. If there's no current element, this function is equivalent to paFirst().

void* paPrev(PARRAY pa)

Returns the previous element in the array. Previous is the element before the current one. If there's no current element, the function is equivalent to paLast().

void* paCurrent(PARRAY pa)

Returns the current element in the array, or NULL if there's no current element.

void* paElementAt(PARRAY pa,int idx)

Returns the element at index idx in the array. If idx is out of the array's bounds, NULL is returned. This is the most arrayish of all functions here.

Parameters

int paSize(PARRAY pa)

Returns the number of elements currently in the array.

Advanced functionality

void* paContains(PARRAY pa,int (*cmpfun)(void*,void*),void *elem)

Returns 1 if the array contains the given element elem. The function cmpfun() that performs element comparisons must be defined by the caller. If the given element is not found, the return value is NULL.

void paSetCurrent(PARRAY pa,int idx)

Sets the currency to the element found at index idx in the array. If idx is out of bounds, the currency is left unchanged.

Obscure functionality

None for now.

Tue Apr  2 15:00:33 CEST 2002