CLI: Create ast_cli_completion_vector.
[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 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 #ifdef __AST_DEBUG_MALLOC
621 #define ast_str_create(a)       _ast_str_create(a,__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 #else
640 AST_INLINE_API(
641 struct ast_str * attribute_malloc ast_str_create(size_t init_len),
642 {
643         struct ast_str *buf;
644
645         buf = (struct ast_str *)ast_calloc(1, sizeof(*buf) + init_len);
646         if (buf == NULL)
647                 return NULL;
648
649         buf->__AST_STR_LEN = init_len;
650         buf->__AST_STR_USED = 0;
651         buf->__AST_STR_TS = DS_MALLOC;
652
653         return buf;
654 }
655 )
656 #endif
657
658 /*! \brief Reset the content of a dynamic string.
659  * Useful before a series of ast_str_append.
660  */
661 AST_INLINE_API(
662 void ast_str_reset(struct ast_str *buf),
663 {
664         if (buf) {
665                 buf->__AST_STR_USED = 0;
666                 if (buf->__AST_STR_LEN) {
667                         buf->__AST_STR_STR[0] = '\0';
668                 }
669         }
670 }
671 )
672
673 /*! \brief Update the length of the buffer, after using ast_str merely as a buffer.
674  *  \param buf A pointer to the ast_str string.
675  */
676 AST_INLINE_API(
677 void ast_str_update(struct ast_str *buf),
678 {
679         buf->__AST_STR_USED = strlen(buf->__AST_STR_STR);
680 }
681 )
682
683 /*! \brief Trims trailing whitespace characters from an ast_str string.
684  *  \param buf A pointer to the ast_str string.
685  */
686 AST_INLINE_API(
687 void ast_str_trim_blanks(struct ast_str *buf),
688 {
689         if (!buf) {
690                 return;
691         }
692         while (buf->__AST_STR_USED && ((unsigned char) buf->__AST_STR_STR[buf->__AST_STR_USED - 1]) < 33) {
693                 buf->__AST_STR_STR[--(buf->__AST_STR_USED)] = '\0';
694         }
695 }
696 )
697
698 /*!\brief Returns the current length of the string stored within buf.
699  * \param buf A pointer to the ast_str structure.
700  */
701 AST_INLINE_API(
702 size_t attribute_pure ast_str_strlen(const struct ast_str *buf),
703 {
704         return buf->__AST_STR_USED;
705 }
706 )
707
708 /*!\brief Returns the current maximum length (without reallocation) of the current buffer.
709  * \param buf A pointer to the ast_str structure.
710  * \retval Current maximum length of the buffer.
711  */
712 AST_INLINE_API(
713 size_t attribute_pure ast_str_size(const struct ast_str *buf),
714 {
715         return buf->__AST_STR_LEN;
716 }
717 )
718
719 /*!\brief Returns the string buffer within the ast_str buf.
720  * \param buf A pointer to the ast_str structure.
721  * \retval A pointer to the enclosed string.
722  */
723 AST_INLINE_API(
724 char * attribute_pure ast_str_buffer(const struct ast_str *buf),
725 {
726         /* for now, cast away the const qualifier on the pointer
727          * being returned; eventually, it should become truly const
728          * and only be modified via accessor functions
729          */
730         return (char *) buf->__AST_STR_STR;
731 }
732 )
733
734 /*!\brief Truncates the enclosed string to the given length.
735  * \param buf A pointer to the ast_str structure.
736  * \param len Maximum length of the string. If len is larger than the
737  *        current maximum length, things will explode. If it is negative
738  *        at most -len characters will be trimmed off the end.
739  * \retval A pointer to the resulting string.
740  */
741 AST_INLINE_API(
742 char *ast_str_truncate(struct ast_str *buf, ssize_t len),
743 {
744         if (len < 0) {
745                 if ((typeof(buf->__AST_STR_USED)) -len >= buf->__AST_STR_USED) {
746                         buf->__AST_STR_USED = 0;
747                 } else {
748                         buf->__AST_STR_USED += len;
749                 }
750         } else {
751                 buf->__AST_STR_USED = len;
752         }
753         buf->__AST_STR_STR[buf->__AST_STR_USED] = '\0';
754         return buf->__AST_STR_STR;
755 }
756 )
757         
758 /*
759  * AST_INLINE_API() is a macro that takes a block of code as an argument.
760  * Using preprocessor #directives in the argument is not supported by all
761  * compilers, and it is a bit of an obfuscation anyways, so avoid it.
762  * As a workaround, define a macro that produces either its argument
763  * or nothing, and use that instead of #ifdef/#endif within the
764  * argument to AST_INLINE_API().
765  */
766 #if defined(DEBUG_THREADLOCALS)
767 #define _DB1(x) x
768 #else
769 #define _DB1(x)
770 #endif
771
772 /*!
773  * Make space in a new string (e.g. to read in data from a file)
774  */
775 #ifdef __AST_DEBUG_MALLOC
776 AST_INLINE_API(
777 int _ast_str_make_space(struct ast_str **buf, size_t new_len, const char *file, int lineno, const char *function),
778 {
779         struct ast_str *old_buf = *buf;
780
781         if (new_len <= (*buf)->__AST_STR_LEN) 
782                 return 0;       /* success */
783         if ((*buf)->__AST_STR_TS == DS_ALLOCA || (*buf)->__AST_STR_TS == DS_STATIC)
784                 return -1;      /* cannot extend */
785         *buf = (struct ast_str *)__ast_realloc(*buf, new_len + sizeof(struct ast_str), file, lineno, function);
786         if (*buf == NULL) {
787                 *buf = old_buf;
788                 return -1;
789         }
790         if ((*buf)->__AST_STR_TS != DS_MALLOC) {
791                 pthread_setspecific((*buf)->__AST_STR_TS->key, *buf);
792                 _DB1(__ast_threadstorage_object_replace(old_buf, *buf, new_len + sizeof(struct ast_str));)
793         }
794
795         (*buf)->__AST_STR_LEN = new_len;
796         return 0;
797 }
798 )
799 #define ast_str_make_space(a,b) _ast_str_make_space(a,b,__FILE__,__LINE__,__PRETTY_FUNCTION__)
800 #else
801 AST_INLINE_API(
802 int ast_str_make_space(struct ast_str **buf, size_t new_len),
803 {
804         struct ast_str *old_buf = *buf;
805
806         if (new_len <= (*buf)->__AST_STR_LEN) 
807                 return 0;       /* success */
808         if ((*buf)->__AST_STR_TS == DS_ALLOCA || (*buf)->__AST_STR_TS == DS_STATIC)
809                 return -1;      /* cannot extend */
810         *buf = (struct ast_str *)ast_realloc(*buf, new_len + sizeof(struct ast_str));
811         if (*buf == NULL) {
812                 *buf = old_buf;
813                 return -1;
814         }
815         if ((*buf)->__AST_STR_TS != DS_MALLOC) {
816                 pthread_setspecific((*buf)->__AST_STR_TS->key, *buf);
817                 _DB1(__ast_threadstorage_object_replace(old_buf, *buf, new_len + sizeof(struct ast_str));)
818         }
819
820         (*buf)->__AST_STR_LEN = new_len;
821         return 0;
822 }
823 )
824 #endif
825
826 AST_INLINE_API(
827 int ast_str_copy_string(struct ast_str **dst, struct ast_str *src),
828 {
829
830         /* make sure our destination is large enough */
831         if (src->__AST_STR_USED + 1 > (*dst)->__AST_STR_LEN) {
832                 if (ast_str_make_space(dst, src->__AST_STR_USED + 1)) {
833                         return -1;
834                 }
835         }
836
837         memcpy((*dst)->__AST_STR_STR, src->__AST_STR_STR, src->__AST_STR_USED + 1);
838         (*dst)->__AST_STR_USED = src->__AST_STR_USED;
839         return 0;
840 }
841 )
842
843 #define ast_str_alloca(init_len)                        \
844         ({                                              \
845                 struct ast_str *__ast_str_buf;                  \
846                 __ast_str_buf = ast_alloca(sizeof(*__ast_str_buf) + init_len);  \
847                 __ast_str_buf->__AST_STR_LEN = init_len;                        \
848                 __ast_str_buf->__AST_STR_USED = 0;                              \
849                 __ast_str_buf->__AST_STR_TS = DS_ALLOCA;                        \
850                 __ast_str_buf->__AST_STR_STR[0] = '\0';                 \
851                 (__ast_str_buf);                                        \
852         })
853
854 /*!
855  * \brief Retrieve a thread locally stored dynamic string
856  *
857  * \param ts This is a pointer to the thread storage structure declared by using
858  *      the AST_THREADSTORAGE macro.  If declared with 
859  *      AST_THREADSTORAGE(my_buf, my_buf_init), then this argument would be 
860  *      (&my_buf).
861  * \param init_len This is the initial length of the thread's dynamic string. The
862  *      current length may be bigger if previous operations in this thread have
863  *      caused it to increase.
864  *
865  * \return This function will return the thread locally stored dynamic string
866  *         associated with the thread storage management variable passed as the
867  *         first argument.
868  *         The result will be NULL in the case of a memory allocation error.
869  *
870  * Example usage:
871  * \code
872  * AST_THREADSTORAGE(my_str, my_str_init);
873  * #define MY_STR_INIT_SIZE   128
874  * ...
875  * void my_func(const char *fmt, ...)
876  * {
877  *      struct ast_str *buf;
878  *
879  *      if (!(buf = ast_str_thread_get(&my_str, MY_STR_INIT_SIZE)))
880  *           return;
881  *      ...
882  * }
883  * \endcode
884  */
885 #if !defined(DEBUG_THREADLOCALS)
886 AST_INLINE_API(
887 struct ast_str *ast_str_thread_get(struct ast_threadstorage *ts,
888         size_t init_len),
889 {
890         struct ast_str *buf;
891
892         buf = (struct ast_str *)ast_threadstorage_get(ts, sizeof(*buf) + init_len);
893         if (buf == NULL)
894                 return NULL;
895
896         if (!buf->__AST_STR_LEN) {
897                 buf->__AST_STR_LEN = init_len;
898                 buf->__AST_STR_USED = 0;
899                 buf->__AST_STR_TS = ts;
900         }
901
902         return buf;
903 }
904 )
905 #else /* defined(DEBUG_THREADLOCALS) */
906 AST_INLINE_API(
907 struct ast_str *__ast_str_thread_get(struct ast_threadstorage *ts,
908         size_t init_len, const char *file, const char *function, unsigned int line),
909 {
910         struct ast_str *buf;
911
912         buf = (struct ast_str *)__ast_threadstorage_get(ts, sizeof(*buf) + init_len, file, function, line);
913         if (buf == NULL)
914                 return NULL;
915
916         if (!buf->__AST_STR_LEN) {
917                 buf->__AST_STR_LEN = init_len;
918                 buf->__AST_STR_USED = 0;
919                 buf->__AST_STR_TS = ts;
920         }
921
922         return buf;
923 }
924 )
925
926 #define ast_str_thread_get(ts, init_len) __ast_str_thread_get(ts, init_len, __FILE__, __PRETTY_FUNCTION__, __LINE__)
927 #endif /* defined(DEBUG_THREADLOCALS) */
928
929 /*!
930  * \brief Error codes from __ast_str_helper()
931  * The undelying processing to manipulate dynamic string is done
932  * by __ast_str_helper(), which can return a success or a
933  * permanent failure (e.g. no memory).
934  */
935 enum {
936         /*! An error has occurred and the contents of the dynamic string
937          *  are undefined */
938         AST_DYNSTR_BUILD_FAILED = -1,
939         /*! The buffer size for the dynamic string had to be increased, and
940          *  __ast_str_helper() needs to be called again after
941          *  a va_end() and va_start().  This return value is legacy and will
942          *  no longer be used.
943          */
944         AST_DYNSTR_BUILD_RETRY = -2
945 };
946
947 /*!
948  * \brief Core functionality of ast_str_(set|append)_va
949  *
950  * The arguments to this function are the same as those described for
951  * ast_str_set_va except for an addition argument, append.
952  * If append is non-zero, this will append to the current string instead of
953  * writing over it.
954  *
955  * AST_DYNSTR_BUILD_RETRY is a legacy define.  It should probably never
956  * again be used.
957  *
958  * A return of AST_DYNSTR_BUILD_FAILED indicates a memory allocation error.
959  *
960  * A return value greater than or equal to zero indicates the number of
961  * characters that have been written, not including the terminating '\0'.
962  * In the append case, this only includes the number of characters appended.
963  *
964  * \note This function should never need to be called directly.  It should
965  *       through calling one of the other functions or macros defined in this
966  *       file.
967  */
968 #ifdef __AST_DEBUG_MALLOC
969 int __attribute__((format(printf, 4, 0))) __ast_debug_str_helper(struct ast_str **buf, ssize_t max_len,
970                                                            int append, const char *fmt, va_list ap, const char *file, int lineno, const char *func);
971 #define __ast_str_helper(a,b,c,d,e)     __ast_debug_str_helper(a,b,c,d,e,__FILE__,__LINE__,__PRETTY_FUNCTION__)
972 #else
973 int __attribute__((format(printf, 4, 0))) __ast_str_helper(struct ast_str **buf, ssize_t max_len,
974                                                            int append, const char *fmt, va_list ap);
975 #endif
976 char *__ast_str_helper2(struct ast_str **buf, ssize_t max_len,
977         const char *src, size_t maxsrc, int append, int escapecommas);
978
979 /*!
980  * \brief Set a dynamic string from a va_list
981  *
982  * \param buf This is the address of a pointer to a struct ast_str.
983  *      If it is retrieved using ast_str_thread_get, the
984         struct ast_threadstorage pointer will need to
985  *      be updated in the case that the buffer has to be reallocated to
986  *      accommodate a longer string than what it currently has space for.
987  * \param max_len This is the maximum length to allow the string buffer to grow
988  *      to.  If this is set to 0, then there is no maximum length.
989  * \param fmt This is the format string (printf style)
990  * \param ap This is the va_list
991  *
992  * \return The return value of this function is the same as that of the printf
993  *         family of functions.
994  *
995  * Example usage (the first part is only for thread-local storage)
996  * \code
997  * AST_THREADSTORAGE(my_str, my_str_init);
998  * #define MY_STR_INIT_SIZE   128
999  * ...
1000  * void my_func(const char *fmt, ...)
1001  * {
1002  *      struct ast_str *buf;
1003  *      va_list ap;
1004  *
1005  *      if (!(buf = ast_str_thread_get(&my_str, MY_STR_INIT_SIZE)))
1006  *           return;
1007  *      ...
1008  *      va_start(fmt, ap);
1009  *      ast_str_set_va(&buf, 0, fmt, ap);
1010  *      va_end(ap);
1011  * 
1012  *      printf("This is the string we just built: %s\n", buf->str);
1013  *      ...
1014  * }
1015  * \endcode
1016  *
1017  * \note Care should be taken when using this function. The function can
1018  * result in reallocating the ast_str. If a pointer to the ast_str is passed
1019  * by value to a function that calls ast_str_set_va(), then the original ast_str
1020  * pointer may be invalidated due to a reallocation.
1021  *
1022  */
1023 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),
1024 {
1025         return __ast_str_helper(buf, max_len, 0, fmt, ap);
1026 }
1027 )
1028
1029 /*!
1030  * \brief Append to a dynamic string using a va_list
1031  *
1032  * Same as ast_str_set_va(), but append to the current content.
1033  *
1034  * \note Care should be taken when using this function. The function can
1035  * result in reallocating the ast_str. If a pointer to the ast_str is passed
1036  * by value to a function that calls ast_str_append_va(), then the original ast_str
1037  * pointer may be invalidated due to a reallocation.
1038  *
1039  * \param buf, max_len, fmt, ap
1040  */
1041 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),
1042 {
1043         return __ast_str_helper(buf, max_len, 1, fmt, ap);
1044 }
1045 )
1046
1047 /*!\brief Set a dynamic string to a non-NULL terminated substring. */
1048 AST_INLINE_API(char *ast_str_set_substr(struct ast_str **buf, ssize_t maxlen, const char *src, size_t maxsrc),
1049 {
1050         return __ast_str_helper2(buf, maxlen, src, maxsrc, 0, 0);
1051 }
1052 )
1053
1054 /*!\brief Append a non-NULL terminated substring to the end of a dynamic string. */
1055 AST_INLINE_API(char *ast_str_append_substr(struct ast_str **buf, ssize_t maxlen, const char *src, size_t maxsrc),
1056 {
1057         return __ast_str_helper2(buf, maxlen, src, maxsrc, 1, 0);
1058 }
1059 )
1060
1061 /*!\brief Set a dynamic string to a non-NULL terminated substring, with escaping of commas. */
1062 AST_INLINE_API(char *ast_str_set_escapecommas(struct ast_str **buf, ssize_t maxlen, const char *src, size_t maxsrc),
1063 {
1064         return __ast_str_helper2(buf, maxlen, src, maxsrc, 0, 1);
1065 }
1066 )
1067
1068 /*!\brief Append a non-NULL terminated substring to the end of a dynamic string, with escaping of commas. */
1069 AST_INLINE_API(char *ast_str_append_escapecommas(struct ast_str **buf, ssize_t maxlen, const char *src, size_t maxsrc),
1070 {
1071         return __ast_str_helper2(buf, maxlen, src, maxsrc, 1, 1);
1072 }
1073 )
1074
1075 /*!
1076  * \brief Set a dynamic string using variable arguments
1077  *
1078  * \note Care should be taken when using this function. The function can
1079  * result in reallocating the ast_str. If a pointer to the ast_str is passed
1080  * by value to a function that calls ast_str_set(), then the original ast_str
1081  * pointer may be invalidated due to a reallocation.
1082  *
1083  * \param buf This is the address of a pointer to a struct ast_str which should
1084  *      have been retrieved using ast_str_thread_get.  It will need to
1085  *      be updated in the case that the buffer has to be reallocated to
1086  *      accomodate a longer string than what it currently has space for.
1087  * \param max_len This is the maximum length to allow the string buffer to grow
1088  *      to.  If this is set to 0, then there is no maximum length.
1089  *      If set to -1, we are bound to the current maximum length.
1090  * \param fmt This is the format string (printf style)
1091  *
1092  * \return The return value of this function is the same as that of the printf
1093  *         family of functions.
1094  *
1095  * All the rest is the same as ast_str_set_va()
1096  */
1097 AST_INLINE_API(
1098 int __attribute__((format(printf, 3, 4))) ast_str_set(
1099         struct ast_str **buf, ssize_t max_len, const char *fmt, ...),
1100 {
1101         int res;
1102         va_list ap;
1103
1104         va_start(ap, fmt);
1105         res = ast_str_set_va(buf, max_len, fmt, ap);
1106         va_end(ap);
1107
1108         return res;
1109 }
1110 )
1111
1112 /*!
1113  * \brief Append to a thread local dynamic string
1114  *
1115  * \note Care should be taken when using this function. The function can
1116  * result in reallocating the ast_str. If a pointer to the ast_str is passed
1117  * by value to a function that calls ast_str_append(), then the original ast_str
1118  * pointer may be invalidated due to a reallocation.
1119  *
1120  * The arguments, return values, and usage of this function are the same as
1121  * ast_str_set(), but the new data is appended to the current value.
1122  */
1123 AST_INLINE_API(
1124 int __attribute__((format(printf, 3, 4))) ast_str_append(
1125         struct ast_str **buf, ssize_t max_len, const char *fmt, ...),
1126 {
1127         int res;
1128         va_list ap;
1129
1130         va_start(ap, fmt);
1131         res = ast_str_append_va(buf, max_len, fmt, ap);
1132         va_end(ap);
1133
1134         return res;
1135 }
1136 )
1137
1138 /*!
1139  * \brief Check if a string is only digits
1140  *
1141  * \retval 1 The string contains only digits
1142  * \retval 0 The string contains non-digit characters
1143  */
1144 AST_INLINE_API(
1145 int ast_check_digits(const char *arg),
1146 {
1147         while (*arg) {
1148                 if (*arg < '0' || *arg > '9') {
1149                         return 0;
1150                 }
1151                 arg++;
1152         }
1153         return 1;
1154 }
1155 )
1156
1157 /*!
1158  * \brief Convert the tech portion of a device string to upper case
1159  *
1160  * \retval dev_str Returns the char* passed in for convenience
1161  */
1162 AST_INLINE_API(
1163 char *ast_tech_to_upper(char *dev_str),
1164 {
1165         char *pos;
1166         if (!dev_str || !strchr(dev_str, '/')) {
1167                 return dev_str;
1168         }
1169
1170         for (pos = dev_str; *pos && *pos != '/'; pos++) {
1171                 *pos = toupper(*pos);
1172         }
1173         return dev_str;
1174 }
1175 )
1176
1177 /*!
1178  * \brief Restrict hash value range
1179  *
1180  * \details
1181  * Hash values used all over asterisk are expected to be non-negative
1182  * (signed) int values.  This function restricts an unsigned int hash
1183  * value to the positive half of the (signed) int values.
1184  */
1185 static force_inline int attribute_pure ast_str_hash_restrict(unsigned int hash)
1186 {
1187         return (int) (hash & (unsigned int) INT_MAX);
1188 }
1189
1190 /*!
1191  * \brief Compute a hash value on a string
1192  *
1193  * This famous hash algorithm was written by Dan Bernstein and is
1194  * commonly used.
1195  *
1196  * http://www.cse.yorku.ca/~oz/hash.html
1197  */
1198 static force_inline int attribute_pure ast_str_hash(const char *str)
1199 {
1200         unsigned int hash = 5381;
1201
1202         while (*str) {
1203                 hash = hash * 33 ^ (unsigned char) *str++;
1204         }
1205
1206         return ast_str_hash_restrict(hash);
1207 }
1208
1209 /*!
1210  * \brief Compute a hash value on a string
1211  *
1212  * \param[in] str The string to add to the hash
1213  * \param[in] seed The hash value to start with
1214  *
1215  * \details
1216  * This version of the function is for when you need to compute a
1217  * string hash of more than one string.
1218  *
1219  * This famous hash algorithm was written by Dan Bernstein and is
1220  * commonly used.
1221  *
1222  * \sa http://www.cse.yorku.ca/~oz/hash.html
1223  */
1224 static force_inline int ast_str_hash_add(const char *str, int seed)
1225 {
1226         unsigned int hash = (unsigned int) seed;
1227
1228         while (*str) {
1229                 hash = hash * 33 ^ (unsigned char) *str++;
1230         }
1231
1232         return ast_str_hash_restrict(hash);
1233 }
1234
1235 /*!
1236  * \brief Compute a hash value on a case-insensitive string
1237  *
1238  * Uses the same hash algorithm as ast_str_hash, but converts
1239  * all characters to lowercase prior to computing a hash. This
1240  * allows for easy case-insensitive lookups in a hash table.
1241  */
1242 static force_inline int attribute_pure ast_str_case_hash(const char *str)
1243 {
1244         unsigned int hash = 5381;
1245
1246         while (*str) {
1247                 hash = hash * 33 ^ (unsigned char) tolower(*str++);
1248         }
1249
1250         return ast_str_hash_restrict(hash);
1251 }
1252
1253 /*!
1254  * \brief Convert a string to all lower-case
1255  *
1256  * \param str The string to be converted to lower case
1257  *
1258  * \retval str for convenience
1259  */
1260 static force_inline char *attribute_pure ast_str_to_lower(char *str)
1261 {
1262         char *str_orig = str;
1263         if (!str) {
1264                 return str;
1265         }
1266
1267         for (; *str; ++str) {
1268                 *str = tolower(*str);
1269         }
1270
1271         return str_orig;
1272 }
1273
1274 /*!
1275  * \brief Convert a string to all upper-case
1276  *
1277  * \param str The string to be converted to upper case
1278  *
1279  * \retval str for convenience
1280  */
1281 static force_inline char *attribute_pure ast_str_to_upper(char *str)
1282 {
1283         char *str_orig = str;
1284         if (!str) {
1285                 return str;
1286         }
1287
1288         for (; *str; ++str) {
1289                 *str = toupper(*str);
1290         }
1291
1292         return str_orig;
1293 }
1294
1295 /*!
1296  * \since 12
1297  * \brief Allocates a hash container for bare strings
1298  *
1299  * \param buckets The number of buckets to use for the hash container
1300  *
1301  * \retval AO2 container for strings
1302  * \retval NULL if allocation failed
1303  */
1304 #define ast_str_container_alloc(buckets) ast_str_container_alloc_options(AO2_ALLOC_OPT_LOCK_MUTEX, buckets)
1305
1306 /*!
1307  * \since 12
1308  * \brief Allocates a hash container for bare strings
1309  *
1310  * \param opts Options to be provided to the container
1311  * \param buckets The number of buckets to use for the hash container
1312  *
1313  * \retval AO2 container for strings
1314  * \retval NULL if allocation failed
1315  */
1316 //struct ao2_container *ast_str_container_alloc_options(enum ao2_container_opts opts, int buckets);
1317 struct ao2_container *ast_str_container_alloc_options(enum ao2_alloc_opts opts, int buckets);
1318
1319 /*!
1320  * \since 12
1321  * \brief Adds a string to a string container allocated by ast_str_container_alloc
1322  *
1323  * \param str_container The container to which to add a string
1324  * \param add The string to add to the container
1325  *
1326  * \retval zero on success
1327  * \retval non-zero if the operation failed
1328  */
1329 int ast_str_container_add(struct ao2_container *str_container, const char *add);
1330
1331 /*!
1332  * \since 12
1333  * \brief Removes a string from a string container allocated by ast_str_container_alloc
1334  *
1335  * \param str_container The container from which to remove a string
1336  * \param remove The string to remove from the container
1337  */
1338 void ast_str_container_remove(struct ao2_container *str_container, const char *remove);
1339
1340 /*!
1341  * \brief Create a pseudo-random string of a fixed length.
1342  *
1343  * This function is useful for generating a string whose randomness
1344  * does not need to be across all time and space, does not need to
1345  * be cryptographically secure, and needs to fit in a limited space.
1346  *
1347  * This function will write a null byte at the final position
1348  * in the buffer (buf[size - 1]). So if you pass in a size of
1349  * 10, then this will generate a random 9-character string.
1350  *
1351  * \param buf Buffer to write random string into.
1352  * \param size The size of the buffer.
1353  * \return A pointer to buf
1354  */
1355 char *ast_generate_random_string(char *buf, size_t size);
1356
1357 /*!
1358  * \brief Compares 2 strings using realtime-style operators
1359  * \since 13.9.0
1360  *
1361  * \param left The left side of the equation
1362  * \param op The operator to apply
1363  * \param right The right side of the equation
1364  *
1365  * \retval 1 matches
1366  * \retval 0 doesn't match
1367  *
1368  * \details
1369  *
1370  * Operators:
1371  *      "=", "!=", "<", "<=", ">", ">=":
1372  *         If both left and right can be converted to float, then they will be
1373  *         compared as such. Otherwise the result will be derived from strcmp(left, right).
1374  * "regex":
1375  *     The right value will be compiled as a regular expression and matched against the left
1376  *     value.
1377  * "like":
1378  *     Any '%' character in the right value will be converted to '.*' and the resulting
1379  *     string will be handled as a regex.
1380  * NULL , "":
1381  *     If the right value starts and ends with a '/' then it will be processed as a regex.
1382  *     Otherwise, same as "=".
1383  */
1384 int ast_strings_match(const char *left, const char *op, const char *right);
1385
1386 /*!
1387  * \brief Read lines from a string buffer
1388  * \since 13.18.0
1389  *
1390  * \param buffer [IN/OUT] A pointer to a char * string with either Unix or Windows line endings
1391  *
1392  * \return The "next" line
1393  *
1394  * \warning The original string and *buffer will be modified.
1395  *
1396  * \details
1397  * Both '\n' and '\r\n' are treated as single delimiters but consecutive occurrances of
1398  * the delimiters are NOT considered to be a single delimiter.  This preserves blank
1399  * lines in the input.
1400  *
1401  * MacOS line endings ('\r') are not supported at this time.
1402  *
1403  */
1404 char *ast_read_line_from_buffer(char **buffer);
1405
1406 #endif /* _ASTERISK_STRINGS_H */