Clean up doxygen warnings
[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
30 #include "asterisk/utils.h"
31 #include "asterisk/threadstorage.h"
32
33 #if defined(DEBUG_OPAQUE)
34 #define __AST_STR_USED used2
35 #define __AST_STR_LEN len2
36 #define __AST_STR_STR str2
37 #define __AST_STR_TS ts2
38 #else
39 #define __AST_STR_USED used
40 #define __AST_STR_LEN len
41 #define __AST_STR_STR str
42 #define __AST_STR_TS ts
43 #endif
44
45 /* You may see casts in this header that may seem useless but they ensure this file is C++ clean */
46
47 #define AS_OR(a,b)      (a && ast_str_strlen(a)) ? ast_str_buffer(a) : (b)
48
49 #ifdef AST_DEVMODE
50 #define ast_strlen_zero(foo)    _ast_strlen_zero(foo, __FILE__, __PRETTY_FUNCTION__, __LINE__)
51 static force_inline int _ast_strlen_zero(const char *s, const char *file, const char *function, int line)
52 {
53         if (!s || (*s == '\0')) {
54                 return 1;
55         }
56         if (!strcmp(s, "(null)")) {
57                 ast_log(__LOG_WARNING, file, line, function, "Possible programming error: \"(null)\" is not NULL!\n");
58         }
59         return 0;
60 }
61
62 #else
63 static force_inline int attribute_pure ast_strlen_zero(const char *s)
64 {
65         return (!s || (*s == '\0'));
66 }
67 #endif
68
69 #ifdef SENSE_OF_HUMOR
70 #define ast_strlen_real(a)      (a) ? strlen(a) : 0
71 #define ast_strlen_imaginary(a) ast_random()
72 #endif
73
74 /*! \brief returns the equivalent of logic or for strings:
75  * first one if not empty, otherwise second one.
76  */
77 #define S_OR(a, b) ({typeof(&((a)[0])) __x = (a); ast_strlen_zero(__x) ? (b) : __x;})
78
79 /*! \brief returns the equivalent of logic or for strings, with an additional boolean check:
80  * second one if not empty and first one is true, otherwise third one.
81  * example: S_COR(usewidget, widget, "<no widget>")
82  */
83 #define S_COR(a, b, c) ({typeof(&((b)[0])) __x = (b); (a) && !ast_strlen_zero(__x) ? (__x) : (c);})
84
85 /*!
86   \brief Gets a pointer to the first non-whitespace character in a string.
87   \param str the input string
88   \return a pointer to the first non-whitespace character
89  */
90 AST_INLINE_API(
91 char * attribute_pure ast_skip_blanks(const char *str),
92 {
93         while (*str && ((unsigned char) *str) < 33)
94                 str++;
95         return (char *) str;
96 }
97 )
98
99 /*!
100   \brief Trims trailing whitespace characters from a string.
101   \param str the input string
102   \return a pointer to the modified string
103  */
104 AST_INLINE_API(
105 char *ast_trim_blanks(char *str),
106 {
107         char *work = str;
108
109         if (work) {
110                 work += strlen(work) - 1;
111                 /* It's tempting to only want to erase after we exit this loop, 
112                    but since ast_trim_blanks *could* receive a constant string
113                    (which we presumably wouldn't have to touch), we shouldn't
114                    actually set anything unless we must, and it's easier just
115                    to set each position to \0 than to keep track of a variable
116                    for it */
117                 while ((work >= str) && ((unsigned char) *work) < 33)
118                         *(work--) = '\0';
119         }
120         return str;
121 }
122 )
123
124 /*!
125   \brief Gets a pointer to first whitespace character in a string.
126   \param str the input string
127   \return a pointer to the first whitespace character
128  */
129 AST_INLINE_API(
130 char * attribute_pure ast_skip_nonblanks(const char *str),
131 {
132         while (*str && ((unsigned char) *str) > 32)
133                 str++;
134         return (char *) str;
135 }
136 )
137   
138 /*!
139   \brief Strip leading/trailing whitespace from a string.
140   \param s The string to be stripped (will be modified).
141   \return The stripped string.
142
143   This functions strips all leading and trailing whitespace
144   characters from the input string, and returns a pointer to
145   the resulting string. The string is modified in place.
146 */
147 AST_INLINE_API(
148 char *ast_strip(char *s),
149 {
150         if ((s = ast_skip_blanks(s))) {
151                 ast_trim_blanks(s);
152         }
153         return s;
154
155 )
156
157 /*!
158   \brief Strip leading/trailing whitespace and quotes from a string.
159   \param s The string to be stripped (will be modified).
160   \param beg_quotes The list of possible beginning quote characters.
161   \param end_quotes The list of matching ending quote characters.
162   \return The stripped string.
163
164   This functions strips all leading and trailing whitespace
165   characters from the input string, and returns a pointer to
166   the resulting string. The string is modified in place.
167
168   It can also remove beginning and ending quote (or quote-like)
169   characters, in matching pairs. If the first character of the
170   string matches any character in beg_quotes, and the last
171   character of the string is the matching character in
172   end_quotes, then they are removed from the string.
173
174   Examples:
175   \code
176   ast_strip_quoted(buf, "\"", "\"");
177   ast_strip_quoted(buf, "'", "'");
178   ast_strip_quoted(buf, "[{(", "]})");
179   \endcode
180  */
181 char *ast_strip_quoted(char *s, const char *beg_quotes, const char *end_quotes);
182
183 /*!
184   \brief Strip backslash for "escaped" semicolons, 
185         the string to be stripped (will be modified).
186   \return The stripped string.
187  */
188 char *ast_unescape_semicolon(char *s);
189
190 /*!
191   \brief Convert some C escape sequences  \verbatim (\b\f\n\r\t) \endverbatim into the
192         equivalent characters. The string to be converted (will be modified).
193   \return The converted string.
194  */
195 char *ast_unescape_c(char *s);
196
197 /*!
198   \brief Size-limited null-terminating string copy.
199   \param dst The destination buffer.
200   \param src The source string
201   \param size The size of the destination buffer
202   \return Nothing.
203
204   This is similar to \a strncpy, with two important differences:
205     - the destination buffer will \b always be null-terminated
206     - the destination buffer is not filled with zeros past the copied string length
207   These differences make it slightly more efficient, and safer to use since it will
208   not leave the destination buffer unterminated. There is no need to pass an artificially
209   reduced buffer size to this function (unlike \a strncpy), and the buffer does not need
210   to be initialized to zeroes prior to calling this function.
211 */
212 AST_INLINE_API(
213 void ast_copy_string(char *dst, const char *src, size_t size),
214 {
215         while (*src && size) {
216                 *dst++ = *src++;
217                 size--;
218         }
219         if (__builtin_expect(!size, 0))
220                 dst--;
221         *dst = '\0';
222 }
223 )
224
225 /*!
226   \brief Build a string in a buffer, designed to be called repeatedly
227   
228   \note This method is not recommended. New code should use ast_str_*() instead.
229
230   This is a wrapper for snprintf, that properly handles the buffer pointer
231   and buffer space available.
232
233   \param buffer current position in buffer to place string into (will be updated on return)
234   \param space remaining space in buffer (will be updated on return)
235   \param fmt printf-style format string
236   \retval 0 on success
237   \retval non-zero on failure.
238 */
239 int ast_build_string(char **buffer, size_t *space, const char *fmt, ...) __attribute__((format(printf, 3, 4)));
240
241 /*!
242   \brief Build a string in a buffer, designed to be called repeatedly
243   
244   This is a wrapper for snprintf, that properly handles the buffer pointer
245   and buffer space available.
246
247   \return 0 on success, non-zero on failure.
248   \param buffer current position in buffer to place string into (will be updated on return)
249   \param space remaining space in buffer (will be updated on return)
250   \param fmt printf-style format string
251   \param ap varargs list of arguments for format
252 */
253 int ast_build_string_va(char **buffer, size_t *space, const char *fmt, va_list ap) __attribute__((format(printf, 3, 0)));
254
255 /*!
256  * \brief Given a string regex_string in the form of "/regex/", convert it into the form of "regex"
257  *
258  * This function will trim one leading / and one trailing / from a given input string
259  * ast_str regex_pattern must be preallocated before calling this function
260  *
261  * \return 0 on success, non-zero on failure.
262  * \return 1 if we only stripped a leading /
263  * \return 2 if we only stripped a trailing /
264  * \return 3 if we did not strip any / characters
265  * \param regex_string  the string containing /regex/
266  * \param regex_pattern the destination ast_str which will contain "regex" after execution
267  */
268 int ast_regex_string_to_regex_pattern(const char *regex_string, struct ast_str **regex_pattern);
269
270 /*!
271  * \brief Make sure something is true.
272  * Determine if a string containing a boolean value is "true".
273  * This function checks to see whether a string passed to it is an indication of an "true" value.
274  * It checks to see if the string is "yes", "true", "y", "t", "on" or "1".
275  *
276  * \retval 0 if val is a NULL pointer.
277  * \retval -1 if "true".
278  * \retval 0 otherwise.
279  */
280 int attribute_pure ast_true(const char *val);
281
282 /*! 
283  * \brief Make sure something is false.
284  * Determine if a string containing a boolean value is "false".
285  * This function checks to see whether a string passed to it is an indication of an "false" value.  
286  * It checks to see if the string is "no", "false", "n", "f", "off" or "0".  
287  *
288  * \retval 0 if val is a NULL pointer.
289  * \retval -1 if "true".
290  * \retval 0 otherwise.
291  */
292 int attribute_pure ast_false(const char *val);
293
294 /*
295  *  \brief Join an array of strings into a single string.
296  * \param s the resulting string buffer
297  * \param len the length of the result buffer, s
298  * \param w an array of strings to join.
299  *
300  * This function will join all of the strings in the array 'w' into a single
301  * string.  It will also place a space in the result buffer in between each
302  * string from 'w'.
303 */
304 void ast_join(char *s, size_t len, const char * const w[]);
305
306 /*
307   \brief Parse a time (integer) string.
308   \param src String to parse
309   \param dst Destination
310   \param _default Value to use if the string does not contain a valid time
311   \param consumed The number of characters 'consumed' in the string by the parse (see 'man sscanf' for details)
312   \retval 0 on success
313   \retval non-zero on failure.
314 */
315 int ast_get_time_t(const char *src, time_t *dst, time_t _default, int *consumed);
316
317 /*
318   \brief Parse a time (float) string.
319   \param src String to parse
320   \param dst Destination
321   \param _default Value to use if the string does not contain a valid time
322   \param consumed The number of characters 'consumed' in the string by the parse (see 'man sscanf' for details)
323   \return zero on success, non-zero on failure
324 */
325 int ast_get_timeval(const char *src, struct timeval *tv, struct timeval _default, int *consumed);
326
327 /*!
328  * Support for dynamic strings.
329  *
330  * A dynamic string is just a C string prefixed by a few control fields
331  * that help setting/appending/extending it using a printf-like syntax.
332  *
333  * One should never declare a variable with this type, but only a pointer
334  * to it, e.g.
335  *
336  *      struct ast_str *ds;
337  *
338  * The pointer can be initialized with the following:
339  *
340  *      ds = ast_str_create(init_len);
341  *              creates a malloc()'ed dynamic string;
342  *
343  *      ds = ast_str_alloca(init_len);
344  *              creates a string on the stack (not very dynamic!).
345  *
346  *      ds = ast_str_thread_get(ts, init_len)
347  *              creates a malloc()'ed dynamic string associated to
348  *              the thread-local storage key ts
349  *
350  * Finally, the string can be manipulated with the following:
351  *
352  *      ast_str_set(&buf, max_len, fmt, ...)
353  *      ast_str_append(&buf, max_len, fmt, ...)
354  *
355  * and their varargs variant
356  *
357  *      ast_str_set_va(&buf, max_len, ap)
358  *      ast_str_append_va(&buf, max_len, ap)
359  *
360  * \param max_len The maximum allowed capacity of the ast_str. Note that
361  *  if the value of max_len is less than the current capacity of the
362  *  ast_str (as returned by ast_str_size), then the parameter is effectively
363  *  ignored.
364  *      0 means unlimited, -1 means "at most the available space"
365  *
366  * \return All the functions return <0 in case of error, or the
367  *      length of the string added to the buffer otherwise. Note that
368  *      in most cases where an error is returned, characters ARE written
369  *      to the ast_str.
370  */
371
372 /*! \brief The descriptor of a dynamic string
373  *  XXX storage will be optimized later if needed
374  * We use the ts field to indicate the type of storage.
375  * Three special constants indicate malloc, ast_alloca() or static
376  * variables, all other values indicate a
377  * struct ast_threadstorage pointer.
378  */
379 struct ast_str {
380         size_t __AST_STR_LEN;                   /*!< The current maximum length of the string */
381         size_t __AST_STR_USED;                  /*!< Amount of space used */
382         struct ast_threadstorage *__AST_STR_TS; /*!< What kind of storage is this ? */
383 #define DS_MALLOC       ((struct ast_threadstorage *)1)
384 #define DS_ALLOCA       ((struct ast_threadstorage *)2)
385 #define DS_STATIC       ((struct ast_threadstorage *)3) /* not supported yet */
386         char __AST_STR_STR[0];                  /*!< The string buffer */
387 };
388
389 /*!
390  * \brief Create a malloc'ed dynamic length string
391  *
392  * \param init_len This is the initial length of the string buffer
393  *
394  * \return This function returns a pointer to the dynamic string length.  The
395  *         result will be NULL in the case of a memory allocation error.
396  *
397  * \note The result of this function is dynamically allocated memory, and must
398  *       be free()'d after it is no longer needed.
399  */
400 #if (defined(MALLOC_DEBUG) && !defined(STANDALONE))
401 #define ast_str_create(a)       _ast_str_create(a,__FILE__,__LINE__,__PRETTY_FUNCTION__)
402 AST_INLINE_API(
403 struct ast_str * attribute_malloc _ast_str_create(size_t init_len,
404                 const char *file, int lineno, const char *func),
405 {
406         struct ast_str *buf;
407
408         buf = (struct ast_str *)__ast_calloc(1, sizeof(*buf) + init_len, file, lineno, func);
409         if (buf == NULL)
410                 return NULL;
411
412         buf->__AST_STR_LEN = init_len;
413         buf->__AST_STR_USED = 0;
414         buf->__AST_STR_TS = DS_MALLOC;
415
416         return buf;
417 }
418 )
419 #else
420 AST_INLINE_API(
421 struct ast_str * attribute_malloc ast_str_create(size_t init_len),
422 {
423         struct ast_str *buf;
424
425         buf = (struct ast_str *)ast_calloc(1, sizeof(*buf) + init_len);
426         if (buf == NULL)
427                 return NULL;
428
429         buf->__AST_STR_LEN = init_len;
430         buf->__AST_STR_USED = 0;
431         buf->__AST_STR_TS = DS_MALLOC;
432
433         return buf;
434 }
435 )
436 #endif
437
438 /*! \brief Reset the content of a dynamic string.
439  * Useful before a series of ast_str_append.
440  */
441 AST_INLINE_API(
442 void ast_str_reset(struct ast_str *buf),
443 {
444         if (buf) {
445                 buf->__AST_STR_USED = 0;
446                 if (buf->__AST_STR_LEN) {
447                         buf->__AST_STR_STR[0] = '\0';
448                 }
449         }
450 }
451 )
452
453 /*! \brief Update the length of the buffer, after using ast_str merely as a buffer.
454  *  \param buf A pointer to the ast_str string.
455  */
456 AST_INLINE_API(
457 void ast_str_update(struct ast_str *buf),
458 {
459         buf->__AST_STR_USED = strlen(buf->__AST_STR_STR);
460 }
461 )
462
463 /*! \brief Trims trailing whitespace characters from an ast_str string.
464  *  \param buf A pointer to the ast_str string.
465  */
466 AST_INLINE_API(
467 void ast_str_trim_blanks(struct ast_str *buf),
468 {
469         if (!buf) {
470                 return;
471         }
472         while (buf->__AST_STR_USED && buf->__AST_STR_STR[buf->__AST_STR_USED - 1] < 33) {
473                 buf->__AST_STR_STR[--(buf->__AST_STR_USED)] = '\0';
474         }
475 }
476 )
477
478 /*!\brief Returns the current length of the string stored within buf.
479  * \param buf A pointer to the ast_str structure.
480  */
481 AST_INLINE_API(
482 size_t attribute_pure ast_str_strlen(const struct ast_str *buf),
483 {
484         return buf->__AST_STR_USED;
485 }
486 )
487
488 /*!\brief Returns the current maximum length (without reallocation) of the current buffer.
489  * \param buf A pointer to the ast_str structure.
490  * \retval Current maximum length of the buffer.
491  */
492 AST_INLINE_API(
493 size_t attribute_pure ast_str_size(const struct ast_str *buf),
494 {
495         return buf->__AST_STR_LEN;
496 }
497 )
498
499 /*!\brief Returns the string buffer within the ast_str buf.
500  * \param buf A pointer to the ast_str structure.
501  * \retval A pointer to the enclosed string.
502  */
503 AST_INLINE_API(
504 char * attribute_pure ast_str_buffer(const struct ast_str *buf),
505 {
506         /* for now, cast away the const qualifier on the pointer
507          * being returned; eventually, it should become truly const
508          * and only be modified via accessor functions
509          */
510         return (char *) buf->__AST_STR_STR;
511 }
512 )
513
514 /*!\brief Truncates the enclosed string to the given length.
515  * \param buf A pointer to the ast_str structure.
516  * \param len Maximum length of the string. If len is larger than the
517  *        current maximum length, things will explode. If it is negative
518  *        at most -len characters will be trimmed off the end.
519  * \retval A pointer to the resulting string.
520  */
521 AST_INLINE_API(
522 char *ast_str_truncate(struct ast_str *buf, ssize_t len),
523 {
524         if (len < 0) {
525                 if ((typeof(buf->__AST_STR_USED)) -len >= buf->__AST_STR_USED) {
526                         buf->__AST_STR_USED = 0;
527                 } else {
528                         buf->__AST_STR_USED += len;
529                 }
530         } else {
531                 buf->__AST_STR_USED = len;
532         }
533         buf->__AST_STR_STR[buf->__AST_STR_USED] = '\0';
534         return buf->__AST_STR_STR;
535 }
536 )
537         
538 /*
539  * AST_INLINE_API() is a macro that takes a block of code as an argument.
540  * Using preprocessor #directives in the argument is not supported by all
541  * compilers, and it is a bit of an obfuscation anyways, so avoid it.
542  * As a workaround, define a macro that produces either its argument
543  * or nothing, and use that instead of #ifdef/#endif within the
544  * argument to AST_INLINE_API().
545  */
546 #if defined(DEBUG_THREADLOCALS)
547 #define _DB1(x) x
548 #else
549 #define _DB1(x)
550 #endif
551
552 /*!
553  * Make space in a new string (e.g. to read in data from a file)
554  */
555 #if (defined(MALLOC_DEBUG) && !defined(STANDALONE))
556 AST_INLINE_API(
557 int _ast_str_make_space(struct ast_str **buf, size_t new_len, const char *file, int lineno, const char *function),
558 {
559         struct ast_str *old_buf = *buf;
560
561         if (new_len <= (*buf)->__AST_STR_LEN) 
562                 return 0;       /* success */
563         if ((*buf)->__AST_STR_TS == DS_ALLOCA || (*buf)->__AST_STR_TS == DS_STATIC)
564                 return -1;      /* cannot extend */
565         *buf = (struct ast_str *)__ast_realloc(*buf, new_len + sizeof(struct ast_str), file, lineno, function);
566         if (*buf == NULL) {
567                 *buf = old_buf;
568                 return -1;
569         }
570         if ((*buf)->__AST_STR_TS != DS_MALLOC) {
571                 pthread_setspecific((*buf)->__AST_STR_TS->key, *buf);
572                 _DB1(__ast_threadstorage_object_replace(old_buf, *buf, new_len + sizeof(struct ast_str));)
573         }
574
575         (*buf)->__AST_STR_LEN = new_len;
576         return 0;
577 }
578 )
579 #define ast_str_make_space(a,b) _ast_str_make_space(a,b,__FILE__,__LINE__,__PRETTY_FUNCTION__)
580 #else
581 AST_INLINE_API(
582 int ast_str_make_space(struct ast_str **buf, size_t new_len),
583 {
584         struct ast_str *old_buf = *buf;
585
586         if (new_len <= (*buf)->__AST_STR_LEN) 
587                 return 0;       /* success */
588         if ((*buf)->__AST_STR_TS == DS_ALLOCA || (*buf)->__AST_STR_TS == DS_STATIC)
589                 return -1;      /* cannot extend */
590         *buf = (struct ast_str *)ast_realloc(*buf, new_len + sizeof(struct ast_str));
591         if (*buf == NULL) {
592                 *buf = old_buf;
593                 return -1;
594         }
595         if ((*buf)->__AST_STR_TS != DS_MALLOC) {
596                 pthread_setspecific((*buf)->__AST_STR_TS->key, *buf);
597                 _DB1(__ast_threadstorage_object_replace(old_buf, *buf, new_len + sizeof(struct ast_str));)
598         }
599
600         (*buf)->__AST_STR_LEN = new_len;
601         return 0;
602 }
603 )
604 #endif
605
606 AST_INLINE_API(
607 int ast_str_copy_string(struct ast_str **dst, struct ast_str *src),
608 {
609
610         /* make sure our destination is large enough */
611         if (src->__AST_STR_USED + 1 > (*dst)->__AST_STR_LEN) {
612                 if (ast_str_make_space(dst, src->__AST_STR_USED + 1)) {
613                         return -1;
614                 }
615         }
616
617         memcpy((*dst)->__AST_STR_STR, src->__AST_STR_STR, src->__AST_STR_USED + 1);
618         (*dst)->__AST_STR_USED = src->__AST_STR_USED;
619         return 0;
620 }
621 )
622
623 #define ast_str_alloca(init_len)                        \
624         ({                                              \
625                 struct ast_str *__ast_str_buf;                  \
626                 __ast_str_buf = ast_alloca(sizeof(*__ast_str_buf) + init_len);  \
627                 __ast_str_buf->__AST_STR_LEN = init_len;                        \
628                 __ast_str_buf->__AST_STR_USED = 0;                              \
629                 __ast_str_buf->__AST_STR_TS = DS_ALLOCA;                        \
630                 __ast_str_buf->__AST_STR_STR[0] = '\0';                 \
631                 (__ast_str_buf);                                        \
632         })
633
634 /*!
635  * \brief Retrieve a thread locally stored dynamic string
636  *
637  * \param ts This is a pointer to the thread storage structure declared by using
638  *      the AST_THREADSTORAGE macro.  If declared with 
639  *      AST_THREADSTORAGE(my_buf, my_buf_init), then this argument would be 
640  *      (&my_buf).
641  * \param init_len This is the initial length of the thread's dynamic string. The
642  *      current length may be bigger if previous operations in this thread have
643  *      caused it to increase.
644  *
645  * \return This function will return the thread locally stored dynamic string
646  *         associated with the thread storage management variable passed as the
647  *         first argument.
648  *         The result will be NULL in the case of a memory allocation error.
649  *
650  * Example usage:
651  * \code
652  * AST_THREADSTORAGE(my_str, my_str_init);
653  * #define MY_STR_INIT_SIZE   128
654  * ...
655  * void my_func(const char *fmt, ...)
656  * {
657  *      struct ast_str *buf;
658  *
659  *      if (!(buf = ast_str_thread_get(&my_str, MY_STR_INIT_SIZE)))
660  *           return;
661  *      ...
662  * }
663  * \endcode
664  */
665 #if !defined(DEBUG_THREADLOCALS)
666 AST_INLINE_API(
667 struct ast_str *ast_str_thread_get(struct ast_threadstorage *ts,
668         size_t init_len),
669 {
670         struct ast_str *buf;
671
672         buf = (struct ast_str *)ast_threadstorage_get(ts, sizeof(*buf) + init_len);
673         if (buf == NULL)
674                 return NULL;
675
676         if (!buf->__AST_STR_LEN) {
677                 buf->__AST_STR_LEN = init_len;
678                 buf->__AST_STR_USED = 0;
679                 buf->__AST_STR_TS = ts;
680         }
681
682         return buf;
683 }
684 )
685 #else /* defined(DEBUG_THREADLOCALS) */
686 AST_INLINE_API(
687 struct ast_str *__ast_str_thread_get(struct ast_threadstorage *ts,
688         size_t init_len, const char *file, const char *function, unsigned int line),
689 {
690         struct ast_str *buf;
691
692         buf = (struct ast_str *)__ast_threadstorage_get(ts, sizeof(*buf) + init_len, file, function, line);
693         if (buf == NULL)
694                 return NULL;
695
696         if (!buf->__AST_STR_LEN) {
697                 buf->__AST_STR_LEN = init_len;
698                 buf->__AST_STR_USED = 0;
699                 buf->__AST_STR_TS = ts;
700         }
701
702         return buf;
703 }
704 )
705
706 #define ast_str_thread_get(ts, init_len) __ast_str_thread_get(ts, init_len, __FILE__, __PRETTY_FUNCTION__, __LINE__)
707 #endif /* defined(DEBUG_THREADLOCALS) */
708
709 /*!
710  * \brief Error codes from __ast_str_helper()
711  * The undelying processing to manipulate dynamic string is done
712  * by __ast_str_helper(), which can return a success or a
713  * permanent failure (e.g. no memory).
714  */
715 enum {
716         /*! An error has occurred and the contents of the dynamic string
717          *  are undefined */
718         AST_DYNSTR_BUILD_FAILED = -1,
719         /*! The buffer size for the dynamic string had to be increased, and
720          *  __ast_str_helper() needs to be called again after
721          *  a va_end() and va_start().  This return value is legacy and will
722          *  no longer be used.
723          */
724         AST_DYNSTR_BUILD_RETRY = -2
725 };
726
727 /*!
728  * \brief Core functionality of ast_str_(set|append)_va
729  *
730  * The arguments to this function are the same as those described for
731  * ast_str_set_va except for an addition argument, append.
732  * If append is non-zero, this will append to the current string instead of
733  * writing over it.
734  *
735  * AST_DYNSTR_BUILD_RETRY is a legacy define.  It should probably never
736  * again be used.
737  *
738  * A return of AST_DYNSTR_BUILD_FAILED indicates a memory allocation error.
739  *
740  * A return value greater than or equal to zero indicates the number of
741  * characters that have been written, not including the terminating '\0'.
742  * In the append case, this only includes the number of characters appended.
743  *
744  * \note This function should never need to be called directly.  It should
745  *       through calling one of the other functions or macros defined in this
746  *       file.
747  */
748 #if (defined(MALLOC_DEBUG) && !defined(STANDALONE))
749 int __attribute__((format(printf, 4, 0))) __ast_debug_str_helper(struct ast_str **buf, ssize_t max_len,
750                                                            int append, const char *fmt, va_list ap, const char *file, int lineno, const char *func);
751 #define __ast_str_helper(a,b,c,d,e)     __ast_debug_str_helper(a,b,c,d,e,__FILE__,__LINE__,__PRETTY_FUNCTION__)
752 #else
753 int __attribute__((format(printf, 4, 0))) __ast_str_helper(struct ast_str **buf, ssize_t max_len,
754                                                            int append, const char *fmt, va_list ap);
755 #endif
756 char *__ast_str_helper2(struct ast_str **buf, ssize_t max_len,
757         const char *src, size_t maxsrc, int append, int escapecommas);
758
759 /*!
760  * \brief Set a dynamic string from a va_list
761  *
762  * \param buf This is the address of a pointer to a struct ast_str.
763  *      If it is retrieved using ast_str_thread_get, the
764         struct ast_threadstorage pointer will need to
765  *      be updated in the case that the buffer has to be reallocated to
766  *      accommodate a longer string than what it currently has space for.
767  * \param max_len This is the maximum length to allow the string buffer to grow
768  *      to.  If this is set to 0, then there is no maximum length.
769  * \param fmt This is the format string (printf style)
770  * \param ap This is the va_list
771  *
772  * \return The return value of this function is the same as that of the printf
773  *         family of functions.
774  *
775  * Example usage (the first part is only for thread-local storage)
776  * \code
777  * AST_THREADSTORAGE(my_str, my_str_init);
778  * #define MY_STR_INIT_SIZE   128
779  * ...
780  * void my_func(const char *fmt, ...)
781  * {
782  *      struct ast_str *buf;
783  *      va_list ap;
784  *
785  *      if (!(buf = ast_str_thread_get(&my_str, MY_STR_INIT_SIZE)))
786  *           return;
787  *      ...
788  *      va_start(fmt, ap);
789  *      ast_str_set_va(&buf, 0, fmt, ap);
790  *      va_end(ap);
791  * 
792  *      printf("This is the string we just built: %s\n", buf->str);
793  *      ...
794  * }
795  * \endcode
796  */
797 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),
798 {
799         return __ast_str_helper(buf, max_len, 0, fmt, ap);
800 }
801 )
802
803 /*!
804  * \brief Append to a dynamic string using a va_list
805  *
806  * Same as ast_str_set_va(), but append to the current content.
807  *
808  * \param buf, max_len, fmt, ap
809  */
810 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),
811 {
812         return __ast_str_helper(buf, max_len, 1, fmt, ap);
813 }
814 )
815
816 /*!\brief Set a dynamic string to a non-NULL terminated substring. */
817 AST_INLINE_API(char *ast_str_set_substr(struct ast_str **buf, ssize_t maxlen, const char *src, size_t maxsrc),
818 {
819         return __ast_str_helper2(buf, maxlen, src, maxsrc, 0, 0);
820 }
821 )
822
823 /*!\brief Append a non-NULL terminated substring to the end of a dynamic string. */
824 AST_INLINE_API(char *ast_str_append_substr(struct ast_str **buf, ssize_t maxlen, const char *src, size_t maxsrc),
825 {
826         return __ast_str_helper2(buf, maxlen, src, maxsrc, 1, 0);
827 }
828 )
829
830 /*!\brief Set a dynamic string to a non-NULL terminated substring, with escaping of commas. */
831 AST_INLINE_API(char *ast_str_set_escapecommas(struct ast_str **buf, ssize_t maxlen, const char *src, size_t maxsrc),
832 {
833         return __ast_str_helper2(buf, maxlen, src, maxsrc, 0, 1);
834 }
835 )
836
837 /*!\brief Append a non-NULL terminated substring to the end of a dynamic string, with escaping of commas. */
838 AST_INLINE_API(char *ast_str_append_escapecommas(struct ast_str **buf, ssize_t maxlen, const char *src, size_t maxsrc),
839 {
840         return __ast_str_helper2(buf, maxlen, src, maxsrc, 1, 1);
841 }
842 )
843
844 /*!
845  * \brief Set a dynamic string using variable arguments
846  *
847  * \param buf This is the address of a pointer to a struct ast_str which should
848  *      have been retrieved using ast_str_thread_get.  It will need to
849  *      be updated in the case that the buffer has to be reallocated to
850  *      accomodate a longer string than what it currently has space for.
851  * \param max_len This is the maximum length to allow the string buffer to grow
852  *      to.  If this is set to 0, then there is no maximum length.
853  *      If set to -1, we are bound to the current maximum length.
854  * \param fmt This is the format string (printf style)
855  *
856  * \return The return value of this function is the same as that of the printf
857  *         family of functions.
858  *
859  * All the rest is the same as ast_str_set_va()
860  */
861 AST_INLINE_API(
862 int __attribute__((format(printf, 3, 4))) ast_str_set(
863         struct ast_str **buf, ssize_t max_len, const char *fmt, ...),
864 {
865         int res;
866         va_list ap;
867
868         va_start(ap, fmt);
869         res = ast_str_set_va(buf, max_len, fmt, ap);
870         va_end(ap);
871
872         return res;
873 }
874 )
875
876 /*!
877  * \brief Append to a thread local dynamic string
878  *
879  * The arguments, return values, and usage of this function are the same as
880  * ast_str_set(), but the new data is appended to the current value.
881  */
882 AST_INLINE_API(
883 int __attribute__((format(printf, 3, 4))) ast_str_append(
884         struct ast_str **buf, ssize_t max_len, const char *fmt, ...),
885 {
886         int res;
887         va_list ap;
888
889         va_start(ap, fmt);
890         res = ast_str_append_va(buf, max_len, fmt, ap);
891         va_end(ap);
892
893         return res;
894 }
895 )
896
897 /*!
898  * \brief Check if a string is only digits
899  *
900  * \retval 1 The string contains only digits
901  * \retval 0 The string contains non-digit characters
902  */
903 AST_INLINE_API(
904 int ast_check_digits(const char *arg),
905 {
906         while (*arg) {
907                 if (*arg < '0' || *arg > '9') {
908                         return 0;
909                 }
910                 arg++;
911         }
912         return 1;
913 }
914 )
915
916 /*!
917  * \brief Convert the tech portion of a device string to upper case
918  *
919  * \retval dev_str Returns the char* passed in for convenience
920  */
921 AST_INLINE_API(
922 char *ast_tech_to_upper(char *dev_str),
923 {
924         char *pos;
925         if (!dev_str || !strchr(dev_str, '/')) {
926                 return dev_str;
927         }
928
929         for (pos = dev_str; *pos && *pos != '/'; pos++) {
930                 *pos = toupper(*pos);
931         }
932         return dev_str;
933 }
934 )
935
936 /*!
937  * \brief Compute a hash value on a string
938  *
939  * This famous hash algorithm was written by Dan Bernstein and is
940  * commonly used.
941  *
942  * http://www.cse.yorku.ca/~oz/hash.html
943  */
944 static force_inline int attribute_pure ast_str_hash(const char *str)
945 {
946         int hash = 5381;
947
948         while (*str)
949                 hash = hash * 33 ^ *str++;
950
951         return abs(hash);
952 }
953
954 /*!
955  * \brief Compute a hash value on a string
956  *
957  * \param[in] str The string to add to the hash
958  * \param[in] hash The hash value to add to
959  * 
960  * \details
961  * This version of the function is for when you need to compute a
962  * string hash of more than one string.
963  *
964  * This famous hash algorithm was written by Dan Bernstein and is
965  * commonly used.
966  *
967  * \sa http://www.cse.yorku.ca/~oz/hash.html
968  */
969 static force_inline int ast_str_hash_add(const char *str, int hash)
970 {
971         while (*str)
972                 hash = hash * 33 ^ *str++;
973
974         return abs(hash);
975 }
976
977 /*!
978  * \brief Compute a hash value on a case-insensitive string
979  *
980  * Uses the same hash algorithm as ast_str_hash, but converts
981  * all characters to lowercase prior to computing a hash. This
982  * allows for easy case-insensitive lookups in a hash table.
983  */
984 static force_inline int attribute_pure ast_str_case_hash(const char *str)
985 {
986         int hash = 5381;
987
988         while (*str) {
989                 hash = hash * 33 ^ tolower(*str++);
990         }
991
992         return abs(hash);
993 }
994
995 #endif /* _ASTERISK_STRINGS_H */