ARRAY(3) Library Functions Manual ARRAY(3)

ArrayA simple dynamic array data structure.

#include <Array.h>

Array *

ArrayFree(Array *);

ArrayTrim(Array *);

ArraySize(Array *);

void *
ArrayGet(Array *, size_t);

ArrayInsert(Array *, void *, size_t);

ArrayAdd(Array *, void *);

void *
ArrayDelete(Array *, size_t);

ArraySort(Array *, int (*) (void *, void *));

Array *
ArrayFromVarArgs(size_t, va_list);

Array *
ArrayDuplicate(Array *);

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.

() and () 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. () 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.

() and () are the main functions used to modify the array. () 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 (), 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.

() is used to get the element at the specified index.

() is used to convert a variadic arguments list into an Array. In many cases, the Array API is much easier to work with than () and friends.

() 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.

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.

HashMap(3), Queue(3)

November 24, 2022 Telodendria Project