🧵 str
Painfully common string utilities for C
Loading...
Searching...
No Matches
str.h
Go to the documentation of this file.
1/*
2 * 🧵 str — str.h
3 * Copyright (c) 2025–2026 Fawn <rubiefawn@proton.me>
4 *
5 * Permission to use, copy, modify, and distribute this software for any
6 * purpose with or without fee is hereby granted, provided that the above
7 * copyright notice and this permission notice appear in all copies.
8 *
9 * THE SOFTWARE IS PROVIDED “AS IS” AND THE AUTHOR DISCLAIMS ALL WARRANTIES
10 * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
11 * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
12 * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
13 * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
14 * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
15 * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
16 */
17
22#pragma once
23#include <stddef.h>
24#if __STDC_VERSION__ < 202311L
25 #include <stdbool.h>
26#endif
27
35typedef struct str {
36 char *data;
37 size_t len;
39
41#define str_literal(SZ_LITERAL) (str){ (SZ_LITERAL), sizeof(SZ_LITERAL) - 1 }
42
46
49str str_slice_cstr(char *sz, size_t len);
50
54
58
62
66
69str str_strip_prefix_cstr(str it, const char *prefix);
70
73str str_strip_prefix_if(str it, bool (*predicate)(char));
74
77#define str_strip_prefix(IT, PREFIX) _Generic((PREFIX),\
78 str : str_strip_prefix_str,\
79 const char* : str_strip_prefix_cstr,\
80 char* : str_strip_prefix_cstr,\
81 bool (*)(char): str_strip_prefix_if\
82)((IT), (PREFIX))
83
87
90str str_strip_postfix_cstr(str it, const char *postfix);
91
94str str_strip_postfix_if(str it, bool (*predicate)(char));
95
98#define str_strip_postfix(IT, POSTFIX) _Generic((POSTFIX),\
99 str : str_strip_postfix_str,\
100 const char* : str_strip_postfix_cstr,\
101 char* : str_strip_postfix_cstr,\
102 bool (*)(char): str_strip_postfix_if\
103)((IT), (POSTFIX))
104
108
110int str_cmp_cstr(str a, const char *b);
111
113int cstr_cmp_str(const char *a, str b);
114
117#define cstr_cmp_cstr strcmp
118
121#define str_cmp(LHS, RHS) _Generic((LHS),\
122 str: _Generic((RHS),\
123 str : str_cmp_str,\
124 const char*: str_cmp_cstr,\
125 char*: str_cmp_cstr\
126 ),\
127 const char*: _Generic((RHS),\
128 str : cstr_cmp_str,\
129 const char*: strcmp,\
130 char*: strcmp\
131 ),\
132 char*: _Generic((RHS),\
133 str : cstr_cmp_str,\
134 const char*: strcmp,\
135 char*: strcmp\
136 )\
137)((LHS), (RHS))
138
140bool str_eq_str(str a, str b);
141
143bool str_eq_cstr(str a, const char *b);
144
146bool cstr_eq_str(const char *a, str b);
147
149bool cstr_eq_cstr(const char *a, const char *b);
150
152#define str_eq(LHS, RHS) _Generic((LHS),\
153 str: _Generic((RHS),\
154 str : str_eq_str,\
155 const char*: str_eq_cstr,\
156 char*: str_eq_cstr\
157 ),\
158 const char*: _Generic((RHS),\
159 str : cstr_eq_str,\
160 const char*: cstr_eq_cstr,\
161 char*: cstr_eq_cstr\
162 ),\
163 char*: _Generic((RHS),\
164 str : cstr_eq_str,\
165 const char*: cstr_eq_cstr,\
166 char*: cstr_eq_cstr\
167 )\
168)((LHS), (RHS))
169
180size_t str_eq_str_any(str it, size_t count, ...);
181
192size_t str_eq_strs_any(str it, size_t count, const str others[static count]);
193
195size_t str_eq_cstr_any(str it, size_t count, ...);
196
198size_t str_eq_cstrs_any(str it, size_t count, const char *others[static count]);
199
201size_t cstr_eq_str_any(const char *it, size_t count, ...);
202
204size_t cstr_eq_strs_any(const char *it, size_t count, const str others[static count]);
205
207size_t cstr_eq_cstr_any(const char *it, size_t count, ...);
208
210size_t cstr_eq_cstrs_any(const char *it, size_t count, const char *others[static count]);
211
225#if __STDC_VERSION__ >= 202311L
226 #define str_eq_any(LHS, COUNT, RHS, ...) _Generic((LHS),\
227 str: _Generic((RHS),\
228 str : str_eq_str_any,\
229 const str* : str_eq_strs_any,\
230 str* : str_eq_strs_any,\
231 const char* : str_eq_cstr_any,\
232 char* : str_eq_cstr_any,\
233 const char**: str_eq_cstrs_any,\
234 char**: str_eq_cstrs_any\
235 ),\
236 const char*: _Generic((RHS),\
237 str : cstr_eq_str_any,\
238 const str* : cstr_eq_strs_any,\
239 str* : cstr_eq_strs_any,\
240 const char* : cstr_eq_cstr_any,\
241 char* : cstr_eq_cstr_any,\
242 const char**: cstr_eq_cstrs_any,\
243 char**: cstr_eq_cstrs_any\
244 ),\
245 char*: _Generic((RHS),\
246 str : cstr_eq_str_any,\
247 const str* : cstr_eq_strs_any,\
248 str* : cstr_eq_strs_any,\
249 const char* : cstr_eq_cstr_any,\
250 char* : cstr_eq_cstr_any,\
251 const char**: cstr_eq_cstrs_any,\
252 char**: cstr_eq_cstrs_any\
253 )\
254 )((LHS), (COUNT), (RHS) __VA_OPT__(, __VA_ARGS__))
255#elif defined(__GNUC__) || defined(__clang__) || defined(_MSC_VER)
256 // ##__VA_ARGS__ is a GNU C extension. It is available on GCC from
257 // at least v3.4.6 (maybe earlier) and clang v3.0.0 (maybe earlier).
258 // It also seems to work on MSVC 16.0+, though this is undocumented
259 // behavior (it works even with /Zc:preprocessor), and I don't have
260 // access to earlier versions to test, so I don't know how far back
261 // this works.
262 #define str_eq_any(LHS, COUNT, RHS, ...) _Generic((LHS),\
263 str: _Generic((RHS),\
264 str : str_eq_str_any,\
265 const str* : str_eq_strs_any,\
266 str* : str_eq_strs_any,\
267 const char* : str_eq_cstr_any,\
268 char* : str_eq_cstr_any,\
269 const char**: str_eq_cstrs_any,\
270 char**: str_eq_cstrs_any\
271 ),\
272 const char*: _Generic((RHS),\
273 str : cstr_eq_str_any,\
274 const str* : cstr_eq_strs_any,\
275 str* : cstr_eq_strs_any,\
276 const char* : cstr_eq_cstr_any,\
277 char* : cstr_eq_cstr_any,\
278 const char**: cstr_eq_cstrs_any,\
279 char**: cstr_eq_cstrs_any\
280 ),\
281 char*: _Generic((RHS),\
282 str : cstr_eq_str_any,\
283 const str* : cstr_eq_strs_any,\
284 str* : cstr_eq_strs_any,\
285 const char* : cstr_eq_cstr_any,\
286 char* : cstr_eq_cstr_any,\
287 const char**: cstr_eq_cstrs_any,\
288 char**: cstr_eq_cstrs_any\
289 )\
290 )((LHS), (COUNT), (RHS), ##__VA_ARGS__)
291#else
292 #if defined(_MSC_VER) // < v16.0?
293 #pragma message("Neither C23's __VA_OPT__ nor GNU's ##__VA_ARGS__ are available, str_eq_any() will be unavailable")
294 #elif defined(__clang__) // < v3.0.0?
295 #pragma message "Neither C23's __VA_OPT__ nor GNU's ##__VA_ARGS__ are available, str_eq_any() will be unavailable"
296 #elif defined(__GNUC__) // < v3.4.6?
297 #pragma GCC warning "Neither C23's __VA_OPT__ nor GNU's ##__VA_ARGS__ are available, str_eq_any() will be unavailable"
298 #endif
299 // Portable #warning directive was added in C23 lol
300#endif
301
312size_t str_satisfies_any(str it, size_t count, ...);
313
324size_t str_satisfies_anys(str it, size_t count, bool (*predicates[static count])(str));
325
336size_t cstr_satisfies_any(const char *it, size_t count, ...);
337
339size_t cstr_satisfies_anys(const char *it, size_t count, bool (*predicates[static count])(const char*));
340
348bool str_satisfies_all(str it, size_t count, ...);
349
357bool str_satisfies_alls(str it, size_t count, bool (*predicates[static count])(str));
358
366bool cstr_satisfies_all(const char *it, size_t count, ...);
367
369bool cstr_satisfies_alls(const char *it, size_t count, bool (*predicates[static count])(const char*));
370
377bool str_chars_satisfies(str it, bool (*predicate)(char));
378
380bool cstr_chars_satisfies(const char *it, bool (*predicate)(char));
381
384size_t str_has_prefix_str(str it, str prefix);
385
387size_t str_has_prefix_cstr(str it, const char *prefix);
388
390size_t cstr_has_prefix_str(const char *it, str prefix);
391
393size_t cstr_has_prefix_cstr(const char *it, const char *prefix);
394
397size_t str_has_postfix_str(str it, str postfix);
398
400size_t str_has_postfix_cstr(str it, const char *postfix);
401
403size_t cstr_has_postfix_str(const char *it, str postfix);
404
406size_t cstr_has_postfix_cstr(const char *it, const char *postfix);
407
409#define str_has_prefix(LHS, RHS) _Generic((LHS),\
410 str: _Generic((RHS),\
411 str : str_has_prefix_str,\
412 const char*: str_has_prefix_cstr,\
413 char*: str_has_prefix_cstr\
414 ),\
415 const char*: _Generic((RHS),\
416 str : cstr_has_prefix_str,\
417 const char*: cstr_has_prefix_cstr,\
418 char*: cstr_has_prefix_cstr\
419 ),\
420 char*: _Generic((RHS),\
421 str : cstr_has_prefix_str,\
422 const char*: cstr_has_prefix_cstr,\
423 char*: cstr_has_prefix_cstr\
424 )\
425)((LHS), (RHS))
426
428#define str_has_postfix(LHS, RHS) _Generic((LHS),\
429 str: _Generic((RHS),\
430 str : str_has_postfix_str,\
431 const char*: str_has_postfix_cstr,\
432 char*: str_has_postfix_cstr\
433 ),\
434 const char*: _Generic((RHS),\
435 str : cstr_has_postfix_str,\
436 const char*: cstr_has_postfix_cstr,\
437 char*: cstr_has_postfix_cstr\
438 ),\
439 char*: _Generic((RHS),\
440 str : cstr_has_postfix_str,\
441 const char*: cstr_has_postfix_cstr,\
442 char*: cstr_has_postfix_cstr\
443 )\
444)((LHS), (RHS))
445
463str str_split_char(str *rest, char delim);
464
482str str_rsplit_char(str *rest, char delim);
483
493str str_split_if(str *rest, bool (*predicate)(char));
494
504str str_rsplit_if(str *rest, bool (*predicate)(char));
505
507#define str_split(IT, ON) _Generic((ON),\
508 char : str_split_char,\
509 int : str_split_char,\
510 bool (*)(char): str_split_if\
511)((IT), (ON))
512
514#define str_rsplit(IT, ON) _Generic((ON),\
515 char : str_rsplit_char,\
516 int : str_rsplit_char,\
517 bool (*)(char): str_rsplit_if\
518)((IT), (ON))
size_t cstr_has_prefix_cstr(const char *it, const char *prefix)
Checks if a string begins with another string.
size_t str_eq_cstrs_any(str it, size_t count, const char *others[static count])
Compares a string to several others to see if its contents are equal to any of them.
size_t str_eq_str_any(str it, size_t count,...)
Compares a string to several others to see if its contents are equal to any of them.
size_t str_eq_strs_any(str it, size_t count, const str others[static count])
Compares a string to several others to see if its contents are equal to any of them.
size_t cstr_has_postfix_cstr(const char *it, const char *postfix)
Checks if a string ends with another string.
str str_strip_prefix_if(str it, bool(*predicate)(char))
Returns a non-owning copy of a str with all leading characters satisfying predicate removed.
bool str_eq_cstr(str a, const char *b)
Compares two strings to see if their contents are equal.
str str_strip_prefix_cstr(str it, const char *prefix)
Returns a non-owning copy of a str with a given prefix removed, if it is present.
bool cstr_eq_str(const char *a, str b)
Compares two strings to see if their contents are equal.
str str_strip_whitespace(str it)
Returns a non-owning copy of a str with all leading and trailing whitespace removed.
str str_strip_postfix_str(str it, str postfix)
Returns a non-owning copy of a str with a given postfix removed, if it is present.
size_t cstr_satisfies_any(const char *it, size_t count,...)
Checks if a string satisfies any of several predicates.
int str_cmp_str(str a, str b)
Compares two strings lexicographically.
bool str_satisfies_alls(str it, size_t count, bool(*predicates[static count])(str))
Checks if a string satisfies all of several predicates.
size_t cstr_eq_strs_any(const char *it, size_t count, const str others[static count])
Compares a string to several others to see if its contents are equal to any of them.
bool str_eq_str(str a, str b)
Compares two strings to see if their contents are equal.
bool str_satisfies_all(str it, size_t count,...)
Checks if a string satisfies all of several predicates.
size_t cstr_has_postfix_str(const char *it, str postfix)
Checks if a string ends with another string.
str str_strip_whitespace_pre(str it)
Returns a non-owning copy of a str with all leading whitespace removed.
size_t cstr_has_prefix_str(const char *it, str prefix)
Checks if a string begins with another string.
str str_rsplit_char(str *rest, char delim)
Splits a str on the last occurence of the delimiter delim.
str str_strip_prefix_str(str it, str prefix)
Returns a non-owning copy of a str with a given prefix removed, if it is present.
size_t cstr_eq_cstr_any(const char *it, size_t count,...)
Compares a string to several others to see if its contents are equal to any of them.
int str_cmp_cstr(str a, const char *b)
Compares two strings lexicographically.
str str_split_if(str *rest, bool(*predicate)(char))
Splits a str on the first character satisfying predicate.
str str_rsplit_if(str *rest, bool(*predicate)(char))
Splits a str on the last character satisfying predicate.
str str_split_char(str *rest, char delim)
Splits a str on the first occurence of the delimiter delim.
str str_strip_postfix_cstr(str it, const char *postfix)
Returns a non-owning copy of a str with a given postfix removed, if it is present.
bool cstr_satisfies_all(const char *it, size_t count,...)
Checks if a string satisfies all of several predicates.
size_t str_has_prefix_str(str it, str prefix)
Checks if a string begins with another string.
str str_slice_cstr(char *sz, size_t len)
Constructs a non-owning str from part of a nil-terminated C-string.
bool cstr_chars_satisfies(const char *it, bool(*predicate)(char))
Checks if all characters in a string satisfies a predicate.
size_t cstr_eq_str_any(const char *it, size_t count,...)
Compares a string to several others to see if its contents are equal to any of them.
int cstr_cmp_str(const char *a, str b)
Compares two strings lexicographically.
size_t cstr_eq_cstrs_any(const char *it, size_t count, const char *others[static count])
Compares a string to several others to see if its contents are equal to any of them.
bool cstr_satisfies_alls(const char *it, size_t count, bool(*predicates[static count])(const char *))
Checks if a string satisfies all of several predicates.
str str_from_cstr(char *sz)
Constructs a non-owning str from a nil-terminated C-string.
size_t str_has_postfix_str(str it, str postfix)
Checks if a string ends with another string.
size_t str_has_postfix_cstr(str it, const char *postfix)
Checks if a string ends with another string.
size_t cstr_satisfies_anys(const char *it, size_t count, bool(*predicates[static count])(const char *))
Checks if a string satisfies any of several predicates.
size_t str_eq_cstr_any(str it, size_t count,...)
Compares a string to several others to see if its contents are equal to any of them.
size_t str_satisfies_any(str it, size_t count,...)
Checks if a string satisfies any of several predicates.
str str_strip_whitespace_post(str it)
Returns a non-owning copy of a str with all trailing whitespace removed.
str str_strip_postfix_if(str it, bool(*predicate)(char))
Returns a non-owning copy of a str with all trailing characters satisfying predicate removed.
bool str_chars_satisfies(str it, bool(*predicate)(char))
Checks if all characters in a string satisfies a predicate.
size_t str_has_prefix_cstr(str it, const char *prefix)
Checks if a string begins with another string.
size_t str_satisfies_anys(str it, size_t count, bool(*predicates[static count])(str))
Checks if a string satisfies any of several predicates.
bool cstr_eq_cstr(const char *a, const char *b)
Compares two strings to see if their contents are equal.
A string "slice", which is a pointer & length pair.
Definition str.h:35
char * data
Pointer to the start of the string.
Definition str.h:36
size_t len
The length of the string.
Definition str.h:37