author | Olivier Brunel
<jjk@jjacky.com> 2023-07-02 12:18:58 UTC |
committer | Olivier Brunel
<jjk@jjacky.com> 2023-07-24 10:16:41 UTC |
parent | ec84e459d4cb46ccb8548dac28178173fdce1531 |
src/doc/samisc.h.0.md | +6 | -6 |
src/doc/samisc.h/{sacoloff.3.md => sa_coloff.3.md} | +8 | -8 |
src/doc/samisc.h/{sacolptr.3.md => sa_colptr.3.md} | +11 | -11 |
src/doc/samisc.h/sa_off2ptr.3.md | +29 | -0 |
src/doc/samisc.h/{sapatrim_put.3.md => sa_patrim_put.3.md} | +5 | -5 |
src/doc/samisc.h/saoff2ptr.3.md | +0 | -29 |
src/liblimb/include/limb/samisc.h | +4 | -4 |
src/liblimb/samisc.h/{sacoloff.c => sa_coloff.c} | +1 | -1 |
src/liblimb/samisc.h/{sacolptr.c => sa_colptr.c} | +3 | -3 |
src/liblimb/samisc.h/{saoff2ptr.c => sa_off2ptr.c} | +1 | -1 |
src/liblimb/samisc.h/{sapatrim_put.c => sa_patrim_put.c} | +1 | -1 |
diff --git a/src/doc/samisc.h.0.md b/src/doc/samisc.h.0.md index d0fed88..3fd57cd 100644 --- a/src/doc/samisc.h.0.md +++ b/src/doc/samisc.h.0.md @@ -11,21 +11,21 @@ samisc.h - miscellaneous functions dealing with stralloc # DESCRIPTION -The header defines helper functions when working with stralloc. +The header defines some helper functions when working with *stralloc*. ## Functions The following functions are defined : -: [sacoloff](3) +: [sa_coloff](3) :: Collect NUL-terminated strings from the given stralloc and store their :: offsets into it -: [sacolptr](3) -:: Same as [sacoloff](3) but stores pointers to the strings +: [sa_colptr](3) +:: Same as [sa_coloff](3) but stores pointers to the strings -: [saoff2ptr](3) +: [sa_off2ptr](3) :: Transform an array of offsets into an array of pointers from an stralloc -: [sapatrim_put](3) +: [sa_patrim_put](3) :: Encode data in [patrim](5) format into the specified stralloc. diff --git a/src/doc/samisc.h/sacoloff.3.md b/src/doc/samisc.h/sa_coloff.3.md similarity index 59% rename from src/doc/samisc.h/sacoloff.3.md rename to src/doc/samisc.h/sa_coloff.3.md index e3fba94..9d0f642 100644 --- a/src/doc/samisc.h/sacoloff.3.md +++ b/src/doc/samisc.h/sa_coloff.3.md @@ -1,21 +1,21 @@ % limb manual -% sacoloff(3) +% sa_coloff(3) # NAME -sacoloff - append an array of offsets to strings from an stralloc into it +sa_coloff - append an array of offsets to strings from an stralloc into it # SYNOPSIS #include <limb/samisc.h> ```pre hl -int sacoloff(stralloc *<em>sa</em>, size_t <em>from</em>, size_t <em>end</em>) +int sa_coloff(stralloc *<em>sa</em>, size_t <em>from</em>, size_t <em>end</em>) ``` # DESCRIPTION -The `sacoloff`() function will scan the content of the given stralloc `sa` +The `sa_coloff`() function will scan the content of the given stralloc `sa` starting at offset `from`, expecting to find a succession of NUL-terminated strings, up to `end`. It will append into `sa` an array of offsets where each string is located within `sa->s`. @@ -23,21 +23,21 @@ string is located within `sa->s`. ! INFO: ! The offsets added into `sa` are actually casted as *uintptr_t* so that they ! can later be turned into full string pointers (*char \**) if needed. -! Such a conversion can be done using [saoff2ptr](3). +! Such a conversion can be done using [sa_off2ptr](3). # RETURN VALUE -Upon successful completion, the `sacoloff`() function returns the number of +Upon successful completion, the `sa_coloff`() function returns the number of strings found, or the number of elements in the array. Otherwise, it returns -1 and sets `errno` to indicate the error. # ERRORS -The `sacoloff`() function may fail if : +The `sa_coloff`() function may fail if : : *ENOMEM* :: Out of memory to add pointers into `sa` # SEE ALSO -[saoff2ptr](3), [sacolptr](3) +[sa_off2ptr](3), [sa_colptr](3) diff --git a/src/doc/samisc.h/sacolptr.3.md b/src/doc/samisc.h/sa_colptr.3.md similarity index 70% rename from src/doc/samisc.h/sacolptr.3.md rename to src/doc/samisc.h/sa_colptr.3.md index 2083d3c..d5e9a33 100644 --- a/src/doc/samisc.h/sacolptr.3.md +++ b/src/doc/samisc.h/sa_colptr.3.md @@ -1,21 +1,21 @@ % limb manual -% sacolptr(3) +% sa_colptr(3) # NAME -sacolptr - append an array of pointers to strings from an stralloc into it +sa_colptr - append an array of pointers to strings from an stralloc into it # SYNOPSIS #include <limb/samisc.h> ```pre hl -int sacolptr(stralloc *<em>sa</em>, size_t <em>from</em>, size_t <em>end</em>) +int sa_colptr(stralloc *<em>sa</em>, size_t <em>from</em>, size_t <em>end</em>) ``` # DESCRIPTION -The `sacolptr`() function will scan the content of the given stralloc `sa` +The `sa_colptr`() function will scan the content of the given stralloc `sa` starting at offset `from`, expecting to find a succession of NUL-terminated strings, up to `end`. It will append into `sa` an array of pointers to the strings. @@ -23,18 +23,18 @@ strings. This allows to use said array easily with other functions not stralloc-aware. ! INFO: -! This function is merely is wrapper around [sacoloff](3) and [saoff2ptr](3). +! This function is merely is wrapper around [sa_coloff](3) and [sa_off2ptr](3). # RETURN VALUE -Upon successful completion, the `sacolptr`() function returns the number of +Upon successful completion, the `sa_colptr`() function returns the number of strings found, or the number of elements in the array. Otherwise, it returns -1 and sets `errno` to indicate the error. # ERRORS -The `sacolptr`() function may fail and set `errno` for any of the errors -specified on [sacoloff](3). +The `sa_colptr`() function may fail and set `errno` for any of the errors +specified on [sa_coloff](3). # EXAMPLE @@ -62,13 +62,13 @@ main(void) stralloc sa = STRALLOC_ZERO; /* append the list of all files in the current directory into sa */ - salst(&sa, ".", NULL); + sa_ls(&sa, ".", NULL); /* offset where the array will be stored */ size_t arroff = sa.len; /* append the array from strings contained within */ - int n = sacolptr(&sa, 0, sa.len); + int n = sa_colptr(&sa, 0, sa.len); /* sort the array */ char **arr = (char **) (sa.s + arroff); @@ -85,4 +85,4 @@ main(void) # SEE ALSO -[sacoloff](3), [saoff2ptr](3) +[sa_coloff](3), [sa_off2ptr](3) diff --git a/src/doc/samisc.h/sa_off2ptr.3.md b/src/doc/samisc.h/sa_off2ptr.3.md new file mode 100644 index 0000000..c0a6653 --- /dev/null +++ b/src/doc/samisc.h/sa_off2ptr.3.md @@ -0,0 +1,29 @@ +% limb manual +% sa_off2ptr(3) + +# NAME + +sa_off2ptr - turn an array of offsets from an stralloc into an array of strings + +# SYNOPSIS + + #include <limb/samisc.h> + +```pre hl +void sa_off2ptr(stralloc *<em>sa</em>, size_t <em>arroff</em>, size_t <em>n</em>) +``` + +# DESCRIPTION + +The `sa_off2ptr`() function will transform an array of `n` offsets located at +`arroff` into `sa->s` into an array of string pointers. + +This allows to use said array easily with other functions not stralloc-aware. + +! HINT: +! You can easily append such an array of offsets from a concatenation of +! NUL-terminated strings into a stralloc using [sa_coloff](3). + +# SEE ALSO + +[sa_coloff](3), [sa_colptr](3) diff --git a/src/doc/samisc.h/sapatrim_put.3.md b/src/doc/samisc.h/sa_patrim_put.3.md similarity index 54% rename from src/doc/samisc.h/sapatrim_put.3.md rename to src/doc/samisc.h/sa_patrim_put.3.md index 5d3939b..67ec328 100644 --- a/src/doc/samisc.h/sapatrim_put.3.md +++ b/src/doc/samisc.h/sa_patrim_put.3.md @@ -1,21 +1,21 @@ % limb manual -% sapatrim_put(3) +% sa_patrim_put(3) # NAME -sapatrim_put - encode data in PATRIM format into an stralloc +sa_patrim_put - encode data in PATRIM format into an stralloc # SYNOPSIS #include <limb/samisc.h> ```pre hl -int sapatrim_put(stralloc *<em>sa</em>, u64 <em>id</em>, u64 <em>u</em>, const char *<em>data</em>) +int sa_patrim_put(stralloc *<em>sa</em>, u64 <em>id</em>, u64 <em>u</em>, const char *<em>data</em>) ``` # DESCRIPTION -The `sapatrim_put`() function will encode into the given stralloc `sa` the +The `sa_patrim_put`() function will encode into the given stralloc `sa` the specified `id` in [patrim](5) format. If it represents an (unsigned) integer, `u` must be its value, and `data` is @@ -26,5 +26,5 @@ said data (of length `u`). # RETURN VALUE -The `sapatrim_put`() function returns 1 on success and 0 on failure, i.e. +The `sa_patrim_put`() function returns 1 on success and 0 on failure, i.e. failure to allocate memory within the given `sa`. diff --git a/src/doc/samisc.h/saoff2ptr.3.md b/src/doc/samisc.h/saoff2ptr.3.md deleted file mode 100644 index 3f3a2a4..0000000 --- a/src/doc/samisc.h/saoff2ptr.3.md +++ /dev/null @@ -1,29 +0,0 @@ -% limb manual -% saoff2ptr(3) - -# NAME - -saoff2ptr - turn an array of offsets from an stralloc into an array of strings - -# SYNOPSIS - - #include <limb/samisc.h> - -```pre hl -void saoff2ptr(stralloc *<em>sa</em>, size_t <em>arroff</em>, size_t <em>n</em>) -``` - -# DESCRIPTION - -The `saoff2ptr`() function will transform an array of `n` offsets located at -`arroff` into `sa->s` into an array of string pointers. - -This allows to use said array easily with other functions not stralloc-aware. - -! HINT: -! You can easily append such an array of offsets from a concatenation of -! NUL-terminated strings into a stralloc using [sacoloff](3). - -# SEE ALSO - -[sacoloff](3), [sacolptr](3) diff --git a/src/liblimb/include/limb/samisc.h b/src/liblimb/include/limb/samisc.h index 588db4b..30441f3 100644 --- a/src/liblimb/include/limb/samisc.h +++ b/src/liblimb/include/limb/samisc.h @@ -7,9 +7,9 @@ #include <limb/int.h> #include <limb/stralloc.h> -extern int sapatrim_put(stralloc *sa, u64 id, u64 u, const char *data); -extern int sacoloff(stralloc *sa, size_t from, size_t end); -extern void saoff2ptr(stralloc *sa, size_t arroff, size_t n); -extern int sacolptr(stralloc *sa, size_t from, size_t end); +extern int sa_patrim_put(stralloc *sa, u64 id, u64 u, const char *data); +extern int sa_coloff(stralloc *sa, size_t from, size_t end); +extern void sa_off2ptr(stralloc *sa, size_t arroff, size_t n); +extern int sa_colptr(stralloc *sa, size_t from, size_t end); #endif /* LIMB_SAMISC_H */ diff --git a/src/liblimb/samisc.h/sacoloff.c b/src/liblimb/samisc.h/sa_coloff.c similarity index 92% rename from src/liblimb/samisc.h/sacoloff.c rename to src/liblimb/samisc.h/sa_coloff.c index 3fb7dfa..169571b 100644 --- a/src/liblimb/samisc.h/sacoloff.c +++ b/src/liblimb/samisc.h/sa_coloff.c @@ -5,7 +5,7 @@ #include <limb/samisc.h> int -sacoloff(stralloc *sa, size_t from, size_t end) +sa_coloff(stralloc *sa, size_t from, size_t end) { size_t salen = sa->len; int ret = 0; diff --git a/src/liblimb/samisc.h/sacolptr.c b/src/liblimb/samisc.h/sa_colptr.c similarity index 79% rename from src/liblimb/samisc.h/sacolptr.c rename to src/liblimb/samisc.h/sa_colptr.c index 446aa0d..25b295d 100644 --- a/src/liblimb/samisc.h/sacolptr.c +++ b/src/liblimb/samisc.h/sa_colptr.c @@ -4,15 +4,15 @@ #include <limb/samisc.h> int -sacolptr(stralloc *sa, size_t from, size_t end) +sa_colptr(stralloc *sa, size_t from, size_t end) { size_t arroff = sa->len; /* first collect the offsets from sa->s, as relocation might happen as we * grow sa to store the array */ - int n = sacoloff(sa, from, end); + int n = sa_coloff(sa, from, end); if (n < 0) return n; /* then turn offsets into pointers */ - saoff2ptr(sa, arroff, n); + sa_off2ptr(sa, arroff, n); return n; } diff --git a/src/liblimb/samisc.h/saoff2ptr.c b/src/liblimb/samisc.h/sa_off2ptr.c similarity index 90% rename from src/liblimb/samisc.h/saoff2ptr.c rename to src/liblimb/samisc.h/sa_off2ptr.c index e0053ec..ddeec91 100644 --- a/src/liblimb/samisc.h/saoff2ptr.c +++ b/src/liblimb/samisc.h/sa_off2ptr.c @@ -5,7 +5,7 @@ #include <limb/samisc.h> void -saoff2ptr(stralloc *sa, size_t arroff, size_t n) +sa_off2ptr(stralloc *sa, size_t arroff, size_t n) { uintptr_t *a = (uintptr_t *) (sa->s + arroff); for (size_t i = 0; i < n; ++i) { diff --git a/src/liblimb/samisc.h/sapatrim_put.c b/src/liblimb/samisc.h/sa_patrim_put.c similarity index 89% rename from src/liblimb/samisc.h/sapatrim_put.c rename to src/liblimb/samisc.h/sa_patrim_put.c index a854b45..f5fc892 100644 --- a/src/liblimb/samisc.h/sapatrim_put.c +++ b/src/liblimb/samisc.h/sa_patrim_put.c @@ -5,7 +5,7 @@ #include <limb/samisc.h> int -sapatrim_put(stralloc *sa, u64 id, u64 u, const char *data) +sa_patrim_put(stralloc *sa, u64 id, u64 u, const char *data) { size_t salen = sa->len;