Asterisk - The Open Source Telephony Project  21.4.1
strings.h
Go to the documentation of this file.
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 1999 - 2006, Digium, Inc.
5  *
6  * Mark Spencer <markster@digium.com>
7  *
8  * See http://www.asterisk.org for more information about
9  * the Asterisk project. Please do not directly contact
10  * any of the maintainers of this project for assistance;
11  * the project provides a web site, mailing lists and IRC
12  * channels for your use.
13  *
14  * This program is free software, distributed under the terms of
15  * the GNU General Public License Version 2. See the LICENSE file
16  * at the top of the source tree.
17  */
18 
19 /*! \file
20  * \brief String manipulation functions
21  */
22 
23 #ifndef _ASTERISK_STRINGS_H
24 #define _ASTERISK_STRINGS_H
25 
26 /* #define DEBUG_OPAQUE */
27 
28 #include <ctype.h>
29 #include <limits.h>
30 
31 #include "asterisk/utils.h"
32 #include "asterisk/threadstorage.h"
33 #include "asterisk/astobj2.h"
34 
35 #if defined(DEBUG_OPAQUE)
36 #define __AST_STR_USED used2
37 #define __AST_STR_LEN len2
38 #define __AST_STR_STR str2
39 #define __AST_STR_TS ts2
40 #else
41 #define __AST_STR_USED used
42 #define __AST_STR_LEN len
43 #define __AST_STR_STR str
44 #define __AST_STR_TS ts
45 #endif
46 
47 /* You may see casts in this header that may seem useless but they ensure this file is C++ clean */
48 
49 #define AS_OR(a,b) (a && ast_str_strlen(a)) ? ast_str_buffer(a) : (b)
50 
51 #ifdef AST_DEVMODE
52 #define ast_strlen_zero(foo) _ast_strlen_zero(foo, __FILE__, __PRETTY_FUNCTION__, __LINE__)
53 static force_inline int _ast_strlen_zero(const char *s, const char *file, const char *function, int line)
54 {
55  if (!s || (*s == '\0')) {
56  return 1;
57  }
58  if (!strcmp(s, "(null)")) {
59  ast_log(__LOG_WARNING, file, line, function, "Possible programming error: \"(null)\" is not NULL!\n");
60  }
61  return 0;
62 }
63 
64 #else
65 static force_inline int attribute_pure ast_strlen_zero(const char *s)
66 {
67  return (!s || (*s == '\0'));
68 }
69 #endif
70 
71 #ifdef SENSE_OF_HUMOR
72 #define ast_strlen_real(a) (a) ? strlen(a) : 0
73 #define ast_strlen_imaginary(a) ast_random()
74 #endif
75 
76 /*!
77  * \brief returns the equivalent of logic or for strings:
78  * first one if not empty, otherwise second one.
79  */
80 #define S_OR(a, b) ({typeof(&((a)[0])) __x = (a); ast_strlen_zero(__x) ? (b) : __x;})
81 
82 /*!
83  * \brief returns the equivalent of logic or for strings, with an additional boolean check:
84  * second one if not empty and first one is true, otherwise third one.
85  * example: S_COR(usewidget, widget, "<no widget>")
86  */
87 #define S_COR(a, b, c) ({typeof(&((b)[0])) __x = (b); (a) && !ast_strlen_zero(__x) ? (__x) : (c);})
88 
89 /*!
90  \brief Checks whether a string begins with another.
91  \since 12.0.0
92  \param str String to check.
93  \param prefix Prefix to look for.
94  \retval 1 if \a str begins with \a prefix
95  \retval 0 otherwise.
96  */
97 static int force_inline attribute_pure ast_begins_with(const char *str, const char *prefix)
98 {
99  ast_assert(str != NULL);
100  ast_assert(prefix != NULL);
101  while (*str == *prefix && *prefix != '\0') {
102  ++str;
103  ++prefix;
104  }
105  return *prefix == '\0';
106 }
107 
108 /*!
109  \brief Checks whether a string ends with another.
110  \since 12.0.0
111  \param str String to check.
112  \param suffix Suffix to look for.
113  \retval 1 if \a str ends with \a suffix
114  \retval 0 otherwise.
115  */
116 static int force_inline attribute_pure ast_ends_with(const char *str, const char *suffix)
117 {
118  size_t str_len;
119  size_t suffix_len;
120 
121  ast_assert(str != NULL);
122  ast_assert(suffix != NULL);
123  str_len = strlen(str);
124  suffix_len = strlen(suffix);
125 
126  if (suffix_len > str_len) {
127  return 0;
128  }
129 
130  return strcmp(str + str_len - suffix_len, suffix) == 0;
131 }
132 
133 /*!
134  * \brief return Yes or No depending on the argument.
135  *
136  * Note that this macro is used my AMI, where a literal "Yes" and "No" are
137  * expected, and translations would cause problems.
138  *
139  * \param x Boolean value
140  * \retval "Yes" if x is true (non-zero)
141  * \retval "No" if x is false (zero)
142  */
143 #define AST_YESNO(x) ((x) ? "Yes" : "No")
144 
145 /*!
146  \brief Gets a pointer to the first non-whitespace character in a string.
147  \param str the input string
148  \return a pointer to the first non-whitespace character
149  */
150 AST_INLINE_API(
151 char * attribute_pure ast_skip_blanks(const char *str),
152 {
153  if (str) {
154  while (*str && ((unsigned char) *str) < 33) {
155  str++;
156  }
157  }
158 
159  return (char *) str;
160 }
161 )
162 
163 /*!
164  \brief Trims trailing whitespace characters from a string.
165  \param str the input string
166  \return a pointer to the modified string
167  */
168 AST_INLINE_API(
169 char *ast_trim_blanks(char *str),
170 {
171  char *work = str;
172 
173  if (work) {
174  work += strlen(work) - 1;
175  /* It's tempting to only want to erase after we exit this loop,
176  but since ast_trim_blanks *could* receive a constant string
177  (which we presumably wouldn't have to touch), we shouldn't
178  actually set anything unless we must, and it's easier just
179  to set each position to \0 than to keep track of a variable
180  for it */
181  while ((work >= str) && ((unsigned char) *work) < 33)
182  *(work--) = '\0';
183  }
184  return str;
185 }
186 )
187 
188 /*!
189  \brief Gets a pointer to first whitespace character in a string.
190  \param str the input string
191  \return a pointer to the first whitespace character
192  */
193 AST_INLINE_API(
194 char * attribute_pure ast_skip_nonblanks(const char *str),
195 {
196  if (str) {
197  while (*str && ((unsigned char) *str) > 32) {
198  str++;
199  }
200  }
201 
202  return (char *) str;
203 }
204 )
205 
206 /*!
207  \brief Strip leading/trailing whitespace from a string.
208  \param s The string to be stripped (will be modified).
209  \return The stripped string.
210 
211  This functions strips all leading and trailing whitespace
212  characters from the input string, and returns a pointer to
213  the resulting string. The string is modified in place.
214 */
215 AST_INLINE_API(
216 char *ast_strip(char *s),
217 {
218  if ((s = ast_skip_blanks(s))) {
219  ast_trim_blanks(s);
220  }
221  return s;
222 }
223 )
224 
225 /*!
226  \brief Strip leading/trailing whitespace and quotes from a string.
227  \param s The string to be stripped (will be modified).
228  \param beg_quotes The list of possible beginning quote characters.
229  \param end_quotes The list of matching ending quote characters.
230  \return The stripped string.
231 
232  This functions strips all leading and trailing whitespace
233  characters from the input string, and returns a pointer to
234  the resulting string. The string is modified in place.
235 
236  It can also remove beginning and ending quote (or quote-like)
237  characters, in matching pairs. If the first character of the
238  string matches any character in beg_quotes, and the last
239  character of the string is the matching character in
240  end_quotes, then they are removed from the string.
241 
242  Examples:
243  \code
244  ast_strip_quoted(buf, "\"", "\"");
245  ast_strip_quoted(buf, "'", "'");
246  ast_strip_quoted(buf, "[{(", "]})");
247  \endcode
248  */
249 char *ast_strip_quoted(char *s, const char *beg_quotes, const char *end_quotes);
250 
251 /*!
252  \brief Flags for ast_strsep
253  */
255  AST_STRSEP_STRIP = 0x01, /*!< Trim, then strip quotes. You may want to trim again */
256  AST_STRSEP_TRIM = 0x02, /*!< Trim leading and trailing whitespace */
257  AST_STRSEP_UNESCAPE = 0x04, /*!< Unescape '\' */
258  AST_STRSEP_ALL = 0x07, /*!< Trim, strip, unescape */
259 };
260 
261 /*!
262  \brief Act like strsep but ignore separators inside quotes.
263  \param s Pointer to address of the string to be processed.
264  Will be modified and can't be constant.
265  \param sep A single character delimiter.
266  \param flags Controls post-processing of the result.
267  AST_STRSEP_TRIM trims all leading and trailing whitespace from the result.
268  If the result containes only whitespace, it'll be passed through unchanged.
269  AST_STRSEP_STRIP does a trim then strips the outermost quotes. You may want
270  to trim again after the strip. Just OR both the TRIM and STRIP flags.
271  AST_STRSEP_UNESCAPE unescapes '\' sequences.
272  AST_STRSEP_ALL does all of the above processing.
273  \return The next token or NULL if done or if there are more than 8 levels of
274  nested quotes. If provided an empty string, will return the empty string.
275 
276  This function acts like strsep with three exceptions...
277  The separator is a single character instead of a string.
278  Separators inside quotes are treated literally instead of like separators.
279  You can elect to have leading and trailing whitespace and quotes
280  stripped from the result and have '\' sequences unescaped.
281 
282  Like strsep, ast_strsep maintains no internal state and you can call it
283  recursively using different separators on the same storage.
284 
285  Also like strsep, for consistent results, consecutive separators are not
286  collapsed so you may get an empty string as a valid result.
287 
288  Examples:
289  \code
290  char *mystr = ast_strdupa("abc=def,ghi='zzz=yyy,456',jkl");
291  char *token, *token2, *token3;
292 
293  while((token = ast_strsep(&mystr, ',', AST_STRSEP_STRIP))) {
294  // 1st token will be aaa=def
295  // 2nd token will be ghi='zzz=yyy,456'
296  while((token2 = ast_strsep(&token, '=', AST_STRSEP_STRIP))) {
297  // 1st token2 will be ghi
298  // 2nd token2 will be zzz=yyy,456
299  while((token3 = ast_strsep(&token2, ',', AST_STRSEP_STRIP))) {
300  // 1st token3 will be zzz=yyy
301  // 2nd token3 will be 456
302  // and so on
303  }
304  }
305  // 3rd token will be jkl
306  }
307 
308  \endcode
309  */
310 char *ast_strsep(char **s, const char sep, uint32_t flags);
311 
312 /*!
313  * \brief Like ast_strsep() except you can specify a specific quote character
314  *
315  \param s Pointer to address of the string to be processed.
316  Will be modified and can't be constant.
317  \param sep A single character delimiter.
318  \param quote The quote character
319  \param flags Controls post-processing of the result.
320  AST_STRSEP_TRIM trims all leading and trailing whitespace from the result.
321  AST_STRSEP_STRIP does a trim then strips the outermost quotes. You may want
322  to trim again after the strip. Just OR both the TRIM and STRIP flags.
323  AST_STRSEP_UNESCAPE unescapes '\' sequences.
324  AST_STRSEP_ALL does all of the above processing.
325  \return The next token or NULL if done or if there are more than 8 levels of
326  nested quotes. If provided an empty string, will return the empty string.
327  */
328 char *ast_strsep_quoted(char **s, const char sep, const char quote, uint32_t flags);
329 
330 /*!
331  \brief Strip backslash for "escaped" semicolons,
332  the string to be stripped (will be modified).
333  \return The stripped string.
334  */
335 char *ast_unescape_semicolon(char *s);
336 
337 /*!
338  \brief Convert some C escape sequences \verbatim (\b\f\n\r\t) \endverbatim into the
339  equivalent characters. The string to be converted (will be modified).
340  \return The converted string.
341  */
342 char *ast_unescape_c(char *s);
343 
344 /*!
345  * \brief Escape the 'to_escape' characters in the given string.
346  *
347  * \note The given output buffer will contain a truncated escaped
348  * version of the source string if the given buffer is not large
349  * enough.
350  *
351  * \param dest the escaped string
352  * \param s the source string to escape
353  * \param size The size of the destination buffer
354  * \param to_escape an array of characters to escape
355  *
356  * \return Pointer to the destination.
357  */
358 char *ast_escape(char *dest, const char *s, size_t size, const char *to_escape);
359 
360 /*!
361  * \brief Escape standard 'C' sequences in the given string.
362  *
363  * \note The given output buffer will contain a truncated escaped
364  * version of the source string if the given buffer is not large
365  * enough.
366  *
367  * \param dest the escaped string
368  * \param s the source string to escape
369  * \param size The size of the destination buffer
370  *
371  * \return Pointer to the escaped string.
372  */
373 char *ast_escape_c(char *dest, const char *s, size_t size);
374 
375 /*!
376  * \brief Escape the 'to_escape' characters in the given string.
377  *
378  * \note Caller is responsible for freeing the returned string
379  *
380  * \param s the source string to escape
381  * \param to_escape an array of characters to escape
382  *
383  * \return Pointer to the escaped string or NULL.
384  */
385 char *ast_escape_alloc(const char *s, const char *to_escape);
386 
387 /*!
388  * \brief Escape standard 'C' sequences in the given string.
389  *
390  * \note Caller is responsible for freeing the returned string
391  *
392  * \param s the source string to escape
393  *
394  * \return Pointer to the escaped string or NULL.
395  */
396 char *ast_escape_c_alloc(const char *s);
397 
398 /*!
399  \brief Size-limited null-terminating string copy.
400  \param dst The destination buffer.
401  \param src The source string
402  \param size The size of the destination buffer
403 
404  This is similar to \a strncpy, with two important differences:
405  - the destination buffer will \b always be null-terminated
406  - the destination buffer is not filled with zeros past the copied string length
407  These differences make it slightly more efficient, and safer to use since it will
408  not leave the destination buffer unterminated. There is no need to pass an artificially
409  reduced buffer size to this function (unlike \a strncpy), and the buffer does not need
410  to be initialized to zeroes prior to calling this function.
411 */
412 AST_INLINE_API(
413 void ast_copy_string(char *dst, const char *src, size_t size),
414 {
415  volatile size_t sz = size;
416  volatile char *sp = (char *)src;
417  while (*sp && sz) {
418  *dst++ = *sp++;
419  sz--;
420  }
421  if (__builtin_expect(!sz, 0))
422  dst--;
423  *dst = '\0';
424 }
425 )
426 
427 /*!
428  * \brief Check if there is an exact match for 'needle' between delimiters in 'haystack'.
429  *
430  * \note This will skip extra leading spaces between delimiters.
431  *
432  * \param needle The string to search for
433  * \param haystack The string searched in
434  * \param delim The haystack delimiter
435  *
436  * \retval true If an exact match for needle is in haystack.
437  * \retval false otherwise
438  */
439 int ast_in_delimited_string(const char *needle, const char *haystack, char delim);
440 
441 /*!
442  \brief Build a string in a buffer, designed to be called repeatedly
443 
444  \note This method is not recommended. New code should use ast_str_*() instead.
445 
446  This is a wrapper for snprintf, that properly handles the buffer pointer
447  and buffer space available.
448 
449  \param buffer current position in buffer to place string into (will be updated on return)
450  \param space remaining space in buffer (will be updated on return)
451  \param fmt printf-style format string
452  \retval 0 on success
453  \retval non-zero on failure.
454 */
455 int ast_build_string(char **buffer, size_t *space, const char *fmt, ...) __attribute__((format(printf, 3, 4)));
456 
457 /*!
458  \brief Build a string in a buffer, designed to be called repeatedly
459 
460  This is a wrapper for snprintf, that properly handles the buffer pointer
461  and buffer space available.
462 
463  \retval zero on success.
464  \retval non-zero on failure.
465  \param buffer current position in buffer to place string into (will be updated on return)
466  \param space remaining space in buffer (will be updated on return)
467  \param fmt printf-style format string
468  \param ap varargs list of arguments for format
469 */
470 int ast_build_string_va(char **buffer, size_t *space, const char *fmt, va_list ap) __attribute__((format(printf, 3, 0)));
471 
472 /*!
473  * \brief Make sure something is true.
474  * Determine if a string containing a boolean value is "true".
475  * This function checks to see whether a string passed to it is an indication of an "true" value.
476  * It checks to see if the string is "yes", "true", "y", "t", "on" or "1".
477  *
478  * \retval -1 if "true".
479  * \retval 0 otherwise, like NULL pointer.
480  */
481 int attribute_pure ast_true(const char *val);
482 
483 /*!
484  * \brief Make sure something is false.
485  * Determine if a string containing a boolean value is "false".
486  * This function checks to see whether a string passed to it is an indication of an "false" value.
487  * It checks to see if the string is "no", "false", "n", "f", "off" or "0".
488  *
489  * \retval -1 if "true".
490  * \retval 0 otherwise, like NUL pointer.
491  */
492 int attribute_pure ast_false(const char *val);
493 
494 /*!
495  * \brief Join an array of strings into a single string.
496  * \param s the resulting string buffer
497  * \param len the length of the result buffer, s
498  * \param w an array of strings to join.
499  * \param size the number of elements to join
500  * \param delim delimiter between elements
501  *
502  * This function will join all of the strings in the array 'w' into a single
503  * string. It will also place 'delim' in the result buffer in between each
504  * string from 'w'.
505  * \since 12
506 */
507 void ast_join_delim(char *s, size_t len, const char * const w[],
508  unsigned int size, char delim);
509 
510 /*!
511  * \brief Join an array of strings into a single string.
512  * \param s the resulting string buffer
513  * \param len the length of the result buffer, s
514  * \param w an array of strings to join.
515  *
516  * This function will join all of the strings in the array 'w' into a single
517  * string. It will also place a space in the result buffer in between each
518  * string from 'w'.
519 */
520 #define ast_join(s, len, w) ast_join_delim(s, len, w, -1, ' ')
521 
522 /*!
523  * \brief Attempts to convert the given string to camel case using
524  * the specified delimiter.
525  *
526  * note - returned string needs to be freed
527  *
528  * \param s the string to convert
529  * \param delim delimiter to parse out
530  *
531  * \return The string converted to "CamelCase"
532  * \since 12
533 */
534 char *ast_to_camel_case_delim(const char *s, const char *delim);
535 
536 /*!
537  * \brief Attempts to convert the given string to camel case using
538  * an underscore as the specified delimiter.
539  *
540  * note - returned string needs to be freed
541  *
542  * \param s the string to convert
543  *
544  * \return The string converted to "CamelCase"
545 */
546 #define ast_to_camel_case(s) ast_to_camel_case_delim(s, "_")
547 
548 /*!
549  \brief Parse a time (integer) string.
550  \param src String to parse
551  \param dst Destination
552  \param _default Value to use if the string does not contain a valid time
553  \param consumed The number of characters 'consumed' in the string by the parse (see 'man sscanf' for details)
554  \retval zero on success.
555  \retval non-zero on failure.
556 */
557 int ast_get_time_t(const char *src, time_t *dst, time_t _default, int *consumed);
558 
559 /*!
560  \brief Parse a time (float) string.
561  \param src String to parse
562  \param dst Destination
563  \param _default Value to use if the string does not contain a valid time
564  \param consumed The number of characters 'consumed' in the string by the parse (see 'man sscanf' for details)
565  \retval zero on success.
566  \retval non-zero on failure.
567 */
568 int ast_get_timeval(const char *src, struct timeval *tv, struct timeval _default, int *consumed);
569 
570 /*!
571  * \brief Support for dynamic strings.
572  *
573  * A dynamic string is just a C string prefixed by a few control fields
574  * that help setting/appending/extending it using a printf-like syntax.
575  *
576  * One should never declare a variable with this type, but only a pointer
577  * to it, e.g.
578  *
579  * struct ast_str *ds;
580  *
581  * The pointer can be initialized with the following:
582  *
583  * ds = ast_str_create(init_len);
584  * creates a malloc()'ed dynamic string;
585  *
586  * ds = ast_str_alloca(init_len);
587  * creates a string on the stack (not very dynamic!).
588  *
589  * ds = ast_str_thread_get(ts, init_len)
590  * creates a malloc()'ed dynamic string associated to
591  * the thread-local storage key ts
592  *
593  * Finally, the string can be manipulated with the following:
594  *
595  * ast_str_set(&buf, max_len, fmt, ...)
596  * ast_str_append(&buf, max_len, fmt, ...)
597  *
598  * and their varargs variant
599  *
600  * ast_str_set_va(&buf, max_len, ap)
601  * ast_str_append_va(&buf, max_len, ap)
602  *
603  * \param max_len The maximum allowed capacity of the ast_str. Note that
604  * if the value of max_len is less than the current capacity of the
605  * ast_str (as returned by ast_str_size), then the parameter is effectively
606  * ignored.
607  * 0 means unlimited, -1 means "at most the available space"
608  *
609  * \return All the functions return <0 in case of error, or the
610  * length of the string added to the buffer otherwise. Note that
611  * in most cases where an error is returned, characters ARE written
612  * to the ast_str.
613  */
614 
615 /*!
616  * \brief The descriptor of a dynamic string
617  * XXX storage will be optimized later if needed
618  * We use the ts field to indicate the type of storage.
619  * Three special constants indicate malloc, ast_alloca() or static
620  * variables, all other values indicate a
621  * struct ast_threadstorage pointer.
622  */
623 struct ast_str {
624  size_t __AST_STR_LEN; /*!< The current maximum length of the string */
625  size_t __AST_STR_USED; /*!< Amount of space used */
626  struct ast_threadstorage *__AST_STR_TS; /*!< What kind of storage is this ? */
627 #define DS_MALLOC ((struct ast_threadstorage *)1)
628 #define DS_ALLOCA ((struct ast_threadstorage *)2)
629 #define DS_STATIC ((struct ast_threadstorage *)3) /* not supported yet */
630  char __AST_STR_STR[0]; /*!< The string buffer */
631 };
632 
633 /*!
634  * \brief Given a string regex_string in the form of "/regex/", convert it into the form of "regex"
635  *
636  * This function will trim one leading / and one trailing / from a given input string
637  * ast_str regex_pattern must be preallocated before calling this function
638  *
639  * \retval 0 on success, non-zero on failure.
640  * \retval 1 if we only stripped a leading /
641  * \retval 2 if we only stripped a trailing /
642  * \retval 3 if we did not strip any / characters
643  * \param regex_string the string containing /regex/
644  * \param regex_pattern the destination ast_str which will contain "regex" after execution
645  */
646 int ast_regex_string_to_regex_pattern(const char *regex_string, struct ast_str **regex_pattern);
647 
648 /*!
649  * \brief Create a malloc'ed dynamic length string
650  *
651  * \param init_len This is the initial length of the string buffer
652  *
653  * \return This function returns a pointer to the dynamic string length. The
654  * result will be NULL in the case of a memory allocation error.
655  *
656  * \note The result of this function is dynamically allocated memory, and must
657  * be free()'d after it is no longer needed.
658  */
659 #define ast_str_create(init_len) \
660  _ast_str_create(init_len, __FILE__, __LINE__, __PRETTY_FUNCTION__)
661 AST_INLINE_API(
662 struct ast_str * attribute_malloc _ast_str_create(size_t init_len,
663  const char *file, int lineno, const char *func),
664 {
665  struct ast_str *buf;
666 
667  buf = (struct ast_str *)__ast_calloc(1, sizeof(*buf) + init_len, file, lineno, func);
668  if (buf == NULL)
669  return NULL;
670 
671  buf->__AST_STR_LEN = init_len;
672  buf->__AST_STR_USED = 0;
673  buf->__AST_STR_TS = DS_MALLOC;
674 
675  return buf;
676 }
677 )
678 
679 /*!
680  * \brief Reset the content of a dynamic string.
681  * Useful before a series of ast_str_append.
682  */
683 AST_INLINE_API(
684 void ast_str_reset(struct ast_str *buf),
685 {
686  if (buf) {
687  buf->__AST_STR_USED = 0;
688  if (buf->__AST_STR_LEN) {
689  buf->__AST_STR_STR[0] = '\0';
690  }
691  }
692 }
693 )
694 
695 /*! \brief Update the length of the buffer, after using ast_str merely as a buffer.
696  * \param buf A pointer to the ast_str string.
697  */
698 AST_INLINE_API(
699 void ast_str_update(struct ast_str *buf),
700 {
701  buf->__AST_STR_USED = strlen(buf->__AST_STR_STR);
702 }
703 )
704 
705 /*!
706  * \brief Trims trailing whitespace characters from an ast_str string.
707  * \param buf A pointer to the ast_str string.
708  */
709 AST_INLINE_API(
710 void ast_str_trim_blanks(struct ast_str *buf),
711 {
712  if (!buf) {
713  return;
714  }
715  while (buf->__AST_STR_USED && ((unsigned char) buf->__AST_STR_STR[buf->__AST_STR_USED - 1]) < 33) {
716  buf->__AST_STR_STR[--(buf->__AST_STR_USED)] = '\0';
717  }
718 }
719 )
720 
721 /*!
722  * \brief Returns the current length of the string stored within buf.
723  * \param buf A pointer to the ast_str structure.
724  */
725 AST_INLINE_API(
726 size_t attribute_pure ast_str_strlen(const struct ast_str *buf),
727 {
728  return buf->__AST_STR_USED;
729 }
730 )
731 
732 /*!
733  * \brief Returns the current maximum length (without reallocation) of the current buffer.
734  * \param buf A pointer to the ast_str structure.
735  * \return Current maximum length of the buffer.
736  */
737 AST_INLINE_API(
738 size_t attribute_pure ast_str_size(const struct ast_str *buf),
739 {
740  return buf->__AST_STR_LEN;
741 }
742 )
743 
744 /*!
745  * \brief Returns the string buffer within the ast_str buf.
746  * \param buf A pointer to the ast_str structure.
747  * \return A pointer to the enclosed string.
748  */
749 AST_INLINE_API(
750 char * attribute_pure ast_str_buffer(const struct ast_str *buf),
751 {
752  /* for now, cast away the const qualifier on the pointer
753  * being returned; eventually, it should become truly const
754  * and only be modified via accessor functions
755  */
756  if (__builtin_expect(buf->__AST_STR_LEN > 0, 1)) {
757  return (char *) buf->__AST_STR_STR;
758  }
759  return "";
760 }
761 )
762 
763 /*!
764  * \brief Truncates the enclosed string to the given length.
765  * \param buf A pointer to the ast_str structure.
766  * \param len Maximum length of the string. If len is larger than the
767  * current maximum length, things will explode. If it is negative
768  * at most -len characters will be trimmed off the end.
769  * \return A pointer to the resulting string.
770  */
771 AST_INLINE_API(
772 char *ast_str_truncate(struct ast_str *buf, ssize_t len),
773 {
774  if (len < 0) {
775  if ((typeof(buf->__AST_STR_USED)) -len >= buf->__AST_STR_USED) {
776  buf->__AST_STR_USED = 0;
777  } else {
778  buf->__AST_STR_USED += len;
779  }
780  } else {
781  buf->__AST_STR_USED = len;
782  }
783  buf->__AST_STR_STR[buf->__AST_STR_USED] = '\0';
784  return buf->__AST_STR_STR;
785 }
786 )
787 
788 /*
789  * AST_INLINE_API() is a macro that takes a block of code as an argument.
790  * Using preprocessor #directives in the argument is not supported by all
791  * compilers, and it is a bit of an obfuscation anyways, so avoid it.
792  * As a workaround, define a macro that produces either its argument
793  * or nothing, and use that instead of #ifdef/#endif within the
794  * argument to AST_INLINE_API().
795  */
796 #if defined(DEBUG_THREADLOCALS)
797 #define _DB1(x) x
798 #else
799 #define _DB1(x)
800 #endif
801 
802 /*!
803  * Make space in a new string (e.g. to read in data from a file)
804  */
805 AST_INLINE_API(
806 int _ast_str_make_space(struct ast_str **buf, size_t new_len, const char *file, int lineno, const char *function),
807 {
808  struct ast_str *old_buf = *buf;
809 
810  if (new_len <= (*buf)->__AST_STR_LEN)
811  return 0; /* success */
812  if ((*buf)->__AST_STR_TS == DS_ALLOCA || (*buf)->__AST_STR_TS == DS_STATIC)
813  return -1; /* cannot extend */
814  *buf = (struct ast_str *)__ast_realloc(*buf, new_len + sizeof(struct ast_str), file, lineno, function);
815  if (*buf == NULL) {
816  *buf = old_buf;
817  return -1;
818  }
819  if ((*buf)->__AST_STR_TS != DS_MALLOC) {
820  pthread_setspecific((*buf)->__AST_STR_TS->key, *buf);
821  _DB1(__ast_threadstorage_object_replace(old_buf, *buf, new_len + sizeof(struct ast_str));)
822  }
823 
824  (*buf)->__AST_STR_LEN = new_len;
825  return 0;
826 }
827 )
828 #define ast_str_make_space(buf, new_len) \
829  _ast_str_make_space(buf, new_len, __FILE__, __LINE__, __PRETTY_FUNCTION__)
830 
831 AST_INLINE_API(
832 int ast_str_copy_string(struct ast_str **dst, struct ast_str *src),
833 {
834 
835  /* make sure our destination is large enough */
836  if (src->__AST_STR_USED + 1 > (*dst)->__AST_STR_LEN) {
837  if (ast_str_make_space(dst, src->__AST_STR_USED + 1)) {
838  return -1;
839  }
840  }
841 
842  memcpy((*dst)->__AST_STR_STR, src->__AST_STR_STR, src->__AST_STR_USED + 1);
843  (*dst)->__AST_STR_USED = src->__AST_STR_USED;
844  return 0;
845 }
846 )
847 
848 #define ast_str_alloca(init_len) \
849  ({ \
850  struct ast_str *__ast_str_buf; \
851  __ast_str_buf = ast_alloca(sizeof(*__ast_str_buf) + init_len); \
852  __ast_str_buf->__AST_STR_LEN = init_len; \
853  __ast_str_buf->__AST_STR_USED = 0; \
854  __ast_str_buf->__AST_STR_TS = DS_ALLOCA; \
855  __ast_str_buf->__AST_STR_STR[0] = '\0'; \
856  (__ast_str_buf); \
857  })
858 
859 /*!
860  * \brief Retrieve a thread locally stored dynamic string
861  *
862  * \param ts This is a pointer to the thread storage structure declared by using
863  * the AST_THREADSTORAGE macro. If declared with
864  * AST_THREADSTORAGE(my_buf, my_buf_init), then this argument would be
865  * (&my_buf).
866  * \param init_len This is the initial length of the thread's dynamic string. The
867  * current length may be bigger if previous operations in this thread have
868  * caused it to increase.
869  *
870  * \return This function will return the thread locally stored dynamic string
871  * associated with the thread storage management variable passed as the
872  * first argument.
873  * The result will be NULL in the case of a memory allocation error.
874  *
875  * Example usage:
876  * \code
877  * AST_THREADSTORAGE(my_str, my_str_init);
878  * #define MY_STR_INIT_SIZE 128
879  * ...
880  * void my_func(const char *fmt, ...)
881  * {
882  * struct ast_str *buf;
883  *
884  * if (!(buf = ast_str_thread_get(&my_str, MY_STR_INIT_SIZE)))
885  * return;
886  * ...
887  * }
888  * \endcode
889  */
890 #if !defined(DEBUG_THREADLOCALS)
891 AST_INLINE_API(
892 struct ast_str *ast_str_thread_get(struct ast_threadstorage *ts,
893  size_t init_len),
894 {
895  struct ast_str *buf;
896 
897  buf = (struct ast_str *)ast_threadstorage_get(ts, sizeof(*buf) + init_len);
898  if (buf == NULL)
899  return NULL;
900 
901  if (!buf->__AST_STR_LEN) {
902  buf->__AST_STR_LEN = init_len;
903  buf->__AST_STR_USED = 0;
904  buf->__AST_STR_TS = ts;
905  }
906 
907  return buf;
908 }
909 )
910 #else /* defined(DEBUG_THREADLOCALS) */
911 AST_INLINE_API(
912 struct ast_str *__ast_str_thread_get(struct ast_threadstorage *ts,
913  size_t init_len, const char *file, const char *function, unsigned int line),
914 {
915  struct ast_str *buf;
916 
917  buf = (struct ast_str *)__ast_threadstorage_get(ts, sizeof(*buf) + init_len, file, function, line);
918  if (buf == NULL)
919  return NULL;
920 
921  if (!buf->__AST_STR_LEN) {
922  buf->__AST_STR_LEN = init_len;
923  buf->__AST_STR_USED = 0;
924  buf->__AST_STR_TS = ts;
925  }
926 
927  return buf;
928 }
929 )
930 
931 #define ast_str_thread_get(ts, init_len) __ast_str_thread_get(ts, init_len, __FILE__, __PRETTY_FUNCTION__, __LINE__)
932 #endif /* defined(DEBUG_THREADLOCALS) */
933 
934 /*!
935  * \brief Error codes from __ast_str_helper()
936  * The underlying processing to manipulate dynamic string is done
937  * by __ast_str_helper(), which can return a success or a
938  * permanent failure (e.g. no memory).
939  */
940 enum {
941  /*! An error has occurred and the contents of the dynamic string
942  * are undefined */
944  /*! The buffer size for the dynamic string had to be increased, and
945  * __ast_str_helper() needs to be called again after
946  * a va_end() and va_start(). This return value is legacy and will
947  * no longer be used.
948  */
950 };
951 
952 /*!
953  * \brief Core functionality of ast_str_(set|append)_va
954  *
955  * The arguments to this function are the same as those described for
956  * ast_str_set_va except for an addition argument, append.
957  * If append is non-zero, this will append to the current string instead of
958  * writing over it.
959  *
960  * AST_DYNSTR_BUILD_RETRY is a legacy define. It should probably never
961  * again be used.
962  *
963  * A return of AST_DYNSTR_BUILD_FAILED indicates a memory allocation error.
964  *
965  * A return value greater than or equal to zero indicates the number of
966  * characters that have been written, not including the terminating '\0'.
967  * In the append case, this only includes the number of characters appended.
968  *
969  * \note This function should never need to be called directly. It should
970  * through calling one of the other functions or macros defined in this
971  * file.
972  */
973 int __attribute__((format(printf, 4, 0))) __ast_str_helper(struct ast_str **buf,
974  ssize_t max_len, int append, const char *fmt, va_list ap,
975  const char *file, int lineno, const char *func);
976 #define _ast_str_helper(buf, max_len, append, fmt, ap) \
977  __ast_str_helper(buf, max_len, append, fmt, ap, __FILE__, __LINE__, __PRETTY_FUNCTION__)
978 
979 char *__ast_str_helper2(struct ast_str **buf, ssize_t max_len,
980  const char *src, size_t maxsrc, int append, int escapecommas);
981 
982 /*!
983  * \brief Set a dynamic string from a va_list
984  *
985  * \param buf This is the address of a pointer to a struct ast_str.
986  * If it is retrieved using ast_str_thread_get, the
987  struct ast_threadstorage pointer will need to
988  * be updated in the case that the buffer has to be reallocated to
989  * accommodate a longer string than what it currently has space for.
990  * \param max_len This is the maximum length to allow the string buffer to grow
991  * to. If this is set to 0, then there is no maximum length.
992  * \param fmt This is the format string (printf style)
993  * \param ap This is the va_list
994  *
995  * \return The return value of this function is the same as that of the printf
996  * family of functions.
997  *
998  * Example usage (the first part is only for thread-local storage)
999  * \code
1000  * AST_THREADSTORAGE(my_str, my_str_init);
1001  * #define MY_STR_INIT_SIZE 128
1002  * ...
1003  * void my_func(const char *fmt, ...)
1004  * {
1005  * struct ast_str *buf;
1006  * va_list ap;
1007  *
1008  * if (!(buf = ast_str_thread_get(&my_str, MY_STR_INIT_SIZE)))
1009  * return;
1010  * ...
1011  * va_start(fmt, ap);
1012  * ast_str_set_va(&buf, 0, fmt, ap);
1013  * va_end(ap);
1014  *
1015  * printf("This is the string we just built: %s\n", buf->str);
1016  * ...
1017  * }
1018  * \endcode
1019  *
1020  * \note Care should be taken when using this function. The function can
1021  * result in reallocating the ast_str. If a pointer to the ast_str is passed
1022  * by value to a function that calls ast_str_set_va(), then the original ast_str
1023  * pointer may be invalidated due to a reallocation.
1024  *
1025  */
1026 AST_INLINE_API(int __attribute__((format(printf, 3, 0))) ast_str_set_va(struct ast_str **buf, ssize_t max_len, const char *fmt, va_list ap),
1027 {
1028  return _ast_str_helper(buf, max_len, 0, fmt, ap);
1029 }
1031 
1032 /*!
1033  * \brief Append to a dynamic string using a va_list
1034  *
1035  * Same as ast_str_set_va(), but append to the current content.
1036  *
1037  * \note Care should be taken when using this function. The function can
1038  * result in reallocating the ast_str. If a pointer to the ast_str is passed
1039  * by value to a function that calls ast_str_append_va(), then the original ast_str
1040  * pointer may be invalidated due to a reallocation.
1041  *
1042  * \param buf, max_len, fmt, ap
1043  */
1044 AST_INLINE_API(int __attribute__((format(printf, 3, 0))) ast_str_append_va(struct ast_str **buf, ssize_t max_len, const char *fmt, va_list ap),
1045 {
1046  return _ast_str_helper(buf, max_len, 1, fmt, ap);
1047 }
1049 
1050 /*! \brief Set a dynamic string to a non-NULL terminated substring. */
1051 AST_INLINE_API(char *ast_str_set_substr(struct ast_str **buf, ssize_t maxlen, const char *src, size_t maxsrc),
1052 {
1053  return __ast_str_helper2(buf, maxlen, src, maxsrc, 0, 0);
1054 }
1056 
1057 /*! \brief Append a non-NULL terminated substring to the end of a dynamic string. */
1058 AST_INLINE_API(char *ast_str_append_substr(struct ast_str **buf, ssize_t maxlen, const char *src, size_t maxsrc),
1059 {
1060  return __ast_str_helper2(buf, maxlen, src, maxsrc, 1, 0);
1061 }
1063 
1064 /*! \brief Set a dynamic string to a non-NULL terminated substring, with escaping of commas. */
1065 AST_INLINE_API(char *ast_str_set_escapecommas(struct ast_str **buf, ssize_t maxlen, const char *src, size_t maxsrc),
1066 {
1067  return __ast_str_helper2(buf, maxlen, src, maxsrc, 0, 1);
1068 }
1070 
1071 /*! \brief Append a non-NULL terminated substring to the end of a dynamic string, with escaping of commas. */
1072 AST_INLINE_API(char *ast_str_append_escapecommas(struct ast_str **buf, ssize_t maxlen, const char *src, size_t maxsrc),
1073 {
1074  return __ast_str_helper2(buf, maxlen, src, maxsrc, 1, 1);
1075 }
1077 
1078 /*!
1079  * \brief Set a dynamic string using variable arguments
1080  *
1081  * \note Care should be taken when using this function. The function can
1082  * result in reallocating the ast_str. If a pointer to the ast_str is passed
1083  * by value to a function that calls ast_str_set(), then the original ast_str
1084  * pointer may be invalidated due to a reallocation.
1085  *
1086  * \param buf This is the address of a pointer to a struct ast_str which should
1087  * have been retrieved using ast_str_thread_get. It will need to
1088  * be updated in the case that the buffer has to be reallocated to
1089  * accomodate a longer string than what it currently has space for.
1090  * \param max_len This is the maximum length to allow the string buffer to grow
1091  * to. If this is set to 0, then there is no maximum length.
1092  * If set to -1, we are bound to the current maximum length.
1093  * \param fmt This is the format string (printf style)
1094  *
1095  * \return The return value of this function is the same as that of the printf
1096  * family of functions.
1097  *
1098  * All the rest is the same as ast_str_set_va()
1099  */
1100 AST_INLINE_API(
1101 int __attribute__((format(printf, 3, 4))) ast_str_set(
1102  struct ast_str **buf, ssize_t max_len, const char *fmt, ...),
1103 {
1104  int res;
1105  va_list ap;
1106 
1107  va_start(ap, fmt);
1108  res = ast_str_set_va(buf, max_len, fmt, ap);
1109  va_end(ap);
1110 
1111  return res;
1112 }
1114 
1115 /*!
1116  * \brief Append to a thread local dynamic string
1117  *
1118  * \note Care should be taken when using this function. The function can
1119  * result in reallocating the ast_str. If a pointer to the ast_str is passed
1120  * by value to a function that calls ast_str_append(), then the original ast_str
1121  * pointer may be invalidated due to a reallocation.
1122  *
1123  * The arguments, return values, and usage of this function are the same as
1124  * ast_str_set(), but the new data is appended to the current value.
1125  */
1126 AST_INLINE_API(
1127 int __attribute__((format(printf, 3, 4))) ast_str_append(
1128  struct ast_str **buf, ssize_t max_len, const char *fmt, ...),
1129 {
1130  int res;
1131  va_list ap;
1132 
1133  va_start(ap, fmt);
1134  res = ast_str_append_va(buf, max_len, fmt, ap);
1135  va_end(ap);
1136 
1137  return res;
1138 }
1140 
1141 /*!
1142  * \brief Provides a temporary ast_str and returns a copy of its buffer
1143  * \since 16.12
1144  * \since 17.6
1145  * \since 18.0
1146  *
1147  * \param init_len The initial length of the temporary ast_str needed.
1148  * \param __expr An expression that needs the temporary ast_str and returns a char *.
1149  *
1150  * \return A copy of __expr's return buffer allocated on the stack.
1151  *
1152  * \details
1153  * There are a few query functions scattered around that need an ast_str in which
1154  * to assemble the results but it's not always convenient to create an ast_str
1155  * and ensure it's freed just to print a log message. For example:
1156  *
1157  * \code
1158  * struct ast_str *temp = ast_str_create(128);
1159  * ast_log(LOG_INFO, "Format caps: %s\n", ast_format_cap_get_names(caps, &temp));
1160  * ast_free(temp);
1161  * \endcode
1162  *
1163  * That's not bad if you only have to do it once but some of our code that deals
1164  * with streams and codecs is pretty complex and good instrumentation is essential.
1165  * The aim of this function is to make that easier.
1166  *
1167  * With this macro, the above code can be simplified:
1168  *
1169  * \code
1170  * ast_log(LOG_INFO, "Format caps: %s\n",
1171  * ast_str_tmp(128, ast_format_cap_get_names(caps, &STR_TMP));
1172  * \endcode
1173  *
1174  * STR_TMP will always be a reference to the temporary ast_str created
1175  * by the macro. Its scope is limited by the macro so you can use it multiple
1176  * times without conflict:
1177  *
1178  * \code
1179  * ast_log(LOG_INFO, "Format caps in: %s Format caps out: %s\n",
1180  * ast_str_tmp(128, ast_format_cap_get_names(caps_in, &STR_TMP),
1181  * ast_str_tmp(128, ast_format_cap_get_names(caps_out, &STR_TMP)
1182  * );
1183  * \endcode
1184  *
1185  * \warning
1186  * The returned string is stack allocated so don't go overboard.
1187  *
1188  */
1189 #define ast_str_tmp(init_len, __expr) \
1190 ({ \
1191  struct ast_str *STR_TMP = ast_str_create(init_len); \
1192  char *ret = ast_strdupa(__expr); \
1193  ast_free(STR_TMP); \
1194  ret; \
1195 })
1196 
1197 
1198 
1199 /*!
1200  * \brief Check if a string is only digits
1201  *
1202  * \retval 1 The string contains only digits
1203  * \retval 0 The string contains non-digit characters
1204  */
1205 AST_INLINE_API(
1206 int ast_check_digits(const char *arg),
1207 {
1208  while (*arg) {
1209  if (*arg < '0' || *arg > '9') {
1210  return 0;
1211  }
1212  arg++;
1213  }
1214  return 1;
1215 }
1217 
1218 /*!
1219  * \brief Convert the tech portion of a device string to upper case
1220  *
1221  * \retval dev_str the char* passed in for convenience
1222  */
1223 AST_INLINE_API(
1224 char *ast_tech_to_upper(char *dev_str),
1225 {
1226  char *pos;
1227  if (!dev_str || !strchr(dev_str, '/')) {
1228  return dev_str;
1229  }
1230 
1231  for (pos = dev_str; *pos && *pos != '/'; pos++) {
1232  *pos = toupper(*pos);
1233  }
1234  return dev_str;
1235 }
1237 
1238 /*!
1239  * \brief Restrict hash value range
1240  *
1241  * \details
1242  * Hash values used all over asterisk are expected to be non-negative
1243  * (signed) int values. This function restricts an unsigned int hash
1244  * value to the positive half of the (signed) int values.
1245  */
1246 static force_inline int attribute_pure ast_str_hash_restrict(unsigned int hash)
1247 {
1248  return (int) (hash & (unsigned int) INT_MAX);
1249 }
1250 
1251 /*!
1252  * \brief Compute a hash value on a string
1253  *
1254  * This famous hash algorithm was written by Dan Bernstein and is
1255  * commonly used.
1256  *
1257  * http://www.cse.yorku.ca/~oz/hash.html
1258  */
1259 static force_inline int attribute_pure ast_str_hash(const char *str)
1260 {
1261  unsigned int hash = 5381;
1262 
1263  while (*str) {
1264  hash = hash * 33 ^ (unsigned char) *str++;
1265  }
1266 
1267  return ast_str_hash_restrict(hash);
1268 }
1269 
1270 /*!
1271  * \brief Compute a hash value on a string
1272  *
1273  * \param[in] str The string to add to the hash
1274  * \param[in] seed The hash value to start with
1275  *
1276  * \details
1277  * This version of the function is for when you need to compute a
1278  * string hash of more than one string.
1279  *
1280  * This famous hash algorithm was written by Dan Bernstein and is
1281  * commonly used.
1282  *
1283  * \sa http://www.cse.yorku.ca/~oz/hash.html
1284  */
1285 static force_inline int ast_str_hash_add(const char *str, int seed)
1286 {
1287  unsigned int hash = (unsigned int) seed;
1288 
1289  while (*str) {
1290  hash = hash * 33 ^ (unsigned char) *str++;
1291  }
1292 
1293  return ast_str_hash_restrict(hash);
1294 }
1295 
1296 /*!
1297  * \brief Compute a hash value on a case-insensitive string
1298  *
1299  * Uses the same hash algorithm as ast_str_hash, but converts
1300  * all characters to lowercase prior to computing a hash. This
1301  * allows for easy case-insensitive lookups in a hash table.
1302  */
1303 static force_inline int attribute_pure ast_str_case_hash(const char *str)
1304 {
1305  unsigned int hash = 5381;
1306 
1307  while (*str) {
1308  hash = hash * 33 ^ (unsigned char) tolower(*str++);
1309  }
1310 
1311  return ast_str_hash_restrict(hash);
1312 }
1313 
1314 /*!
1315  * \brief Convert a string to all lower-case
1316  *
1317  * \param str The string to be converted to lower case
1318  *
1319  * \retval str the char* passed in for convenience
1320  */
1321 static force_inline char *ast_str_to_lower(char *str)
1322 {
1323  char *str_orig = str;
1324  if (!str) {
1325  return str;
1326  }
1327 
1328  for (; *str; ++str) {
1329  *str = tolower(*str);
1330  }
1331 
1332  return str_orig;
1333 }
1334 
1335 /*!
1336  * \brief Convert a string to all upper-case
1337  *
1338  * \param str The string to be converted to upper case
1339  *
1340  * \retval str the char* passed in for convenience
1341  */
1342 static force_inline char *ast_str_to_upper(char *str)
1343 {
1344  char *str_orig = str;
1345  if (!str) {
1346  return str;
1347  }
1348 
1349  for (; *str; ++str) {
1350  *str = toupper(*str);
1351  }
1352 
1353  return str_orig;
1354 }
1355 
1356 /*!
1357  * \since 12
1358  * \brief Allocates a hash container for bare strings
1359  *
1360  * \param buckets The number of buckets to use for the hash container
1361  *
1362  * \return AO2 container for strings
1363  * \retval NULL if allocation failed
1364  */
1365 #define ast_str_container_alloc(buckets) ast_str_container_alloc_options(AO2_ALLOC_OPT_LOCK_MUTEX, buckets)
1366 
1367 /*!
1368  * \since 12
1369  * \brief Allocates a hash container for bare strings
1370  *
1371  * \param opts Options to be provided to the container
1372  * \param buckets The number of buckets to use for the hash container
1373  *
1374  * \return AO2 container for strings
1375  * \retval NULL if allocation failed
1376  */
1377 struct ao2_container *ast_str_container_alloc_options(enum ao2_alloc_opts opts, int buckets);
1378 
1379 /*!
1380  * \since 12
1381  * \brief Adds a string to a string container allocated by ast_str_container_alloc
1382  *
1383  * \param str_container The container to which to add a string
1384  * \param add The string to add to the container
1385  *
1386  * \retval zero on success
1387  * \retval non-zero if the operation failed
1388  */
1389 int ast_str_container_add(struct ao2_container *str_container, const char *add);
1390 
1391 /*!
1392  * \since 12
1393  * \brief Removes a string from a string container allocated by ast_str_container_alloc
1394  *
1395  * \param str_container The container from which to remove a string
1396  * \param remove The string to remove from the container
1397  */
1398 void ast_str_container_remove(struct ao2_container *str_container, const char *remove);
1399 
1400 /*!
1401  * \brief Create a pseudo-random string of a fixed length.
1402  *
1403  * This function is useful for generating a string whose randomness
1404  * does not need to be across all time and space, does not need to
1405  * be cryptographically secure, and needs to fit in a limited space.
1406  *
1407  * This function will write a null byte at the final position
1408  * in the buffer (buf[size - 1]). So if you pass in a size of
1409  * 10, then this will generate a random 9-character string.
1410  *
1411  * \param buf Buffer to write random string into.
1412  * \param size The size of the buffer.
1413  * \return A pointer to buf
1414  */
1415 char *ast_generate_random_string(char *buf, size_t size);
1416 
1417 /*!
1418  * \brief Compare strings for equality checking for NULL.
1419  * \since 16.3.0
1420  *
1421  * This function considers NULL values as non-strings, thus a false condition.
1422  * This means that it will return false if one, or both of the given values are
1423  * NULL (i.e. two NULLs are not equal strings).
1424  *
1425  * \param str1 The string to compare to str2
1426  * \param str2 The string to compare to str1
1427  *
1428  * \retval true if valid strings and equal.
1429  * \retval false otherwise.
1430  */
1431 int ast_strings_equal(const char *str1, const char *str2);
1432 
1433 /*!
1434  * \brief Compares 2 strings using realtime-style operators
1435  * \since 13.9.0
1436  *
1437  * \param left The left side of the equation
1438  * \param op The operator to apply
1439  * \param right The right side of the equation
1440  *
1441  * \retval 1 matches
1442  * \retval 0 doesn't match
1443  *
1444  * \details
1445  *
1446  * Operators:
1447  * "=", "!=", "<", "<=", ">", ">=":
1448  * If both left and right can be converted to float, then they will be
1449  * compared as such. Otherwise the result will be derived from strcmp(left, right).
1450  * "regex":
1451  * The right value will be compiled as a regular expression and matched against the left
1452  * value.
1453  * "like":
1454  * Any '%' character in the right value will be converted to '.*' and the resulting
1455  * string will be handled as a regex.
1456  * NULL , "":
1457  * If the right value starts and ends with a '/' then it will be processed as a regex.
1458  * Otherwise, same as "=".
1459  */
1460 int ast_strings_match(const char *left, const char *op, const char *right);
1461 
1462 /*!
1463  * \brief Read lines from a string buffer
1464  * \since 13.18.0
1465  *
1466  * \param[in,out] buffer A pointer to a char * string with either Unix or Windows line endings
1467  *
1468  * \return The "next" line
1469  *
1470  * \warning The original string and *buffer will be modified.
1471  *
1472  * \details
1473  * Both '\\n' and '\\r\\n' are treated as single delimiters but consecutive occurrences of
1474  * the delimiters are NOT considered to be a single delimiter. This preserves blank
1475  * lines in the input.
1476  *
1477  * macOS line endings ('\\r') are not supported at this time.
1478  *
1479  */
1480 char *ast_read_line_from_buffer(char **buffer);
1481 
1482 #endif /* _ASTERISK_STRINGS_H */
void ast_join_delim(char *s, size_t len, const char *const w[], unsigned int size, char delim)
Join an array of strings into a single string.
Definition: utils.c:2378
void * ast_threadstorage_get(struct ast_threadstorage *ts, size_t init_size)
Retrieve thread storage.
size_t ast_str_size(const struct ast_str *buf)
Returns the current maximum length (without reallocation) of the current buffer.
Definition: strings.h:742
static int force_inline attribute_pure ast_ends_with(const char *str, const char *suffix)
Checks whether a string ends with another.
Definition: strings.h:116
char * ast_str_buffer(const struct ast_str *buf)
Returns the string buffer within the ast_str buf.
Definition: strings.h:761
char * ast_escape(char *dest, const char *s, size_t size, const char *to_escape)
Escape the 'to_escape' characters in the given string.
Definition: utils.c:2034
data for a thread locally stored variable
Definition: threadstorage.h:58
int ast_str_set_va(struct ast_str **buf, ssize_t max_len, const char *fmt, va_list ap)
Set a dynamic string from a va_list.
Definition: strings.h:1030
char * ast_str_append_escapecommas(struct ast_str **buf, ssize_t maxlen, const char *src, size_t maxsrc)
Append a non-NULL terminated substring to the end of a dynamic string, with escaping of commas...
Definition: strings.h:1076
void ast_str_container_remove(struct ao2_container *str_container, const char *remove)
Removes a string from a string container allocated by ast_str_container_alloc.
Definition: strings.c:221
int ast_str_append(struct ast_str **buf, ssize_t max_len, const char *fmt,...)
Append to a thread local dynamic string.
Definition: strings.h:1139
char * ast_escape_c(char *dest, const char *s, size_t size)
Escape standard 'C' sequences in the given string.
Definition: utils.c:2077
Definitions to aid in the use of thread local storage.
int ast_get_timeval(const char *src, struct timeval *tv, struct timeval _default, int *consumed)
Parse a time (float) string.
Definition: utils.c:2419
char * ast_skip_nonblanks(const char *str)
Gets a pointer to first whitespace character in a string.
Definition: strings.h:204
Utility functions.
char * ast_str_truncate(struct ast_str *buf, ssize_t len)
Truncates the enclosed string to the given length.
Definition: strings.h:786
int ast_str_set(struct ast_str **buf, ssize_t max_len, const char *fmt,...)
Set a dynamic string using variable arguments.
Definition: strings.h:1113
#define ast_str_tmp(init_len, __expr)
Provides a temporary ast_str and returns a copy of its buffer.
Definition: strings.h:1189
int ast_get_time_t(const char *src, time_t *dst, time_t _default, int *consumed)
Parse a time (integer) string.
Definition: utils.c:2446
char * ast_strip_quoted(char *s, const char *beg_quotes, const char *end_quotes)
Strip leading/trailing whitespace and quotes from a string.
Definition: utils.c:1818
int ast_build_string(char **buffer, size_t *space, const char *fmt,...)
Build a string in a buffer, designed to be called repeatedly.
Definition: utils.c:2167
struct ao2_container * ast_str_container_alloc_options(enum ao2_alloc_opts opts, int buckets)
Allocates a hash container for bare strings.
Definition: strings.c:200
#define ast_strdupa(s)
duplicate a string in memory from the stack
Definition: astmm.h:298
char * ast_str_append_substr(struct ast_str **buf, ssize_t maxlen, const char *src, size_t maxsrc)
Append a non-NULL terminated substring to the end of a dynamic string.
Definition: strings.h:1062
char * ast_strip(char *s)
Strip leading/trailing whitespace from a string.
Definition: strings.h:223
char * ast_strsep(char **s, const char sep, uint32_t flags)
Act like strsep but ignore separators inside quotes.
Definition: utils.c:1835
static force_inline char * ast_str_to_lower(char *str)
Convert a string to all lower-case.
Definition: strings.h:1321
char * ast_escape_alloc(const char *s, const char *to_escape)
Escape the 'to_escape' characters in the given string.
Definition: utils.c:2132
#define ast_alloca(size)
call __builtin_alloca to ensure we get gcc builtin semantics
Definition: astmm.h:288
static force_inline char * ast_str_to_upper(char *str)
Convert a string to all upper-case.
Definition: strings.h:1342
ao2_alloc_opts
Options available when allocating an ao2 object.
Definition: astobj2.h:361
char * ast_tech_to_upper(char *dev_str)
Convert the tech portion of a device string to upper case.
Definition: strings.h:1236
int attribute_pure ast_true(const char *val)
Make sure something is true. Determine if a string containing a boolean value is "true". This function checks to see whether a string passed to it is an indication of an "true" value. It checks to see if the string is "yes", "true", "y", "t", "on" or "1".
Definition: utils.c:2199
Support for dynamic strings.
Definition: strings.h:623
char * ast_generate_random_string(char *buf, size_t size)
Create a pseudo-random string of a fixed length.
Definition: strings.c:226
size_t __AST_STR_USED
Definition: strings.h:625
char __AST_STR_STR[0]
Definition: strings.h:630
int ast_strings_equal(const char *str1, const char *str2)
Compare strings for equality checking for NULL.
Definition: strings.c:238
int _ast_str_make_space(struct ast_str **buf, size_t new_len, const char *file, int lineno, const char *function)
Definition: strings.h:827
char * ast_skip_blanks(const char *str)
Gets a pointer to the first non-whitespace character in a string.
Definition: strings.h:161
char * ast_trim_blanks(char *str)
Trims trailing whitespace characters from a string.
Definition: strings.h:186
int ast_regex_string_to_regex_pattern(const char *regex_string, struct ast_str **regex_pattern)
Given a string regex_string in the form of "/regex/", convert it into the form of "regex"...
Definition: utils.c:2179
static force_inline int ast_str_hash_add(const char *str, int seed)
Compute a hash value on a string.
Definition: strings.h:1285
char * ast_strsep_quoted(char **s, const char sep, const char quote, uint32_t flags)
Like ast_strsep() except you can specify a specific quote character.
Definition: utils.c:1899
ast_strsep_flags
Flags for ast_strsep.
Definition: strings.h:254
char * ast_escape_c_alloc(const char *s)
Escape standard 'C' sequences in the given string.
Definition: utils.c:2140
int ast_str_append_va(struct ast_str **buf, ssize_t max_len, const char *fmt, va_list ap)
Append to a dynamic string using a va_list.
Definition: strings.h:1048
int ast_build_string_va(char **buffer, size_t *space, const char *fmt, va_list ap)
Build a string in a buffer, designed to be called repeatedly.
Definition: utils.c:2148
int ast_check_digits(const char *arg)
Check if a string is only digits.
Definition: strings.h:1216
char * ast_unescape_semicolon(char *s)
Strip backslash for "escaped" semicolons, the string to be stripped (will be modified).
Definition: utils.c:1964
char * ast_str_set_escapecommas(struct ast_str **buf, ssize_t maxlen, const char *src, size_t maxsrc)
Set a dynamic string to a non-NULL terminated substring, with escaping of commas. ...
Definition: strings.h:1069
void ast_str_reset(struct ast_str *buf)
Reset the content of a dynamic string. Useful before a series of ast_str_append.
Definition: strings.h:693
struct ast_threadstorage * __AST_STR_TS
Definition: strings.h:626
size_t ast_str_strlen(const struct ast_str *buf)
Returns the current length of the string stored within buf.
Definition: strings.h:730
static force_inline int attribute_pure ast_str_hash_restrict(unsigned int hash)
Restrict hash value range.
Definition: strings.h:1246
void ast_copy_string(char *dst, const char *src, size_t size)
Size-limited null-terminating string copy.
Definition: strings.h:425
size_t __AST_STR_LEN
Definition: strings.h:624
void ast_str_update(struct ast_str *buf)
Update the length of the buffer, after using ast_str merely as a buffer.
Definition: strings.h:703
int attribute_pure ast_false(const char *val)
Make sure something is false. Determine if a string containing a boolean value is "false"...
Definition: utils.c:2216
static int force_inline attribute_pure ast_begins_with(const char *str, const char *prefix)
Checks whether a string begins with another.
Definition: strings.h:97
int ast_in_delimited_string(const char *needle, const char *haystack, char delim)
Check if there is an exact match for 'needle' between delimiters in 'haystack'.
Definition: strings.c:433
int __ast_str_helper(struct ast_str **buf, ssize_t max_len, int append, const char *fmt, va_list ap, const char *file, int lineno, const char *func)
Core functionality of ast_str_(set|append)_va.
Definition: strings.c:55
char * ast_str_set_substr(struct ast_str **buf, ssize_t maxlen, const char *src, size_t maxsrc)
Set a dynamic string to a non-NULL terminated substring.
Definition: strings.h:1055
Generic container type.
struct ast_str * ast_str_thread_get(struct ast_threadstorage *ts, size_t init_len)
Retrieve a thread locally stored dynamic string.
Definition: strings.h:909
void ast_str_trim_blanks(struct ast_str *buf)
Trims trailing whitespace characters from an ast_str string.
Definition: strings.h:719
char * ast_to_camel_case_delim(const char *s, const char *delim)
Attempts to convert the given string to camel case using the specified delimiter. ...
Definition: utils.c:2397
int ast_str_container_add(struct ao2_container *str_container, const char *add)
Adds a string to a string container allocated by ast_str_container_alloc.
Definition: strings.c:205
static force_inline int attribute_pure ast_str_case_hash(const char *str)
Compute a hash value on a case-insensitive string.
Definition: strings.h:1303
int ast_strings_match(const char *left, const char *op, const char *right)
Compares 2 strings using realtime-style operators.
Definition: strings.c:247
#define ast_str_create(init_len)
Create a malloc'ed dynamic length string.
Definition: strings.h:659
static force_inline int attribute_pure ast_str_hash(const char *str)
Compute a hash value on a string.
Definition: strings.h:1259
char * ast_unescape_c(char *s)
Convert some C escape sequences.
Definition: utils.c:1983
char * ast_read_line_from_buffer(char **buffer)
Read lines from a string buffer.
Definition: strings.c:371