author | Olivier Brunel
<jjk@jjacky.com> 2023-06-07 18:14:28 UTC |
committer | Olivier Brunel
<jjk@jjacky.com> 2023-07-24 10:16:41 UTC |
parent | 40a7aa78c1a22267039e186e778be20dd27b26c8 |
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.