forked from lda/telodendria
Begin moving documentation to headers.
This commit is contained in:
parent
3b06ab120b
commit
72467f6503
3 changed files with 141 additions and 27 deletions
|
@ -25,45 +25,140 @@
|
||||||
#ifndef TELODENDRIA_ARRAY_H
|
#ifndef TELODENDRIA_ARRAY_H
|
||||||
#define 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 <stddef.h>
|
#include <stddef.h>
|
||||||
#include <stdarg.h>
|
#include <stdarg.h>
|
||||||
|
|
||||||
|
/**
|
||||||
|
* The functions in this API operate on an array structure which is
|
||||||
|
* opaque to the caller.
|
||||||
|
*/
|
||||||
typedef struct Array Array;
|
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 */
|
#endif /* TELODENDRIA_ARRAY_H */
|
||||||
|
|
|
@ -25,7 +25,26 @@
|
||||||
#ifndef TELODENDRIA_SHA2_H
|
#ifndef TELODENDRIA_SHA2_H
|
||||||
#define 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 */
|
#endif /* TELODENDRIA_SHA2_H */
|
||||||
|
|
|
@ -398,8 +398,8 @@ last:
|
||||||
{
|
{
|
||||||
StreamPuts(out, ", ");
|
StreamPuts(out, ", ");
|
||||||
}
|
}
|
||||||
StreamPuts(out, ")\n");
|
|
||||||
}
|
}
|
||||||
|
StreamPuts(out, ")\n");
|
||||||
|
|
||||||
line = strtok(decl->docs, "\n");
|
line = strtok(decl->docs, "\n");
|
||||||
while (line)
|
while (line)
|
||||||
|
|
Loading…
Reference in a new issue