Welcome to little lamb

Code » limb » commit c1732b0

Add stralloc.h

author Olivier Brunel
2023-05-12 12:59:19 UTC
committer Olivier Brunel
2023-07-05 07:37:02 UTC
parent a7b7a9b8e920cf1eb9d8a08c2a2af39fa046b848

Add stralloc.h

Just a few macros for the lazy. :)

src/doc/stralloc.h.0.md +31 -0
src/doc/stralloc.h/stralloc_cat.3.md +104 -0
src/liblimb/include/limb/stralloc.h +13 -0

diff --git a/src/doc/stralloc.h.0.md b/src/doc/stralloc.h.0.md
new file mode 100644
index 0000000..6020b8f
--- /dev/null
+++ b/src/doc/stralloc.h.0.md
@@ -0,0 +1,31 @@
+% limb manual
+% stralloc.h(0)
+
+# NAME
+
+stralloc.h - heap memory management
+
+# SYNOPSIS
+
+    #include <limb/stralloc.h>
+
+# DESCRIPTION
+
+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.
+
+## Functions
+
+The following functions/macros are defined :
+
+: [stralloc_cats0](3)
+:: Appends a string and its NUL-terminating byte into a *stralloc*.
+
+: [stralloc_copys0](3)
+:: Copy a string and its NUL-terminating byte into a *stralloc*.
+
+: [stralloc_inserts0](3)
+:: Insert a string and its NUL-terminating byte into a *stralloc*.
diff --git a/src/doc/stralloc.h/stralloc_cat.3.md b/src/doc/stralloc.h/stralloc_cat.3.md
new file mode 100644
index 0000000..b3a5c4d
--- /dev/null
+++ b/src/doc/stralloc.h/stralloc_cat.3.md
@@ -0,0 +1,104 @@
+% limb manual
+% stralloc_cat(3)
+
+# NAME
+
+stralloc\_catb, stralloc\_cats, stralloc\_cats0, stralloc_catv, stralloc\_cat,
+stralloc\_copyb, stralloc\_copys, stralloc\_copys0, stralloc\_copy,
+stralloc\insertb, stralloc\_inserts, stralloc\_inserts0, stralloc\_insert,
+stralloc\\append, stralloc_0 - adding data into a stralloc
+
+# SYNOPSIS
+
+    #include <limb/stralloc.h>
+
+```pre hl
+int stralloc_catb(stralloc *sa, const char *data, size_t dlen)
+int stralloc_cats(stralloc *sa, const char *str)
+int stralloc_cats0(stralloc *sa, const char *str)
+int stralloc_catv(stralloc *sa, const struct iovec *v, unsigned n)
+int stralloc_cat(stralloc *sa, const stralloc *sasce)
+
+int stralloc_copyb(stralloc *sa, const char *data, size_t dlen)
+int stralloc_copys(stralloc *sa, const char *str)
+int stralloc_copys0(stralloc *sa, const char *str)
+int stralloc_copy(stralloc *sa1, const stralloc *sasce)
+
+int stralloc_insertb(stralloc *sa, size_t offset, const char *data, size_t dlen)
+int stralloc_inserts(stralloc *sa, size_t offset, const char *str)
+int stralloc_inserts0(stralloc *sa, size_t offset, const char *str)
+int stralloc_insert(stralloc *sa, size_t offset, const stralloc *sasce)
+
+int stralloc_append(stralloc *sa, char c)
+int stralloc_0(stralloc *sa)
+```
+
+# DESCRIPTION
+
+The `stralloc_catb`() function appends the content of memory pointed by `data`
+of length `dlen` into the stralloc `sa`.
+
+The `stralloc_cats`() function is similar to `stralloc_catb`() but appending
+the NUL-terminated string pointed by `str`, not including said NUL-terminating
+byte.
+
+The `stralloc_cats0`() function is similar to `stralloc_cats`() but including
+the NUL-terminating byte.
+
+The `stralloc_catv`() function is similar to `stralloc_catb`() but gathering the
+data to add from the array of vectors `v` of `n` elements.
+
+The `stralloc_cat`() function is similar to `stralloc_catb`() function but
+appending the content of stralloc `sasce`.
+
+
+The `stralloc_copyb`() function copies the content of memory pointed by `data`
+of length `dlen` into the stralloc `sa`. That is, the stralloc will only contain
+`data` afterwards.
+
+The `stralloc_copys`() function is similar to `stralloc_copyb`() but copying
+the NUL-terminated string pointed by `str`, not including said NUL-terminating
+byte.
+
+The `stralloc_copys0`() function is similar to `stralloc_copys`() but including
+the NUL-terminating byte.
+
+The `stralloc_copy`() function is similar to `stralloc_copyb`() function but
+copying the content of stralloc `sasce`.
+
+
+The `stralloc_insertb`() function inserts the content of memory pointed by
+`data` of length `dlen` into the stralloc `sa` at offset `offset`.
+
+The `stralloc_inserts`() function is similar to `stralloc_insertb`() but
+inserting the NUL-terminated string pointed by `str`, not including said
+NUL-terminating byte.
+
+The `stralloc_inserts0`() function is similar to `stralloc_inserts`() but
+including the NUL-terminating byte.
+
+The `stralloc_insert`() function is similar to `stralloc_insertb`() function but
+inserting the content of stralloc `sasce`.
+
+
+The `stralloc_append`() function appends byte `c` into the stralloc `sa`.
+
+The `stralloc_0`() function appends a NUL-byte into stralloc `sa`.
+
+# RETURN VALUE
+
+These functions return 1 on success. Otherwise they return 0 and set `errno` to
+indicate the error.
+
+# ERRORS
+
+These functions may fail if :
+
+: *ENOMEM*
+:: Out of memory.
+
+The `stralloc_insertb`(), `stralloc_inserts`(), `stralloc_inserts0`() and
+`stralloc_insert`() functions may also fail if :
+
+: *EINVAL*
+:: The `offset` is too high.
diff --git a/src/liblimb/include/limb/stralloc.h b/src/liblimb/include/limb/stralloc.h
new file mode 100644
index 0000000..e31dbd5
--- /dev/null
+++ b/src/liblimb/include/limb/stralloc.h
@@ -0,0 +1,13 @@
+/* This file is part of limb                           https://lila.oss/limb
+ * Copyright (C) 2023 Olivier Brunel                          jjk@jjacky.com */
+/* SPDX-License-Identifier: GPL-2.0-only */
+#ifndef LIMB_STRALLOC_H
+#define LIMB_STRALLOC_H
+
+#include <skalibs/stralloc.h>
+
+#define stralloc_copys0(sa, s)      stralloc_copyb(sa, (s), strlen(s) + 1)
+#define stralloc_cats0(sa, s)       stralloc_catb(sa, (s), strlen(s) + 1)
+#define stralloc_inserts0(sa, o, s) stralloc_insertb(sa, o, (s), strlen(s) + 1)
+
+#endif /* LIMB_STRALLOC_H */