bytestr.html (8458B)
1 <html> 2 <head> 3 <meta name="viewport" content="width=device-width, initial-scale=1.0" /> 4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> 5 <meta http-equiv="Content-Language" content="en" /> 6 <title>skalibs: the bytestr header</title> 7 <meta name="Description" content="skalibs: the bytestr header" /> 8 <meta name="Keywords" content="skalibs header bytestr byte string memory" /> 9 <!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> --> 10 </head> 11 <body> 12 13 <p> 14 <a href="index.html">libstddjb</a><br /> 15 <a href="../libskarnet.html">libskarnet</a><br /> 16 <a href="../index.html">skalibs</a><br /> 17 <a href="//skarnet.org/software/">Software</a><br /> 18 <a href="//skarnet.org/">skarnet.org</a> 19 </p> 20 21 <h1> The <tt>skalibs/bytestr.h</tt> header </h1> 22 23 <p> 24 The following functions are declared in the <tt>skalibs/bytestr.h</tt> header 25 and implemented in the <tt>libskarnet.a</tt> or <tt>libskarnet.so</tt> library. 26 </p> 27 28 <h2> Purpose </h2> 29 30 <p> 31 These functions handle arrays of bytes (strings). They are similar to their 32 counterparts from the standard 33 <a href="https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/string.h.html">string.h</a> 34 header, but they return <em>indices</em> instead of <em>pointers</em>. 35 </p> 36 37 <p> 38 <tt>byte_*</tt> functions and macros work with strings that are not 39 necessarily null-terminated, but require sizes of the strings to be passed. 40 On the contary, <tt>str_*</tt> family accepts null-terminated strings. 41 <tt>case_*</tt> functions and macros are like their <tt>str_*</tt> counterparts, 42 but are case-insensitive. 43 </p> 44 45 <h2> Functions </h2> 46 47 <p> 48 <code> size_t byte_chr (char const *s, size_t n, int c) </code> <br> 49 Looks for the first occurrence of byte <em>c</em> in array <em>s</em> of size 50 <em>n</em>. Returns its index, or <em>n</em> if there is no such byte in 51 <em>s</em>. 52 </p> 53 54 <p> 55 <code> size_t byte_rchr (char const *s, size_t n, int c) </code> <br> 56 Looks for the last occurrence of byte <em>c</em> in array <em>s</em> of size 57 <em>n</em>. Returns its index, or <em>n</em> if there is no such byte in 58 <em>s</em>. 59 </p> 60 61 <p> 62 <code> size_t byte_in (char const *s, size_t n, char const *sep, size_t len) </code> <br> 63 Looks for the first occurrence of any byte from array <em>sep</em> of size 64 <em>len</em> in array <em>s</em> of size <em>n</em>. Returns the index of such 65 an occurrence, or <em>n</em> if there are no bytes from <em>sep</em> in <em>s</em>. 66 </p> 67 68 <p> 69 <code> size_t byte_count (char const *s, size_t len, char b) </code> <br> 70 Returns the amount of occurrences of byte <em>b</em> in string <em>s</em> of 71 size <em>len</em>. 72 </p> 73 74 <p> 75 <code> size_t byte_search (char const *haystack, size_t hlen, char const *needle, size_t nlen) </code> <br> 76 Looks for the first occurrence of string <em>needle</em> of size <em>nlen</em> in 77 string <em>haystack</em> of size <em>hlen</em>. Returns the index of the first 78 byte of that occurrence, or <tt>hlen + 1 - nlen</tt> if <em>needle</em> cannot 79 be found in <em>haystack</em>. 80 </p> 81 82 <p> 83 <code> void byte_zzero (char *s, size_t n) </code> <br> 84 Zeroes <em>n</em> bytes of memory beginning with address <em>s</em>. Special 85 measures are taken to prevent the compiler from optimizing out the call: 86 <ul> 87 <li> If the <tt>explicit_bzero</tt> function is present on the system, it is 88 used. Calls to this function are guaranteed not to be removed by the compiler. </li> 89 <li> Otherwise, <tt>byte_zzero</tt> performs a normal <tt>memset</tt> followed 90 by a special no-op function with a weak alias in order to trick the compiler. </li> 91 </ul> 92 This is useful for erasing sensitive data before returning from some 93 function, typically in cryptography settings. Compilers usually remove 94 <tt>memset</tt> calls since these have no observable effect for the rest of the code. 95 </p> 96 97 <p> 98 <code> size_t str_chr (char const *s, int c) </code> <br> 99 Looks for the first occurrence of byte <em>c</em> in null-terminated string 100 <em>s</em>. Returns the index of this occurrence, or the length of the string 101 if there is no such byte in <em>s</em>. 102 </p> 103 104 <p> 105 <code> size_t str_rchr (char const *s, int c) </code> <br> 106 Looks for the last occurrence of byte <em>c</em> in null-terminated string 107 <em>s</em>. Returns the index of this occurrence, or the length of the string 108 if there is no such byte in <em>s</em>. 109 </p> 110 111 <p> 112 <code> int str_start (char const *s, char const *t) </code> <br> 113 Returns 1 if (null-terminated) string <em>s</em> begins with (null-terminated) 114 string <em>t</em>, and 0 otherwise. 115 </p> 116 117 <p> 118 <code> size_t str_strn (char const *haystack, size_t hlen, char const *needle, size_t nlen) </code> <br> 119 Looks for the first occurrence of string <em>needle</em> of size <em>nlen</em> in 120 string <em>haystack</em> of size <em>hlen</em>. Returns the index of the first 121 character in this occurrence, or <em>hlen</em> if <em>needle</em> is not present 122 in <em>haystack</em>. 123 </p> 124 125 <p> 126 <code> void case_lowers (char *s) </code> <br> 127 Turns all capital letters in null-terminated string <em>s</em> into lowercase 128 letters. This function only works with ASCII symbols. 129 </p> 130 131 <p> 132 <code> void case_lowerb (char *s, size_t len) </code> <br> 133 Turns all capital letters in string <em>s</em> of size <em>len</em> into 134 lowercase letters. This function only works with ASCII symbols. 135 </p> 136 137 <p> 138 <code> void case_uppers (char *s) </code> <br> 139 Turns all lowercase letters in null-terminated string <em>s</em> into capital 140 letters. This function only works with ASCII symbols. 141 </p> 142 143 <p> 144 <code> void case_upperb (char *s, size_t len) </code> <br> 145 Turns all lowercase letters in string <em>s</em> of size <em>len</em> into 146 capital letters. This function only works with ASCII symbols. 147 </p> 148 149 <p> 150 <code> int case_startb (char const *s, size_t slen, char const *t) </code> <br> 151 Returns 1 if string <em>s</em> of size <em>slen</em> begins with 152 null-terminated string <em>t</em>, ignoring case, and 0 otherwise. 153 </p> 154 155 <p> 156 <code> size_t case_str (char const *haystack, char const *needle) </code> <br> 157 Looks for the first occurrence of null-terminated string <em>needle</em> in 158 null-terminated string <em>haystack</em>, ignoring case while comparing 159 bytes. Returns the index of the first byte of this occurrence or the length of 160 <em>haystack</em> if <em>needle</em> is not presented in <em>haystack</em>. 161 </p> 162 163 <h2> Macros </h2> 164 165 <p> 166 These macros are either wrappers around functions described above or C standard 167 library functions. They only exist for compatibility purposes. Programmers are 168 expected to use the standard functions directly: in the rare case where a 169 standard function interface is <em>good</em>, it is best to use it. 170 </p> 171 172 <p> 173 <code> byte_copy(to, n, from) </code> <br> 174 <code> byte_copyr(to, n, from) </code> <br> 175 Same as <tt>memmove(to, from, n)</tt>. 176 </p> 177 178 <p> 179 <code> byte_diff(a, n, b) </code> <br> 180 Same as <tt>memcmp(a, b, n)</tt>. 181 </p> 182 183 <p> 184 <code> byte_zero(p, n) </code> <br> 185 Same as <tt>memset(p, 0 ,n)</tt>. There is a caveat in zeroing memory range with 186 <tt>memset</tt> — compiler may omit the call to <tt>memset</tt> if it is 187 called in the end of function. If you need to destroy sensitive data, use 188 <tt>byte_zzero</tt> instead. 189 </p> 190 191 <p> 192 <code> str_len(s) </code> <br> 193 Same as <tt>strlen(s)</tt>. 194 </p> 195 196 <p> 197 <code> str_nlen(s) </code> <br> 198 Same as <tt>strnlen(s)</tt>. 199 </p> 200 201 <p> 202 <code> str_diff(s1, s2) </code> <br> 203 Same as <tt>strcmp(s1, s2)</tt>. 204 </p> 205 206 <p> 207 <code> str_diffn(s1, s2, n) </code> <br> 208 Same as <tt>strncmp(s1, s2, n)</tt>. 209 </p> 210 211 <p> 212 <code> str_copy(to, from) </code> <br> 213 Copies null-terminated string <em>from</em>, including null terminator, to 214 buffer <em>to</em>. Returns the length of the string. 215 </p> 216 217 <p> 218 <code> case_diffs(s1, s2) </code> <br> 219 Same as <tt>strcasecmp(s1, s2)</tt>. 220 </p> 221 222 <p> 223 <code> case_diffn(s1, s2, n) </code> <br> 224 Same as <tt>strcasecmp(s1, s2, n)</tt>. 225 </p> 226 227 <p> 228 <code> byte_equal(s, n, t) </code> <br> 229 Same as <tt>!memcmp(s, t, n)</tt>. 230 </p> 231 232 <p> 233 <code> str_diffb(a, n, b) </code> <br> 234 Same as <tt>strncmp(a, b, n)</tt>. 235 </p> 236 237 <p> 238 <code> str_equal(s, t) </code> <br> 239 Same as <tt>!strcmp(s, t)</tt>. 240 </p> 241 242 <p> 243 <code> case_diffb(a, n, b) </code> <br> 244 Same as <tt>strncasecmp(a, b, n)</tt>. 245 </p> 246 247 <p> 248 <code> case_equals(a, b) </code> <br> 249 Same as <tt>!strcasecmp(a, b)</tt>. 250 </p> 251 252 <p> 253 <code> case_equalb(a, n, b) </code> <br> 254 Same as <tt>!strncasecmp(a, b, n)</tt>. 255 </p> 256 257 <p> 258 <code> case_starts(s, t) </code> <br> 259 Same as <tt>case_startb(s, strlen(s), t)</tt>. 260 </p> 261 262 </body> 263 </html>