forked from Telodendria/Telodendria
133 lines
4.1 KiB
Groff
133 lines
4.1 KiB
Groff
.Dd $Mdocdate: November 24 2022 $
|
|
.Dt ARRAY 3
|
|
.Os Telodendria Project
|
|
.Sh NAME
|
|
.Nm Array
|
|
.Nd A simple dynamic array data structure.
|
|
.Sh SYNOPSIS
|
|
.In Array.h
|
|
.Ft Array *
|
|
.Fn ArrayCreate "void"
|
|
.Ft void
|
|
.Fn ArrayFree "Array *"
|
|
.Ft int
|
|
.Fn ArrayTrim "Array *"
|
|
.Ft size_t
|
|
.Fn ArraySize "Array *"
|
|
.Ft void *
|
|
.Fn ArrayGet "Array *" "size_t"
|
|
.Ft int
|
|
.Fn ArrayInsert "Array *" "void *" "size_t"
|
|
.Ft int
|
|
.Fn ArrayAdd "Array *" "void *"
|
|
.Ft void *
|
|
.Fn ArrayDelete "Array *" "size_t"
|
|
.Ft void
|
|
.Fn ArraySort "Array *" "int (*) (void *, void *)"
|
|
.Ft Array *
|
|
.Fn ArrayFromVarArgs "size_t" "va_list"
|
|
.Ft Array *
|
|
.Fn ArrayDuplicate "Array *"
|
|
.Sh 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.
|
|
.Pp
|
|
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.
|
|
.Pp
|
|
Due to these design choices, this array implementation is best suited to
|
|
linear writing, and then linear or random reading.
|
|
.Pp
|
|
These functions operate on an array structure which is opaque to the
|
|
caller.
|
|
.Pp
|
|
.Fn ArrayCreate
|
|
and
|
|
.Fn ArrayFree
|
|
allocate and deallocate an array, respectively.
|
|
Note that
|
|
.Fn 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.
|
|
.Fn ArrayTrim
|
|
reduces the amount of unused memory by calling
|
|
.Xr 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.
|
|
.Pp
|
|
.Fn ArrayInsert
|
|
and
|
|
.Fn ArrayDelete
|
|
are the main functions used to modify the array.
|
|
.Fn ArrayAdd
|
|
is a convenience method that simply appends a value to the end of the
|
|
array. It uses
|
|
.Fn ArrayInsert .
|
|
The array can also be sorted by using
|
|
.Fn ArraySort ,
|
|
which takes a pointer to a function that compares elements. The function
|
|
should take two
|
|
.Dv 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.
|
|
.Pp
|
|
.Fn ArrayGet
|
|
is used to get the element at the specified index.
|
|
.Pp
|
|
.Fn 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
|
|
.Fn va_arg
|
|
and friends.
|
|
.Pp
|
|
.Fn 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.
|
|
.Sh RETURN VALUES
|
|
.Fn ArrayCreate ,
|
|
.Fn ArrayFromVarArgs ,
|
|
and
|
|
.Fn ArrayDuplicate
|
|
return a pointer on the heap to a newly allocated array structure, or
|
|
.Dv NULL
|
|
if the allocation fails.
|
|
.Pp
|
|
.Fn ArrayGet
|
|
and
|
|
.Fn ArrayDelete
|
|
return pointers to values that were put into the array, or
|
|
.Dv NULL
|
|
if the provided array is
|
|
.Dv NULL
|
|
or the provided index was out of bounds.
|
|
.Fn ArrayDelete
|
|
returns the element at the specified index after removing it so that
|
|
it can be properly handled by the caller.
|
|
.Pp
|
|
.Fn ArrayTrim ,
|
|
.Fn ArrayInsert ,
|
|
and
|
|
.Fn ArrayAdd
|
|
return a boolean value indicating their status. They return a value of zero
|
|
on failure, and a non-zero value on success.
|
|
.Sh SEE ALSO
|
|
.Xr HashMap 3 ,
|
|
.Xr Queue 3
|