Welcome to little lamb

Code » limb » commit e27cbc8

doc: Complete bytestr.h

author Olivier Brunel
2023-06-07 18:14:28 UTC
committer Olivier Brunel
2023-07-24 10:16:41 UTC
parent 40a7aa78c1a22267039e186e778be20dd27b26c8

doc: Complete bytestr.h

src/doc/bytestr.h.0.md +26 -6
src/doc/bytestr.h/byte_chr.3.md +36 -0
src/doc/bytestr.h/byte_count.3.md +24 -0
src/doc/bytestr.h/byte_equal.3.md +24 -0
src/doc/bytestr.h/byte_get_match_full.3.md +1 -1
src/doc/bytestr.h/byte_in.3.md +1 -0
src/doc/bytestr.h/byte_rchr.3.md +1 -0
src/doc/bytestr.h/byte_str.3.md +1 -1
src/doc/bytestr.h/byte_zzero.3.md +31 -0

diff --git a/src/doc/bytestr.h.0.md b/src/doc/bytestr.h.0.md
index ff36a60..0fca05f 100644
--- a/src/doc/bytestr.h.0.md
+++ b/src/doc/bytestr.h.0.md
@@ -13,19 +13,39 @@ bytestr.h - byte arrays/strings functions
 
 This header defines functions to work with byte arrays and/or strings.
 
-! INFO: skalibs
-! This header is a complement to skalibs' own [skalibs/bytestr.h](0) and thusly
-! includes said header.
+They work on data not necessarily NUL-terminated, hence the requirement for
+length, and return indices/offset within the array instead of pointers, as with
+standard library functions.
+
+<inc skalibs.md>
 
 ## Functions
 
 The following functions are defined :
 
+: [byte_chr](3)
+:: Find the first occurence of a character (byte) in a byte array.
+
+: [byte_count](3)
+:: Returns the number of occurence of a character (byte) in a byte array.
+
+: [byte_equal](3)
+:: Returns whether two byte arrays are equal or not.
+
 : [byte_get_match_full](3)
-:: Find the (partial) match of a given string in an array
+:: Find the (partial) match of a given string in an array.
 
 : [byte_get_match](3)
-:: Find the (partial) match of a given string in an array of strings
+:: Find the (partial) match of a given string in an array of strings.
+
+: [byte_in](3)
+:: Find the first occurence of any of the given bytes in a byte array.
+
+: [byte_rchr](3)
+:: Find the last occurence of a character (byte) in a byte array.
 
 : [byte_str](3)
-:: To locate a substring within a string
+:: Find the first occurence of a byte array in another byte array.
+
+: [byte_zzero](3)
+:: Zero-out the content of a byte array.
diff --git a/src/doc/bytestr.h/byte_chr.3.md b/src/doc/bytestr.h/byte_chr.3.md
new file mode 100644
index 0000000..7793885
--- /dev/null
+++ b/src/doc/bytestr.h/byte_chr.3.md
@@ -0,0 +1,36 @@
+% limb manual
+% byte_chr(3)
+
+# NAME
+
+byte_chr, byte_rchr, byte_in - locate a byte within a byte array
+
+# SYNOPSIS
+
+    #include <limb/bytestr.h>
+
+```pre hl
+size_t byte_chr(const char *<em>haystack</em>, size_t <em>hlen</em>, int <em>c</em>)
+size_t byte_rchr(const char *<em>haystack</em>, size_t <em>hlen</em>, int <em>c</em>)
+size_t byte_in(const char *haystack, size_t hlen, const char *sep, size_t slen)
+```
+
+# DESCRIPTION
+
+The `byte_chr`() function looks for the first occurrence of byte `c` in the
+byte array `haystack` of length `hlen`.
+
+The `byte_rchr`() function looks for the last occurrence of a byte `c` in the
+byte array `haystack` of length `hlen`.
+
+The `byte_in`() function looks for the first occurrence of any of the `slen`
+bytes in `sep` in the array `haystack` of length `hlen`.
+
+# RETURN VALUE
+
+The `byte_chr`() and `byte_rchr`() functions return the offset of the first or
+last occurrence of byte `c` in the byte array `haystack`, respectively, when
+found. Otherwise they return `hlen`.
+
+The `byte_in`() function returns the offset of the first occurrence of any of
+the `slen` bytes in `sep` in the array `haystack`, or `hlen` when not found.
diff --git a/src/doc/bytestr.h/byte_count.3.md b/src/doc/bytestr.h/byte_count.3.md
new file mode 100644
index 0000000..1302117
--- /dev/null
+++ b/src/doc/bytestr.h/byte_count.3.md
@@ -0,0 +1,24 @@
+% limb manual
+% byte_count(3)
+
+# NAME
+
+byte_count - count occurrences of a byte in a byte array
+
+# SYNOPSIS
+
+    #include <limb/bytestr.h>
+
+```pre hl
+size_t byte_count(const char *<em>haystack</em>, size_t <em>hlen</em>, char <em>c</em>)
+```
+
+# DESCRIPTION
+
+The `byte_count`() function returns the number of occurrences of byte `c` in the
+byte array `haystack` of length `hlen`.
+
+# RETURN VALUE
+
+The `byte_count`() function returns the number of byte `c` in the byte array
+`haystack`.
diff --git a/src/doc/bytestr.h/byte_equal.3.md b/src/doc/bytestr.h/byte_equal.3.md
new file mode 100644
index 0000000..6b84741
--- /dev/null
+++ b/src/doc/bytestr.h/byte_equal.3.md
@@ -0,0 +1,24 @@
+% limb manual
+% byte_equal(3)
+
+# NAME
+
+byte_equal - compares two byte arrays
+
+# SYNOPSIS
+
+    #include <limb/bytestr.h>
+
+```pre hl
+int byte_equal(const char *<em>arr1</em>, size_t <em>len</em>, const char *<em>arr2</em>)
+```
+
+# DESCRIPTION
+
+The `byte_equal`() function returns whether or not `arr1` and `arr2`, of length
+`len`, are the same.
+
+# RETURN VALUE
+
+The `byte_equal`() function returns 1 when the `len` first bytes of `arr1` and
+`arr2` are the same. Otherwise it returns 0.
diff --git a/src/doc/bytestr.h/byte_get_match_full.3.md b/src/doc/bytestr.h/byte_get_match_full.3.md
index 96f0e55..c56f877 100644
--- a/src/doc/bytestr.h/byte_get_match_full.3.md
+++ b/src/doc/bytestr.h/byte_get_match_full.3.md
@@ -3,7 +3,7 @@
 
 # NAME
 
-byte\_get\_match\_full, byte\_get\_match - find the (partial) match of a given
+byte_get_match_full, byte_get_match - find the (partial) match of a given
 string in an array
 
 # SYNOPSIS
diff --git a/src/doc/bytestr.h/byte_in.3.md b/src/doc/bytestr.h/byte_in.3.md
new file mode 120000
index 0000000..efc8a35
--- /dev/null
+++ b/src/doc/bytestr.h/byte_in.3.md
@@ -0,0 +1 @@
+byte_chr.3.md
\ No newline at end of file
diff --git a/src/doc/bytestr.h/byte_rchr.3.md b/src/doc/bytestr.h/byte_rchr.3.md
new file mode 120000
index 0000000..efc8a35
--- /dev/null
+++ b/src/doc/bytestr.h/byte_rchr.3.md
@@ -0,0 +1 @@
+byte_chr.3.md
\ No newline at end of file
diff --git a/src/doc/bytestr.h/byte_str.3.md b/src/doc/bytestr.h/byte_str.3.md
index 2a780eb..9769117 100644
--- a/src/doc/bytestr.h/byte_str.3.md
+++ b/src/doc/bytestr.h/byte_str.3.md
@@ -3,7 +3,7 @@
 
 # NAME
 
-byte\_str - locate a substring within a string
+byte_str - locate a byte array within another byte array
 
 # SYNOPSIS
 
diff --git a/src/doc/bytestr.h/byte_zzero.3.md b/src/doc/bytestr.h/byte_zzero.3.md
new file mode 100644
index 0000000..d9d053d
--- /dev/null
+++ b/src/doc/bytestr.h/byte_zzero.3.md
@@ -0,0 +1,31 @@
+% limb manual
+% byte_zzero(3)
+
+# NAME
+
+byte_zzero - fill a byte array with zeroes
+
+# SYNOPSIS
+
+    #include <limb/bytestr.h>
+
+```pre hl
+void byte_zzero(const char *<em>arr</em>, size_t <em>len</em>)
+```
+
+# DESCRIPTION
+
+The `byte_zzero`() function writes zeroes in the `len` bytes of memory pointed
+by `arr`.
+
+It guarantees that compiler optimizations will not remove the erase operation if
+the compiler deduces that the operation is "unnecessary" (e.g. memory is not
+used afterwards), which may be of importance when erasing sensitive information,
+such as keys in a cryptographic context.
+
+! NOTE:
+! In order to ensure memory is erased :
+! - if available, [explicit_bzero](3) is called,
+! - otherwise, Otherwise, [memset](3) is used to clear the memory, then a
+!   special no-op function with a weak alias is called, in order to trick the
+!   compiler.