Welcome to little lamb

Code » limb » commit 0b9c56e

samisc.h: Complete doc & adjust interface

author Olivier Brunel
2023-07-02 12:18:58 UTC
committer Olivier Brunel
2023-07-24 10:16:41 UTC
parent ec84e459d4cb46ccb8548dac28178173fdce1531

samisc.h: Complete doc & adjust interface

We'll name all our stralloc helpers sa_* to keep consistency and help
clashes with skalibs (notably when wanting to change interface/arguments
order).

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;