BLI_string.h

Go to the documentation of this file.

/* SPDX-FileCopyrightText: 2001-2002 NaN Holding BV. All rights reserved.
 *
 * SPDX-License-Identifier: GPL-2.0-or-later */
 
#pragma once

 
#include <inttypes.h>
#include <stdarg.h>
 
#include "BLI_compiler_attrs.h"
#include "BLI_utildefines.h"
 
#ifdef __cplusplus
#  include <string>
#endif
 
/* Buffer size of maximum `uint64` plus commas and terminator. */
#define BLI_STR_FORMAT_UINT64_GROUPED_SIZE 27
 
/* Buffer size of maximum `int64` plus commas and terminator. */
#define BLI_STR_FORMAT_INT64_GROUPED_SIZE 28
 
/* Buffer size of maximum `int32` with commas and terminator. */
#define BLI_STR_FORMAT_INT32_GROUPED_SIZE 15
 
/* Buffer size of maximum `int64` formatted as byte size (with GiB for example). */
#define BLI_STR_FORMAT_INT64_BYTE_UNIT_SIZE 15
 
/* Buffer size of maximum `int64` formatted as byte size, minimum length (".1G" for example). */
#define BLI_STR_FORMAT_INT64_BYTE_UNIT_COMPACT_SIZE 5
 
/* Buffer size of maximum `int32` formatted as compact decimal size ("15.6M" for example). */
#define BLI_STR_FORMAT_INT32_DECIMAL_UNIT_SIZE 7
 
/* Buffer size of maximum `int32` formatted as very short decimal size ("15B" for example). */
#define BLI_STR_FORMAT_INT32_INTEGER_UNIT_SIZE 5

char *BLI_strdupn(const char *str, size_t len) ATTR_MALLOC ATTR_WARN_UNUSED_RESULT ATTR_NONNULL(1);

char *BLI_strdup(const char *str) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL(1) ATTR_MALLOC;

char *BLI_strdup_null(const char *str) ATTR_WARN_UNUSED_RESULT ATTR_MALLOC;

char *BLI_strdupcat(const char *__restrict str1,
                    const char *__restrict str2) ATTR_WARN_UNUSED_RESULT
    ATTR_NONNULL(1, 2) ATTR_MALLOC;

char *BLI_strncpy(char *__restrict dst, const char *__restrict src, size_t dst_maxncpy)
    ATTR_NONNULL(1, 2);

char *BLI_strncpy_ensure_pad(char *__restrict dst,
                             const char *__restrict src,
                             char pad,
                             size_t dst_maxncpy) ATTR_NONNULL(1, 2);

size_t BLI_strncpy_rlen(char *__restrict dst,
                        const char *__restrict src,
                        size_t dst_maxncpy) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL(1, 2);
 
char *BLI_strncat(char *__restrict dst, const char *__restrict src, size_t dst_maxncpy)
    ATTR_NONNULL(1, 2);

const char *BLI_strchr_or_end(const char *str,
                              char ch) ATTR_WARN_UNUSED_RESULT ATTR_RETURNS_NONNULL
    ATTR_NONNULL(1);

bool BLI_str_quoted_substr_range(const char *__restrict str,
                                 const char *__restrict prefix,
                                 int *__restrict r_start,
                                 int *__restrict r_end) ATTR_WARN_UNUSED_RESULT
    ATTR_NONNULL(1, 2, 3, 4);
#if 0 /* UNUSED */
char *BLI_str_quoted_substrN(const char *__restrict str,
                             const char *__restrict prefix) ATTR_WARN_UNUSED_RESULT
    ATTR_NONNULL(1, 2) ATTR_MALLOC;
#endif
bool BLI_str_quoted_substr(const char *__restrict str,
                           const char *__restrict prefix,
                           char *result,
                           size_t result_maxncpy);

size_t BLI_snprintf(char *__restrict dst, size_t dst_maxncpy, const char *__restrict format, ...)
    ATTR_NONNULL(1, 3) ATTR_PRINTF_FORMAT(3, 4);
size_t BLI_snprintf_rlen(char *__restrict dst,
                         size_t dst_maxncpy,
                         const char *__restrict format,
                         ...) ATTR_NONNULL(1, 3) ATTR_PRINTF_FORMAT(3, 4);

size_t BLI_vsnprintf(char *__restrict dst,
                     size_t dst_maxncpy,
                     const char *__restrict format,
                     va_list arg) ATTR_PRINTF_FORMAT(3, 0);
size_t BLI_vsnprintf_rlen(char *__restrict dst,
                          size_t dst_maxncpy,
                          const char *__restrict format,
                          va_list arg) ATTR_PRINTF_FORMAT(3, 0);
 
char *BLI_sprintfN_with_buffer(char *fixed_buf,
                               size_t fixed_buf_size,
                               size_t *result_len,
                               const char *__restrict format,
                               ...) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL(1, 3, 4)
    ATTR_PRINTF_FORMAT(4, 5);
char *BLI_vsprintfN_with_buffer(char *fixed_buf,
                                size_t fixed_buf_size,
                                size_t *result_len,
                                const char *__restrict format,
                                va_list args) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL(1, 3, 4)
    ATTR_PRINTF_FORMAT(4, 0);

char *BLI_sprintfN(const char *__restrict format, ...) ATTR_WARN_UNUSED_RESULT
    ATTR_NONNULL(1) ATTR_MALLOC ATTR_PRINTF_FORMAT(1, 2);
char *BLI_vsprintfN(const char *__restrict format, va_list args) ATTR_NONNULL(1, 2) ATTR_MALLOC
    ATTR_PRINTF_FORMAT(1, 0);

size_t BLI_str_escape(char *__restrict dst, const char *__restrict src, size_t dst_maxncpy)
    ATTR_NONNULL(1, 2);
 
#ifdef __cplusplus
std::string BLI_str_escape(const char *str);
#endif

size_t BLI_str_unescape_ex(char *__restrict dst,
                           const char *__restrict src,
                           size_t src_maxncpy,
                           /* Additional arguments. */
                           size_t dst_maxncpy,
                           bool *r_is_complete) ATTR_NONNULL(1, 2, 5);
size_t BLI_str_unescape(char *__restrict dst, const char *__restrict src, size_t src_maxncpy)
    ATTR_NONNULL(1, 2);

const char *BLI_str_escape_find_quote(const char *str) ATTR_NONNULL(1);

size_t BLI_str_format_int_grouped(char dst[BLI_STR_FORMAT_INT32_GROUPED_SIZE], int num)
    ATTR_NONNULL(1);
size_t BLI_str_format_uint64_grouped(char dst[BLI_STR_FORMAT_UINT64_GROUPED_SIZE], uint64_t num)
    ATTR_NONNULL(1);
size_t BLI_str_format_int64_grouped(char dst[BLI_STR_FORMAT_INT64_GROUPED_SIZE], int64_t num)
    ATTR_NONNULL(1);
void BLI_str_format_byte_unit(char dst[BLI_STR_FORMAT_INT64_BYTE_UNIT_SIZE],
                              long long int bytes,
                              bool base_10) ATTR_NONNULL(1);

void BLI_str_format_byte_unit_compact(char dst[BLI_STR_FORMAT_INT64_BYTE_UNIT_COMPACT_SIZE],
                                      long long int bytes,
                                      bool base_10) ATTR_NONNULL(1);

void BLI_str_format_decimal_unit(char dst[BLI_STR_FORMAT_INT32_DECIMAL_UNIT_SIZE],
                                 int number_to_format) ATTR_NONNULL(1);
void BLI_str_format_integer_unit(char dst[BLI_STR_FORMAT_INT32_INTEGER_UNIT_SIZE],
                                 int number_to_format) ATTR_NONNULL(1);
int BLI_strcaseeq(const char *a, const char *b) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL(1, 2);
char *BLI_strcasestr(const char *s, const char *find) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL(1, 2);
char *BLI_strncasestr(const char *s, const char *find, size_t len) ATTR_WARN_UNUSED_RESULT
    ATTR_NONNULL(1, 2);
int BLI_strcasecmp(const char *s1, const char *s2) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL(1, 2);
int BLI_strncasecmp(const char *s1, const char *s2, size_t len) ATTR_WARN_UNUSED_RESULT
    ATTR_NONNULL(1, 2);
int BLI_strcasecmp_natural(const char *s1, const char *s2) ATTR_WARN_UNUSED_RESULT
    ATTR_NONNULL(1, 2);
int BLI_strcmp_ignore_pad(const char *str1, const char *str2, char pad) ATTR_WARN_UNUSED_RESULT
    ATTR_NONNULL(1, 2);

size_t BLI_strnlen(const char *str, size_t maxlen) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL(1);

 
void BLI_str_tolower_ascii(char *str, size_t len) ATTR_NONNULL(1);
void BLI_str_toupper_ascii(char *str, size_t len) ATTR_NONNULL(1);
 
char BLI_tolower_ascii(const char c) ATTR_WARN_UNUSED_RESULT;
char BLI_toupper_ascii(const char c) ATTR_WARN_UNUSED_RESULT;

void BLI_str_rstrip(char *str) ATTR_NONNULL(1);
int BLI_str_rstrip_float_zero(char *str, char pad) ATTR_NONNULL(1);

int BLI_str_rstrip_digits(char *str) ATTR_NONNULL();

int BLI_str_index_in_array_n(const char *__restrict str,
                             const char **__restrict str_array,
                             int str_array_len) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL(1);
int BLI_str_index_in_array(const char *__restrict str,
                           const char **__restrict str_array) ATTR_WARN_UNUSED_RESULT
    ATTR_NONNULL(1, 2);

bool BLI_str_startswith(const char *__restrict str,
                        const char *__restrict start) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL(1, 2);
bool BLI_str_endswith(const char *__restrict str, const char *__restrict end) ATTR_NONNULL(1, 2);
bool BLI_strn_endswith(const char *__restrict str, const char *__restrict end, size_t str_len)
    ATTR_NONNULL(1, 2);

size_t BLI_str_partition(const char *str, const char delim[], const char **sep, const char **suf)
    ATTR_NONNULL(1, 2, 3, 4);
size_t BLI_str_rpartition(const char *str, const char delim[], const char **sep, const char **suf)
    ATTR_NONNULL(1, 2, 3, 4);
size_t BLI_str_partition_ex(const char *str,
                            const char *end,
                            const char delim[],
                            const char **sep,
                            const char **suf,
                            bool from_right) ATTR_NONNULL(1, 3, 4, 5);
 
int BLI_string_max_possible_word_count(int str_len) ATTR_WARN_UNUSED_RESULT;
bool BLI_string_has_word_prefix(const char *haystack,
                                const char *needle,
                                size_t needle_len) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL(1, 2);
bool BLI_string_all_words_matched(const char *name,
                                  const char *str,
                                  int (*words)[2],
                                  int words_len) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL(1, 2, 3);

int BLI_string_find_split_words(const char *str,
                                size_t str_maxlen,
                                char delim,
                                int r_words[][2],
                                int words_max) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL(1, 4);

bool BLI_string_elem_split_by_delim(const char *haystack,
                                    const char delim,
                                    const char *needle) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL(1, 3);
 
/* -------------------------------------------------------------------- */
 
#define STRNCPY_RLEN(dst, src) BLI_strncpy_rlen(dst, src, ARRAY_SIZE(dst))
#define SNPRINTF(dst, format, ...) BLI_snprintf(dst, ARRAY_SIZE(dst), format, __VA_ARGS__)
#define SNPRINTF_RLEN(dst, format, ...) \
  BLI_snprintf_rlen(dst, ARRAY_SIZE(dst), format, __VA_ARGS__)
#define VSNPRINTF(dst, format, args) BLI_vsnprintf(dst, ARRAY_SIZE(dst), format, args)
#define VSNPRINTF_RLEN(dst, format, args) BLI_vsnprintf_rlen(dst, ARRAY_SIZE(dst), format, args)
#define STR_CONCAT(dst, len, suffix) \
  len += BLI_strncpy_rlen(dst + len, suffix, ARRAY_SIZE(dst) - len)
#define STR_CONCATF(dst, len, format, ...) \
  len += BLI_snprintf_rlen(dst + len, ARRAY_SIZE(dst) - len, format, __VA_ARGS__)
#define STRNLEN(str) BLI_strnlen(str, ARRAY_SIZE(str))

 
/* -------------------------------------------------------------------- */
 
/* Manual line breaks for readability. */
/* clang-format off */
/* STR_ELEM#(v, ...): is the first arg equal any others? */
/* Internal helpers. */
#define _VA_STR_ELEM2(v, a) (strcmp(v, a) == 0)
#define _VA_STR_ELEM3(v, a, b) \
  (_VA_STR_ELEM2(v, a) || (_VA_STR_ELEM2(v, b)))
#define _VA_STR_ELEM4(v, a, b, c) \
  (_VA_STR_ELEM3(v, a, b) || (_VA_STR_ELEM2(v, c)))
#define _VA_STR_ELEM5(v, a, b, c, d) \
  (_VA_STR_ELEM4(v, a, b, c) || (_VA_STR_ELEM2(v, d)))
#define _VA_STR_ELEM6(v, a, b, c, d, e) \
  (_VA_STR_ELEM5(v, a, b, c, d) || (_VA_STR_ELEM2(v, e)))
#define _VA_STR_ELEM7(v, a, b, c, d, e, f) \
  (_VA_STR_ELEM6(v, a, b, c, d, e) || (_VA_STR_ELEM2(v, f)))
#define _VA_STR_ELEM8(v, a, b, c, d, e, f, g) \
  (_VA_STR_ELEM7(v, a, b, c, d, e, f) || (_VA_STR_ELEM2(v, g)))
#define _VA_STR_ELEM9(v, a, b, c, d, e, f, g, h) \
  (_VA_STR_ELEM8(v, a, b, c, d, e, f, g) || (_VA_STR_ELEM2(v, h)))
#define _VA_STR_ELEM10(v, a, b, c, d, e, f, g, h, i) \
  (_VA_STR_ELEM9(v, a, b, c, d, e, f, g, h) || (_VA_STR_ELEM2(v, i)))
#define _VA_STR_ELEM11(v, a, b, c, d, e, f, g, h, i, j) \
  (_VA_STR_ELEM10(v, a, b, c, d, e, f, g, h, i) || (_VA_STR_ELEM2(v, j)))
#define _VA_STR_ELEM12(v, a, b, c, d, e, f, g, h, i, j, k) \
  (_VA_STR_ELEM11(v, a, b, c, d, e, f, g, h, i, j) || (_VA_STR_ELEM2(v, k)))
#define _VA_STR_ELEM13(v, a, b, c, d, e, f, g, h, i, j, k, l) \
  (_VA_STR_ELEM12(v, a, b, c, d, e, f, g, h, i, j, k) || (_VA_STR_ELEM2(v, l)))
#define _VA_STR_ELEM14(v, a, b, c, d, e, f, g, h, i, j, k, l, m) \
  (_VA_STR_ELEM13(v, a, b, c, d, e, f, g, h, i, j, k, l) || (_VA_STR_ELEM2(v, m)))
#define _VA_STR_ELEM15(v, a, b, c, d, e, f, g, h, i, j, k, l, m, n) \
  (_VA_STR_ELEM14(v, a, b, c, d, e, f, g, h, i, j, k, l, m) || (_VA_STR_ELEM2(v, n)))
#define _VA_STR_ELEM16(v, a, b, c, d, e, f, g, h, i, j, k, l, m, n, o) \
  (_VA_STR_ELEM15(v, a, b, c, d, e, f, g, h, i, j, k, l, m, n) || (_VA_STR_ELEM2(v, o)))
#define _VA_STR_ELEM17(v, a, b, c, d, e, f, g, h, i, j, k, l, m, n, o, p) \
  (_VA_STR_ELEM16(v, a, b, c, d, e, f, g, h, i, j, k, l, m, n, o) || (_VA_STR_ELEM2(v, p)))
/* clang-format on */
 
/* reusable STR_ELEM macro */
#define STR_ELEM(...) VA_NARGS_CALL_OVERLOAD(_VA_STR_ELEM, __VA_ARGS__)

 
/* -------------------------------------------------------------------- */
#ifdef WITH_STRSIZE_DEBUG
#  define BLI_string_debug_size(str, str_maxncpy) memset(str, 0xff, sizeof(*(str)) * str_maxncpy)
void BLI_string_debug_size_after_nil(char *str, size_t str_maxncpy);
#else
#  define BLI_string_debug_size(str, str_maxncpy) \
    if (0) { \
      (void)str, (void)str_maxncpy; \
    } \
    ((void)0)
#  define BLI_string_debug_size_after_nil(str, str_maxncpy) BLI_string_debug_size(str, str_maxncpy)
#endif /* !WITH_STRSIZE_DEBUG */


template<size_t N> inline char *STRNCPY(char (&dst)[N], const char *src)
{
  return BLI_strncpy(dst, src, N);
}