1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
|
<html>
<head>
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<meta http-equiv="Content-Language" content="en" />
<title>skalibs: the bytestr header</title>
<meta name="Description" content="skalibs: the bytestr header" />
<meta name="Keywords" content="skalibs header bytestr byte string memory" />
<!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> -->
</head>
<body>
<p>
<a href="index.html">libstddjb</a><br />
<a href="../libskarnet.html">libskarnet</a><br />
<a href="../index.html">skalibs</a><br />
<a href="//skarnet.org/software/">Software</a><br />
<a href="//skarnet.org/">skarnet.org</a>
</p>
<h1> The <tt>skalibs/bytestr.h</tt> header </h1>
<p>
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>
</html>
|
