diff --git a/src/include/Array.h b/src/include/Array.h index 89e7cdd..3de66e8 100644 --- a/src/include/Array.h +++ b/src/include/Array.h @@ -25,45 +25,140 @@ #ifndef TELODENDRIA_ARRAY_H #define TELODENDRIA_ARRAY_H +/*** + * @Nm Array + * @Nd A simple dynamic array data structure. + * @Dd November 24 2022 + * @Xr HashMap Queue + * + * 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. + */ + #include #include +/** + * The functions in this API operate on an array structure which is + * opaque to the caller. + */ typedef struct Array Array; -extern Array * - ArrayCreate(void); +/** + * Allocate a new array. This function returns a pointer that can be + * used with the other functions in this API, or NULL if there was an + * error allocating memory for the array. + */ +extern Array * ArrayCreate(void); -extern size_t - ArraySize(Array *); +/** + * Deallocate an array. Note that this function 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. + */ +extern void ArrayFree(Array *); -extern void * - ArrayGet(Array *, size_t); +/** + * Get the size, in number of elements, of the given array. + */ +extern size_t ArraySize(Array *); -extern int - ArrayInsert(Array *, size_t, void *); +/** + * Get the element at the specified index from the specified array. + * This function will return NULL if the array is NULL, or the index + * is out of bounds. Otherwise, it will return a pointer to a value + * put into the array using + * .Fn ArrayInsert + * or + * .Fn ArraySet . + */ +extern void * ArrayGet(Array *, size_t); -extern void * - ArraySet(Array *, size_t, void *); +/** + * Insert the specified element at the specified index in the specified + * array. This function will shift the element currently at that index, + * and any elements after it before inserting the given element. + * .Pp + * This function returns a boolean value indicating whether or not it + * suceeded. + */ +extern int ArrayInsert(Array *, size_t, void *); -extern int - ArrayAdd(Array *, void *); +/** + * Set the value at the specified index in the specified array to the + * specified value. This function will return the old value at that + * index, if any. + */ +extern void * ArraySet(Array *, size_t, void *); -extern void * - ArrayDelete(Array *, size_t); +/** + * Append the specified element to the end of the specified array. This + * function uses + * .Fn ArrayInsert + * under the hood to insert an element at the end. It thus has the same + * return value as + * .Fn ArrayInsert . + */ +extern int ArrayAdd(Array *, void *); -extern void - ArraySort(Array *, int (*) (void *, void *)); +/** + * Remove the element at the specified index from the specified array. + * This function returns the element removed, if any. + */ +extern void * ArrayDelete(Array *, size_t); -extern void - ArrayFree(Array *); +/** + * Sort the specified array using the specified sort function. The + * sort function compares two elements. It takes two void pointers as + * parameters, and returns an integer. The return value indicates to + * the sorting algorithm how the elements relate to each other. A + * return value of 0 indicates that 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. A return value less than 0 indicates the opposite: the + * second element should appear after the first in the array. + */ +extern void ArraySort(Array *, int (*) (void *, void *)); -extern int - ArrayTrim(Array *); +/** + * If possible, reduce the amount of memory allocated to this array + * by calling + * .Fn Realloc + * on the internal structure to perfectly fit the elements in the + * array. This function is intended to be used by functions that return + * relatively read-only arrays that will be long-lived. + */ +extern int ArrayTrim(Array *); -extern Array * - ArrayFromVarArgs(size_t, va_list); +/** + * Convert a variadic arguments list into an Array. In most cases, the + * Array API is much easier to work with than + * .Fn va_arg + * and friends. + */ +extern Array * ArrayFromVarArgs(size_t, va_list); -extern Array * - ArrayDuplicate(Array *); +/** + * Duplicate an existing array. Note that arrays only hold pointers to + * their data, not the data itself, so the duplicated array will point + * to the same places in memory as the original array. + */ +extern Array * ArrayDuplicate(Array *); #endif /* TELODENDRIA_ARRAY_H */ diff --git a/src/include/Sha2.h b/src/include/Sha2.h index a27be6b..2701993 100644 --- a/src/include/Sha2.h +++ b/src/include/Sha2.h @@ -25,7 +25,26 @@ #ifndef TELODENDRIA_SHA2_H #define TELODENDRIA_SHA2_H -extern char * - Sha256(char *); +/*** + * @Nm Sha2 + * @Nd A simple implementation of the SHA2 hashing functions. + * @Dd December 19 2022 + * @Xr Memory Base64 + * + * This API defines simple functions for computing SHA2 hashes. + * At the moment, it only defines + * .Fn Sha256 , + * which computes the SHA-256 hash of the given C string. It is + * not trivial to implement SHA-512 in ANSI C due to the lack of + * a 64-bit integer type, so that hash function has been omitted. + */ + +/** + * This function takes a pointer to a NULL-terminated C string, and + * returns a string allocated on the heap using the Memory API, or + * NULL if there was an error allocating memory. The returned string + * should be freed when it is no longer needed. + */ +extern char * Sha256(char *); #endif /* TELODENDRIA_SHA2_H */ diff --git a/tools/src/hdoc.c b/tools/src/hdoc.c index 4e2a014..54a5319 100644 --- a/tools/src/hdoc.c +++ b/tools/src/hdoc.c @@ -398,8 +398,8 @@ last: { StreamPuts(out, ", "); } - StreamPuts(out, ")\n"); } + StreamPuts(out, ")\n"); line = strtok(decl->docs, "\n"); while (line)