src/basic/string-util.h

   1 /* SPDX-License-Identifier: LGPL-2.1-or-later */
   2 #pragma once
   3
   4 #include <string.h>
   5
   6 #include "alloc-util.h"
   7 #include "forward.h"
   8 #include "string-util-fundamental.h" /* IWYU pragma: export */
   9
  10 static inline char* strstr_ptr(const char *haystack, const char *needle) {
  11         if (!haystack || !needle)
  12                 return NULL;
  13         return strstr(haystack, needle);
  14 }
  15
  16 static inline char* strstrafter(const char *haystack, const char *needle) {
  17         char *p;
  18
  19         /* Returns NULL if not found, or pointer to first character after needle if found */
  20
  21         p = strstr_ptr(haystack, needle);
  22         if (!p)
  23                 return NULL;
  24
  25         return p + strlen(needle);
  26 }
  27
  28 static inline const char* strnull(const char *s) {
  29         return s ?: "(null)";
  30 }
  31
  32 static inline const char* strna(const char *s) {
  33         return s ?: "n/a";
  34 }
  35
  36 static inline const char* true_false(bool b) {
  37         return b ? "true" : "false";
  38 }
  39
  40 static inline const char* plus_minus(bool b) {
  41         return b ? "+" : "-";
  42 }
  43
  44 static inline const char* one_zero(bool b) {
  45         return b ? "1" : "0";
  46 }
  47
  48 static inline const char* enable_disable(bool b) {
  49         return b ? "enable" : "disable";
  50 }
  51
  52 static inline const char* enabled_disabled(bool b) {
  53         return b ? "enabled" : "disabled";
  54 }
  55
  56 /* This macro's return pointer will have the "const" qualifier set or unset the same way as the input
  57  * pointer. */
  58 #define empty_to_null(p)                                \
  59         ({                                              \
  60                 const char *_p = (p);                   \
  61                 (typeof(p)) (isempty(_p) ? NULL : _p);  \
  62         })
  63
  64 static inline const char* empty_to_na(const char *p) {
  65         return isempty(p) ? "n/a" : p;
  66 }
  67
  68 static inline const char* empty_to_dash(const char *str) {
  69         return isempty(str) ? "-" : str;
  70 }
  71
  72 static inline bool empty_or_dash(const char *str) {
  73         return !str ||
  74                 str[0] == 0 ||
  75                 (str[0] == '-' && str[1] == 0);
  76 }
  77
  78 static inline const char* empty_or_dash_to_null(const char *p) {
  79         return empty_or_dash(p) ? NULL : p;
  80 }
  81 #define empty_or_dash_to_null(p)                                \
  82         ({                                                      \
  83                 const char *_p = (p);                           \
  84                 (typeof(p)) (empty_or_dash(_p) ? NULL : _p);    \
  85         })
  86
  87 char* first_word(const char *s, const char *word) _pure_;
  88
  89 char* strextendn(char **x, const char *s, size_t l) _nonnull_if_nonzero_(2, 3);
  90
  91 #define strjoin(a, ...) strextend_with_separator_internal(NULL, NULL, a, __VA_ARGS__, NULL)
  92
  93 #define strjoina(a, ...)                                                \
  94         ({                                                              \
  95                 const char *_appendees_[] = { a, __VA_ARGS__ };         \
  96                 char *_d_, *_p_;                                        \
  97                 size_t _len_ = 0;                                       \
  98                 size_t _i_;                                             \
  99                 for (_i_ = 0; _i_ < ELEMENTSOF(_appendees_) && _appendees_[_i_]; _i_++) \
 100                         _len_ += strlen(_appendees_[_i_]);              \
 101                 _p_ = _d_ = newa(char, _len_ + 1);                      \
 102                 for (_i_ = 0; _i_ < ELEMENTSOF(_appendees_) && _appendees_[_i_]; _i_++) \
 103                         _p_ = stpcpy(_p_, _appendees_[_i_]);            \
 104                 *_p_ = 0;                                               \
 105                 _d_;                                                    \
 106         })
 107
 108 char* strstrip(char *s);
 109 char* delete_chars(char *s, const char *bad);
 110 char* delete_trailing_chars(char *s, const char *bad);
 111 char* truncate_nl_full(char *s, size_t *ret_len);
 112 static inline char* truncate_nl(char *s) {
 113         return truncate_nl_full(s, NULL);
 114 }
 115
 116 static inline char* skip_leading_chars(const char *s, const char *bad) {
 117         if (!s)
 118                 return NULL;
 119
 120         if (!bad)
 121                 bad = WHITESPACE;
 122
 123         return (char*) s + strspn(s, bad);
 124 }
 125
 126 char ascii_tolower(char x) _const_;
 127 char* ascii_strlower(char *s);
 128 char* ascii_strlower_n(char *s, size_t n);
 129
 130 char ascii_toupper(char x) _const_;
 131 char* ascii_strupper(char *s);
 132
 133 int ascii_strcasecmp_n(const char *a, const char *b, size_t n);
 134 int ascii_strcasecmp_nn(const char *a, size_t n, const char *b, size_t m);
 135
 136 bool chars_intersect(const char *a, const char *b) _pure_;
 137
 138 static inline bool _pure_ in_charset(const char *s, const char *charset) {
 139         assert(s);
 140         assert(charset);
 141         return s[strspn(s, charset)] == '\0';
 142 }
 143
 144 static inline bool char_is_cc(char p) {
 145         /* char is unsigned on some architectures, e.g. aarch64. So, compiler may warn the condition
 146          * p >= 0 is always true. See #19543. Hence, let's cast to unsigned before the comparison. Note
 147          * that the cast in the right hand side is redundant, as according to the C standard, compilers
 148          * automatically cast a signed value to unsigned when comparing with an unsigned variable. Just
 149          * for safety and readability. */
 150         return (uint8_t) p < (uint8_t) ' ' || p == 127;
 151 }
 152 bool string_has_cc(const char *p, const char *ok) _pure_;
 153
 154 char* ellipsize_mem(const char *s, size_t old_length_bytes, size_t new_length_columns, unsigned percent);
 155 static inline char* ellipsize(const char *s, size_t length, unsigned percent) {
 156         return ellipsize_mem(s, strlen(s), length, percent);
 157 }
 158
 159 char* cellescape(char *buf, size_t len, const char *s);
 160
 161 /* This limit is arbitrary, enough to give some idea what the string contains */
 162 #define CELLESCAPE_DEFAULT_LENGTH 64
 163
 164 char* strshorten(char *s, size_t l);
 165
 166 int strgrowpad0(char **s, size_t l);
 167
 168 char* strreplace(const char *text, const char *old_string, const char *new_string);
 169
 170 char* strip_tab_ansi(char **ibuf, size_t *_isz, size_t highlight[2]);
 171
 172 char* strextend_with_separator_internal(char **x, const char *separator, ...) _sentinel_;
 173 #define strextend_with_separator(x, separator, ...) strextend_with_separator_internal(x, separator, __VA_ARGS__, NULL)
 174 #define strextend(x, ...) strextend_with_separator_internal(x, NULL, __VA_ARGS__, NULL)
 175
 176 int strextendf_with_separator(char **x, const char *separator, const char *format, ...) _printf_(3,4);
 177 #define strextendf(x, ...) strextendf_with_separator(x, NULL, __VA_ARGS__)
 178
 179 #define strprepend_with_separator(x, separator, ...)                            \
 180         ({                                                                      \
 181                 char **_p_ = ASSERT_PTR(x), *_s_;                               \
 182                 _s_ = strextend_with_separator_internal(NULL, (separator), __VA_ARGS__, empty_to_null(*_p_), NULL); \
 183                 if (_s_) {                                                      \
 184                         free(*_p_);                                             \
 185                         *_p_ = _s_;                                             \
 186                 }                                                               \
 187                 _s_;                                                            \
 188         })
 189 #define strprepend(x, ...) strprepend_with_separator(x, NULL, __VA_ARGS__)
 190
 191 char* strrep(const char *s, unsigned n);
 192
 193 #define strrepa(s, n)                                                   \
 194         ({                                                              \
 195                 const char *_sss_ = (s);                                \
 196                 size_t _nnn_ = (n), _len_ = strlen(_sss_);              \
 197                 assert_se(MUL_ASSIGN_SAFE(&_len_, _nnn_));              \
 198                 char *_d_, *_p_;                                        \
 199                 _p_ = _d_ = newa(char, _len_ + 1);                      \
 200                 for (size_t _i_ = 0; _i_ < _nnn_; _i_++)                \
 201                         _p_ = stpcpy(_p_, _sss_);                       \
 202                 *_p_ = 0;                                               \
 203                 _d_;                                                    \
 204         })
 205
 206 int split_pair(const char *s, const char *sep, char **ret_first, char **ret_second);
 207
 208 int free_and_strdup(char **p, const char *s);
 209 int free_and_strdup_warn(char **p, const char *s);
 210 int free_and_strndup(char **p, const char *s, size_t l) _nonnull_if_nonzero_(2, 3);
 211
 212 int strdup_to_full(char **ret, const char *src);
 213 static inline int strdup_to(char **ret, const char *src) {
 214         int r = strdup_to_full(ASSERT_PTR(ret), src);
 215         return r < 0 ? r : 0;  /* Suppress return value of 1. */
 216 }
 217
 218 bool string_is_safe(const char *p) _pure_;
 219 bool string_is_safe_ascii(const char *p) _pure_;
 220
 221 DISABLE_WARNING_STRINGOP_TRUNCATION;
 222 static inline void strncpy_exact(char *buf, const char *src, size_t buf_len) {
 223         strncpy(buf, src, buf_len);
 224 }
 225 REENABLE_WARNING;
 226
 227 /* Like startswith_no_case(), but operates on arbitrary memory blocks.
 228  * It works only for ASCII strings.
 229  */
 230 static inline void* memory_startswith_no_case(const void *p, size_t sz, const char *token) {
 231         assert(token);
 232
 233         size_t n = strlen(token);
 234         if (sz < n)
 235                 return NULL;
 236
 237         assert(p);
 238
 239         for (size_t i = 0; i < n; i++)
 240                 if (ascii_tolower(((char *)p)[i]) != ascii_tolower(token[i]))
 241                         return NULL;
 242
 243         return (uint8_t*) p + n;
 244 }
 245
 246 char* str_realloc(char *p);
 247 char* string_erase(char *x);
 248
 249 int string_truncate_lines(const char *s, size_t n_lines, char **ret);
 250 int string_extract_line(const char *s, size_t i, char **ret);
 251
 252 int string_contains_word_strv(const char *string, const char *separators, char * const *words, const char **ret_word);
 253 static inline int string_contains_word(const char *string, const char *separators, const char *word) {
 254         return string_contains_word_strv(string, separators, STRV_MAKE(word), NULL);
 255 }
 256
 257 bool streq_skip_trailing_chars(const char *s1, const char *s2, const char *ok);
 258
 259 char* string_replace_char(char *str, char old_char, char new_char);
 260
 261 typedef enum MakeCStringMode {
 262         MAKE_CSTRING_REFUSE_TRAILING_NUL,
 263         MAKE_CSTRING_ALLOW_TRAILING_NUL,
 264         MAKE_CSTRING_REQUIRE_TRAILING_NUL,
 265         _MAKE_CSTRING_MODE_MAX,
 266         _MAKE_CSTRING_MODE_INVALID = -1,
 267 } MakeCStringMode;
 268
 269 int make_cstring(const char *s, size_t n, MakeCStringMode mode, char **ret);
 270
 271 size_t strspn_from_end(const char *str, const char *accept) _pure_;
 272
 273 char* strdupspn(const char *a, const char *accept);
 274 char* strdupcspn(const char *a, const char *reject);
 275
 276 /* These are like strdupa()/strndupa(), but honour ALLOCA_MAX */
 277 #define strdupa_safe(s)                                                 \
 278         ({                                                              \
 279                 const char *_t = (s);                                   \
 280                 (char*) memdupa_suffix0(_t, strlen(_t));                \
 281         })
 282
 283 #define strndupa_safe(s, n)                                             \
 284         ({                                                              \
 285                 const char *_t = (s);                                   \
 286                 (char*) memdupa_suffix0(_t, strnlen(_t, n));            \
 287         })
 288
 289 char* find_line_startswith(const char *haystack, const char *needle);
 290 char* find_line(const char *haystack, const char *needle);
 291 char* find_line_after(const char *haystack, const char *needle);
 292
 293 bool version_is_valid(const char *s) _pure_;
 294 bool version_is_valid_versionspec(const char *s) _pure_;
 295
 296 ssize_t strlevenshtein(const char *x, const char *y);
 297
 298 char* strrstr(const char *haystack, const char *needle) _pure_;
 299
 300 size_t str_common_prefix(const char *a, const char *b) _pure_;