Welcome to little lamb

Code » limb » commit 546c25e

Document stralloc.h

author Olivier Brunel
2023-05-17 04:51:42 UTC
committer Olivier Brunel
2023-07-05 07:37:02 UTC
parent 20559b713ac53c9cc18622cb9407be27df6f8e6b

Document stralloc.h

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.