[PATCH skalibs] Document skalibs/bytestr.h header

---
 doc/libstddjb/bytestr.html | 235 ++++++++++++++++++++++++++++++++++++-
 1 file changed, 234 insertions(+), 1 deletion(-)
diff --git a/doc/libstddjb/bytestr.html b/doc/libstddjb/bytestr.html
index 8ae68aa..53cd902 100644
--- a/doc/libstddjb/bytestr.html
+++ b/doc/libstddjb/bytestr.html
_at__at_ -21,8 +21,241 _at__at_
 <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/siovec.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 <tt>string.h</tt> 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 occurence 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 occurence 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 occurence of any byte from array <em>sep</em> of size
+<em>len</em> in array <em>s</em> of size <em>n</em>. Returns index of such
+occurence or <em>n</em> if there is 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 occurences 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 occurence 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 in such the occurence, or <tt>hlen + 1 - nlen</tt>.
+</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 compiler from optimizing this function calls out:
+<ul>
+    <li>If <tt>explicit_bzero</tt> function is present on the system, it is
+        used. This function calls are guaranteed to not be removed by compiler.
+    </li>
+    <li>Otherwise, this function performs usual <tt>memset</tt> and then calls
+        special no-op function with weak alias to trick the compiler.</li>
+</ul>
+This is useful for erasing sensitive data before returning from some
+function. 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 occurence of byte <em>c</em> in null-terminated string
+<em>s</em>. Returns index of such occurence, or 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 occurence of byte <em>c</em> in null-terminated string
+<em>s</em>. Returns index of such occurence, or 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 whether null-terminated string <em>s</em> begins with null-terminated
+string <em>t</em>, not including the null terminator, 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 occurence 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 occurence, 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 works only 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 works only 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 works only 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 works only with ASCII symbols.
+</p>
+
+<p>
+<code> int case_startb (char const *s, size_t slen, char const *t) </code> <br>
+Returns 1 whether string <em>s</em> of size <em>slen</em> begins with
+null-terminated string <em>t</em>, not including the null terminator and
+ignoring case, and 0 otherwise.
+</p>
+
+<p>
+<code> size_t case_str (char const *haystack, char const *needle) </code> <br>
+Looks for the first occurence of null-terminated string <em>needle</em> in
+null-terminated string <em>haystack</em>, ignoring the case while comparing
+bytes. Returns index of the first byte of such occurence 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 exist for compatibility purposes. Programmers are
+expected to use relevant functions directly.
+</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> &mdash; 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>
 </html>
-- 
2.34.1