Mstdlib-1.24.0
m_str.h
1/* The MIT License (MIT)
2 *
3 * Copyright (c) 2015 Monetra Technologies, LLC.
4 *
5 * Permission is hereby granted, free of charge, to any person obtaining a copy
6 * of this software and associated documentation files (the "Software"), to deal
7 * in the Software without restriction, including without limitation the rights
8 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9 * copies of the Software, and to permit persons to whom the Software is
10 * furnished to do so, subject to the following conditions:
11 *
12 * The above copyright notice and this permission notice shall be included in
13 * all copies or substantial portions of the Software.
14 *
15 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
21 * THE SOFTWARE.
22 */
23
24#ifndef __M_STR_H__
25#define __M_STR_H__
26
27/* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - */
28
29#include <mstdlib/mstdlib.h>
30#include <mstdlib/base/m_chr.h>
31
32/* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - */
33
34__BEGIN_DECLS
35
36M_BEGIN_IGNORE_REDECLARATIONS
37#if M_BLACKLIST_FUNC == 1
38# ifdef strlen
39# undef strlen
40# else
41 M_DEPRECATED_FOR(M_str_len, size_t strlen(const char *))
42# endif
43# ifdef strcat
44# undef strcat
45# else
46 M_DEPRECATED_FOR(M_str_cat, char *strcat(char *, const char *))
47# endif
48# ifdef strcpy
49# undef strcpy
50# else
51 M_DEPRECATED_FOR(M_str_cpy, char *strcpy(char *, const char *))
52# endif
53# ifdef strncat
54# undef strncat
55# else
56 M_DEPRECATED_FOR(M_str_cat, char *strncat(char *, const char *, size_t))
57# endif
58# ifdef strlcat
59# undef strlcat
60# else
61 M_DEPRECATED_FOR(M_str_cat, size_t strlcat(char *, const char *, size_t))
62# endif
63# ifdef strncpy
64# undef strncpy
65# else
66 M_DEPRECATED_FOR(M_str_cpy, char *strncpy(char *, const char *, size_t))
67# endif
68# ifdef strlcpy
69# undef strlcpy
70# else
71 M_DEPRECATED_FOR(M_str_cpy, size_t strlcpy(char *, const char *, size_t))
72# endif
73
74# ifdef strcmp
75# undef strcmp
76# else
77 M_DEPRECATED_FOR(M_str_eq, int strcmp(const char *, const char *))
78# endif
79
80# ifdef strncmp
81# undef strncmp
82# else
83 M_DEPRECATED_FOR(M_str_eq_max, int strncmp(const char *, const char *, size_t))
84# endif
85
86# ifdef strcasecmp
87# undef strcasecmp
88# else
89 M_DEPRECATED_FOR(M_str_caseeq, int strcasecmp(const char *, const char *))
90# endif
91
92# ifdef strncasecmp
93# undef strncasecmp
94# else
95 M_DEPRECATED_FOR(M_str_caseeq_max, int strncasecmp(const char *, const char *, size_t))
96# endif
97
98# ifdef atoi
99# undef atoi
100# else
101 M_DEPRECATED_FOR(M_str_to_int32, int atoi(const char *))
102# endif
103
104# ifdef atoll
105# undef atoll
106# else
107 M_DEPRECATED_FOR(M_str_to_int64, long long atoll(const char *))
108# endif
109
110#endif
111M_END_IGNORE_REDECLARATIONS
112
113/* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - */
114
115/*! \defgroup m_string String Functions
116 * \ingroup mstdlib_base
117 * String Validation and Manipulation Functions
118 */
119
120/* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - */
121
122/*! \addtogroup m_str_check String Checking/Validation
123 * \ingroup m_string
124 *
125 * String Checking and Validation
126 *
127 * @{
128 */
129
130/* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
131 * Safety Wrappers
132 */
133
134/*! Ensure a NULL will not be used as a string.
135 *
136 * \param[in] s NULL-terminated string.
137 *
138 * \return "" if s is NULL or s.
139 */
140M_API const char *M_str_safe(const char *s);
141
142
143/* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
144 * Query
145 */
146
147/*! Determines if the string is considered empty.
148 *
149 * A string is considered empty if it is NULL or has a 0 length.
150 *
151 * \param[in] s NULL-terminated string.
152 *
153 * \return M_TRUE if it is empty. Otherwise M_FALSE.
154 */
155M_API M_bool M_str_isempty(const char *s) M_WARN_UNUSED_RESULT;
156
157
158/*! Check if a string is considered true.
159 *
160 * A string is considered true when it equals any of the following (case insensitive):
161 * - t
162 * - true
163 * - y
164 * - yes
165 * - 1
166 * - on
167 *
168 * \param[in] s NULL-terminated string.
169 *
170 * \return M_TRUE if it is considered true. Otherwise M_FALSE.
171 */
172M_API M_bool M_str_istrue(const char *s) M_WARN_UNUSED_RESULT;
173
174
175/*! A wrapper around strlen that treats NULL as a string with length 0.
176 *
177 * \param[in] s NULL-terminated string.
178 *
179 * \return Length of string.
180 */
181M_API size_t M_str_len(const char *s) M_WARN_UNUSED_RESULT;
182
183
184/*! A wrapper around strlen that treats NULL as a string with length 0, but returns at most max bytes.
185 *
186 * \param[in] s NULL-terminated string.
187 * \param[in] max Maximum number of bytes to return.
188 *
189 * \return Length of string up to max bytes.
190 */
191M_API size_t M_str_len_max(const char *s, size_t max) M_WARN_UNUSED_RESULT;
192
193/*! Determines if all characters of string \p s satisfy predicate \p pred.
194 *
195 * \param[in] s NULL-terminated string.
196 * \param[in] pred Predicate to apply to each character.
197 *
198 * \return M_TRUE if all characters match. Otherwise M_FALSE.
199 */
200M_API M_bool M_str_ispredicate(const char *s, M_chr_predicate_func pred);
201
202
203/*! Check whether each character of a string s are alphanumeric.
204 *
205 * \param[in] s NULL-terminated string.
206 *
207 * \return M_TRUE if all characters match. Otherwise M_FALSE.
208 */
209M_API M_bool M_str_isalnum(const char *s) M_WARN_UNUSED_RESULT;
210
211
212/*! Check whether each character of a string s ar alphanumeric or contains spaces.
213 *
214 * \param[in] s NULL-terminated string.
215 *
216 * \return M_TRUE if all characters match. Otherwise M_FALSE.
217 */
218M_API M_bool M_str_isalnumsp(const char *s) M_WARN_UNUSED_RESULT;
219
220
221/*! Check whether each character of a string s is alpha.
222 *
223 * \param[in] s NULL-terminated string.
224 *
225 * \return M_TRUE if all characters match. Otherwise M_FALSE.
226 */
227M_API M_bool M_str_isalpha(const char *s) M_WARN_UNUSED_RESULT;
228
229
230/*! Check whether each character of a string s is alpha or contains spaces.
231 *
232 * \param[in] s NULL-terminated string.
233 *
234 * \return M_TRUE if all characters match. Otherwise M_FALSE.
235 */
236M_API M_bool M_str_isalphasp(const char *s) M_WARN_UNUSED_RESULT;
237
238
239/*! Check whether each character of a string s is a space.
240 *
241 * \param[in] s NULL-terminated string.
242 *
243 * \return M_TRUE if all characters match. Otherwise M_FALSE.
244 */
245M_API M_bool M_str_isspace(const char *s) M_WARN_UNUSED_RESULT;
246
247
248/*! Checks for 7-bit ASCII character.
249 *
250 * \param[in] s NULL-terminated string.
251 *
252 * \return M_TRUE if all characters match. Otherwise M_FALSE.
253 */
254M_API M_bool M_str_isascii(const char *s) M_WARN_UNUSED_RESULT;
255
256
257/*! Check whether each character of a string s is printable except space.
258 *
259 * \param[in] s NULL-terminated string.
260 *
261 * \return M_TRUE if all characters match. Otherwise M_FALSE.
262 */
263M_API M_bool M_str_isgraph(const char *s) M_WARN_UNUSED_RESULT;
264
265
266/*! Check whether each character of a string s is printable.
267 *
268 * \param[in] s NULL-terminated string.
269 *
270 * \return M_TRUE if all characters match. Otherwise M_FALSE.
271 */
272M_API M_bool M_str_isprint(const char *s) M_WARN_UNUSED_RESULT;
273
274
275/*! Check whether each character of a string s is a hexadecimal digit.
276 *
277 * \param[in] s NULL-terminated string.
278 *
279 * \return M_TRUE if all characters match. Otherwise M_FALSE.
280 * otherwise M_TRUE
281 */
282M_API M_bool M_str_ishex(const char *s) M_WARN_UNUSED_RESULT;
283
284
285/*! Check whether each character of a string s is a decimal digit 0-9.
286 *
287 * \param[in] s NULL-terminated string.
288 *
289 * \return M_TRUE if all characters match. Otherwise M_FALSE.
290 */
291M_API M_bool M_str_isnum(const char *s) M_WARN_UNUSED_RESULT;
292
293
294/*! Check whether each character of a string s is a decimal digit 0-9 or contains a decimal.
295 *
296 * \param[in] s NULL-terminated string.
297 *
298 * \return M_TRUE if all characters match. Otherwise M_FALSE.
299 */
300M_API M_bool M_str_isdec(const char *s) M_WARN_UNUSED_RESULT;
301
302
303/*! Check whether each character of a string s is a money amount.
304 *
305 * Assumes no more than 2 decimal places but does not require 2
306 * decimial digits.
307 *
308 * \param[in] s NULL-terminated string.
309 *
310 * \return M_TRUE if all characters match. Otherwise M_FALSE.
311 */
312M_API M_bool M_str_ismoney(const char *s) M_WARN_UNUSED_RESULT;
313
314
315/*! Check whether each character of a string is in the given character set.
316 *
317 * \param[in] str string to check (NULL-terminated).
318 * \param[in] charset list of characters that are allowed in \a str (NULL-terminated).
319 * \return M_TRUE if all characters in \a str match at least one char in \a charset.
320 */
321M_API M_bool M_str_ischarset(const char *str, const char *charset);
322
323
324/*! Check whether each character of a string is not in the given character set.
325 *
326 * \param[in] str string to check (NULL-terminated).
327 * \param[in] charset list of characters that are not allowed in \a str (NULL-terminated).
328 * \return M_TRUE if none of the characters in \a charset are present in \a str.
329 */
330M_API M_bool M_str_isnotcharset(const char *str, const char *charset);
331
332
333/*! Check whether or not the data provided is a string.
334 *
335 * This is useful for parsing binary protocols that contain string data as a
336 * verification. The length passed in is the size of the buffer, the last byte
337 * of the buffer must be a NULL terminator or this function will fail (This means,
338 * of course, the string length should be exactly 1 byte less than the provided
339 * buffer size). Then the remainder of the buffer will be checked for printable
340 * data, otherwise it is not considered a string.
341 *
342 * \param[in] s Buffer to see if data is a null-terminated string
343 * \param[in] len Size of buffer, including NULL terminator
344 * \return M_TRUE if buffer contains a string, M_FALSE otherwise
345 */
346M_API M_bool M_str_isstr(const unsigned char *s, size_t len);
347
348
349/*! Determines if the first \p max characters of string \p s satisfy predicate \p pred up to max bytes.
350 *
351 * \param[in] s NULL-terminated string.
352 * \param[in] max Max number of characters to process of \p s.
353 * \param[in] pred Predicate to apply to each character.
354 *
355 * \return M_TRUE if all characters match. Otherwise M_FALSE.
356 */
357M_API M_bool M_str_ispredicate_max(const char *s, size_t max, M_chr_predicate_func pred);
358
359/*! Check whether each character of a string s are alphanumeric up to at most max bytes.
360 *
361 * \param[in] s NULL-terminated string.
362 * \param[in] max Maximum number of bytes.
363 *
364 * \return M_TRUE if all characters match. Otherwise M_FALSE.
365 */
366M_API M_bool M_str_isalnum_max(const char *s, size_t max) M_WARN_UNUSED_RESULT;
367
368
369/*! Check whether each character of a string s ar alphanumeric or contains spaces up to at most max bytes.
370 *
371 * \param[in] s NULL-terminated string.
372 * \param[in] max Maximum number of bytes.
373 *
374 * \return M_TRUE if all characters match. Otherwise M_FALSE.
375 */
376M_API M_bool M_str_isalnumsp_max(const char *s, size_t max) M_WARN_UNUSED_RESULT;
377
378
379/*! Check whether each character of a string s is alpha up to at most max bytes.
380 *
381 * \param[in] s NULL-terminated string.
382 * \param[in] max Maximum number of bytes.
383 *
384 * \return M_TRUE if all characters match. Otherwise M_FALSE.
385 */
386M_API M_bool M_str_isalpha_max(const char *s, size_t max) M_WARN_UNUSED_RESULT;
387
388
389/*! Check whether each character of a string s is alpha or contains spaces up to at most max bytes.
390 *
391 * \param[in] s NULL-terminated string.
392 * \param[in] max Maximum number of bytes.
393 *
394 * \return M_TRUE if all characters match. Otherwise M_FALSE.
395 */
396M_API M_bool M_str_isalphasp_max(const char *s, size_t max) M_WARN_UNUSED_RESULT;
397
398
399/*! Check whether each character of a string s is a space up to at most max bytes.
400 *
401 * \param[in] s NULL-terminated string.
402 * \param[in] max Maximum number of bytes.
403 *
404 * \return M_TRUE if all characters match. Otherwise M_FALSE.
405 */
406M_API M_bool M_str_isspace_max(const char *s, size_t max) M_WARN_UNUSED_RESULT;
407
408
409/*! Check whether each character of a string s is printable except space up to at most max bytes.
410 *
411 * \param[in] s NULL-terminated string.
412 * \param[in] max Maximum number of bytes.
413 *
414 * \return M_TRUE if all characters match. Otherwise M_FALSE.
415 */
416M_API M_bool M_str_isgraph_max(const char *s, size_t max) M_WARN_UNUSED_RESULT;
417
418
419/*! Check whether each character of a string s is printable up to at most max bytes.
420 *
421 * \param[in] s NULL-terminated string.
422 * \param[in] max Maximum number of bytes.
423 *
424 * \return M_TRUE if all characters match. Otherwise M_FALSE.
425 */
426M_API M_bool M_str_isprint_max(const char *s, size_t max) M_WARN_UNUSED_RESULT;
427
428
429/*! Check whether each character of a string s is a hexadecimal digit up to at most max bytes.
430 *
431 * \param[in] s NULL-terminated string.
432 * \param[in] max Maximum number of bytes.
433 *
434 * \return M_TRUE if all characters match. Otherwise M_FALSE.
435 */
436M_API M_bool M_str_ishex_max(const char *s, size_t max) M_WARN_UNUSED_RESULT;
437
438
439/*! Check whether each character of a string s is a decimal digit 0-9 up to at most max bytes.
440 *
441 * \param[in] s NULL-terminated string.
442 * \param[in] max Maximum number of bytes.
443 *
444 * \return M_TRUE if all characters match. Otherwise M_FALSE.
445 */
446M_API M_bool M_str_isnum_max(const char *s, size_t max) M_WARN_UNUSED_RESULT;
447
448
449/*! Check whether each character of a string s is a decimal digit 0-9 or contains a decimal up to at most max bytes.
450 *
451 * \param[in] s NULL-terminated string.
452 * \param[in] max Maximum number of bytes.
453 *
454 * \return M_TRUE if all characters match. Otherwise M_FALSE.
455 */
456M_API M_bool M_str_isdec_max(const char *s, size_t max) M_WARN_UNUSED_RESULT;
457
458
459/*! A wrapper around strcmp that treats NULL as an empty string.
460 *
461 * NOTE: this is not a constant-time comparison and thus should ONLY be used
462 * for sorting such as within qsort()!
463 *
464 * \param[in] s1 NULL-terminated string.
465 * \param[in] s2 NULL-terminated string.
466 *
467 * \return An integer less than, equal to, or greater than zero if s1 is
468 * less than, equal, or greater than s2 respectively.
469 */
470M_API int M_str_cmpsort(const char *s1, const char *s2) M_WARN_UNUSED_RESULT;
471
472
473/*! A wrapper around strcmp that treats NULL as an empty string, but limited to max characters.
474 *
475 * NOTE: this is not a constant-time comparison and thus should ONLY be used
476 * for sorting such as within qsort()!
477 *
478 * \param[in] s1 NULL-terminated string.
479 * \param[in] s2 NULL-terminated string.
480 * \param[in] max Max number of characters to process of \p s.
481 *
482 * \return An integer less than, equal to, or greater than zero if s1 is
483 * less than, equal, or greater than s2 respectively.
484 */
485M_API int M_str_cmpsort_max(const char *s1, const char *s2, size_t max) M_WARN_UNUSED_RESULT;
486
487
488/*! A wrapper around strcmp that treats NULL as an empty string and compares case insensitive.
489 *
490 * NOTE: this is not a constant-time comparison and thus should ONLY be used
491 * for sorting such as within qsort()!
492 *
493 * \param[in] s1 NULL-terminated string.
494 * \param[in] s2 NULL-terminated string.
495 *
496 * \return An integer less than, equal to, or greater than zero if s1 is
497 * less than, equal, or greater than s2 respectively.
498 */
499M_API int M_str_casecmpsort(const char *s1, const char *s2) M_WARN_UNUSED_RESULT;
500
501
502/*! A wrapper around strcmp that treats NULL as an empty string and compares case insensitive, but limited
503 * to max characters.
504 *
505 * NOTE: this is not a constant-time comparison and thus should ONLY be used
506 * for sorting such as within qsort()!
507 *
508 * \param[in] s1 NULL-terminated string.
509 * \param[in] s2 NULL-terminated string.
510 * \param[in] max Max number of characters to process of \p s.
511 *
512 * \return An integer less than, equal to, or greater than zero if s1 is
513 * less than, equal, or greater than s2 respectively.
514 */
515M_API int M_str_casecmpsort_max(const char *s1, const char *s2, size_t max) M_WARN_UNUSED_RESULT;
516
517
518/*! Comparison for string equality.
519 *
520 * This implementation is constant-time meaning it should not be vulnerable to timing-based attacks.
521 * Limited to first max bytes. NULL and "" are considered equal strings.
522 *
523 * s1 will be evaluated to max regardless of the length of s2.
524 * s1 should be the input (user) string and s2 the known (internal)
525 * string. This order causes any timing information from this function
526 * to be the timing of reading s1. The length of s2 cannot be determined
527 * using this order. If s1 is the known (internal) string it is possible,
528 * though highly unlikely, to determine the length. While the evaluation
529 * will be constant time it will always be the time to scan the known string.
530 *
531 * \param[in] s1 NULL-terminated string. Should be (user) input.
532 * \param[in] s2 NULL-terminated string. Should be known (internal) string.
533 * \param[in] max maximum length to check.
534 *
535 * \return M_TRUE if equal, M_FALSE if not equal.
536 */
537M_API M_bool M_str_eq_max(const char *s1, const char *s2, size_t max);
538
539
540/*! Comparison for string equality.
541 *
542 * This implementation is constant-time meaning it should not be vulnerable to timing-based attacks.
543 * NULL and "" are considered equal strings.
544 *
545 * s1 will be evaluated to end regardless of the length of s2.
546 * s1 should be the input (user) string and s2 the known (internal)
547 * string. This order causes any timing information from this function
548 * to be the timing of reading s1. The length of s2 cannot be determined
549 * using this order. If s1 is the known (internal) string it is possible
550 * though highly unlikely, to determine the length. While the evaluation
551 * will be constant time it will always be the time to scan the known string.
552 *
553 * \param[in] s1 NULL-terminated string. Should be (user) input.
554 * \param[in] s2 NULL-terminated string. Should be known (internal) string.
555 *
556 * \return M_TRUE if equal, M_FALSE if not equal.
557 */
558M_API M_bool M_str_eq(const char *s1, const char *s2);
559
560
561/*! Comparison for string equality in a case-insensitive manner.
562 *
563 * This implementation is constant-time meaning it should not be vulnerable to timing-based attacks.
564 * Limited to first max bytes. NULL and "" are considered equal strings.
565 *
566 * s1 will be evaluated to max regardless of the length of s2.
567 * s1 should be the input (user) string and s2 the known (internal)
568 * string. This order causes any timing information from this function
569 * to be the timing of reading s1. The length of s2 cannot be determined
570 * though highly unlikely, to determine the length. While the evaluation
571 * will be constant time it will always be the time to scan the known string.
572 *
573 * \param[in] s1 NULL-terminated string.
574 * \param[in] s2 NULL-terminated string.
575 * \param[in] max maximum length to check.
576 *
577 * \return M_TRUE if equal, M_FALSE if not equal.
578 */
579M_API M_bool M_str_caseeq_max(const char *s1, const char *s2, size_t max);
580
581
582/*! Comparison for string equality in a case-insensitive manner.
583 *
584 * This implementation is constant-time meaning it should not be vulnerable to timing-based attacks.
585 * NULL and "" are considered equal strings.
586 *
587 * s1 will be evaluated to end regardless of the length of s2.
588 * s1 should be the input (user) string and s2 the known (internal)
589 * string. This order causes any timing information from this function
590 * to be the timing of reading s1. The length of s2 cannot be determined
591 * though highly unlikely, to determine the length. While the evaluation
592 * will be constant time it will always be the time to scan the known string.
593 *
594 * \param[in] s1 NULL-terminated string. Should be (user) input.
595 * \param[in] s2 NULL-terminated string. Should be known (internal) string.
596 *
597 * \return M_TRUE if equal, M_FALSE if not equal.
598 */
599M_API M_bool M_str_caseeq(const char *s1, const char *s2);
600
601
602/*! Determine if a string ends with a given string.
603 *
604 * The input is slighly different than M_str_eq(). The input reads:
605 * Check that s1 ends with s2.
606 *
607 * s1 length is never (\see M_str_eq) known because evaluation will always be the length of s2.
608 *
609 * \param[in] s1 NULL-terminated string, or non-terminated string that's at least as long as s2.
610 * Input string.
611 * \param[in] s2 NULL-terminated string.
612 * Ending string that's being compared to s1.
613 *
614 * \return M_TRUE if s1 ends with s2, otherwise M_FALSE;
615 */
616M_API M_bool M_str_eq_end(const char *s1, const char *s2);
617
618
619/*! Determine if a string ends with a given string in a case-insensitive manner.
620 *
621 * The input is slighly different than M_str_caseeq(). The input reads:
622 * Check that s1 ends with s2.
623 *
624 * s1 length is never (\see M_str_caseeq) known because evaluation will always be the length of s2.
625 *
626 * \param[in] s1 NULL-terminated string, or non-terminated string that's at least as long as s2.
627 * Input string.
628 * \param[in] s2 NULL-terminated string.
629 * Ending string that's being compared to s1.
630 *
631 * \return M_TRUE if s1 ends with s2, otherwise M_FALSE;
632 */
633M_API M_bool M_str_caseeq_end(const char *s1, const char *s2);
634
635
636/*! Determine if a string starts with a given string.
637 *
638 * The input is slighly different than M_str_eq(). The input reads:
639 * Check that s1 starts with s2.
640 *
641 * s1 length is never (\see M_str_eq) known because evaluation will always be the length of s2.
642 *
643 * \param[in] s1 NULL-terminated string, or non-terminated string that's at least as long as s2.
644 * Input string.
645 * \param[in] s2 NULL-terminated string.
646 * Staring string that's being compared to s1.
647 *
648 * \return M_TRUE if s1 starts with s2, otherwise M_FALSE.
649 */
650M_API M_bool M_str_eq_start(const char *s1, const char *s2);
651
652
653/*! Determine if a string starts with a given string in a case-insensitive manner.
654 *
655 * The input is slightly different than M_str_caseeq(). The input reads:
656 * Check that s1 starts with s2.
657 *
658 * s1 length is never (see M_str_caseeq()) known because evaluation will always be the length of s2.
659 *
660 * \param[in] s1 NULL-terminated string, or non-terminated string that's at least as long as s2.
661 * Input string.
662 * \param[in] s2 NULL-terminated string.
663 * Staring string that's being compared to s1.
664 *
665 * \return M_TRUE if s1 starts with s2 (case insensitive), otherwise M_FALSE.
666 */
667M_API M_bool M_str_caseeq_start(const char *s1, const char *s2);
668
669/* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
670 * Matching
671 */
672
673/*! Match pattern against string as per 'man 7 glob'.
674 *
675 * We don't support newer POSIX functions like named character classes (e.g.
676 * [:lower:]), collating symbols, or equivalence class expressions
677 *
678 * \param[in] pattern The pattern to match using.
679 * \param[in] s NULL-terminated string.
680 *
681 * \return M_TRUE if the pattern matches the string otherwise M_FALSE.
682 */
683M_API M_bool M_str_pattern_match(const char *pattern, const char *s) M_WARN_UNUSED_RESULT;
684
685
686/*! Match pattern against string as per 'man 7 glob' case insensitive.
687 *
688 * We don't support newer POSIX functions like named character classes (e.g.
689 * [:lower:]), collating symbols, or equivalence class expressions
690 *
691 * \param[in] pattern The pattern to match using.
692 * \param[in] s NULL-terminated string.
693 *
694 * \return M_TRUE if the pattern matches the string otherwise M_FALSE.
695 *
696 * \see M_str_pattern_match
697 */
698M_API M_bool M_str_case_pattern_match(const char *pattern, const char *s) M_WARN_UNUSED_RESULT;
699
700
701
702/*! @} */
703
704
705/*! \addtogroup m_str_dup String Manipulation (and Duplication)
706 * \ingroup m_string
707 *
708 * String Manipulation (and Duplication) Functions
709 *
710 * @{
711 */
712
713/*! Justify Flags */
714typedef enum {
715 M_STR_JUSTIFY_RIGHT = 0, /*!< Data is right-justified (padded on left).
716 If src exceeds justification length, it is truncated on the left */
717 M_STR_JUSTIFY_LEFT = 1, /*!< Data is left-justified (padded on right).
718 If src exceeds justification length, it is truncated on the left */
719 M_STR_JUSTIFY_RIGHT_TRUNC_RIGHT = 2, /*!< Data is right-justified (padded on left).
720 If src exceeds justification length, it is truncated on the right */
721 M_STR_JUSTIFY_LEFT_TRUNC_RIGHT = 3, /*!< Data is left-justified (padded on right).
722 If src exceeds justification length, it is truncated on the right */
723 M_STR_JUSTIFY_RIGHT_NOTRUNC = 4, /*!< Data is right-justified (padded on left).
724 If src exceeds justification length, destination is not written, error
725 is returned */
726 M_STR_JUSTIFY_LEFT_NOTRUNC = 5, /*!< Data is left-justified (padded on right).
727 If src exceeds justification length, destination is not written,
728 error is returned */
729 M_STR_JUSTIFY_TRUNC_RIGHT = 6, /*!< Data is truncated on the right if length is exceeded. No padding
730 is performed */
731 M_STR_JUSTIFY_TRUNC_LEFT = 7, /*!< Data is truncated on the left if length is exceeded. No padding
732 is performed */
733 M_STR_JUSTIFY_CENTER = 8, /*!< Data is center-justified (padded on left and right).
734 If src exceeds justification length, it is truncated on the left */
735 M_STR_JUSTIFY_CENTER_TRUNC_RIGHT = 9, /*!< Data is center-justified (padded on left and right).
736 If src exceeds justification length, it is truncated on the right */
737 M_STR_JUSTIFY_CENTER_NO_TRUNC = 10, /*!< Data is center-justified (padded on left and right).
738 If src exceeds justification length, destination is not writtern,
739 error is returned */
740 M_STR_JUSTIFY_END = 11 /*!< Non-used value that marks end of list. */
741} M_str_justify_type_t;
742
743
744/* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
745 * Construction
746 */
747
748/*! Create a duplicate of the NULL-terminated string s.
749 *
750 * s must be passed to M_free to release the memory space associated with it.
751 *
752 * \param[in] s NULL-terminated string.
753 *
754 * \return NULL when insufficient memory or s is NULL. Otherwise a NULL-terminated string.
755 *
756 * \see M_free
757 */
758M_API char *M_strdup(const char *s) M_WARN_UNUSED_RESULT M_MALLOC;
759
760
761/*! Create a duplicate of the NULL-terminated string s and additionally applies M_str_upper to the new string.
762 *
763 * Later s can be passed to M_free to release the memory space associated with it.
764 *
765 * \param[in] s NULL-terminated string.
766 *
767 * \return NULL when insufficient memory or s is NULL. Otherwise a NULL-terminated string.
768 *
769 * \see M_strdup
770 * \see M_str_upper
771 * \see M_free
772 */
773M_API char *M_strdup_upper(const char *s) M_WARN_UNUSED_RESULT M_MALLOC;
774
775
776/*! Create a duplicate of the NULL-terminated string s and additionally applies M_str_lower to the new string.
777 *
778 * s must be passed to M_free to release the memory space associated with it.
779 *
780 * \param[in] s NULL-terminated string.
781 *
782 * \return NULL when insufficient memory or s is NULL. Otherwise a NULL-terminated string.
783 *
784 * \see M_strdup
785 * \see M_str_lower
786 * \see M_free
787 */
788M_API char *M_strdup_lower(const char *s) M_WARN_UNUSED_RESULT M_MALLOC;
789
790
791/*! Create new string with all characters converted to title case.
792 *
793 * Title case is where the first letter of each word is converted to uppercase, and all other
794 * letters are converted to lowercase.
795 *
796 * Ex: "This Sentence Is In Title Case"
797 *
798 * \see M_strdup_title_max
799 * \see M_str_title
800 * \see M_free
801 *
802 * \param[in] s null-terminated string to duplicate and convert.
803 * \return newly allocated string on success, \c NULL on failure.
804 */
805M_API char *M_strdup_title(const char *s) M_WARN_UNUSED_RESULT M_MALLOC;
806
807
808/*! Create a duplicate of the NULL-terminated string s and additionally applies M_str_trim to the new string.
809 *
810 * s must be passed to M_free to release the memory space associated with it.
811 *
812 * \param[in] s NULL-terminated string.
813 *
814 * \return NULL when insufficient memory or s is NULL. Otherwise a NULL-terminated string.
815 *
816 * \see M_strdup
817 * \see M_str_trim
818 * \see M_free
819 */
820M_API char *M_strdup_trim(const char *s) M_WARN_UNUSED_RESULT M_MALLOC;
821
822
823/*! Create a duplicate of the NULL-terminated string s and additionally applies M_str_unquote to the new string.
824 *
825 * s must be passed to M_free to release the memory space associated with it.
826 *
827 * \param[in] s NULL-terminated string.
828 * \param[in] quote Quote character that should be removed.
829 * \param[in] escape Character that escapes a quote that is within the quoted string.
830 *
831 * \return NULL when insufficient memory or s is NULL. Otherwise a NULL-terminated string.
832 *
833 * \see M_strdup
834 * \see M_str_unquote
835 * \see M_free
836 */
837M_API char *M_strdup_unquote(const char *s, unsigned char quote, unsigned char escape) M_WARN_UNUSED_RESULT M_MALLOC;
838
839
840/*! Create a duplicate of the NULL-terminated string s, but copy at most max bytes.
841 *
842 * If s is longer than max, only max bytes are copied. The returned string will always be NULL-terminated.
843 *
844 * s must be passed to M_free to release the memory space associated with it.
845 *
846 * \param[in] s NULL-terminated string (or up to max bytes of s).
847 * \param[in] max Maximum number of bytes to copy from s.
848 *
849 * \return NULL when insufficient memory or s is NULL. Otherwise a NULL-terminated substring
850 * s[0..MAX(max-1,strlen(s))].
851 *
852 * \see M_free
853 */
854M_API char *M_strdup_max(const char *s, size_t max) M_ALLOC_SIZE(2) M_WARN_UNUSED_RESULT M_MALLOC;
855
856
857/*! Create a duplicate of the NULL-terminated string s, but copy at most max bytes and additionally applies
858 * M_str_lower_max to the new string.
859 *
860 * If s is longer than max, only max bytes are copied. The returned string will always be NULL-terminated.
861 *
862 * s must be passed to M_free to release the memory space associated with it.
863 *
864 * \param[in] s NULL-terminated string (or up to max bytes of s).
865 * \param[in] max Maximum number of bytes to copy from s.
866 *
867 * \return NULL when insufficient memory or s is NULL. Otherwise a NULL-terminated substring
868 * s[0..MAX(max-1,strlen(s))].
869 *
870 * \see M_strdup_max
871 * \see M_str_upper_max
872 * \see M_free
873 */
874M_API char *M_strdup_upper_max(const char *s, size_t max) M_ALLOC_SIZE(2) M_WARN_UNUSED_RESULT M_MALLOC;
875
876
877/*! Create a duplicate of the NULL-terminated string s, but copy at most max bytes and additionally applies
878 * M_str_lower_max to the new string.
879 *
880 * If s is longer than max, only max bytes are copied. The returned string will always be NULL-terminated.
881 *
882 * s must be passed to M_free to release the memory space associated with it.
883 *
884 * \param[in] s NULL-terminated string (or up to max bytes of s).
885 * \param[in] max Maximum number of bytes to copy from s.
886 *
887 * \see M_strdup_max
888 * \see M_str_lower_max
889 * \see M_free
890 */
891M_API char *M_strdup_lower_max(const char *s, size_t max) M_ALLOC_SIZE(2) M_WARN_UNUSED_RESULT M_MALLOC;
892
893
894/*! Create new string with a given number of characters converted to title case.
895 *
896 * Only copies up to \a max characters from the source string.
897 *
898 * Title case is where the first letter of each word is converted to uppercase, and all other
899 * letters are converted to lowercase.
900 *
901 * Ex: "This Sentence Is In Title Case"
902 *
903 * \see M_strdup_title
904 * \see M_str_title_max
905 * \see M_free
906 *
907 * \param[in] s null-terminated string to duplicate and convert.
908 * \param[in] max max number of characters to copy from \a s, may be less if \a s contains a null character
909 * \return newly allocated string on success, \c NULL on failure.
910 */
911M_API char *M_strdup_title_max(const char *s, size_t max) M_ALLOC_SIZE(2) M_WARN_UNUSED_RESULT M_MALLOC;
912
913
914/*! Create a duplicate of the NULL-terminated string s, but copy at most max bytes and additionally applies
915 * M_str_trim_max to the new string.
916 *
917 * If s is longer than max, only max bytes are copied. The returned string will always be NULL-terminated.
918 *
919 * s must be passed to M_free to release the memory space associated with it.
920 *
921 * \param[in] s NULL-terminated string (or up to max bytes of s).
922 * \param[in] max Maximum number of bytes to copy from s.
923 *
924 * \return NULL when insufficient memory or s is NULL. Otherwise a NULL-terminated substring
925 * s[0..MAX(max-1,strlen(s))].
926 *
927 * \see M_strdup_max
928 * \see M_str_trim_max
929 * \see M_free
930 */
931M_API char *M_strdup_trim_max(const char *s, size_t max) M_ALLOC_SIZE(2) M_WARN_UNUSED_RESULT M_MALLOC;
932
933
934/*! Create a duplicate of the NULL-terminated string s, but copy at most max bytes and additionally applies
935 * M_str_unquote_max to the new string.
936 *
937 * If s is longer than max, only max bytes are copied. The returned string will always be NULL-terminated.
938 *
939 * s must be passed to M_free to release the memory space associated with it.
940 *
941 * \param[in] s NULL-terminated string (or up to max bytes of s).
942 * \param[in] quote Quote character that should be removed.
943 * \param[in] escape Character that escapes a quote that is within the quoted string.
944 * \param[in] max Maximum number of bytes to copy from s.
945 *
946 * \return NULL when insufficient memory or s is NULL. Otherwise a NULL-terminated substring
947 * s[0..MAX(max-1,strlen(s))].
948 * \see M_strdup_max
949 * \see M_free
950 */
951M_API char *M_strdup_unquote_max(const char *s, unsigned char quote, unsigned char escape, size_t max) M_ALLOC_SIZE(2) M_WARN_UNUSED_RESULT M_MALLOC;
952
953
954/*! Justifies the input source as specified by the parameters and writes it to a new duplicate string.
955 *
956 * \param[in] src Null-terminated input string to be justified.
957 * \param[in] justtype Type of justification to be performed.
958 * \param[in] justchar Character to use as padding/filler for justification.
959 * (ignored if M_JUSTIFY_TRUNC_RIGHT or M_JUSTIFY_TRUNC_LEFT)
960 * \param[in] justlen Length requested for justification (or truncation).
961 *
962 * \return NULL on error (such as if it would truncate when requested not to, or invalid use).
963 * New null-terminated string containing justified output on success.
964 */
965M_API char *M_strdup_justify(const char *src, M_str_justify_type_t justtype, unsigned char justchar, size_t justlen) M_WARN_UNUSED_RESULT M_MALLOC;
966
967
968/*! Replace all characters matching a given character set with a string.
969 *
970 * \param[in] s NULL-terminated string.
971 * \param[in] bcs Character set.
972 * \param[in] bcs_len Number of characters in the given set.
973 * \param[in] a Replacement string for every character in the character set.
974 *
975 * \return NULL terminated string on success, Otherwise NULL.
976 *
977 * \see M_str_replace_chr
978 * \see M_strdup_replace_str
979 */
980M_API char *M_strdup_replace_charset(const char *s, const unsigned char *bcs, size_t bcs_len, const char *a);
981
982
983/*! Replace a string with another string.
984 *
985 * \param[in] s NULL-terminated string.
986 * \param[in] b NULL-terminated string to replace.
987 * \param[in] a NULL-terminated string o replace with. b is replaced with a.
988 *
989 * \return NULL terminated string on success, Otherwise NULL.
990 *
991 * \see M_str_replace_chr
992 * \see M_strdup_replace_charset
993 */
994M_API char *M_strdup_replace_str(const char *s, const char *b, const char *a);
995
996
997/*! @} */
998
999
1000/*! \addtogroup m_str_mutate String Manipulation (in-place)
1001 * \ingroup m_string
1002 *
1003 * String Manipulation (in-place)) Functions
1004 *
1005 * @{
1006 */
1007
1008/* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
1009 * Mutation
1010 */
1011
1012/*! Convert all characters in place to lower case.
1013 *
1014 * \param[in,out] s NULL-terminated string.
1015 *
1016 * \return pointer to string on success. Otherwise NULL.
1017 * */
1018M_API char *M_str_lower(char *s);
1019
1020
1021/*! Convert all characters in place to lower case up to a maximum length.
1022 *
1023 * \param[in,out] s NULL-terminated string.
1024 * \param[in] max Max length to convert.
1025 *
1026 * \return pointer to string on success. Otherwise NULL.
1027 * */
1028M_API char *M_str_lower_max(char *s, size_t max);
1029
1030
1031/*! Convert all characters in place to upper case.
1032 *
1033 * \param[in,out] s NULL-terminated string.
1034 *
1035 * \return Pointer to string on success. Otherwise NULL.
1036 * */
1037M_API char *M_str_upper(char *s);
1038
1039
1040/*! Convert all characters in place to upper case up to a maximum length.
1041 *
1042 * \param[in,out] s NULL-terminated string.
1043 * \param[in] max max Max length to convert.
1044 *
1045 * \return Pointer to string on success. Otherwise NULL.
1046 * */
1047M_API char *M_str_upper_max(char *s, size_t max);
1048
1049
1050/*! Convert all characters to title case, in-place.
1051 *
1052 * Title case is where the first letter of each word is converted to uppercase, and all other
1053 * letters are converted to lowercase.
1054 *
1055 * Ex: "This Sentence Is In Title Case"
1056 *
1057 * \see M_str_title_max
1058 * \see M_strdup_title
1059 *
1060 * \param[in,out] s null-terminated string to convert.
1061 * \return \a s on success, \c NULL on failure.
1062 */
1063M_API char *M_str_title(char *s);
1064
1065
1066/*! Convert given number of characters to title case, in-place.
1067 *
1068 * Title case is where the first letter of each word is converted to uppercase, and all other
1069 * letters are converted to lowercase.
1070 *
1071 * Ex: "This Sentence Is In Title Case!"
1072 *
1073 * \see M_str_title
1074 * \see M_strdup_title_max
1075 *
1076 * \param s string to convert (doesn't have to be null-terminated, but must be at least \a max long)
1077 * \param max max number of characters to touch in \a s, may be less if \a s contains a null character
1078 * \return \a s on success, \c NULL on failure.
1079 */
1080M_API char *M_str_title_max(char *s, size_t max);
1081
1082
1083/*! Remove whitespace from the beginning and end of the string in place.
1084 *
1085 * \param[in,out] s NULL-terminated string.
1086 *
1087 * \return Start of the string without whitespace.
1088 *
1089 * \see M_chr_isspace
1090 */
1091M_API char *M_str_trim(char *s);
1092
1093
1094/*! Remove whitespace from the beginning and end of the string in place up to a maximum length.
1095 *
1096 * \param[in,out] s NULL-terminated string.
1097 * \param[in] max Max length to trim.
1098 *
1099 * \return the start of the string without whitespace.
1100 *
1101 * \see M_chr_isspace
1102 */
1103M_API char *M_str_trim_max(char *s, size_t max);
1104
1105
1106/*! Return a copy of the given string with bracketed expressions removed.
1107 *
1108 * You must use different characters for \a open and \a close. If you pass the same
1109 * character for both, this function will return NULL.
1110 *
1111 * For example, the string "abc (asd(e))?" becomes "abc ?" after calling this
1112 * function with '(' as the \a open bracket and ')' as the \a close bracket.
1113 *
1114 * \see M_str_remove_bracketed_quoted
1115 * \see M_str_keep_bracketed
1116 * \see M_str_remove_quoted
1117 *
1118 * \param[in] src string to copy
1119 * \param[in] open character that represents the start of a bracketed expression
1120 * \param[in] close character that represents the end of a bracketed expression
1121 * \return copy of input string, with bracketed expressions removed
1122 */
1123M_API char *M_str_remove_bracketed(const char *src, char open, char close) M_WARN_UNUSED_RESULT M_MALLOC;
1124
1125
1126/*! Return a copy of the given string with bracketed expressions removed.
1127 *
1128 * Brackets inside quoted expressions are ignored.
1129 *
1130 * You must use different characters for \a open and \a close. If you pass the same
1131 * character for both, this function will return NULL.
1132 *
1133 * For example, the string "abc (asd(e))?" becomes "abc ?" after calling this
1134 * function with '(' as the \a open bracket and ')' as the \a close bracket.
1135 *
1136 * \see M_str_remove_bracketed_quoted
1137 * \see M_str_keep_bracketed
1138 * \see M_str_remove_quoted
1139 *
1140 * \param[in] src string to copy
1141 * \param[in] open character that represents the start of a bracketed expression
1142 * \param[in] close character that represents the end of a bracketed expression
1143 * \param[in] quote character that represents open/close of quoted string
1144 * \param[in] escape character that can be used to escape a quote char
1145 * \return copy of input string, with bracketed expressions removed
1146 */
1147M_API char *M_str_remove_bracketed_quoted(const char *src, char open, char close, char quote, char escape) M_WARN_UNUSED_RESULT M_MALLOC;
1148
1149
1150/*! Return a copy of the given string with everything outside bracketed expressions removed.
1151 *
1152 * You must use different characters for \a open and \a close. If you pass the same
1153 * character for both, this function will return NULL.
1154 *
1155 * For example, the string "abc (asd(e))?" becomes "asd(e)" after calling this
1156 * function with '(' as the \a open bracket and ')' as the \a close bracket.
1157 *
1158 * \see M_str_keep_bracketed_quoted
1159 * \see M_str_remove_bracketed
1160 * \see M_str_keep_quoted
1161 *
1162 * \param[in] src string to copy
1163 * \param[in] open character that represents the start of a bracketed expression
1164 * \param[in] close character that represents the end of a bracketed expression
1165 * \return copy of input string, containing only the contents of bracketed expressions
1166 */
1167M_API char *M_str_keep_bracketed(const char *src, char open, char close) M_WARN_UNUSED_RESULT M_MALLOC;
1168
1169
1170/*! Return a copy of the given string with everything outside bracketed expressions removed (quote aware).
1171 *
1172 * Brackets inside quoted expressions are ignored.
1173 *
1174 * You must use different characters for \a open and \a close. If you pass the same
1175 * character for both, this function will return NULL.
1176 *
1177 * For example, the string "abc (asd(e))?" becomes "asd(e)" after calling this
1178 * function with '(' as the \a open bracket and ')' as the \a close bracket.
1179 *
1180 * \see M_str_keep_bracketed
1181 * \see M_str_remove_bracketed
1182 * \see M_str_keep_quoted
1183 *
1184 * \param[in] src string to copy
1185 * \param[in] open character that represents the start of a bracketed expression
1186 * \param[in] close character that represents the end of a bracketed expression
1187 * \param[in] quote character that represents open/close of quoted string
1188 * \param[in] escape character that can be used to escape a quote char
1189 * \return copy of input string, containing only the contents of bracketed expressions
1190 */
1191M_API char *M_str_keep_bracketed_quoted(const char *src, char open, char close, char quote, char escape) M_WARN_UNUSED_RESULT M_MALLOC;
1192
1193
1194/*! Return a copy of the given string with quoted expressions removed.
1195 *
1196 * Quote characters that are preceded by the escape character are not processed as
1197 * quotes. If you don't wish to specify an escape character, pass '\0' for that argument.
1198 *
1199 * \param[in] src string to copy
1200 * \param[in] quote_char character that represents begin/end of a quoted section
1201 * \param[in] escape_char character that can be used to escape a quote char
1202 * \return copy of input string, with quoted expressions removed
1203 */
1204M_API char *M_str_remove_quoted(const char *src, char quote_char, char escape_char) M_WARN_UNUSED_RESULT M_MALLOC;
1205
1206
1207/*! Return a copy of the given string with everything outside quoted expressions removed.
1208 *
1209 * Quote characters that are preceded by the escape character are not processed as
1210 * quotes. If you don't wish to specify an escape character, pass '\0' for that argument.
1211 *
1212 * Any escape character sequences ([escape][escape] or [escape][quote]) inside the quoted
1213 * content are replaced by the characters they represent ([escape] or [quote], respectively).
1214 *
1215 * \param[in] src string to copy
1216 * \param[in] quote_char character that represents begin/end of a quoted section
1217 * \param[in] escape_char character that can be added
1218 * \return copy of input string, containing only the contents of quoted expressions
1219 */
1220M_API char *M_str_keep_quoted(const char *src, char quote_char, char escape_char) M_WARN_UNUSED_RESULT M_MALLOC;
1221
1222
1223/*! Remove quotes from a string and unescape escaped quotes in place.
1224 *
1225 * \param[in,out] s NULL-terminated string.
1226 * \param[in] quote Quote character.
1227 * \param[in] escape Escape character. Removed from other escape characters and quotes.
1228 *
1229 * \return Start of unquoted string.
1230 */
1231M_API char *M_str_unquote(char *s, unsigned char quote, unsigned char escape);
1232
1233
1234/*! Remove quotes from a string and unescape escaped quotes in place up to a maximum length.
1235 *
1236 * \param[in,out] s NULL-terminated string.
1237 * \param[in] quote Quote character.
1238 * \param[in] escape Escape character. Removed from other escape characters and quotes.
1239 * \param[in] max Max length.
1240 *
1241 * \return Start of unquoted string.
1242 */
1243M_API char *M_str_unquote_max(char *s, unsigned char quote, unsigned char escape, size_t max);
1244
1245
1246/*! Quote a string
1247 *
1248 * \param[in] s NULL-terminated string.
1249 * \param[in] quote Quote character.
1250 * \param[in] escape Escape character.
1251 *
1252 * \return Start of quoted string
1253 */
1254M_API char *M_str_quote(const char *s, unsigned char quote, unsigned char escape) M_WARN_UNUSED_RESULT M_MALLOC;
1255
1256
1257/*! Quote a string up to a maximum length.
1258 *
1259 * \param[in] s NULL-terminated string.
1260 * \param[in] quote Quote character.
1261 * \param[in] escape Escape character.
1262 * \param[in] max Max length.
1263 *
1264 * \return Start of quoted string.
1265 */
1266M_API char *M_str_quote_max(const char *s, unsigned char quote, unsigned char escape, size_t max) M_WARN_UNUSED_RESULT M_MALLOC;
1267
1268
1269/*! Quote a string only if necessary.
1270 *
1271 * Quotes if the string starts or ends with a space. Or if the delimiter is found in the string.
1272 *
1273 * \param[out] out Quoted string.
1274 * \param[in] s NULL-terminated string.
1275 * \param[in] quote Quote character.
1276 * \param[in] escape Escape character.
1277 * \param[in] delim Delimiter.
1278 *
1279 * \return M_TRUE if the string was quoted and out was set. Otherwise M_FALSE.
1280 */
1281M_API M_bool M_str_quote_if_necessary(char **out, const char *s, unsigned char quote, unsigned char escape, unsigned char delim);
1282
1283
1284/*! Delete all whitespace characters from the string.
1285 *
1286 * \param[in,out] s NULL-terminated string.
1287 *
1288 * \return Start of string with whitespace removed.
1289 *
1290 * \see M_chr_isspace
1291 */
1292M_API char *M_str_delete_spaces(char *s);
1293
1294
1295/*! Delete all newline characters (\\r and \\n) from the string.
1296 *
1297 * \param[in,out] s NULL-terminated string.
1298 *
1299 * \return Start of string with newlines removed.
1300 */
1301M_API char *M_str_delete_newlines(char *s);
1302
1303
1304/*! Replace a character within a string with another character in place.
1305 *
1306 * \param[in] s NULL-terminated string.
1307 * \param[in] b Character to replace.
1308 * \param[in] a Character to replace with. b is replaced with a.
1309 *
1310 * \return start of string with character replaced. Does not make a duplicate.
1311 *
1312 * \see M_strdup_replace_charset
1313 * \see M_strdup_replace_str
1314 */
1315M_API char *M_str_replace_chr(char *s, char b, char a);
1316
1317
1318/*! Justifies the input source as specified by the parameters and writes it to the destination buffer.
1319 * Source and Destination buffers may overlap.
1320 *
1321 * \param[out] dest Destination buffer where the output is placed.
1322 * \param[in] destlen Length of destination buffer.
1323 * \param[in] src Input buffer to be justified.
1324 * \param[in] justtype Type of justification to be performed.
1325 * \param[in] justchar Character to use as padding/filler for justification
1326 * (ignored if M_JUSTIFY_TRUNC_RIGHT or M_JUSTIFY_TRUNC_LEFT)
1327 * \param[in] justlen Length requested for justification (or truncation).
1328 *
1329 * \return 0 on error (such as if it would truncate when requested not to, or invalid use).
1330 * Length of justified output on success (typically same as justlen, unless using M_JUSTIFY_TRUNC_RIGHT
1331 * or M_JUSTIFY_TRUNC_LEFT).
1332 */
1333M_API size_t M_str_justify(char *dest, size_t destlen, const char *src, M_str_justify_type_t justtype, unsigned char justchar, size_t justlen);
1334
1335
1336/*! Justifies the input source as specified by the parameters and writes it to the destination buffer.
1337 * Source and destination buffers may overlap.
1338 *
1339 * \param[out] dest Destination buffer where the output is placed.
1340 * \param[in] destlen Length of destination buffer.
1341 * \param[in] src Input buffer to be justified.
1342 * \param[in] srclen Length of input source.
1343 * \param[in] justtype Type of justification to be performed.
1344 * \param[in] justchar Character to use as padding/filler for justification.
1345 * (ignored if M_JUSTIFY_TRUNC_RIGHT or M_JUSTIFY_TRUNC_LEFT)
1346 * \param[in] justlen Length requested for justification (or truncation).
1347 *
1348 * \return 0 on error (such as if it would truncate when requested not to, or invalid use).
1349 * Length of justified output on success (typically same as justlen, unless using M_JUSTIFY_TRUNC_RIGHT
1350 * or M_JUSTIFY_TRUNC_LEFT).
1351 */
1352M_API size_t M_str_justify_max(char *dest, size_t destlen, const char *src, size_t srclen, M_str_justify_type_t justtype, unsigned char justchar, size_t justlen);
1353
1354
1355/* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
1356 * Fill
1357 */
1358
1359/*! Copy a string from one location to another.
1360 *
1361 * This guarantees NULL termination of dest.
1362 *
1363 * \param[out] dest Destination buffer where the output is placed.
1364 * \param[in] dest_len Length of destination buffer.
1365 * \param[in] src Input buffer.
1366 *
1367 * \return M_TRUE on success otherwise M_FALSE.
1368 */
1369M_API M_bool M_str_cpy(char *dest, size_t dest_len, const char *src);
1370
1371
1372/*! Copy a given length of a string from one location to another.
1373 *
1374 * This guarantees NULL termination of dest.
1375 *
1376 * \param[out] dest Destination buffer where the output is placed.
1377 * \param[in] dest_len Length of destination buffer.
1378 * \param[in] src Input buffer.
1379 * \param[in] src_len Length of input buffer.
1380 *
1381 * \return M_TRUE on success otherwise M_FALSE.
1382 */
1383M_API M_bool M_str_cpy_max(char *dest, size_t dest_len, const char *src, size_t src_len);
1384
1385
1386/*! Append a string on to another.
1387 *
1388 * \param[in,out] dest String to be appended to.
1389 * \param[in] dest_len The length of dest.
1390 * \param[in] src String to be appended.
1391 *
1392 * \return M_TRUE if src was appended to dest. Otherwise M_FALSE.
1393 */
1394M_API M_bool M_str_cat(char *dest, size_t dest_len, const char *src);
1395
1396
1397/*! @} */
1398
1399
1400/*! \addtogroup m_str_search String Searching
1401 * \ingroup m_string
1402 *
1403 * String Searching
1404 *
1405 * @{
1406 */
1407
1408/* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - */
1409
1410/*! Find the first occurrence of c in s.
1411 *
1412 * \see M_str_rchr
1413 * \see M_str_str
1414 * \see M_str_find_first_from_charset
1415 * \see M_str_find_first_not_from_charset
1416 *
1417 * \param[in] s NULL-terminated string.
1418 * \param[in] c Character to search for.
1419 * \return NULL if s is NULL or c is not found. Otherwise a pointer to the first occurrence of c in s.
1420 */
1421M_API char *M_str_chr(const char *s, char c) M_WARN_UNUSED_RESULT;
1422
1423
1424/*! Find the last occurrence of c in s.
1425 *
1426 * \see M_str_chr
1427 *
1428 * \param[in] s NULL-terminated string.
1429 * \param[in] c Character to search for.
1430 *
1431 * \return NULL if s is NULL or c is not found. Otherwise a pointer to the last occurrence of c in s.
1432 */
1433M_API char *M_str_rchr(const char *s, char c) M_WARN_UNUSED_RESULT;
1434
1435
1436/*! Find the first occurence in \a str of any character in \a charset.
1437 *
1438 * This is identical to C standard function strpbrk(), except that it treats NULL pointers
1439 * as empty strings instead of segfaulting.
1440 *
1441 * \see M_str_find_first_not_from_charset
1442 * \see M_str_chr
1443 * \see M_str_str
1444 *
1445 * \param[in] str string to search in (stored as NULL-terminated C string).
1446 * \param[in] charset list of chars to search for (stored as NULL-terminated C string).
1447 * \return pointer to first matching character from \a charset in \a str, or NULL if no matches found
1448 */
1449M_API char *M_str_find_first_from_charset(const char *str, const char *charset);
1450
1451
1452/*! Find the first occurence in \a str of any character that's not in \a charset.
1453 *
1454 * \see M_str_find_first_from_charset
1455 * \see M_str_chr
1456 * \see M_str_str
1457 *
1458 * \param[in] str string to search in (stored as NULL-terminated C string).
1459 * \param[in] charset list of chars to skip (stored as NULL-terminated C string).
1460 * \return pointer to first char in \a str that's not in \a charset, or NULL if no matches found
1461 */
1462M_API char *M_str_find_first_not_from_charset(const char *str, const char *charset);
1463
1464
1465/*! A wrapper around strstr that treats NULL as the empty string.
1466 *
1467 * \see M_str_chr
1468 * \see M_str_find_first_from_charset
1469 * \see M_str_find_first_not_from_charset
1470 *
1471 * \param[in] haystack String to search.
1472 * \param[in] needle String to search for in haystack.
1473 *
1474 * \return Pointer to the first occurrence of needle in haystack; otherwise NULL
1475 */
1476M_API char *M_str_str(const char *haystack, const char *needle) M_WARN_UNUSED_RESULT;
1477
1478
1479/*! A wrapper around strstr that ignores case and treats NULL as the empty string.
1480 *
1481 * \param[in] haystack String to search.
1482 * \param[in] needle String to search for in haystack.
1483 *
1484 * \return Pointer to the first occurrence of needle in haystack; otherwise NULL
1485 */
1486M_API char *M_str_casestr(const char *haystack, const char *needle) M_WARN_UNUSED_RESULT;
1487
1488
1489/*! A wrapper around strstr that ignores case and treats NULL as the empty string.
1490 *
1491 * \param[in] haystack String to search.
1492 * \param[in] needle String to search for in haystack.
1493 *
1494 * \return Integer index to the first occurrence of needle in haystack;
1495 * otherwise -1 if needle is not a substring of haystack
1496 */
1497M_API ssize_t M_str_casestr_pos(const char *haystack, const char *needle) M_WARN_UNUSED_RESULT;
1498
1499
1500/*! @} */
1501
1502
1503/*! \addtogroup m_str_parse String Parsing and Joining
1504 * \ingroup m_string
1505 *
1506 * String Parsing and Joining Functions
1507 *
1508 * @{
1509 */
1510
1511/* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
1512 * Substrings
1513 */
1514
1515/*! Clobber the first occurrence of character c in string s with NULL
1516 * and return a pointer to the successive character.
1517 *
1518 * \param[in] s String to break into segments.
1519 * \param[in] c Character at which to break into segments.
1520 *
1521 * \return NULL if s is NULL. Pointer to trailing NULL if c not found in s.
1522 * Otherwise pointer to the character following the first occurrence of c in s.
1523 */
1524M_API char *M_str_split_on_char(char *s, char c);
1525
1526
1527/*! Find each substring of s delimited by delim and additionally record
1528 * each substring's length.
1529 *
1530 * The string can contain the character '\0' and will be processed up to \p s_len.
1531 * All parts will be NULL terminated.
1532 *
1533 * Empty list elements (consecutive delimiters) will produce empty strings in the
1534 * output array.
1535 *
1536 * The last length of len_array will include any trailing '\0'.
1537 *
1538 * \param[in] delim Delimiter.
1539 * \param[in] s String to search.
1540 * \param[in] s_len Length of string.
1541 * \param[out] num The size of len_array and the returned array.
1542 * \param[out] len_array An array of size num containing the lengths of the substrings.
1543 *
1544 * \return an array of length num containing all substrings.
1545 */
1546M_API char **M_str_explode(unsigned char delim, const char *s, size_t s_len, size_t *num, size_t **len_array) M_WARN_UNUSED_RESULT M_MALLOC;
1547
1548
1549/*! Find each substring of s taking into account quoting.
1550 *
1551 * The string can contain the character '\0' and will be processed up to \p s_len.
1552 * All parts are guaranteed to be NULL terminated.
1553 * This takes into account if the delimiter is within a quote. Also allows the quote character
1554 * to be escaped and not treated as a quote character.
1555 *
1556 * An example of this would be CSV parsing. ',' is a delimiter but if it's in '"' it is not. "
1557 * within a " is escaped with " to denote that isn't the end of the quote.
1558 *
1559 * Empty list elements (consecutive delimiters) will produce empty strings in the
1560 * output array.
1561 *
1562 * \param[in] delim Delimiter.
1563 * \param[in] s String to search.
1564 * \param[in] s_len Length of string.
1565 * \param[in] quote_char Character to use to denote quoted segments. Use 0 if not needed.
1566 * \param[in] escape_char Character to use for escaping the quote character. Can be the same as the quote character.
1567 * use 0 if not needed.
1568 * \param[in] max_sects Maximum number of parts to return. The last part will have remaining data after last
1569 * allowed split. Use 0 to disable and return all parts.
1570 * \param[out] num the size of len_array and the returned array.
1571 * \param[out] len_array An array of size num containing the lengths of the substrings.
1572 *
1573 * \return an array of num string containing all substrings.
1574 */
1575M_API char **M_str_explode_quoted(unsigned char delim, const char *s, size_t s_len, unsigned char quote_char, unsigned char escape_char, size_t max_sects, size_t *num, size_t **len_array) M_WARN_UNUSED_RESULT M_MALLOC;
1576
1577
1578
1579/*! Find each substring of s (a NULL terminated string).
1580 *
1581 * s will only be read until the first NULL. All parts are guaranteed to be NULL terminated.
1582 *
1583 * Empty list elements (consecutive delimiters) will produce empty strings in the
1584 * output array.
1585 *
1586 * \param[in] delim Delimiter.
1587 * \param[in] s String to search.
1588 * \param[out] num Number of substrings in returned array.
1589 *
1590 * \return an array of num string containing all substrings.
1591 */
1592M_API char **M_str_explode_str(unsigned char delim, const char *s, size_t *num) M_WARN_UNUSED_RESULT M_MALLOC;
1593
1594
1595
1596/*! Split a string among the given number of lines, while keeping words intact.
1597 *
1598 * After you're done with the returned array, you must free it with M_str_explode_free().
1599 *
1600 * Words in this context are defined as contiguous blocks of non-whitespace characters. For each line,
1601 * leading and trailing whitespace will be trimmed, but internal whitespace will be left alone.
1602 *
1603 * An example use case is breaking up strings for display on small LCD screens.
1604 *
1605 * \see M_str_explode_free
1606 * \see M_buf_add_str_lines
1607 *
1608 * \param[in] max_lines Maximum number of lines to output.
1609 * \param[in] max_chars Maximum characters per line.
1610 * \param[in] src_str Source string.
1611 * \param[in] truncate If true, truncation is allowed. If false, NULL will be returned if the string won't fit.
1612 * \param[out] num Number of lines displayed. Will be zero, if no output text was produced.
1613 * \return Array of strings where each is a line, or NULL if no output text was produced.
1614 */
1615M_API char **M_str_explode_lines(size_t max_lines, size_t max_chars, const char *src_str,
1616 M_bool truncate, size_t *num) M_WARN_UNUSED_RESULT M_MALLOC;
1617
1618
1619
1620/*! Find each substring of s (a NULL terminated string) taking into account quoting.
1621 *
1622 * s will only be read until the first NULL. All parts are guaranteed to be NULL terminated.
1623 * This takes into account if the delimiter is within a quote. Also allows the quote character
1624 * to be escaped and not treated as a quote character.
1625 *
1626 * An example of this would be CSV parsing. ',' is a delimiter but if it's in '"' it is not. "
1627 * within a " is escaped with " to denote that isn't the end of the quote.
1628 *
1629 * \param[in] delim Delimiter.
1630 * \param[in] s String to search.
1631 * \param[in] quote_char Character to use to denote quoted segments. Use 0 if not needed.
1632 * \param[in] escape_char Character to use for escaping the quote character. Can be the same as the quote character.
1633 * use 0 if not needed.
1634 * \param[in] max_sects Maximum number of parts to return. The last part will have remaining data after last
1635 * allowed split. Use 0 to disable and return all parts.
1636 * \param[out] num the size of len_array and the returned array.
1637 *
1638 * \return an array of num string containing all substrings.
1639 */
1640M_API char **M_str_explode_str_quoted(unsigned char delim, const char *s, unsigned char quote_char, unsigned char escape_char, size_t max_sects, size_t *num) M_WARN_UNUSED_RESULT M_MALLOC;
1641
1642
1643/*! Given a string containing an list of integers delimited by delim, return an array containing the integer values.
1644 *
1645 * For example, after calling:
1646 * ints = M_str_explode_int(',', "-10,11,13,,,,-15", &num)
1647 * then the returns values will be:
1648 * num=4
1649 * ints[0] = -10
1650 * ints[1] = 11
1651 * ints[2] = 13
1652 * ints[3] = -15
1653 *
1654 * \param[in] delim Delimiter.
1655 * \param[in] s String containing the integer list.
1656 * \param[out] num The number of integers in the returned array.
1657 *
1658 * \return an array containing num integers.
1659 */
1660M_API int *M_str_explode_int(unsigned char delim, const char *s, size_t *num) M_WARN_UNUSED_RESULT M_MALLOC;
1661
1662
1663/*! Free the substrings found by M_str_explode*.
1664 *
1665 * \param[in] strs An array of strings returned by M_str_explode*.
1666 * \param[in] num The number of strings in strs.
1667 *
1668 * \see M_str_explode
1669 */
1670M_API void M_str_explode_free(char **strs, size_t num) M_FREE(1);
1671
1672
1673/* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
1674 * Join
1675 */
1676
1677/*! Join an array of string separated by a delimiter and quoted if the delimiter is present in a string.
1678 *
1679 * \param[in] delim Delimiter.
1680 * \param[in] enclose_char Character to use for quoting.
1681 * \param[in] escape_char Character used for escaping the quote character if it's found in a string.
1682 * \param[in] strs array of string to join.
1683 * \param[in] num_strs Number of string in the array of strings.
1684 * \param[in] always_enclose M_TRUE if all string should be quoted. M_FALSE if strings are only quoted when necessary.
1685 *
1686 * \return Joined string.
1687 */
1688M_API char *M_str_implode(unsigned char delim, unsigned char enclose_char, unsigned char escape_char, char **strs, size_t num_strs, M_bool always_enclose) M_WARN_UNUSED_RESULT M_MALLOC;
1689
1690
1691/*! Convert an array of signed integers into a string representation where each
1692 * integer is delimited by a given character.
1693 *
1694 * For example:
1695 * M_str_implode_int('|', {1,-22,333}, 3) => "1|-22|333"
1696 *
1697 * \param[in] delim Delimiter.
1698 * \param[in] ints String containing the integer list.
1699 * \param[in] num_ints The number of integers in the returned array.
1700 *
1701 * \return String representation of integer list.
1702 */
1703M_API char *M_str_implode_int(unsigned char delim, const int *ints, size_t num_ints) M_WARN_UNUSED_RESULT M_MALLOC;
1704
1705
1706/*! @} */
1707
1708
1709/*! \addtogroup m_str_convert String Conversion
1710 * \ingroup m_string
1711 *
1712 * String Conversion
1713 *
1714 * @{
1715 */
1716
1717
1718/*! Possible return codes for integer conversion primitives */
1719typedef enum {
1720 M_STR_INT_SUCCESS = 0, /*!< Successful conversion */
1721 M_STR_INT_OVERFLOW = 1, /*!< Overflow */
1722 M_STR_INT_INVALID = 2 /*!< Invalid Characters */
1723} M_str_int_retval_t;
1724
1725
1726/* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
1727 * Conversion to number
1728 */
1729
1730/*! Convert a string representing money (a fractional decimal amount) to an
1731 * integer number of cents. Fractional amounts are rounded to the nearest cent.
1732 *
1733 * \param s String containing a floating point (2 decimal places) money representation.
1734 *
1735 * \return Long integer, rounded if there are floating point errors, with amount of cents.
1736 */
1737M_API long M_atofi100(const char *s) M_WARN_UNUSED_RESULT;
1738
1739
1740/*! Convert a floating point number into a 64bit integer using arbitrary
1741 * precision as defined by impliedDecimals.
1742 *
1743 * For instance, if impliedDecimals is 5, and 12.34 is passed, the resulting value would be 1234000.
1744 *
1745 * \param[in] s string to convert to decimal
1746 * \param[in] impliedDecimals Number of implied decimals resulting output should have
1747 *
1748 * \return 64bit integer representing number from s with implied decimals.
1749 */
1750M_API M_int64 M_atofi_prec(const char *s, int impliedDecimals) M_WARN_UNUSED_RESULT;
1751
1752
1753/*! Interpret a string as an ascii numeric. String may begin with whitespace which
1754 * will be ignored, then an optional + or - sign.
1755 *
1756 * \param[in] s NULL-terminated string.
1757 *
1758 * \return Determined integer. On failure will return 0 which cannot be differentiated from a legitimate 0.
1759 */
1760M_API M_int64 M_str_to_int64(const char *s) M_WARN_UNUSED_RESULT;
1761
1762
1763/*! Interpret a string as an ascii numeric. String may begin with whitespace which
1764 * will be ignored, then an optional + or - sign.
1765 *
1766 * \param[in] s NULL-terminated string.
1767 *
1768 * \return Determined integer. On failure will return 0 which cannot be differentiated from a legitimate 0.
1769 */
1770M_API M_uint64 M_str_to_uint64(const char *s) M_WARN_UNUSED_RESULT;
1771
1772
1773/*! Interpret a string as an ascii numeric. String may begin with whitespace which
1774 * will be ignored, then an optional + or - sign.
1775 *
1776 * \param[in] s NULL-terminated string.
1777 * \param[in] len Maximum length of given string to parse.
1778 * \param[in] base Valid range 2 - 36. 0 to autodetect based on input (0x = hex, 0 = octal, anything else is decimal).
1779 * \param[out] val Integer to store result.
1780 * \param[out] endptr Pointer to store the end of the parsed string.
1781 *
1782 * \return One of M_str_int_retval_t return codes.
1783 */
1784M_API M_str_int_retval_t M_str_to_int64_ex(const char *s, size_t len, unsigned char base, M_int64 *val, const char **endptr);
1785
1786
1787/*! Interpret a string as an ascii numeric. String may begin with whitespace which
1788 * will be ignored, then an optional + or - sign.
1789 *
1790 * \param[in] s NULL-terminated string.
1791 * \param[in] len Maximum length of given string to parse.
1792 * \param[in] base Valid range 2 - 36. 0 to autodetect based on input (0x = hex, 0 = octal, anything else is decimal).
1793 * \param[out] val Integer to store result.
1794 * \param[out] endptr Pointer to store the end of the parsed string.
1795 *
1796 * \return One of M_str_int_retval_t return codes.
1797 */
1798M_API M_str_int_retval_t M_str_to_uint64_ex(const char *s, size_t len, unsigned char base, M_uint64 *val, const char **endptr);
1799
1800
1801/*! Interpret a string as an ascii numeric. String may begin with whitespace which
1802 * will be ignored, then an optional + or - sign.
1803 *
1804 * \param[in] s NULL-terminated string.
1805 * \param[in] len Maximum length of given string to parse.
1806 * \param[in] base Valid range 2 - 36. 0 to autodetect based on input (0x = hex, 0 = octal, anything else is decimal).
1807 * \param[out] val Integer to store result.
1808 * \param[out] endptr Pointer to store the end of the parsed string.
1809 *
1810 * \return One of M_str_int_retval_t return codes.
1811 */
1812M_API M_str_int_retval_t M_str_to_int32_ex(const char *s, size_t len, unsigned char base, M_int32 *val, const char **endptr);
1813
1814
1815/*! Interpret a string as an ascii numeric. String may begin with whitespace which
1816 * will be ignored, then an optional + or - sign.
1817 *
1818 * \param[in] s NULL-terminated string.
1819 * \param[in] len Maximum length of given string to parse.
1820 * \param[in] base Valid range 2 - 36. 0 to autodetect based on input (0x = hex, 0 = octal, anything else is decimal).
1821 * \param[out] val Integer to store result
1822 * \param[out] endptr Pointer to store the end of the parsed string.
1823 *
1824 * \return One of M_str_int_retval_t return codes.
1825 */
1826M_API M_str_int_retval_t M_str_to_uint32_ex(const char *s, size_t len, unsigned char base, M_uint32 *val, const char **endptr);
1827
1828
1829/*! Interpret a string as an ascii numeric. String may begin with whitespace which
1830 * will be ignored, then an optional + or - sign.
1831 *
1832 * \param[in] s NULL-terminated string.
1833 *
1834 * \return determined integer. On failure will return 0 which cannot be differentiated from a legitimate 0.
1835 */
1836M_API M_int32 M_str_to_int32(const char *s) M_WARN_UNUSED_RESULT;
1837
1838
1839/*! Interpret a string as an ascii numeric. String may begin with whitespace which
1840 * will be ignored, then an optional + or - sign.
1841 *
1842 * \param[in] s NULL-terminated string.
1843 *
1844 * \return determined integer. On failure will return 0 which cannot be differentiated from a legitimate 0.
1845 */
1846M_API M_uint32 M_str_to_uint32(const char *s) M_WARN_UNUSED_RESULT;
1847
1848
1849/* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
1850 * Money
1851 */
1852
1853/*! Verify and convert the amount so it always has 2 decimal digits.
1854 *
1855 * Example:
1856 * 1 for $1 and turns it into 1.00.
1857 * 1.1 for $1.10 and turns it into 1.10.
1858 *
1859 * \param[in] amount Amount to verify/convert.
1860 *
1861 * \return Amount with decimal and two decimal digits. Or NULL on error.
1862 */
1863M_API char *M_str_dot_money_out(const char *amount);
1864
1865
1866/* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
1867 * Conversion
1868 */
1869
1870/*! Hex dump flags */
1871enum M_str_hexdump_flags {
1872 M_STR_HEXDUMP_NONE = 0, /*!< Defaults */
1873 M_STR_HEXDUMP_DECLEN = 1 << 0, /*!< Default is length in hex (address) format, print in decimal format instead */
1874 M_STR_HEXDUMP_NOASCII = 1 << 1, /*!< Disable dumping of ASCII representation trailing the hexdump */
1875 M_STR_HEXDUMP_HEADER = 1 << 2, /*!< Add a header above each column of output */
1876 M_STR_HEXDUMP_NOLEN = 1 << 3, /*!< Omit the length indicator */
1877 M_STR_HEXDUMP_CRLF = 1 << 4, /*!< Use CRLF newlines (DOS style) */
1878 M_STR_HEXDUMP_UPPER = 1 << 5, /*!< Output hex digits as uppercase */
1879 M_STR_HEXDUMP_NOSECTS = 1 << 6 /*!< Do not put additional emphasis on 8-byte segments */
1880};
1881
1882/*! Generate a hex dump format of binary data meant to be human-readable, or imported via various
1883 * hex-dump conversion tools such as Text2pcap.
1884 * \param flags one or more enum M_str_hexdump_flags
1885 * \param bytes_per_line Number of bytes represented per line. If zero is used, defaults to 16
1886 * \param line_prefix Prefix each line of the hex dump with the given data.
1887 * \param data Binary data to be dumped
1888 * \param data_len length of binary data to be dumped
1889 * \return Allocated string representing the hex dump. Must be M_free()'d by the caller.
1890 */
1891M_API char *M_str_hexdump(int flags, size_t bytes_per_line, const char *line_prefix, const unsigned char *data, size_t data_len);
1892
1893/*! @} */
1894
1895__END_DECLS
1896
1897#endif /* __M_STR_H__ */
M_chr_predicate_func
M_bool(* M_chr_predicate_func)(char c)
Definition: m_chr.h:134
M_str_isnotcharset
M_bool M_str_isnotcharset(const char *str, const char *charset)
M_str_eq_end
M_bool M_str_eq_end(const char *s1, const char *s2)
M_str_isprint_max
M_bool M_str_isprint_max(const char *s, size_t max) M_WARN_UNUSED_RESULT
M_str_cmpsort_max
int M_str_cmpsort_max(const char *s1, const char *s2, size_t max) M_WARN_UNUSED_RESULT
M_str_casecmpsort_max
int M_str_casecmpsort_max(const char *s1, const char *s2, size_t max) M_WARN_UNUSED_RESULT
M_str_ispredicate
M_bool M_str_ispredicate(const char *s, M_chr_predicate_func pred)
M_str_isalpha_max
M_bool M_str_isalpha_max(const char *s, size_t max) M_WARN_UNUSED_RESULT
M_str_caseeq_end
M_bool M_str_caseeq_end(const char *s1, const char *s2)
M_str_isspace
M_bool M_str_isspace(const char *s) M_WARN_UNUSED_RESULT
M_str_isalnum_max
M_bool M_str_isalnum_max(const char *s, size_t max) M_WARN_UNUSED_RESULT
M_str_isalpha
M_bool M_str_isalpha(const char *s) M_WARN_UNUSED_RESULT
M_str_caseeq
M_bool M_str_caseeq(const char *s1, const char *s2)
M_str_pattern_match
M_bool M_str_pattern_match(const char *pattern, const char *s) M_WARN_UNUSED_RESULT
M_str_isspace_max
M_bool M_str_isspace_max(const char *s, size_t max) M_WARN_UNUSED_RESULT
M_str_isnum_max
M_bool M_str_isnum_max(const char *s, size_t max) M_WARN_UNUSED_RESULT
M_str_isdec
M_bool M_str_isdec(const char *s) M_WARN_UNUSED_RESULT
M_str_safe
const char * M_str_safe(const char *s)
M_str_isempty
M_bool M_str_isempty(const char *s) M_WARN_UNUSED_RESULT
M_str_len_max
size_t M_str_len_max(const char *s, size_t max) M_WARN_UNUSED_RESULT
M_str_eq
M_bool M_str_eq(const char *s1, const char *s2)
M_str_isnum
M_bool M_str_isnum(const char *s) M_WARN_UNUSED_RESULT
M_str_isdec_max
M_bool M_str_isdec_max(const char *s, size_t max) M_WARN_UNUSED_RESULT
M_str_isgraph_max
M_bool M_str_isgraph_max(const char *s, size_t max) M_WARN_UNUSED_RESULT
M_str_isalnumsp_max
M_bool M_str_isalnumsp_max(const char *s, size_t max) M_WARN_UNUSED_RESULT
M_str_eq_max
M_bool M_str_eq_max(const char *s1, const char *s2, size_t max)
M_str_isgraph
M_bool M_str_isgraph(const char *s) M_WARN_UNUSED_RESULT
M_str_ismoney
M_bool M_str_ismoney(const char *s) M_WARN_UNUSED_RESULT
M_str_isalphasp_max
M_bool M_str_isalphasp_max(const char *s, size_t max) M_WARN_UNUSED_RESULT
M_str_caseeq_start
M_bool M_str_caseeq_start(const char *s1, const char *s2)
M_str_casecmpsort
int M_str_casecmpsort(const char *s1, const char *s2) M_WARN_UNUSED_RESULT
M_str_eq_start
M_bool M_str_eq_start(const char *s1, const char *s2)
M_str_isalnum
M_bool M_str_isalnum(const char *s) M_WARN_UNUSED_RESULT
M_str_len
size_t M_str_len(const char *s) M_WARN_UNUSED_RESULT
M_str_caseeq_max
M_bool M_str_caseeq_max(const char *s1, const char *s2, size_t max)
M_str_isalphasp
M_bool M_str_isalphasp(const char *s) M_WARN_UNUSED_RESULT
M_str_istrue
M_bool M_str_istrue(const char *s) M_WARN_UNUSED_RESULT
M_str_ishex_max
M_bool M_str_ishex_max(const char *s, size_t max) M_WARN_UNUSED_RESULT
M_str_cmpsort
int M_str_cmpsort(const char *s1, const char *s2) M_WARN_UNUSED_RESULT
M_str_isalnumsp
M_bool M_str_isalnumsp(const char *s) M_WARN_UNUSED_RESULT
M_str_isprint
M_bool M_str_isprint(const char *s) M_WARN_UNUSED_RESULT
M_str_case_pattern_match
M_bool M_str_case_pattern_match(const char *pattern, const char *s) M_WARN_UNUSED_RESULT
M_str_ispredicate_max
M_bool M_str_ispredicate_max(const char *s, size_t max, M_chr_predicate_func pred)
M_str_isstr
M_bool M_str_isstr(const unsigned char *s, size_t len)
M_str_ishex
M_bool M_str_ishex(const char *s) M_WARN_UNUSED_RESULT
M_str_isascii
M_bool M_str_isascii(const char *s) M_WARN_UNUSED_RESULT
M_str_ischarset
M_bool M_str_ischarset(const char *str, const char *charset)
M_str_hexdump
char * M_str_hexdump(int flags, size_t bytes_per_line, const char *line_prefix, const unsigned char *data, size_t data_len)
M_str_to_int64
M_int64 M_str_to_int64(const char *s) M_WARN_UNUSED_RESULT
M_str_to_uint64
M_uint64 M_str_to_uint64(const char *s) M_WARN_UNUSED_RESULT
M_str_to_int32_ex
M_str_int_retval_t M_str_to_int32_ex(const char *s, size_t len, unsigned char base, M_int32 *val, const char **endptr)
M_str_to_int64_ex
M_str_int_retval_t M_str_to_int64_ex(const char *s, size_t len, unsigned char base, M_int64 *val, const char **endptr)
M_str_dot_money_out
char * M_str_dot_money_out(const char *amount)
M_str_hexdump_flags
M_str_hexdump_flags
Definition: m_str.h:1871
M_str_int_retval_t
M_str_int_retval_t
Definition: m_str.h:1719
M_str_to_uint32
M_uint32 M_str_to_uint32(const char *s) M_WARN_UNUSED_RESULT
M_atofi100
long M_atofi100(const char *s) M_WARN_UNUSED_RESULT
M_str_to_int32
M_int32 M_str_to_int32(const char *s) M_WARN_UNUSED_RESULT
M_str_to_uint32_ex
M_str_int_retval_t M_str_to_uint32_ex(const char *s, size_t len, unsigned char base, M_uint32 *val, const char **endptr)
M_atofi_prec
M_int64 M_atofi_prec(const char *s, int impliedDecimals) M_WARN_UNUSED_RESULT
M_str_to_uint64_ex
M_str_int_retval_t M_str_to_uint64_ex(const char *s, size_t len, unsigned char base, M_uint64 *val, const char **endptr)
M_STR_HEXDUMP_DECLEN
@ M_STR_HEXDUMP_DECLEN
Definition: m_str.h:1873
M_STR_HEXDUMP_NOASCII
@ M_STR_HEXDUMP_NOASCII
Definition: m_str.h:1874
M_STR_HEXDUMP_CRLF
@ M_STR_HEXDUMP_CRLF
Definition: m_str.h:1877
M_STR_HEXDUMP_NOSECTS
@ M_STR_HEXDUMP_NOSECTS
Definition: m_str.h:1879
M_STR_HEXDUMP_UPPER
@ M_STR_HEXDUMP_UPPER
Definition: m_str.h:1878
M_STR_HEXDUMP_HEADER
@ M_STR_HEXDUMP_HEADER
Definition: m_str.h:1875
M_STR_HEXDUMP_NONE
@ M_STR_HEXDUMP_NONE
Definition: m_str.h:1872
M_STR_HEXDUMP_NOLEN
@ M_STR_HEXDUMP_NOLEN
Definition: m_str.h:1876
M_STR_INT_INVALID
@ M_STR_INT_INVALID
Definition: m_str.h:1722
M_STR_INT_SUCCESS
@ M_STR_INT_SUCCESS
Definition: m_str.h:1720
M_STR_INT_OVERFLOW
@ M_STR_INT_OVERFLOW
Definition: m_str.h:1721
M_strdup_trim_max
char * M_strdup_trim_max(const char *s, size_t max) M_ALLOC_SIZE(2) M_WARN_UNUSED_RESULT M_MALLOC
M_strdup_lower
char * M_strdup_lower(const char *s) M_WARN_UNUSED_RESULT M_MALLOC
M_strdup_title
char * M_strdup_title(const char *s) M_WARN_UNUSED_RESULT M_MALLOC
M_strdup_unquote
char * M_strdup_unquote(const char *s, unsigned char quote, unsigned char escape) M_WARN_UNUSED_RESULT M_MALLOC
M_strdup_unquote_max
char * M_strdup_unquote_max(const char *s, unsigned char quote, unsigned char escape, size_t max) M_ALLOC_SIZE(2) M_WARN_UNUSED_RESULT M_MALLOC
M_strdup_lower_max
char * M_strdup_lower_max(const char *s, size_t max) M_ALLOC_SIZE(2) M_WARN_UNUSED_RESULT M_MALLOC
M_strdup_upper
char * M_strdup_upper(const char *s) M_WARN_UNUSED_RESULT M_MALLOC
M_strdup
char * M_strdup(const char *s) M_WARN_UNUSED_RESULT M_MALLOC
M_strdup_upper_max
char * M_strdup_upper_max(const char *s, size_t max) M_ALLOC_SIZE(2) M_WARN_UNUSED_RESULT M_MALLOC
M_str_justify_type_t
M_str_justify_type_t
Definition: m_str.h:714
M_strdup_max
char * M_strdup_max(const char *s, size_t max) M_ALLOC_SIZE(2) M_WARN_UNUSED_RESULT M_MALLOC
M_strdup_replace_charset
char * M_strdup_replace_charset(const char *s, const unsigned char *bcs, size_t bcs_len, const char *a)
M_strdup_replace_str
char * M_strdup_replace_str(const char *s, const char *b, const char *a)
M_strdup_trim
char * M_strdup_trim(const char *s) M_WARN_UNUSED_RESULT M_MALLOC
M_strdup_justify
char * M_strdup_justify(const char *src, M_str_justify_type_t justtype, unsigned char justchar, size_t justlen) M_WARN_UNUSED_RESULT M_MALLOC
M_strdup_title_max
char * M_strdup_title_max(const char *s, size_t max) M_ALLOC_SIZE(2) M_WARN_UNUSED_RESULT M_MALLOC
M_STR_JUSTIFY_TRUNC_RIGHT
@ M_STR_JUSTIFY_TRUNC_RIGHT
Definition: m_str.h:729
M_STR_JUSTIFY_CENTER
@ M_STR_JUSTIFY_CENTER
Definition: m_str.h:733
M_STR_JUSTIFY_LEFT
@ M_STR_JUSTIFY_LEFT
Definition: m_str.h:717
M_STR_JUSTIFY_TRUNC_LEFT
@ M_STR_JUSTIFY_TRUNC_LEFT
Definition: m_str.h:731
M_STR_JUSTIFY_END
@ M_STR_JUSTIFY_END
Definition: m_str.h:740
M_STR_JUSTIFY_LEFT_TRUNC_RIGHT
@ M_STR_JUSTIFY_LEFT_TRUNC_RIGHT
Definition: m_str.h:721
M_STR_JUSTIFY_CENTER_TRUNC_RIGHT
@ M_STR_JUSTIFY_CENTER_TRUNC_RIGHT
Definition: m_str.h:735
M_STR_JUSTIFY_LEFT_NOTRUNC
@ M_STR_JUSTIFY_LEFT_NOTRUNC
Definition: m_str.h:726
M_STR_JUSTIFY_RIGHT_TRUNC_RIGHT
@ M_STR_JUSTIFY_RIGHT_TRUNC_RIGHT
Definition: m_str.h:719
M_STR_JUSTIFY_RIGHT
@ M_STR_JUSTIFY_RIGHT
Definition: m_str.h:715
M_STR_JUSTIFY_CENTER_NO_TRUNC
@ M_STR_JUSTIFY_CENTER_NO_TRUNC
Definition: m_str.h:737
M_STR_JUSTIFY_RIGHT_NOTRUNC
@ M_STR_JUSTIFY_RIGHT_NOTRUNC
Definition: m_str.h:723
M_str_trim_max
char * M_str_trim_max(char *s, size_t max)
M_str_cpy
M_bool M_str_cpy(char *dest, size_t dest_len, const char *src)
M_str_remove_bracketed
char * M_str_remove_bracketed(const char *src, char open, char close) M_WARN_UNUSED_RESULT M_MALLOC
M_str_keep_quoted
char * M_str_keep_quoted(const char *src, char quote_char, char escape_char) M_WARN_UNUSED_RESULT M_MALLOC
M_str_keep_bracketed
char * M_str_keep_bracketed(const char *src, char open, char close) M_WARN_UNUSED_RESULT M_MALLOC
M_str_keep_bracketed_quoted
char * M_str_keep_bracketed_quoted(const char *src, char open, char close, char quote, char escape) M_WARN_UNUSED_RESULT M_MALLOC
M_str_remove_bracketed_quoted
char * M_str_remove_bracketed_quoted(const char *src, char open, char close, char quote, char escape) M_WARN_UNUSED_RESULT M_MALLOC
M_str_lower_max
char * M_str_lower_max(char *s, size_t max)
M_str_quote_max
char * M_str_quote_max(const char *s, unsigned char quote, unsigned char escape, size_t max) M_WARN_UNUSED_RESULT M_MALLOC
M_str_unquote
char * M_str_unquote(char *s, unsigned char quote, unsigned char escape)
M_str_lower
char * M_str_lower(char *s)
M_str_cat
M_bool M_str_cat(char *dest, size_t dest_len, const char *src)
M_str_quote_if_necessary
M_bool M_str_quote_if_necessary(char **out, const char *s, unsigned char quote, unsigned char escape, unsigned char delim)
M_str_replace_chr
char * M_str_replace_chr(char *s, char b, char a)
M_str_upper
char * M_str_upper(char *s)
M_str_remove_quoted
char * M_str_remove_quoted(const char *src, char quote_char, char escape_char) M_WARN_UNUSED_RESULT M_MALLOC
M_str_justify
size_t M_str_justify(char *dest, size_t destlen, const char *src, M_str_justify_type_t justtype, unsigned char justchar, size_t justlen)
M_str_justify_max
size_t M_str_justify_max(char *dest, size_t destlen, const char *src, size_t srclen, M_str_justify_type_t justtype, unsigned char justchar, size_t justlen)
M_str_delete_spaces
char * M_str_delete_spaces(char *s)
M_str_quote
char * M_str_quote(const char *s, unsigned char quote, unsigned char escape) M_WARN_UNUSED_RESULT M_MALLOC
M_str_delete_newlines
char * M_str_delete_newlines(char *s)
M_str_unquote_max
char * M_str_unquote_max(char *s, unsigned char quote, unsigned char escape, size_t max)
M_str_upper_max
char * M_str_upper_max(char *s, size_t max)
M_str_title_max
char * M_str_title_max(char *s, size_t max)
M_str_title
char * M_str_title(char *s)
M_str_trim
char * M_str_trim(char *s)
M_str_cpy_max
M_bool M_str_cpy_max(char *dest, size_t dest_len, const char *src, size_t src_len)
M_str_explode_str_quoted
char ** M_str_explode_str_quoted(unsigned char delim, const char *s, unsigned char quote_char, unsigned char escape_char, size_t max_sects, size_t *num) M_WARN_UNUSED_RESULT M_MALLOC
M_str_explode
char ** M_str_explode(unsigned char delim, const char *s, size_t s_len, size_t *num, size_t **len_array) M_WARN_UNUSED_RESULT M_MALLOC
M_str_split_on_char
char * M_str_split_on_char(char *s, char c)
M_str_explode_free
void M_str_explode_free(char **strs, size_t num) M_FREE(1)
M_str_implode
char * M_str_implode(unsigned char delim, unsigned char enclose_char, unsigned char escape_char, char **strs, size_t num_strs, M_bool always_enclose) M_WARN_UNUSED_RESULT M_MALLOC
M_str_explode_lines
char ** M_str_explode_lines(size_t max_lines, size_t max_chars, const char *src_str, M_bool truncate, size_t *num) M_WARN_UNUSED_RESULT M_MALLOC
M_str_explode_quoted
char ** M_str_explode_quoted(unsigned char delim, const char *s, size_t s_len, unsigned char quote_char, unsigned char escape_char, size_t max_sects, size_t *num, size_t **len_array) M_WARN_UNUSED_RESULT M_MALLOC
M_str_explode_str
char ** M_str_explode_str(unsigned char delim, const char *s, size_t *num) M_WARN_UNUSED_RESULT M_MALLOC
M_str_implode_int
char * M_str_implode_int(unsigned char delim, const int *ints, size_t num_ints) M_WARN_UNUSED_RESULT M_MALLOC
M_str_explode_int
int * M_str_explode_int(unsigned char delim, const char *s, size_t *num) M_WARN_UNUSED_RESULT M_MALLOC
M_str_chr
char * M_str_chr(const char *s, char c) M_WARN_UNUSED_RESULT
M_str_rchr
char * M_str_rchr(const char *s, char c) M_WARN_UNUSED_RESULT
M_str_casestr_pos
ssize_t M_str_casestr_pos(const char *haystack, const char *needle) M_WARN_UNUSED_RESULT
M_str_casestr
char * M_str_casestr(const char *haystack, const char *needle) M_WARN_UNUSED_RESULT
M_str_str
char * M_str_str(const char *haystack, const char *needle) M_WARN_UNUSED_RESULT
M_str_find_first_not_from_charset
char * M_str_find_first_not_from_charset(const char *str, const char *charset)
M_str_find_first_from_charset
char * M_str_find_first_from_charset(const char *str, const char *charset)