NAME
Array —
A simple dynamic array data
structure.
SYNOPSIS
#include
<Array.h>
Array *
ArrayCreate(void);
void
ArrayFree(Array
*);
int
ArrayTrim(Array
*);
size_t
ArraySize(Array
*);
void *
ArrayGet(Array
*, size_t);
int
ArrayInsert(Array
*, void *,
size_t);
int
ArrayAdd(Array
*, void *);
void *
ArrayDelete(Array
*, size_t);
void
ArraySort(Array
*, int (*) (void *, void
*));
Array *
ArrayFromVarArgs(size_t,
va_list);
Array *
ArrayDuplicate(Array
*);
DESCRIPTION
These functions implement a simple array data structure that is automatically resized as necessary when new values are added. This implementation does not actually store the values of the items in it; it only stores pointers to the data. As such, you will still have to manually maintain all your data. The advantage of this is that these functions don't have to copy data, and thus don't care how big the data is. Furthermore, arbitrary data can be stored in the array.
This array implementation is optimized for storage space and appending. Deletions are expensive in that all the items of the list above a deletion are moved down to fill the hole where the deletion occurred. Insertions are also expensive in that all the elements above the given index must be shifted up to make room for the new element.
Due to these design choices, this array implementation is best suited to linear writing, and then linear or random reading.
These functions operate on an array structure which is opaque to the caller.
ArrayCreate()
and
ArrayFree()
allocate and deallocate an array, respectively. Note that
ArrayFree() does not free any of the values stored
in the array; it is the caller's job to manage the memory for each item.
Typically, the caller would iterate over all the items in the array and free
them before freeing the array.
ArrayTrim()
reduces the amount of unused memory by calling
realloc(3) on the internal structure to perfectly fit the elements in
the array. It is intended to be used by functions that return relatively
read-only arrays that will be long-lived.
ArrayInsert()
and
ArrayDelete()
are the main functions used to modify the array.
ArrayAdd()
is a convenience method that simply appends a value to the end of the array.
It uses ArrayInsert(). The array can also be sorted
by using
ArraySort(),
which takes a pointer to a function that compares elements. The function
should take two void pointers as parameters, and
return an integer. The return value indicates to the algorithm how the
elements relate to each other. A return value of 0 indicates the elements
are identical. A return value greater than 0 indicates that the first item
is "bigger" than the second item and should thus appear after it
in the array, and a value less than zero indicates the opposite: the second
element should appear after the first in the array.
ArrayGet()
is used to get the element at the specified index.
ArrayFromVarArgs()
is used to convert a variadic arguments list into an Array. In many cases,
the Array API is much easier to work with than
va_arg()
and friends.
ArrayDuplicate()
duplicates an existing array. Note that Arrays only hold pointers to data,
not the data itself, so the duplicated array will point to the same places
in memory as the original array.
RETURN VALUES
ArrayCreate(),
ArrayFromVarArgs(), and
ArrayDuplicate() return a pointer on the heap to a
newly allocated array structure, or NULL if the
allocation fails.
ArrayGet() and
ArrayDelete() return pointers to values that were
put into the array, or NULL if the provided array is
NULL or the provided index was out of bounds.
ArrayDelete() returns the element at the specified
index after removing it so that it can be properly handled by the
caller.
ArrayTrim(),
ArrayInsert(), and
ArrayAdd() return a boolean value indicating their
status. They return a value of zero on failure, and a non-zero value on
success.