diff options
| -rw-r--r-- | doc/libstddjb/bytestr.html | 237 |
1 files changed, 236 insertions, 1 deletions
diff --git a/doc/libstddjb/bytestr.html b/doc/libstddjb/bytestr.html index 8ae68aa..951712b 100644 --- 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> |