author | Olivier Brunel
<jjk@jjacky.com> 2023-05-17 04:51:42 UTC |
committer | Olivier Brunel
<jjk@jjacky.com> 2023-07-05 07:37:02 UTC |
parent | 20559b713ac53c9cc18622cb9407be27df6f8e6b |
src/doc/samisc.h/sacolptr.3.md | +1 | -1 |
src/doc/stralloc.h.0.md | +109 | -4 |
src/doc/stralloc.h/stralloc_cat.3.md | +4 | -0 |
src/doc/stralloc.h/stralloc_ready_tuned.3.md | +70 | -0 |
src/doc/stralloc.h/stralloc_reverse.3.md | +23 | -0 |
diff --git a/src/doc/samisc.h/sacolptr.3.md b/src/doc/samisc.h/sacolptr.3.md index c373aed..2083d3c 100644 --- a/src/doc/samisc.h/sacolptr.3.md +++ b/src/doc/samisc.h/sacolptr.3.md @@ -44,9 +44,9 @@ To get the list of files in the current directory, and sort them using ```c #include <stdlib.h> #include <string.h> -#include <skalibs/stralloc.h> #include <limb/output.h> #include <limb/samisc.h> +#include <limb/stralloc.h> static int cmp(const void *p1, const void *p2) diff --git a/src/doc/stralloc.h.0.md b/src/doc/stralloc.h.0.md index 6020b8f..2d4c6f4 100644 --- a/src/doc/stralloc.h.0.md +++ b/src/doc/stralloc.h.0.md @@ -15,17 +15,122 @@ This header defines functions to work heap-allocated memory. ! INFO: skalibs ! This header is a complement to skalibs' own [skalibs/stralloc.h](0) and thusly -! includes said header. +! includes said header. The documentation below applies to that combination. + +## Structures + +The following structures are defined : + +: *struct stralloc* +:: A structure representing headp-allocated data, defined as such : + + struct stralloc_s { + char *s; + size_t len; + size_t a; + } + +:: Only members `s` - a pointer to the data, that may change over time as +:: reallocation are needed - and `len` - the length is data currently in use - +:: should be accessed. The member `a` - currently allocated size - might be +:: used in read-only fashion. + +## Types + +The following types are defined : + +: *stralloc* +:: A *struct stralloc_s* + +## Objects + +The following objects are defined : + +: *stralloc_zero* +:: An empty *stralloc*, which can be used for initialization. + +## Macros + +The following macros are defined : + +: *STRALLOC_ZERO* +:: Value to initialize a stack-allocated *stralloc*. ## Functions The following functions/macros are defined : -: [stralloc_cats0](3) -:: Appends a string and its NUL-terminating byte into a *stralloc*. +: [stralloc_ready_tuned](3) +:: Ensure there's enough space in a *stralloc*. + +: [stralloc_readyplus_tuned](3) +:: Ensure there's enough extra space in a *stralloc*. + +: [stralloc_ready](3) +:: Ensure there's enough space in a *stralloc*. + +: [stralloc_readyplus](3) +:: Ensure there's enough extra space in a *stralloc*. + + +: [stralloc_free](3) +:: Free memory associated with a *stralloc*. + +: [stralloc_shrink](3) +:: Reduce memory usage to what's used. + + +: [stralloc_copyb](3) +:: Copy data into a *stralloc*. + +: [stralloc_copy](3) +:: Copy content of a *stralloc* into another one. + +: [stralloc_copys](3) +:: Copy a string (excluding its NUL-terminating byte) into a *stralloc*. : [stralloc_copys0](3) :: Copy a string and its NUL-terminating byte into a *stralloc*. +: [stralloc_catv](3) +:: Append data from an array of vectors into a *stralloc*. + +: [stralloc_catb](3) +:: Append data into a *stralloc*. + +: [stralloc_cat](3) +:: Append the content of a *stralloc* into another one. + +: [stralloc_cats](3) +:: Append a string (excluding its NUL-terminating byte) into a *stralloc*. + +: [stralloc_cats0](3) +:: Append a string and its NUL-terminating byte into a *stralloc*. + +: [stralloc_0](3)] +:: Append a NUL byte into a *stralloc*. + +: [stralloc_append](3) +:: Append a character into a *stralloc*. + + +: [stralloc_insertb](3) +:: Insert data into a *stralloc* at a specific offset. + +: [stralloc_insert](3) +:: Insert the content of a *stralloc* into another one at a specific offset. + +: [stralloc_inserts](3) +:: Insert a string (excluding its NUL-terminating byte) into a *stralloc* at a +:: specific offset. + : [stralloc_inserts0](3) -:: Insert a string and its NUL-terminating byte into a *stralloc*. +:: Insert a string and its NUL-terminating byte into a *stralloc* at a specific +:: offset. + + +: [stralloc_reverse](3) +:: Reverse the content of a *stralloc*. + +: [stralloc_reverse_blocks](3) +:: Reverse the content of a *stralloc* divided into blocks a given length. diff --git a/src/doc/stralloc.h/stralloc_cat.3.md b/src/doc/stralloc.h/stralloc_cat.3.md index b3a5c4d..2643895 100644 --- a/src/doc/stralloc.h/stralloc_cat.3.md +++ b/src/doc/stralloc.h/stralloc_cat.3.md @@ -85,6 +85,10 @@ The `stralloc_append`() function appends byte `c` into the stralloc `sa`. The `stralloc_0`() function appends a NUL-byte into stralloc `sa`. +! NOTE: +! Obviously all these function ensure that there is enough room available in the +! stralloc `sa` before writing data into it. + # RETURN VALUE These functions return 1 on success. Otherwise they return 0 and set `errno` to diff --git a/src/doc/stralloc.h/stralloc_ready_tuned.3.md b/src/doc/stralloc.h/stralloc_ready_tuned.3.md new file mode 100644 index 0000000..03bd20d --- /dev/null +++ b/src/doc/stralloc.h/stralloc_ready_tuned.3.md @@ -0,0 +1,70 @@ +% limb manual +% stralloc_ready(3) + +# NAME + +stralloc\_ready\_tuned, stralloc\_readyplus\_tuned, stralloc\_ready, +stralloc\_readyplus, stralloc\_free, stralloc\_shrink - allocate and free memory +associated with a stralloc + +# SYNOPSIS + + #include <limb/stralloc.h> + +```pre hl +int stralloc_ready_tuned(stralloc *<em>sa</em>, size_t <em>len</em>, size_t <em>base</em>, size_t <em>a</em>, size_t <em>b</em>) +int stralloc_readyplus_tuned(stralloc *<em>sa</em>, size_t <em>len</em>, size_t <em>base</em>, size_t <em>a</em>, size_t <em>b</em>) +int stralloc_ready(stralloc *<em>sa</em>, size_t <em>len</em>) +int stralloc_readyplus(stralloc *<em>sa</em>, size_t <em>len</em>) + +void stralloc_free(stralloc *<em>sa</em>) +int stralloc_shrink(stralloc *<em>sa</em>) +``` + +# DESCRIPTION + +The `stralloc_ready`() macro ensure that at least `len` bytes are allocated in +stralloc `sa`, reallocating memory if needed. This does not mean as much is +available, as there might be data in use already. + +The `stralloc_readyplus`() macro ensure that at least `len` bytes are available +in stralloc `sa`, reallocating memory if needed. Available here means space +that is allocated but not yet in use, making this the most commonly used way to +prepare a *stralloc* before writing data into it. + +The `stralloc_ready_tuned`() is similar to `stralloc_ready`() but with more +fine-tuning settings. + +The `stralloc_readyplus_tuned`() is similar to `stralloc_ready_tuned`() but for +adding `len` bytes to the currently in-use size. + +Note that this is only needed when writing into the *stralloc* directly, as all +functions of the *stralloc* API (e.g. [stralloc_catb](3)) handles that +automatically. + +The `stralloc_shrink`() function will ensure that the allocated memory is only +as large as is in use in stralloc `sa`. + +The `stralloc_free`() function will free all memory associated with the stralloc +`sa`. + +# RETURN VALUE + +These functions (except for `stralloc_free`()) return 1 on success. Otherwise +they return 0 and set `errno` to indicate the error. + +# ERRORS + +These functions (except for `stralloc_free`()) may fail if : + +: *ENOMEM* +:: Out of memory. + +The `stralloc_ready_tuned`(), `stralloc_ready`(), `stralloc_readyplus_tuned`() +and `stralloc_readyplus`() functions may also fail if : + +: *EINVAL* +:: The `base` is zero. + +: *ERANGE* +:: Overflow. diff --git a/src/doc/stralloc.h/stralloc_reverse.3.md b/src/doc/stralloc.h/stralloc_reverse.3.md new file mode 100644 index 0000000..4bf7a74 --- /dev/null +++ b/src/doc/stralloc.h/stralloc_reverse.3.md @@ -0,0 +1,23 @@ +% limb manual +% stralloc_reverse(3) + +# NAME + +stralloc\_reverse, stralloc\_reverse\_blocks - reverse the content of a stralloc + +# SYNOPSIS + + #include <limb/stralloc.h> + +```pre hl +void stralloc_reverse(stralloc *<em>sa</em>) +void stralloc_reverse_blocks(stralloc *<em>sa</em>, size_t <em>blen</em>) +``` + +# DESCRIPTION + +The `stralloc_reverse`() function reverses the content of stralloc `sa`, +byte-by-byte. + +The `stralloc_reverse_blocks`() function is similar, but dividing the data by +blocks of `blen` bytes.