commit 54b77bb078333ecf576a6b59ba9b26354d855d09
parent 6af7267617e30c2646fa160689810cd7eeb56533
Author: Laurent Bercot <ska-skaware@skarnet.org>
Date: Wed, 18 Jan 2023 22:35:59 +0000
Add bytestr.h doc
Signed-off-by: Laurent Bercot <ska@appnovation.com>
Diffstat:
1 file changed, 236 insertions(+), 1 deletion(-)
diff --git a/doc/libstddjb/bytestr.html b/doc/libstddjb/bytestr.html
@@ -21,7 +21,242 @@
<h1> The <tt>skalibs/bytestr.h</tt> header </h1>
<p>
- TODO: write this documentation page. (Sorry!)
+ The following functions are declared in the <tt>skalibs/bytestr.h</tt> header
+and implemented in the <tt>libskarnet.a</tt> or <tt>libskarnet.so</tt> library.
+</p>
+
+<h2> Purpose </h2>
+
+<p>
+ These functions handle arrays of bytes (strings). They are similar to their
+counterparts from the standard
+ <a href="https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/string.h.html">string.h</a>
+header, but they return <em>indices</em> instead of <em>pointers</em>.
+</p>
+
+<p>
+ <tt>byte_*</tt> functions and macros work with strings that are not
+necessarily null-terminated, but require sizes of the strings to be passed.
+On the contary, <tt>str_*</tt> family accepts null-terminated strings.
+<tt>case_*</tt> functions and macros are like their <tt>str_*</tt> counterparts,
+but are case-insensitive.
+</p>
+
+<h2> Functions </h2>
+
+<p>
+<code> size_t byte_chr (char const *s, size_t n, int c) </code> <br>
+Looks for the first occurrence of byte <em>c</em> in array <em>s</em> of size
+<em>n</em>. Returns its index, or <em>n</em> if there is no such byte in
+<em>s</em>.
+</p>
+
+<p>
+<code> size_t byte_rchr (char const *s, size_t n, int c) </code> <br>
+Looks for the last occurrence of byte <em>c</em> in array <em>s</em> of size
+<em>n</em>. Returns its index, or <em>n</em> if there is no such byte in
+<em>s</em>.
+</p>
+
+<p>
+<code> size_t byte_in (char const *s, size_t n, char const *sep, size_t len) </code> <br>
+Looks for the first occurrence of any byte from array <em>sep</em> of size
+<em>len</em> in array <em>s</em> of size <em>n</em>. Returns the index of such
+an occurrence, or <em>n</em> if there are no bytes from <em>sep</em> in <em>s</em>.
+</p>
+
+<p>
+<code> size_t byte_count (char const *s, size_t len, char b) </code> <br>
+Returns the amount of occurrences of byte <em>b</em> in string <em>s</em> of
+size <em>len</em>.
+</p>
+
+<p>
+<code> size_t byte_search (char const *haystack, size_t hlen, char const *needle, size_t nlen) </code> <br>
+Looks for the first occurrence of string <em>needle</em> of size <em>nlen</em> in
+string <em>haystack</em> of size <em>hlen</em>. Returns the index of the first
+byte of that occurrence, or <tt>hlen + 1 - nlen</tt> if <em>needle</em> cannot
+be found in <em>haystack</em>.
+</p>
+
+<p>
+<code> void byte_zzero (char *s, size_t n) </code> <br>
+Zeroes <em>n</em> bytes of memory beginning with address <em>s</em>. Special
+measures are taken to prevent the compiler from optimizing out the call:
+<ul>
+ <li> If the <tt>explicit_bzero</tt> function is present on the system, it is
+used. Calls to this function are guaranteed not to be removed by the compiler. </li>
+ <li> Otherwise, <tt>byte_zzero</tt> performs a normal <tt>memset</tt> followed
+by a special no-op function with a weak alias in order to trick the compiler. </li>
+</ul>
+This is useful for erasing sensitive data before returning from some
+function, typically in cryptography settings. Compilers usually remove
+<tt>memset</tt> calls since these have no observable effect for the rest of the code.
+</p>
+
+<p>
+<code> size_t str_chr (char const *s, int c) </code> <br>
+Looks for the first occurrence of byte <em>c</em> in null-terminated string
+<em>s</em>. Returns the index of this occurrence, or the length of the string
+if there is no such byte in <em>s</em>.
+</p>
+
+<p>
+<code> size_t str_rchr (char const *s, int c) </code> <br>
+Looks for the last occurrence of byte <em>c</em> in null-terminated string
+<em>s</em>. Returns the index of this occurrence, or the length of the string
+if there is no such byte in <em>s</em>.
+</p>
+
+<p>
+<code> int str_start (char const *s, char const *t) </code> <br>
+Returns 1 if (null-terminated) string <em>s</em> begins with (null-terminated)
+string <em>t</em>, and 0 otherwise.
+</p>
+
+<p>
+<code> size_t str_strn (char const *haystack, size_t hlen, char const *needle, size_t nlen) </code> <br>
+Looks for the first occurrence of string <em>needle</em> of size <em>nlen</em> in
+string <em>haystack</em> of size <em>hlen</em>. Returns the index of the first
+character in this occurrence, or <em>hlen</em> if <em>needle</em> is not present
+in <em>haystack</em>.
+</p>
+
+<p>
+<code> void case_lowers (char *s) </code> <br>
+Turns all capital letters in null-terminated string <em>s</em> into lowercase
+letters. This function only works with ASCII symbols.
+</p>
+
+<p>
+<code> void case_lowerb (char *s, size_t len) </code> <br>
+Turns all capital letters in string <em>s</em> of size <em>len</em> into
+lowercase letters. This function only works with ASCII symbols.
+</p>
+
+<p>
+<code> void case_uppers (char *s) </code> <br>
+Turns all lowercase letters in null-terminated string <em>s</em> into capital
+letters. This function only works with ASCII symbols.
+</p>
+
+<p>
+<code> void case_upperb (char *s, size_t len) </code> <br>
+Turns all lowercase letters in string <em>s</em> of size <em>len</em> into
+capital letters. This function only works with ASCII symbols.
+</p>
+
+<p>
+<code> int case_startb (char const *s, size_t slen, char const *t) </code> <br>
+Returns 1 if string <em>s</em> of size <em>slen</em> begins with
+null-terminated string <em>t</em>, ignoring case, and 0 otherwise.
+</p>
+
+<p>
+<code> size_t case_str (char const *haystack, char const *needle) </code> <br>
+Looks for the first occurrence of null-terminated string <em>needle</em> in
+null-terminated string <em>haystack</em>, ignoring case while comparing
+bytes. Returns the index of the first byte of this occurrence or the length of
+<em>haystack</em> if <em>needle</em> is not presented in <em>haystack</em>.
+</p>
+
+<h2> Macros </h2>
+
+<p>
+These macros are either wrappers around functions described above or C standard
+library functions. They only exist for compatibility purposes. Programmers are
+expected to use the standard functions directly: in the rare case where a
+standard function interface is <em>good</em>, it is best to use it.
+</p>
+
+<p>
+<code> byte_copy(to, n, from) </code> <br>
+<code> byte_copyr(to, n, from) </code> <br>
+Same as <tt>memmove(to, from, n)</tt>.
+</p>
+
+<p>
+<code> byte_diff(a, n, b) </code> <br>
+Same as <tt>memcmp(a, b, n)</tt>.
+</p>
+
+<p>
+<code> byte_zero(p, n) </code> <br>
+Same as <tt>memset(p, 0 ,n)</tt>. There is a caveat in zeroing memory range with
+<tt>memset</tt> — compiler may omit the call to <tt>memset</tt> if it is
+called in the end of function. If you need to destroy sensitive data, use
+<tt>byte_zzero</tt> instead.
+</p>
+
+<p>
+<code> str_len(s) </code> <br>
+Same as <tt>strlen(s)</tt>.
+</p>
+
+<p>
+<code> str_nlen(s) </code> <br>
+Same as <tt>strnlen(s)</tt>.
+</p>
+
+<p>
+<code> str_diff(s1, s2) </code> <br>
+Same as <tt>strcmp(s1, s2)</tt>.
+</p>
+
+<p>
+<code> str_diffn(s1, s2, n) </code> <br>
+Same as <tt>strncmp(s1, s2, n)</tt>.
+</p>
+
+<p>
+<code> str_copy(to, from) </code> <br>
+Copies null-terminated string <em>from</em>, including null terminator, to
+buffer <em>to</em>. Returns the length of the string.
+</p>
+
+<p>
+<code> case_diffs(s1, s2) </code> <br>
+Same as <tt>strcasecmp(s1, s2)</tt>.
+</p>
+
+<p>
+<code> case_diffn(s1, s2, n) </code> <br>
+Same as <tt>strcasecmp(s1, s2, n)</tt>.
+</p>
+
+<p>
+<code> byte_equal(s, n, t) </code> <br>
+Same as <tt>!memcmp(s, t, n)</tt>.
+</p>
+
+<p>
+<code> str_diffb(a, n, b) </code> <br>
+Same as <tt>strncmp(a, b, n)</tt>.
+</p>
+
+<p>
+<code> str_equal(s, t) </code> <br>
+Same as <tt>!strcmp(s, t)</tt>.
+</p>
+
+<p>
+<code> case_diffb(a, n, b) </code> <br>
+Same as <tt>strncasecmp(a, b, n)</tt>.
+</p>
+
+<p>
+<code> case_equals(a, b) </code> <br>
+Same as <tt>!strcasecmp(a, b)</tt>.
+</p>
+
+<p>
+<code> case_equalb(a, n, b) </code> <br>
+Same as <tt>!strncasecmp(a, b, n)</tt>.
+</p>
+
+<p>
+<code> case_starts(s, t) </code> <br>
+Same as <tt>case_startb(s, strlen(s), t)</tt>.
</p>
</body>
