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