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