From a2c9a06ca615df726dc06aa257a728b6c57896d1 Mon Sep 17 00:00:00 2001 From: Aryadev Chavali Date: Sun, 28 Apr 2024 14:20:45 +0530 Subject: [PATCH] Documented lib/darr.h --- lib/darr.h | 130 +++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 96 insertions(+), 34 deletions(-) diff --git a/lib/darr.h b/lib/darr.h index 28a5bab..159f035 100644 --- a/lib/darr.h +++ b/lib/darr.h @@ -19,11 +19,13 @@ #include "./base.h" /** - * A dynamically sized buffer of bytes which may be used for a - * variety of purposes. - * @prop data: Buffer of bytes (may be reallocated) - * @prop used: Number of bytes currently used - * @prop available: Number of bytes currently allocated + @brief A dynamically sized buffer of bytes. + + @prop[data] Buffer of bytes (may be reallocated) + + @prop[used] Number of bytes currently used + + @prop[available] Number of bytes currently allocated */ typedef struct { @@ -35,54 +37,114 @@ typedef struct #define DARR_DEFAULT_SIZE 8 #define DARR_REALLOC_MULT 1.5 -/** Get the INDth item in a darr, where the buffer of bytes is - * considerd an array of type TYPE. - * Unsafe operation as safety checks are not done (in particular if - * the dynamic array has IND items or is big enough to store an - * element of TYPE) so it is presumed the caller will. +/** + @brief Get the `IND`th item of type `TYPE` in `DARR_DATA` + + @details Cast `DARR_DATA` to `TYPE`, taking the `IND`th item. + NOTE: This is unsafe as bound checks are not done i.e. if + `DARR_DATA` has at least space for `IND` * sizeof(`TYPE`) items. + It is presumed the caller will check themselves. + + @param[TYPE] Type to cast internal byte array + @param[DARR_DATA] Byte array of darr + @param[IND] Index of item + + @return Item of TYPE */ #define DARR_AT(TYPE, DARR_DATA, IND) ((TYPE *)(DARR_DATA))[(IND)] -/** Initialise a dynamic array (darr) with n elements. - * If n == 0 then initialise with DARR_DEFAULT_SIZE elements. +/** + @brief Initialise a dynamic array `darr` with n bytes of space. + + @details All properties of `darr` are initialised. `darr`.used is + set to 0, `darr`.available is set to `n` and `darr`.data is set to + a pointer of `n` bytes. NOTE: If `n` = 0 then it is set to + DARR_DEFAULT_SIZE + + @param[darr] Pointer to darr_t object to initialise + @param[n] Number of bytes to allocate. If equal to 0 then + considered treated as DARR_DEFAULT_SIZE */ void darr_init(darr_t *darr, size_t n); -/** Ensure the dynamic array (darr) has at least n elements free. - * If the dynamic array has less than n elements free it will - * reallocate. +/** + @brief Ensure a dynamic array has at least n bytes of space free. + + @details If `darr` has n or more bytes free, nothing occurs. + Otherwise, the byte array in `darr` is reallocated such that it has + at least `n` bytes of free space. NOTE: `darr` has at least `n` + bytes free if and only if `darr`.used + `n` <= `darr`.available + + @param[darr] Dynamic array to check + @param[n] Number of bytes */ void darr_ensure_capacity(darr_t *darr, size_t n); -/** Append a byte (b) to the dynamic array (darr). - * If the dynamic array doesn't have enough space it will reallocate - * to ensure it can fit it in. +/** + @brief Append a byte to a dynamic array. + + @details Append a byte to the end of the byte buffer in a dyamic + array. If the dynamic array doesn't have enough free space to fit + the byte, it will reallocate to ensure it can fit it in via + darr_ensure_capacity(). + + @param[darr] Dynamic arrary to append to + @param[b] Byte to append */ void darr_append_byte(darr_t *darr, byte_t b); -/** Append an array of n bytes (b) to the dynamic array (darr). - * If the dynamic array doesn't have enough space to fit all n bytes - * it will reallocate to ensure it can fit it in. +/** + @brief Append an array of n bytes to a dynamic array. + + @details Append an array of bytes to the end of a byte buffer. If + the dynamic array doesn't have enough free space to fit all n bytes + it will reallocate to ensure it can fit it in via + darr_ensure_capacity(). + + @param[darr] Dynamic array to append to + @param[b] Array of bytes to append + @param[n] Size of array of bytes */ void darr_append_bytes(darr_t *darr, byte_t *b, size_t n); -/** Safely get the nth byte of the dynamic array (darr) - * If the dynamic array has less than n bytes used, it will return 0 - * as a default value. +/** + @brief Get the nth byte of a dynamic array + + @details Get the nth byte of the dynamic array. 0 based. NOTE: If + the dynamic array has less than n bytes used, it will return 0 as a + default value, so this is a safe alternative to DARR_AT(). + + @param[darr] Dynamic array to index + @param[n] Index to get byte at + + @return Byte at the nth position, or 0 if n is an invalid index */ byte_t darr_at(darr_t *darr, size_t n); -/** Write the dynamic array (darr) to the file pointer (fp) as a - * buffer of bytes. - * Assumes fp is a valid file pointer and in write mode. - */ -void darr_write_file(darr_t *, FILE *); +/** + @brief Write the bytes of a dynamic array to a file pointer -/** Read a file pointer (fp) in its entirety, converting the bytes - * into a tightly fitted dynamic array. - * Say the file pointer is a file of n bytes. Then the dynamic array - * returned will have available set to n and used set to 0. + @details Given a dynamic array and a file pointer, write the + internal buffer of bytes to the file pointer. NOTE: The file + pointer is assumed to be open and suitable for writing. + + @param[darr] Dynamic array to write + @param[fp] File pointer to write on */ -darr_t darr_read_file(FILE *); +void darr_write_file(darr_t *darr, FILE *fp); + +/** + @brief Read a file pointer in its entirety into a dynamic array + + @details Read a file pointer as a buffer of bytes then return that + buffer wrapped in a darr_t structure. NOTE: the file pointer is + assumed to be open and suitable for reading. + + @param[fp]: File pointer to read + + @return Dynamic array structure with available set to the size of + the `buffer` read and `data` set to the buffer of bytes. + */ +darr_t darr_read_file(FILE *fp); #endif