Move Array documentation to man page.

TODO.txt

@@ -96,3 +96,4 @@ Documentation
 [x] Convert documentation to man pages
 	[x] Clean up dark mode in man page CSS (links)
 	[x] Synopsis table should not be styled
+	[ ] Internal API docs

docs/Array.3

@@ -0,0 +1,112 @@
+.Dd $Mdocdate: September 25 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 *)"
+.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.
+.Sh RETURN VALUES
+.Fn ArrayCreate
+returns a pointer on the heap to a newly allocated array structure.
+.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

src/include/Array.h

@@ -22,24 +22,6 @@
  * SOFTWARE.
  */
 
-/*
- * Array.h: A simple array data structure that is automatically
- * resized when new values are added. This implementation does not
- * actually store the values of the items 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 this array implementation
- * doesn't have to copy items, and thus doesn't have to know how big
- * they are.
- *
- * This array is optimized for storage space and appending. Deletions
- * are expensive in that all the items of the list are moved down
- * to fill the hole where the deletion occurred. Insertions are
- * also expensive in that all the elements are shifted to make room
- * for the new element.
- *
- * Due to these, this array implementation is really intended to be
- * used primarily for linear writing and linear or random reading.
- */
 #ifndef TELODENDRIA_ARRAY_H
 #define TELODENDRIA_ARRAY_H
 
@@ -47,168 +29,30 @@
 
 typedef struct Array Array;
 
-/*
- * Create a new, empty array on the heap.
- *
- * Return: A pointer to an Array, or NULL if there was an error
- * allocating memory for the Array.
- */
 extern Array *
  ArrayCreate(void);
 
-/*
- * Get the size of the provided array. Note that this is the number
- * of elements in the array, not how much memory has been allocated
- * for it.
- *
- * This is an extremely cheap operation, because the size does not
- * need to be computed; rather it is just pulled right out of the
- * Array and returned to the caller.
- *
- * Params:
- *
- *   (Array *) The array to check the size of.
- *
- * Return: The number of elements in the provided array, or 0 if the
- * provided array is NULL.
- */
 extern size_t
  ArraySize(Array *);
 
-/*
- * Get an element out of the provided array at the provided index.
- *
- * Params:
- *
- *   (Array *) The array to get an element from.
- *   (size_t)  The index of the array where the desired element is
- *             located.
- *
- * Return: A pointer to the data located at the given index, or NULL
- * if no array was provided, or the index is greater than or equal
- * to the size of the array.
- */
 extern void *
  ArrayGet(Array *, size_t);
 
-/*
- * Insert an element into the array at the given index.
- *
- * Params:
- *
- *   (Array *) The array to get the element from.
- *   (void *)  The value to insert into the array.
- *   (size_t)  The index at which the given value.
- *
- * Return: A boolean value that indicates whether or not the insert
- * was successful. A return value of 0 indicates that the insert was
- * NOT successful, and a return value of anything else indicates that
- * the insert was successful.
- */
 extern int
  ArrayInsert(Array *, void *, size_t);
 
-/*
- * Append an element to the end of the array. This function actually
- * uses ArrayInsert() under the hood, but it makes appending to an
- * array more convenient because you don't necessarily have to keep
- * track of the array's size.
- *
- * Params:
- *
- *   (Array *) The array to append to.
- *   (void *)  The value to append to the array.
- *
- * Return: The result of appending the element, which is the same as
- * a call to ArrayInsert().
- */
 extern int
  ArrayAdd(Array *, void *);
 
-/*
- * Delete an element from an array by shifting all the elements that
- * come after it down one index.
- *
- * Params:
- *
- *   (Array *) The array to delete a value from.
- *   (size_t)  The desired index to delete. All elements above this
- *             index are then shifted down to fill the gap.
- *
- * Return: A pointer to the deleted element, so that it can be freed
- * or otherwise dealt with, or NULL if the array is NULL or the index
- * is out of bounds.
- */
 extern void *
  ArrayDelete(Array *, size_t);
 
-/*
- * Sort the array using a simple quick-sort algorithm. This function
- * works by taking a caller-specified compare function, so that no
- * assumptions about the data stored in the array need to be made by
- * this code.
- *
- * Params:
- *
- *   (Array *) The array to sort. Note that the sort will be done
- *             in-place.
- *   (int (*)(void *, void *)) A function that takes in two void
- *             pointers and returns an integer. This function is
- *             responsible for comparing the passed items, and
- *             returning a code that indicates how they should be
- *             ordered. A return value of 0 indicates that the two
- *             items 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 return value less than zero indicates
- *             the opposite: that the second element should appear
- *             after the first in the array.
- *
- */
 extern void
  ArraySort(Array *, int (*) (void *, void *));
 
-/*
- * Free all the memory associated with the given array. Note that this
- * does not free any of the values themselves; you should explicitly
- * iterate over the array and free all the values stored inside it
- * before calling this function, otherwise you may lose all the
- * pointers the array contains, and thus have a memory leak.
- *
- * Params:
- *
- *   (Array *) The array to free.
- *
- */
 extern void
  ArrayFree(Array *);
 
-/*
- * "Trim" the array by reallocating it with only the memory it needs
- * to hold the items it currently has. This function might be beneficial
- * to call on long-lived arrays that will be read-only, because it
- * frees any memory on the end of the array that isn't being used. The
- * array resizing algorithm will most likely allocate too much memory
- * for most arrays as elements are added, because there's no way to
- * know exactly how many elements will be stored.
- *
- * For example, a library that generates an Array to return to the
- * user may wish to call this function on it right before returning to
- * the caller if it is not expected that the caller will be modifying
- * the array and may hang on to it for a long time.
- *
- * Params:
- *
- *   (Array *) The array to trim extra memory (if any) off the end.
- *             Note that the array will still be fully-functional; if
- *             you add more elements, then more memory will be
- *             allocated like normal.
- *
- * Return: Whether or not the trim was successful. The trim may fail if
- * realloc() fails, or NULL was passed for the array. If realloc()
- * fails, this function is careful not to clobber the array. Upon
- * failure of this function, the array is guaranteed to be unaltered.
- */
 extern int
  ArrayTrim(Array *);