source/blender/blenlib/BLI_string.h

   1 /* SPDX-FileCopyrightText: 2001-2002 NaN Holding BV. All rights reserved.
   2  *
   3  * SPDX-License-Identifier: GPL-2.0-or-later */
   4
   5 #pragma once
   6
   7 /** \file
   8  * \ingroup bli
   9  */
  10
  11 #include <inttypes.h>
  12 #include <stdarg.h>
  13
  14 #include "BLI_compiler_attrs.h"
  15 #include "BLI_utildefines.h"
  16
  17 #ifdef __cplusplus
  18 extern "C" {
  19 #endif
  20
  21 /* Buffer size of maximum `uint64` plus commas and terminator. */
  22 #define BLI_STR_FORMAT_UINT64_GROUPED_SIZE 27
  23
  24 /* Buffer size of maximum `int32` with commas and terminator. */
  25 #define BLI_STR_FORMAT_INT32_GROUPED_SIZE 15
  26
  27 /* Buffer size of maximum `int64` formatted as byte size (with GiB for example). */
  28 #define BLI_STR_FORMAT_INT64_BYTE_UNIT_SIZE 15
  29
  30 /* Buffer size of maximum `int64` formatted as byte size, minimum length (".1G" for example). */
  31 #define BLI_STR_FORMAT_INT64_BYTE_UNIT_COMPACT_SIZE 5
  32
  33 /* Buffer size of maximum `int32` formatted as compact decimal size ("15.6M" for example). */
  34 #define BLI_STR_FORMAT_INT32_DECIMAL_UNIT_SIZE 7
  35
  36 /* Buffer size of maximum `int32` formatted as very short decimal size ("15B" for example). */
  37 #define BLI_STR_FORMAT_INT32_INTEGER_UNIT_SIZE 5
  38
  39 /**
  40  * Duplicates the first \a len bytes of the C-string \a str
  41  * into a newly mallocN'd string and returns it. \a str
  42  * is assumed to be at least len bytes long.
  43  *
  44  * \param str: The string to be duplicated
  45  * \param len: The number of bytes to duplicate
  46  * \retval Returns the duplicated string
  47  */
  48 char *BLI_strdupn(const char *str, size_t len) ATTR_MALLOC ATTR_WARN_UNUSED_RESULT ATTR_NONNULL(1);
  49
  50 /**
  51  * Duplicates the C-string \a str into a newly mallocN'd
  52  * string and returns it.
  53  *
  54  * \param str: The string to be duplicated
  55  * \retval Returns the duplicated string
  56  */
  57 char *BLI_strdup(const char *str) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL(1) ATTR_MALLOC;
  58
  59 /**
  60  * Duplicates the C-string \a str into a newly mallocN'd
  61  * string and returns it.
  62  *
  63  * \param str: The string to be duplicated, can be null
  64  * \retval Returns the duplicated string or null if \a str is null
  65  */
  66 char *BLI_strdup_null(const char *str) ATTR_WARN_UNUSED_RESULT ATTR_MALLOC;
  67
  68 /**
  69  * Appends the two strings, and returns new mallocN'ed string
  70  * \param str1: first string for copy
  71  * \param str2: second string for append
  72  * \retval Returns dst
  73  */
  74 char *BLI_strdupcat(const char *__restrict str1,
  75                     const char *__restrict str2) ATTR_WARN_UNUSED_RESULT
  76     ATTR_NONNULL(1, 2) ATTR_MALLOC;
  77
  78 /**
  79  * Like `strncpy` but ensures dst is always `\0` terminated.
  80  *
  81  * \param dst: Destination for copy.
  82  * \param src: Source string to copy.
  83  * \param dst_maxncpy: Maximum number of characters to copy (generally the size of dst).
  84  * \retval Returns dst
  85  */
  86 char *BLI_strncpy(char *__restrict dst, const char *__restrict src, size_t dst_maxncpy)
  87     ATTR_NONNULL(1, 2);
  88
  89 /**
  90  * Like BLI_strncpy but ensures dst is always padded by given char,
  91  * on both sides (unless `src` is empty).
  92  *
  93  * \param dst: Destination for copy
  94  * \param src: Source string to copy
  95  * \param pad: the char to use for padding
  96  * \param dst_maxncpy: Maximum number of characters to copy (generally the size of dst).
  97  * \retval Returns dst
  98  */
  99 char *BLI_strncpy_ensure_pad(char *__restrict dst,
 100                              const char *__restrict src,
 101                              char pad,
 102                              size_t dst_maxncpy) ATTR_NONNULL(1, 2);
 103
 104 /**
 105  * Like `strncpy` but ensures dst is always `\0` terminated.
 106  *
 107  * \note This is a duplicate of #BLI_strncpy that returns bytes copied.
 108  * And is a drop in replacement for `snprintf(str, sizeof(str), "%s", arg);`
 109  *
 110  * \param dst: Destination for copy
 111  * \param src: Source string to copy
 112  * \param dst_maxncpy: Maximum number of characters to copy (generally the size of dst).
 113  * \retval The number of bytes copied (The only difference from #BLI_strncpy).
 114  */
 115 size_t BLI_strncpy_rlen(char *__restrict dst,
 116                         const char *__restrict src,
 117                         size_t dst_maxncpy) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL(1, 2);
 118
 119 char *BLI_strncat(char *__restrict dst, const char *__restrict src, size_t dst_maxncpy)
 120     ATTR_NONNULL(1, 2);
 121
 122 /**
 123  * A version of `strchr` that returns the end of the string (point to `\0`)
 124  * if the character is not found.
 125  *
 126  * Useful for stepping over newlines up until the last line.
 127  */
 128 const char *BLI_strchr_or_end(const char *str,
 129                               char ch) ATTR_WARN_UNUSED_RESULT ATTR_RETURNS_NONNULL
 130     ATTR_NONNULL(1);
 131
 132 /**
 133  * Return the range of the quoted string (excluding quotes) `str` after `prefix`.
 134  *
 135  * A version of #BLI_str_quoted_substrN that calculates the range
 136  * instead of un-escaping and allocating the result.
 137  *
 138  * \param str: String potentially including `prefix`.
 139  * \param prefix: Quoted string prefix.
 140  * \param r_start: The start of the quoted string (after the first quote).
 141  * \param r_end: The end of the quoted string (before the last quote).
 142  * \return True when a quoted string range could be found after `prefix`.
 143  */
 144 bool BLI_str_quoted_substr_range(const char *__restrict str,
 145                                  const char *__restrict prefix,
 146                                  int *__restrict r_start,
 147                                  int *__restrict r_end) ATTR_WARN_UNUSED_RESULT
 148     ATTR_NONNULL(1, 2, 3, 4);
 149 #if 0 /* UNUSED */
 150 char *BLI_str_quoted_substrN(const char *__restrict str,
 151                              const char *__restrict prefix) ATTR_WARN_UNUSED_RESULT
 152     ATTR_NONNULL(1, 2) ATTR_MALLOC;
 153 #endif
 154 /**
 155  * Fills \a result with text within "" that appear after some the contents of \a prefix.
 156  * i.e. for string `pose["apples"]` with prefix `pose[`, it will return `apples`.
 157  *
 158  * \param str: is the entire string to chop.
 159  * \param prefix: is the part of the string to step over.
 160  * \param result: The buffer to fill.
 161  * \param result_maxncpy: The maximum size of the buffer (including nil terminator).
 162  * \return True if the prefix was found and the entire quoted string was copied into result.
 163  *
 164  * Assume that the strings returned must be freed afterwards,
 165  * and that the inputs will contain data we want.
 166  */
 167 bool BLI_str_quoted_substr(const char *__restrict str,
 168                            const char *__restrict prefix,
 169                            char *result,
 170                            size_t result_maxncpy);
 171
 172 /**
 173  * Portable replacement for `snprintf`.
 174  */
 175 size_t BLI_snprintf(char *__restrict dst, size_t dst_maxncpy, const char *__restrict format, ...)
 176     ATTR_NONNULL(1, 3) ATTR_PRINTF_FORMAT(3, 4);
 177 /**
 178  * A version of #BLI_snprintf that returns `strlen(dst)`
 179  */
 180 size_t BLI_snprintf_rlen(char *__restrict dst,
 181                          size_t dst_maxncpy,
 182                          const char *__restrict format,
 183                          ...) ATTR_NONNULL(1, 3) ATTR_PRINTF_FORMAT(3, 4);
 184
 185 /**
 186  * Portable replacement for `vsnprintf`.
 187  */
 188 size_t BLI_vsnprintf(char *__restrict dst,
 189                      size_t dst_maxncpy,
 190                      const char *__restrict format,
 191                      va_list arg) ATTR_PRINTF_FORMAT(3, 0);
 192 /**
 193  * A version of #BLI_vsnprintf that returns `strlen(dst)`
 194  */
 195 size_t BLI_vsnprintf_rlen(char *__restrict dst,
 196                           size_t dst_maxncpy,
 197                           const char *__restrict format,
 198                           va_list arg) ATTR_PRINTF_FORMAT(3, 0);
 199
 200 char *BLI_sprintfN_with_buffer(char *fixed_buf,
 201                                size_t fixed_buf_size,
 202                                size_t *result_len,
 203                                const char *__restrict format,
 204                                ...) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL(1, 3, 4)
 205     ATTR_PRINTF_FORMAT(4, 5);
 206 char *BLI_vsprintfN_with_buffer(char *fixed_buf,
 207                                 size_t fixed_buf_size,
 208                                 size_t *result_len,
 209                                 const char *__restrict format,
 210                                 va_list args) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL(1, 3, 4)
 211     ATTR_PRINTF_FORMAT(4, 0);
 212
 213 /**
 214  * Print formatted string into a newly #MEM_mallocN'd string
 215  * and return it.
 216  */
 217 char *BLI_sprintfN(const char *__restrict format, ...) ATTR_WARN_UNUSED_RESULT
 218     ATTR_NONNULL(1) ATTR_MALLOC ATTR_PRINTF_FORMAT(1, 2);
 219 /** A version of #BLI_sprintfN that takes a #va_list. */
 220 char *BLI_vsprintfN(const char *__restrict format, va_list args) ATTR_NONNULL(1, 2) ATTR_MALLOC
 221     ATTR_PRINTF_FORMAT(1, 0);
 222
 223 /**
 224  * This roughly matches C and Python's string escaping with double quotes - `"`.
 225  *
 226  * Since every character may need escaping,
 227  * it's common to create a buffer twice as large as the input.
 228  *
 229  * \param dst: The destination string, at least \a dst_maxncpy, typically `(strlen(src) * 2) + 1`.
 230  * \param src: The un-escaped source string.
 231  * \param dst_maxncpy: The maximum number of bytes allowable to copy.
 232  *
 233  * \note This is used for creating animation paths in blend files.
 234  */
 235 size_t BLI_str_escape(char *__restrict dst, const char *__restrict src, size_t dst_maxncpy)
 236     ATTR_NONNULL(1, 2);
 237 /**
 238  * This roughly matches C and Python's string escaping with double quotes - `"`.
 239  *
 240  * The destination will never be larger than the source, it will either be the same
 241  * or up to half when all characters are escaped.
 242  *
 243  * \param dst: The destination string, at least the size of `strlen(src) + 1`.
 244  * \param src: The escaped source string.
 245  * \param src_maxncpy: The maximum number of bytes allowable to copy from `src`.
 246  * \param dst_maxncpy: The maximum number of bytes allowable to copy into `dst`.
 247  * \param r_is_complete: Set to true when.
 248  */
 249 size_t BLI_str_unescape_ex(char *__restrict dst,
 250                            const char *__restrict src,
 251                            size_t src_maxncpy,
 252                            /* Additional arguments. */
 253                            size_t dst_maxncpy,
 254                            bool *r_is_complete) ATTR_NONNULL(1, 2, 5);
 255 /**
 256  * See #BLI_str_unescape_ex doc-string.
 257  *
 258  * This function makes the assumption that `dst` always has
 259  * at least `src_maxncpy` bytes available.
 260  *
 261  * Use #BLI_str_unescape_ex if `dst` has a smaller fixed size.
 262  *
 263  * \note This is used for parsing animation paths in blend files (runs often).
 264  */
 265 size_t BLI_str_unescape(char *__restrict dst, const char *__restrict src, size_t src_maxncpy)
 266     ATTR_NONNULL(1, 2);
 267
 268 /**
 269  * Find the first un-escaped quote in the string (to find the end of the string).
 270  *
 271  * \param str: Typically this is the first character in a quoted string.
 272  * Where the character before `*str` would be `"`.
 273  *
 274  * \return The pointer to the first un-escaped quote.
 275  */
 276 const char *BLI_str_escape_find_quote(const char *str) ATTR_NONNULL(1);
 277
 278 /**
 279  * Format integers with decimal grouping.
 280  * 1000 -> 1,000
 281  *
 282  * \param dst: The resulting string.
 283  * \param num: Number to format.
 284  * \return The length of \a dst
 285  */
 286 size_t BLI_str_format_int_grouped(char dst[BLI_STR_FORMAT_INT32_GROUPED_SIZE], int num)
 287     ATTR_NONNULL(1);
 288 /**
 289  * Format uint64_t with decimal grouping.
 290  * 1000 -> 1,000
 291  *
 292  * \param dst: The resulting string.
 293  * \param num: Number to format.
 294  * \return The length of \a dst.
 295  */
 296 size_t BLI_str_format_uint64_grouped(char dst[BLI_STR_FORMAT_UINT64_GROUPED_SIZE], uint64_t num)
 297     ATTR_NONNULL(1);
 298 /**
 299  * Format a size in bytes using binary units.
 300  * 1000 -> 1 KB
 301  * Number of decimal places grows with the used unit (e.g. 1.5 MB, 1.55 GB, 1.545 TB).
 302  *
 303  * \param dst: The resulting string.
 304  * Dimension of 14 to support largest possible value for \a bytes (#LLONG_MAX).
 305  * \param bytes: Number to format.
 306  * \param base_10: Calculate using base 10 (GB, MB, ...) or 2 (GiB, MiB, ...).
 307  */
 308 void BLI_str_format_byte_unit(char dst[BLI_STR_FORMAT_INT64_BYTE_UNIT_SIZE],
 309                               long long int bytes,
 310                               bool base_10) ATTR_NONNULL(1);
 311
 312 /**
 313  * Format a size in bytes using binary units in compact (max 4 chars) format.
 314  *
 315  * It shows a lower bound instead of rounding the number.
 316  *
 317  * 1 -> 1B
 318  * 15 -> 15B
 319  * 155 -> 155B
 320  * 1555 -> 1K
 321  * 15555 -> 15K
 322  * 155555 -> .1M
 323  * 1555555 -> 1M
 324  * 15555555 -> 15M
 325  * 155555555 -> .1G
 326  * 1000000000 -> 1G
 327  * ...
 328  *
 329  * \param dst: The resulting string.
 330  * Dimension of 5 to support largest possible value for \a bytes (#LLONG_MAX).
 331  * \param bytes: Number to format.
 332  * \param base_10: Calculate using base 10 (GB, MB, ...) or 2 (GiB, MiB, ...).
 333  */
 334 void BLI_str_format_byte_unit_compact(char dst[BLI_STR_FORMAT_INT64_BYTE_UNIT_COMPACT_SIZE],
 335                                       long long int bytes,
 336                                       bool base_10) ATTR_NONNULL(1);
 337
 338 /**
 339  * Format a count to up to 6 places (plus `\0` terminator) string using long number
 340  * names abbreviations. Used to produce a compact representation of large numbers.
 341  *
 342  * 1 -> 1
 343  * 15 -> 15
 344  * 155 -> 155
 345  * 1555 -> 1.6K
 346  * 15555 -> 15.6K
 347  * 155555 -> 156K
 348  * 1555555 -> 1.6M
 349  * 15555555 -> 15.6M
 350  * 155555555 -> 156M
 351  * 1000000000 -> 1B
 352  * ...
 353  *
 354  * Length of 7 is the maximum of the resulting string, for example, `-15.5K\0`.
 355  */
 356 void BLI_str_format_decimal_unit(char dst[BLI_STR_FORMAT_INT32_DECIMAL_UNIT_SIZE],
 357                                  int number_to_format) ATTR_NONNULL(1);
 358 /**
 359  * Format a count to up to 3 places (plus minus sign, plus '\0' terminator) string using long
 360  * number names abbreviations. Used to produce a compact representation of large numbers as
 361  * integers.
 362  *
 363  * It shows a lower bound instead of rounding the number.
 364  *
 365  * 1 -> 1
 366  * 15 -> 15
 367  * 155 -> 155
 368  * 1555 -> 1K
 369  * 15555 -> 15K
 370  * 155555 -> .1M
 371  * 1555555 -> 1M
 372  * 15555555 -> 15M
 373  * 155555555 -> .1B
 374  * 1000000000 -> 1B
 375  * ...
 376  *
 377  * Length of 5 is the maximum of the resulting string, for example, `-15K\0`.
 378  */
 379 void BLI_str_format_integer_unit(char dst[BLI_STR_FORMAT_INT32_INTEGER_UNIT_SIZE],
 380                                  int number_to_format) ATTR_NONNULL(1);
 381 /**
 382  * Compare two strings without regard to case.
 383  *
 384  * \retval True if the strings are equal, false otherwise.
 385  */
 386 int BLI_strcaseeq(const char *a, const char *b) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL(1, 2);
 387 /**
 388  * Portable replacement for `strcasestr` (not available in MSVC)
 389  */
 390 char *BLI_strcasestr(const char *s, const char *find) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL(1, 2);
 391 /**
 392  * Variation of #BLI_strcasestr with string length limited to \a len
 393  */
 394 char *BLI_strncasestr(const char *s, const char *find, size_t len) ATTR_WARN_UNUSED_RESULT
 395     ATTR_NONNULL(1, 2);
 396 int BLI_strcasecmp(const char *s1, const char *s2) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL(1, 2);
 397 int BLI_strncasecmp(const char *s1, const char *s2, size_t len) ATTR_WARN_UNUSED_RESULT
 398     ATTR_NONNULL(1, 2);
 399 /**
 400  * Case insensitive, *natural* string comparison,
 401  * keeping numbers in order.
 402  */
 403 int BLI_strcasecmp_natural(const char *s1, const char *s2) ATTR_WARN_UNUSED_RESULT
 404     ATTR_NONNULL(1, 2);
 405 /**
 406  * Like `strcmp`, but will ignore any heading/trailing pad char for comparison.
 407  * So e.g. if pad is `*`, `*world` and `world*` will compare equal.
 408  */
 409 int BLI_strcmp_ignore_pad(const char *str1, const char *str2, char pad) ATTR_WARN_UNUSED_RESULT
 410     ATTR_NONNULL(1, 2);
 411
 412 /**
 413  * Determine the length of a fixed-size string.
 414  *
 415  * \return The string length that doesn't exceed `maxlen`.
 416  * The equivalent of `min(strlen(str), maxlen)` that prevents a buffer overflow
 417  * when `str` isn't null terminated before `maxlen`.
 418  */
 419 size_t BLI_strnlen(const char *str, size_t maxlen) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL(1);
 420
 421 /**
 422  * String case conversion, not affected by locale.
 423  */
 424
 425 void BLI_str_tolower_ascii(char *str, size_t len) ATTR_NONNULL(1);
 426 void BLI_str_toupper_ascii(char *str, size_t len) ATTR_NONNULL(1);
 427
 428 char BLI_tolower_ascii(const char c) ATTR_WARN_UNUSED_RESULT;
 429 char BLI_toupper_ascii(const char c) ATTR_WARN_UNUSED_RESULT;
 430
 431 /**
 432  * Strip white-space from end of the string.
 433  */
 434 void BLI_str_rstrip(char *str) ATTR_NONNULL(1);
 435 /**
 436  * Strip trailing zeros from a float, eg:
 437  * - 0.0000 -> 0.0
 438  * - 2.0010 -> 2.001
 439  *
 440  * \param str:
 441  * \param pad:
 442  * \return The number of zeros stripped.
 443  */
 444 int BLI_str_rstrip_float_zero(char *str, char pad) ATTR_NONNULL(1);
 445
 446 /**
 447  * Strip trailing digits.
 448  * - ABC123 -> ABC
 449  *
 450  * \param str:
 451  * \return The number of digits stripped.
 452  */
 453 int BLI_str_rstrip_digits(char *str) ATTR_NONNULL();
 454
 455 /**
 456  * Return index of a string in a string array.
 457  *
 458  * \param str: The string to find.
 459  * \param str_array: Array of strings.
 460  * \param str_array_len: The length of the array, or -1 for a NULL-terminated array.
 461  * \return The index of str in str_array or -1.
 462  */
 463 int BLI_str_index_in_array_n(const char *__restrict str,
 464                              const char **__restrict str_array,
 465                              int str_array_len) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL(1);
 466 /**
 467  * Return index of a string in a string array.
 468  *
 469  * \param str: The string to find.
 470  * \param str_array: Array of strings, (must be NULL-terminated).
 471  * \return The index of str in str_array or -1.
 472  */
 473 int BLI_str_index_in_array(const char *__restrict str,
 474                            const char **__restrict str_array) ATTR_WARN_UNUSED_RESULT
 475     ATTR_NONNULL(1, 2);
 476
 477 /**
 478  * Find if a string starts with another string.
 479  *
 480  * \param str: The string to search within.
 481  * \param start: The string we look for at the start.
 482  * \return If str starts with start.
 483  */
 484 bool BLI_str_startswith(const char *__restrict str,
 485                         const char *__restrict start) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL(1, 2);
 486 /**
 487  * Find if a string ends with another string.
 488  *
 489  * \param str: The string to search within.
 490  * \param end: The string we look for at the end.
 491  * \return If `str` ends with `end`.
 492  */
 493 bool BLI_str_endswith(const char *__restrict str, const char *__restrict end) ATTR_NONNULL(1, 2);
 494 bool BLI_strn_endswith(const char *__restrict str, const char *__restrict end, size_t str_len)
 495     ATTR_NONNULL(1, 2);
 496
 497 /**
 498  * Find the first char matching one of the chars in \a delim, from left.
 499  *
 500  * \param str: The string to search within.
 501  * \param delim: The set of delimiters to search for, as unicode values.
 502  * \param sep: Return value, set to the first delimiter found (or NULL if none found).
 503  * \param suf: Return value, set to next char after the first delimiter found
 504  * (or NULL if none found).
 505  * \return The length of the prefix (i.e. *sep - str).
 506  */
 507 size_t BLI_str_partition(const char *str, const char delim[], const char **sep, const char **suf)
 508     ATTR_NONNULL(1, 2, 3, 4);
 509 /**
 510  * Find the first char matching one of the chars in \a delim, from right.
 511  *
 512  * \param str: The string to search within.
 513  * \param delim: The set of delimiters to search for, as unicode values.
 514  * \param sep: Return value, set to the first delimiter found (or NULL if none found).
 515  * \param suf: Return value, set to next char after the first delimiter found
 516  * (or NULL if none found).
 517  * \return The length of the prefix (i.e. *sep - str).
 518  */
 519 size_t BLI_str_rpartition(const char *str, const char delim[], const char **sep, const char **suf)
 520     ATTR_NONNULL(1, 2, 3, 4);
 521 /**
 522  * Find the first char matching one of the chars in \a delim, either from left or right.
 523  *
 524  * \param str: The string to search within.
 525  * \param end: If non-NULL, the right delimiter of the string.
 526  * \param delim: The set of delimiters to search for, as unicode values.
 527  * \param sep: Return value, set to the first delimiter found (or NULL if none found).
 528  * \param suf: Return value, set to next char after the first delimiter found
 529  * (or NULL if none found).
 530  * \param from_right: If %true, search from the right of \a str, else, search from its left.
 531  * \return The length of the prefix (i.e. *sep - str).
 532  */
 533 size_t BLI_str_partition_ex(const char *str,
 534                             const char *end,
 535                             const char delim[],
 536                             const char **sep,
 537                             const char **suf,
 538                             bool from_right) ATTR_NONNULL(1, 3, 4, 5);
 539
 540 int BLI_string_max_possible_word_count(int str_len) ATTR_WARN_UNUSED_RESULT;
 541 bool BLI_string_has_word_prefix(const char *haystack,
 542                                 const char *needle,
 543                                 size_t needle_len) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL(1, 2);
 544 bool BLI_string_all_words_matched(const char *name,
 545                                   const char *str,
 546                                   int (*words)[2],
 547                                   int words_len) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL(1, 2, 3);
 548
 549 /**
 550  * Find the ranges needed to split \a str into its individual words.
 551  *
 552  * \param str: The string to search for words.
 553  * \param str_maxlen: Size of the string to search (ignored when larger than `strlen(str)`).
 554  * \param delim: Character to use as a delimiter.
 555  * \param r_words: Info about the words found. Set to [index, len] pairs.
 556  * \param words_max: Max number of words to find
 557  * \return The number of words found in \a str
 558  */
 559 int BLI_string_find_split_words(const char *str,
 560                                 size_t str_maxlen,
 561                                 char delim,
 562                                 int r_words[][2],
 563                                 int words_max) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL(1, 4);
 564
 565 /**
 566  * A version of `STR_ELEM(..)` that treats `haystack` as multiple elements split by `delim`.
 567  * Return true when `needle` is found in `haystack`.
 568  *
 569  * \param haystack: The string to search in.
 570  * \param delim: The delimiter which divides haystack.
 571  * \param needle: The string to search for
 572  * (must not contain `delim` or the result will never be true).
 573  *
 574  * The following guarantees are made:
 575  * - Only an exact match returns true, requiring the strings length and case be match.
 576  * - Successive delimiters are supported.
 577  * - An empty needle will match against:
 578  *   - A blank string.
 579  *   - Delimiters at the beginning or end of the string
 580  *   - Two successive delimiters.
 581  */
 582 bool BLI_string_elem_split_by_delim(const char *haystack,
 583                                     const char delim,
 584                                     const char *needle) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL(1, 3);
 585
 586 /* -------------------------------------------------------------------- */
 587 /** \name String Copy/Format Macros
 588  * Avoid repeating destination with `sizeof(..)`.
 589  * \note `ARRAY_SIZE` allows pointers on some platforms.
 590  * \{ */
 591
 592 #ifndef __cplusplus
 593 #  define STRNCPY(dst, src) BLI_strncpy(dst, src, ARRAY_SIZE(dst))
 594 #endif
 595
 596 #define STRNCPY_RLEN(dst, src) BLI_strncpy_rlen(dst, src, ARRAY_SIZE(dst))
 597 #define SNPRINTF(dst, format, ...) BLI_snprintf(dst, ARRAY_SIZE(dst), format, __VA_ARGS__)
 598 #define SNPRINTF_RLEN(dst, format, ...) \
 599   BLI_snprintf_rlen(dst, ARRAY_SIZE(dst), format, __VA_ARGS__)
 600 #define VSNPRINTF(dst, format, args) BLI_vsnprintf(dst, ARRAY_SIZE(dst), format, args)
 601 #define VSNPRINTF_RLEN(dst, format, args) BLI_vsnprintf_rlen(dst, ARRAY_SIZE(dst), format, args)
 602 #define STR_CONCAT(dst, len, suffix) \
 603   len += BLI_strncpy_rlen(dst + len, suffix, ARRAY_SIZE(dst) - len)
 604 #define STR_CONCATF(dst, len, format, ...) \
 605   len += BLI_snprintf_rlen(dst + len, ARRAY_SIZE(dst) - len, format, __VA_ARGS__)
 606
 607 /** \} */
 608
 609 /* -------------------------------------------------------------------- */
 610 /** \name Equal to Any Element (STR_ELEM) Macro
 611  *
 612  * Follows #ELEM macro convention.
 613  * \{ */
 614
 615 /* Manual line breaks for readability. */
 616 /* clang-format off */
 617 /* STR_ELEM#(v, ...): is the first arg equal any others? */
 618 /* Internal helpers. */
 619 #define _VA_STR_ELEM2(v, a) (strcmp(v, a) == 0)
 620 #define _VA_STR_ELEM3(v, a, b) \
 621   (_VA_STR_ELEM2(v, a) || (_VA_STR_ELEM2(v, b)))
 622 #define _VA_STR_ELEM4(v, a, b, c) \
 623   (_VA_STR_ELEM3(v, a, b) || (_VA_STR_ELEM2(v, c)))
 624 #define _VA_STR_ELEM5(v, a, b, c, d) \
 625   (_VA_STR_ELEM4(v, a, b, c) || (_VA_STR_ELEM2(v, d)))
 626 #define _VA_STR_ELEM6(v, a, b, c, d, e) \
 627   (_VA_STR_ELEM5(v, a, b, c, d) || (_VA_STR_ELEM2(v, e)))
 628 #define _VA_STR_ELEM7(v, a, b, c, d, e, f) \
 629   (_VA_STR_ELEM6(v, a, b, c, d, e) || (_VA_STR_ELEM2(v, f)))
 630 #define _VA_STR_ELEM8(v, a, b, c, d, e, f, g) \
 631   (_VA_STR_ELEM7(v, a, b, c, d, e, f) || (_VA_STR_ELEM2(v, g)))
 632 #define _VA_STR_ELEM9(v, a, b, c, d, e, f, g, h) \
 633   (_VA_STR_ELEM8(v, a, b, c, d, e, f, g) || (_VA_STR_ELEM2(v, h)))
 634 #define _VA_STR_ELEM10(v, a, b, c, d, e, f, g, h, i) \
 635   (_VA_STR_ELEM9(v, a, b, c, d, e, f, g, h) || (_VA_STR_ELEM2(v, i)))
 636 #define _VA_STR_ELEM11(v, a, b, c, d, e, f, g, h, i, j) \
 637   (_VA_STR_ELEM10(v, a, b, c, d, e, f, g, h, i) || (_VA_STR_ELEM2(v, j)))
 638 #define _VA_STR_ELEM12(v, a, b, c, d, e, f, g, h, i, j, k) \
 639   (_VA_STR_ELEM11(v, a, b, c, d, e, f, g, h, i, j) || (_VA_STR_ELEM2(v, k)))
 640 #define _VA_STR_ELEM13(v, a, b, c, d, e, f, g, h, i, j, k, l) \
 641   (_VA_STR_ELEM12(v, a, b, c, d, e, f, g, h, i, j, k) || (_VA_STR_ELEM2(v, l)))
 642 #define _VA_STR_ELEM14(v, a, b, c, d, e, f, g, h, i, j, k, l, m) \
 643   (_VA_STR_ELEM13(v, a, b, c, d, e, f, g, h, i, j, k, l) || (_VA_STR_ELEM2(v, m)))
 644 #define _VA_STR_ELEM15(v, a, b, c, d, e, f, g, h, i, j, k, l, m, n) \
 645   (_VA_STR_ELEM14(v, a, b, c, d, e, f, g, h, i, j, k, l, m) || (_VA_STR_ELEM2(v, n)))
 646 #define _VA_STR_ELEM16(v, a, b, c, d, e, f, g, h, i, j, k, l, m, n, o) \
 647   (_VA_STR_ELEM15(v, a, b, c, d, e, f, g, h, i, j, k, l, m, n) || (_VA_STR_ELEM2(v, o)))
 648 #define _VA_STR_ELEM17(v, a, b, c, d, e, f, g, h, i, j, k, l, m, n, o, p) \
 649   (_VA_STR_ELEM16(v, a, b, c, d, e, f, g, h, i, j, k, l, m, n, o) || (_VA_STR_ELEM2(v, p)))
 650 /* clang-format on */
 651
 652 /* reusable STR_ELEM macro */
 653 #define STR_ELEM(...) VA_NARGS_CALL_OVERLOAD(_VA_STR_ELEM, __VA_ARGS__)
 654
 655 /** \} */
 656
 657 /* -------------------------------------------------------------------- */
 658 /** \name String Debugging
 659  * \{ */
 660 #ifdef WITH_STRSIZE_DEBUG
 661 #  define BLI_string_debug_size(str, str_maxncpy) memset(str, 0xff, sizeof(*(str)) * str_maxncpy)
 662 /**
 663  * Fill `str` with a non-nil value after the trailing nil character,
 664  * use to ensure buffer sizes passed to string functions are correct.
 665  */
 666 void BLI_string_debug_size_after_nil(char *str, size_t str_maxncpy);
 667 #else
 668 #  define BLI_string_debug_size(str, str_maxncpy) \
 669     if (0) { \
 670       (void)str, (void)str_maxncpy; \
 671     } \
 672     ((void)0)
 673 #  define BLI_string_debug_size_after_nil(str, str_maxncpy) BLI_string_debug_size(str, str_maxncpy)
 674 #endif /* !WITH_STRSIZE_DEBUG */
 675
 676 /** \} */
 677 #ifdef __cplusplus
 678 }
 679
 680 /**
 681  * Copy source string str into the destination dst of a size known at a compile time.
 682  * Ensures that the destination is not overflown, and that the destination is always
 683  * null-terminated.
 684  *
 685  * Returns the dst.
 686  */
 687 template<size_t N> inline char *STRNCPY(char (&dst)[N], const char *src)
 688 {
 689   return BLI_strncpy(dst, src, N);
 690 }
 691
 692 #endif /* __cplusplus */