use some fancy compiler magic (thanks to Matthew Woehlke on the gcc-help mailing...
[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 #include "asterisk/inline_api.h"
27 #include "asterisk/utils.h"
28 #include "asterisk/threadstorage.h"
29
30 /* You may see casts in this header that may seem useless but they ensure this file is C++ clean */
31
32 #ifdef AST_DEVMODE
33 #define ast_strlen_zero(foo)    _ast_strlen_zero(foo, __FILE__, __PRETTY_FUNCTION__, __LINE__)
34 static force_inline int _ast_strlen_zero(const char *s, const char *file, const char *function, int line)
35 {
36         if (!s || (*s == '\0')) {
37                 return 1;
38         }
39         if (!strcmp(s, "(null)")) {
40                 ast_log(__LOG_WARNING, file, line, function, "Possible programming error: \"(null)\" is not NULL!\n");
41         }
42         return 0;
43 }
44
45 #else
46 static force_inline int ast_strlen_zero(const char *s)
47 {
48         return (!s || (*s == '\0'));
49 }
50 #endif
51
52 /*! \brief returns the equivalent of logic or for strings:
53  * first one if not empty, otherwise second one.
54  */
55 #define S_OR(a, b) ({typeof(&((a)[0])) __x = (a); ast_strlen_zero(__x) ? (b) : __x;})
56
57 /*! \brief returns the equivalent of logic or for strings, with an additional boolean check:
58  * second one if not empty and first one is true, otherwise third one.
59  * example: S_COR(usewidget, widget, "<no widget>")
60  */
61 #define S_COR(a, b, c) ({typeof(&((b)[0])) __x = (b); (a) && !ast_strlen_zero(__x) ? (__x) : (c);})
62
63 /*!
64   \brief Gets a pointer to the first non-whitespace character in a string.
65   \param str the input string
66   \return a pointer to the first non-whitespace character
67  */
68 AST_INLINE_API(
69 char *ast_skip_blanks(const char *str),
70 {
71         while (*str && ((unsigned char) *str) < 33)
72                 str++;
73         return (char *)str;
74 }
75 )
76
77 /*!
78   \brief Trims trailing whitespace characters from a string.
79   \param str the input string
80   \return a pointer to the modified string
81  */
82 AST_INLINE_API(
83 char *ast_trim_blanks(char *str),
84 {
85         char *work = str;
86
87         if (work) {
88                 work += strlen(work) - 1;
89                 /* It's tempting to only want to erase after we exit this loop, 
90                    but since ast_trim_blanks *could* receive a constant string
91                    (which we presumably wouldn't have to touch), we shouldn't
92                    actually set anything unless we must, and it's easier just
93                    to set each position to \0 than to keep track of a variable
94                    for it */
95                 while ((work >= str) && ((unsigned char) *work) < 33)
96                         *(work--) = '\0';
97         }
98         return str;
99 }
100 )
101
102 /*!
103   \brief Gets a pointer to first whitespace character in a string.
104   \param str the input string
105   \return a pointer to the first whitespace character
106  */
107 AST_INLINE_API(
108 char *ast_skip_nonblanks(char *str),
109 {
110         while (*str && ((unsigned char) *str) > 32)
111                 str++;
112         return str;
113 }
114 )
115   
116 /*!
117   \brief Strip leading/trailing whitespace from a string.
118   \param s The string to be stripped (will be modified).
119   \return The stripped string.
120
121   This functions strips all leading and trailing whitespace
122   characters from the input string, and returns a pointer to
123   the resulting string. The string is modified in place.
124 */
125 AST_INLINE_API(
126 char *ast_strip(char *s),
127 {
128         s = ast_skip_blanks(s);
129         if (s)
130                 ast_trim_blanks(s);
131         return s;
132
133 )
134
135 /*!
136   \brief Strip leading/trailing whitespace and quotes from a string.
137   \param s The string to be stripped (will be modified).
138   \param beg_quotes The list of possible beginning quote characters.
139   \param end_quotes The list of matching ending quote characters.
140   \return The stripped string.
141
142   This functions strips all leading and trailing whitespace
143   characters from the input string, and returns a pointer to
144   the resulting string. The string is modified in place.
145
146   It can also remove beginning and ending quote (or quote-like)
147   characters, in matching pairs. If the first character of the
148   string matches any character in beg_quotes, and the last
149   character of the string is the matching character in
150   end_quotes, then they are removed from the string.
151
152   Examples:
153   \code
154   ast_strip_quoted(buf, "\"", "\"");
155   ast_strip_quoted(buf, "'", "'");
156   ast_strip_quoted(buf, "[{(", "]})");
157   \endcode
158  */
159 char *ast_strip_quoted(char *s, const char *beg_quotes, const char *end_quotes);
160
161 /*!
162   \brief Strip backslash for "escaped" semicolons, 
163         the string to be stripped (will be modified).
164   \return The stripped string.
165  */
166 char *ast_unescape_semicolon(char *s);
167
168 /*!
169   \brief Convert some C escape sequences  \verbatim (\b\f\n\r\t) \endverbatim into the
170         equivalent characters. The string to be converted (will be modified).
171   \return The converted string.
172  */
173 char *ast_unescape_c(char *s);
174
175 /*!
176   \brief Size-limited null-terminating string copy.
177   \param dst The destination buffer.
178   \param src The source string
179   \param size The size of the destination buffer
180   \return Nothing.
181
182   This is similar to \a strncpy, with two important differences:
183     - the destination buffer will \b always be null-terminated
184     - the destination buffer is not filled with zeros past the copied string length
185   These differences make it slightly more efficient, and safer to use since it will
186   not leave the destination buffer unterminated. There is no need to pass an artificially
187   reduced buffer size to this function (unlike \a strncpy), and the buffer does not need
188   to be initialized to zeroes prior to calling this function.
189 */
190 AST_INLINE_API(
191 void ast_copy_string(char *dst, const char *src, size_t size),
192 {
193         while (*src && size) {
194                 *dst++ = *src++;
195                 size--;
196         }
197         if (__builtin_expect(!size, 0))
198                 dst--;
199         *dst = '\0';
200 }
201 )
202
203
204 /*!
205   \brief Build a string in a buffer, designed to be called repeatedly
206   
207   \note This method is not recommended. New code should use ast_str_*() instead.
208
209   This is a wrapper for snprintf, that properly handles the buffer pointer
210   and buffer space available.
211
212   \param buffer current position in buffer to place string into (will be updated on return)
213   \param space remaining space in buffer (will be updated on return)
214   \param fmt printf-style format string
215   \retval 0 on success
216   \retval non-zero on failure.
217 */
218 int ast_build_string(char **buffer, size_t *space, const char *fmt, ...) __attribute__ ((format (printf, 3, 4)));
219
220 /*!
221   \brief Build a string in a buffer, designed to be called repeatedly
222   
223   This is a wrapper for snprintf, that properly handles the buffer pointer
224   and buffer space available.
225
226   \return 0 on success, non-zero on failure.
227   \param buffer current position in buffer to place string into (will be updated on return)
228   \param space remaining space in buffer (will be updated on return)
229   \param fmt printf-style format string
230   \param ap varargs list of arguments for format
231 */
232 int ast_build_string_va(char **buffer, size_t *space, const char *fmt, va_list ap) __attribute__((format (printf, 3, 0)));
233
234 /*! 
235  * \brief Make sure something is true.
236  * Determine if a string containing a boolean value is "true".
237  * This function checks to see whether a string passed to it is an indication of an "true" value.  
238  * It checks to see if the string is "yes", "true", "y", "t", "on" or "1".  
239  *
240  * \retval 0 if val is a NULL pointer.
241  * \retval -1 if "true".
242  * \retval 0 otherwise.
243  */
244 int ast_true(const char *val);
245
246 /*! 
247  * \brief Make sure something is false.
248  * Determine if a string containing a boolean value is "false".
249  * This function checks to see whether a string passed to it is an indication of an "false" value.  
250  * It checks to see if the string is "no", "false", "n", "f", "off" or "0".  
251  *
252  * \retval 0 if val is a NULL pointer.
253  * \retval -1 if "true".
254  * \retval 0 otherwise.
255  */
256 int ast_false(const char *val);
257
258 /*
259  *  \brief Join an array of strings into a single string.
260  * \param s the resulting string buffer
261  * \param len the length of the result buffer, s
262  * \param w an array of strings to join.
263  *
264  * This function will join all of the strings in the array 'w' into a single
265  * string.  It will also place a space in the result buffer in between each
266  * string from 'w'.
267 */
268 void ast_join(char *s, size_t len, char * const w[]);
269
270 /*
271   \brief Parse a time (integer) string.
272   \param src String to parse
273   \param dst Destination
274   \param _default Value to use if the string does not contain a valid time
275   \param consumed The number of characters 'consumed' in the string by the parse (see 'man sscanf' for details)
276   \retval 0 on success
277   \retval non-zero on failure.
278 */
279 int ast_get_time_t(const char *src, time_t *dst, time_t _default, int *consumed);
280
281 /*
282   \brief Parse a time (float) string.
283   \param src String to parse
284   \param dst Destination
285   \param _default Value to use if the string does not contain a valid time
286   \param consumed The number of characters 'consumed' in the string by the parse (see 'man sscanf' for details)
287   \return zero on success, non-zero on failure
288 */
289 int ast_get_timeval(const char *src, struct timeval *tv, struct timeval _default, int *consumed);
290
291 /*!
292  * Support for dynamic strings.
293  *
294  * A dynamic string is just a C string prefixed by a few control fields
295  * that help setting/appending/extending it using a printf-like syntax.
296  *
297  * One should never declare a variable with this type, but only a pointer
298  * to it, e.g.
299  *
300  *      struct ast_str *ds;
301  *
302  * The pointer can be initialized with the following:
303  *
304  *      ds = ast_str_create(init_len);
305  *              creates a malloc()'ed dynamic string;
306  *
307  *      ds = ast_str_alloca(init_len);
308  *              creates a string on the stack (not very dynamic!).
309  *
310  *      ds = ast_str_thread_get(ts, init_len)
311  *              creates a malloc()'ed dynamic string associated to
312  *              the thread-local storage key ts
313  *
314  * Finally, the string can be manipulated with the following:
315  *
316  *      ast_str_set(&buf, max_len, fmt, ...)
317  *      ast_str_append(&buf, max_len, fmt, ...)
318  *
319  * and their varargs variant
320  *
321  *      ast_str_set_va(&buf, max_len, ap)
322  *      ast_str_append_va(&buf, max_len, ap)
323  *
324  * \param max_len The maximum allowed length, reallocating if needed.
325  *      0 means unlimited, -1 means "at most the available space"
326  *
327  * \return All the functions return <0 in case of error, or the
328  *      length of the string added to the buffer otherwise.
329  */
330
331 /*! \brief The descriptor of a dynamic string
332  *  XXX storage will be optimized later if needed
333  * We use the ts field to indicate the type of storage.
334  * Three special constants indicate malloc, alloca() or static
335  * variables, all other values indicate a
336  * struct ast_threadstorage pointer.
337  */
338 struct ast_str {
339         size_t len;     /*!< The current maximum length of the string */
340         size_t used;    /*!< Amount of space used */
341         struct ast_threadstorage *ts;   /*!< What kind of storage is this ? */
342 #define DS_MALLOC       ((struct ast_threadstorage *)1)
343 #define DS_ALLOCA       ((struct ast_threadstorage *)2)
344 #define DS_STATIC       ((struct ast_threadstorage *)3) /* not supported yet */
345         char str[0];    /*!< The string buffer */
346 };
347
348 /*!
349  * \brief Create a malloc'ed dynamic length string
350  *
351  * \param init_len This is the initial length of the string buffer
352  *
353  * \return This function returns a pointer to the dynamic string length.  The
354  *         result will be NULL in the case of a memory allocation error.
355  *
356  * \note The result of this function is dynamically allocated memory, and must
357  *       be free()'d after it is no longer needed.
358  */
359 AST_INLINE_API(
360 struct ast_str * attribute_malloc ast_str_create(size_t init_len),
361 {
362         struct ast_str *buf;
363
364         buf = (struct ast_str *)ast_calloc(1, sizeof(*buf) + init_len);
365         if (buf == NULL)
366                 return NULL;
367         
368         buf->len = init_len;
369         buf->used = 0;
370         buf->ts = DS_MALLOC;
371
372         return buf;
373 }
374 )
375
376 /*! \brief Reset the content of a dynamic string.
377  * Useful before a series of ast_str_append.
378  */
379 AST_INLINE_API(
380 void ast_str_reset(struct ast_str *buf),
381 {
382         if (buf) {
383                 buf->used = 0;
384                 if (buf->len)
385                         buf->str[0] = '\0';
386         }
387 }
388 )
389
390 /*! \brief Trims trailing whitespace characters from an ast_str string.
391  *  \param buf A pointer to the ast_str string.
392  */
393 AST_INLINE_API(
394 void ast_str_trim_blanks(struct ast_str *buf),
395 {
396         if (!buf) {
397                 return;
398         }
399         while (buf->used && buf->str[buf->used - 1] < 33) {
400                 buf->str[--(buf->used)] = '\0';
401         }
402 }
403 )
404
405 /*
406  * AST_INLINE_API() is a macro that takes a block of code as an argument.
407  * Using preprocessor #directives in the argument is not supported by all
408  * compilers, and it is a bit of an obfuscation anyways, so avoid it.
409  * As a workaround, define a macro that produces either its argument
410  * or nothing, and use that instead of #ifdef/#endif within the
411  * argument to AST_INLINE_API().
412  */
413 #if defined(DEBUG_THREADLOCALS)
414 #define _DB1(x) x
415 #else
416 #define _DB1(x)
417 #endif
418
419 /*!
420  * Make space in a new string (e.g. to read in data from a file)
421  */
422 #if (defined(MALLOC_DEBUG) && !defined(STANDALONE))
423 AST_INLINE_API(
424 int _ast_str_make_space(struct ast_str **buf, size_t new_len, const char *file, int lineno, const char *function),
425 {
426         _DB1(struct ast_str *old_buf = *buf;)
427
428         if (new_len <= (*buf)->len) 
429                 return 0;       /* success */
430         if ((*buf)->ts == DS_ALLOCA || (*buf)->ts == DS_STATIC)
431                 return -1;      /* cannot extend */
432         *buf = (struct ast_str *)__ast_realloc(*buf, new_len + sizeof(struct ast_str), file, lineno, function);
433         if (*buf == NULL) /* XXX watch out, we leak memory here */
434                 return -1;
435         if ((*buf)->ts != DS_MALLOC) {
436                 pthread_setspecific((*buf)->ts->key, *buf);
437                 _DB1(__ast_threadstorage_object_replace(old_buf, *buf, new_len + sizeof(struct ast_str));)
438         }
439
440         (*buf)->len = new_len;
441         return 0;
442 }
443 )
444 #define ast_str_make_space(a,b) _ast_str_make_space(a,b,__FILE__,__LINE__,__PRETTY_FUNCTION__)
445 #else
446 AST_INLINE_API(
447 int ast_str_make_space(struct ast_str **buf, size_t new_len),
448 {
449         _DB1(struct ast_str *old_buf = *buf;)
450
451         if (new_len <= (*buf)->len) 
452                 return 0;       /* success */
453         if ((*buf)->ts == DS_ALLOCA || (*buf)->ts == DS_STATIC)
454                 return -1;      /* cannot extend */
455         *buf = (struct ast_str *)ast_realloc(*buf, new_len + sizeof(struct ast_str));
456         if (*buf == NULL) /* XXX watch out, we leak memory here */
457                 return -1;
458         if ((*buf)->ts != DS_MALLOC) {
459                 pthread_setspecific((*buf)->ts->key, *buf);
460                 _DB1(__ast_threadstorage_object_replace(old_buf, *buf, new_len + sizeof(struct ast_str));)
461         }
462
463         (*buf)->len = new_len;
464         return 0;
465 }
466 )
467 #endif
468
469 #define ast_str_alloca(init_len)                        \
470         ({                                              \
471                 struct ast_str *__ast_str_buf;                  \
472                 __ast_str_buf = alloca(sizeof(*__ast_str_buf) + init_len);      \
473                 __ast_str_buf->len = init_len;                  \
474                 __ast_str_buf->used = 0;                                \
475                 __ast_str_buf->ts = DS_ALLOCA;                  \
476                 __ast_str_buf->str[0] = '\0';                   \
477                 (__ast_str_buf);                                        \
478         })
479
480 /*!
481  * \brief Retrieve a thread locally stored dynamic string
482  *
483  * \param ts This is a pointer to the thread storage structure declared by using
484  *      the AST_THREADSTORAGE macro.  If declared with 
485  *      AST_THREADSTORAGE(my_buf, my_buf_init), then this argument would be 
486  *      (&my_buf).
487  * \param init_len This is the initial length of the thread's dynamic string. The
488  *      current length may be bigger if previous operations in this thread have
489  *      caused it to increase.
490  *
491  * \return This function will return the thread locally stored dynamic string
492  *         associated with the thread storage management variable passed as the
493  *         first argument.
494  *         The result will be NULL in the case of a memory allocation error.
495  *
496  * Example usage:
497  * \code
498  * AST_THREADSTORAGE(my_str, my_str_init);
499  * #define MY_STR_INIT_SIZE   128
500  * ...
501  * void my_func(const char *fmt, ...)
502  * {
503  *      struct ast_str *buf;
504  *
505  *      if (!(buf = ast_str_thread_get(&my_str, MY_STR_INIT_SIZE)))
506  *           return;
507  *      ...
508  * }
509  * \endcode
510  */
511 #if !defined(DEBUG_THREADLOCALS)
512 AST_INLINE_API(
513 struct ast_str *ast_str_thread_get(struct ast_threadstorage *ts,
514         size_t init_len),
515 {
516         struct ast_str *buf;
517
518         buf = (struct ast_str *)ast_threadstorage_get(ts, sizeof(*buf) + init_len);
519         if (buf == NULL)
520                 return NULL;
521         
522         if (!buf->len) {
523                 buf->len = init_len;
524                 buf->used = 0;
525                 buf->ts = ts;
526         }
527
528         return buf;
529 }
530 )
531 #else /* defined(DEBUG_THREADLOCALS) */
532 AST_INLINE_API(
533 struct ast_str *__ast_str_thread_get(struct ast_threadstorage *ts,
534         size_t init_len, const char *file, const char *function, unsigned int line),
535 {
536         struct ast_str *buf;
537
538         buf = (struct ast_str *)__ast_threadstorage_get(ts, sizeof(*buf) + init_len, file, function, line);
539         if (buf == NULL)
540                 return NULL;
541         
542         if (!buf->len) {
543                 buf->len = init_len;
544                 buf->used = 0;
545                 buf->ts = ts;
546         }
547
548         return buf;
549 }
550 )
551
552 #define ast_str_thread_get(ts, init_len) __ast_str_thread_get(ts, init_len, __FILE__, __PRETTY_FUNCTION__, __LINE__)
553 #endif /* defined(DEBUG_THREADLOCALS) */
554
555 /*!
556  * \brief Error codes from __ast_str_helper()
557  * The undelying processing to manipulate dynamic string is done
558  * by __ast_str_helper(), which can return a success, a
559  * permanent failure (e.g. no memory), or a temporary one (when
560  * the string needs to be reallocated, and we must run va_start()
561  * again; XXX this convoluted interface is only here because
562  * FreeBSD 4 lacks va_copy, but this will be fixed and the
563  * interface simplified).
564  */
565 enum {
566         /*! An error has occurred and the contents of the dynamic string
567          *  are undefined */
568         AST_DYNSTR_BUILD_FAILED = -1,
569         /*! The buffer size for the dynamic string had to be increased, and
570          *  __ast_str_helper() needs to be called again after
571          *  a va_end() and va_start().
572          */
573         AST_DYNSTR_BUILD_RETRY = -2
574 };
575
576 /*!
577  * \brief Set a dynamic string from a va_list
578  *
579  * \param buf This is the address of a pointer to a struct ast_str.
580  *      If it is retrieved using ast_str_thread_get, the
581         struct ast_threadstorage pointer will need to
582  *      be updated in the case that the buffer has to be reallocated to
583  *      accommodate a longer string than what it currently has space for.
584  * \param max_len This is the maximum length to allow the string buffer to grow
585  *      to.  If this is set to 0, then there is no maximum length.
586  * \param fmt This is the format string (printf style)
587  * \param ap This is the va_list
588  *
589  * \return The return value of this function is the same as that of the printf
590  *         family of functions.
591  *
592  * Example usage (the first part is only for thread-local storage)
593  * \code
594  * AST_THREADSTORAGE(my_str, my_str_init);
595  * #define MY_STR_INIT_SIZE   128
596  * ...
597  * void my_func(const char *fmt, ...)
598  * {
599  *      struct ast_str *buf;
600  *      va_list ap;
601  *
602  *      if (!(buf = ast_str_thread_get(&my_str, MY_STR_INIT_SIZE)))
603  *           return;
604  *      ...
605  *      va_start(fmt, ap);
606  *      ast_str_set_va(&buf, 0, fmt, ap);
607  *      va_end(ap);
608  * 
609  *      printf("This is the string we just built: %s\n", buf->str);
610  *      ...
611  * }
612  * \endcode
613  *
614  * \note: the following two functions must be implemented as macros
615  *      because we must do va_end()/va_start() on the original arguments.
616  */
617 #define ast_str_set_va(buf, max_len, fmt, ap)                   \
618         ({                                                              \
619                 int __res;                                              \
620                 while ((__res = __ast_str_helper(buf, max_len,          \
621                         0, fmt, ap)) == AST_DYNSTR_BUILD_RETRY) {       \
622                         va_end(ap);                                     \
623                         va_start(ap, fmt);                              \
624                 }                                                       \
625                 (__res);                                                \
626         })
627
628 /*!
629  * \brief Append to a dynamic string using a va_list
630  *
631  * Same as ast_str_set_va(), but append to the current content.
632  */
633 #define ast_str_append_va(buf, max_len, fmt, ap)                \
634         ({                                                              \
635                 int __res;                                              \
636                 while ((__res = __ast_str_helper(buf, max_len,          \
637                         1, fmt, ap)) == AST_DYNSTR_BUILD_RETRY) {       \
638                         va_end(ap);                                     \
639                         va_start(ap, fmt);                              \
640                 }                                                       \
641                 (__res);                                                \
642         })
643
644 /*!
645  * \brief Core functionality of ast_str_(set|append)_va
646  *
647  * The arguments to this function are the same as those described for
648  * ast_str_set_va except for an addition argument, append.
649  * If append is non-zero, this will append to the current string instead of
650  * writing over it.
651  *
652  * In the case that this function is called and the buffer was not large enough
653  * to hold the result, the partial write will be truncated, and the result
654  * AST_DYNSTR_BUILD_RETRY will be returned to indicate that the buffer size
655  * was increased, and the function should be called a second time.
656  *
657  * A return of AST_DYNSTR_BUILD_FAILED indicates a memory allocation error.
658  *
659  * A return value greater than or equal to zero indicates the number of
660  * characters that have been written, not including the terminating '\0'.
661  * In the append case, this only includes the number of characters appended.
662  *
663  * \note This function should never need to be called directly.  It should
664  *       through calling one of the other functions or macros defined in this
665  *       file.
666  */
667 int __ast_str_helper(struct ast_str **buf, size_t max_len,
668         int append, const char *fmt, va_list ap);
669
670 /*!
671  * \brief Set a dynamic string using variable arguments
672  *
673  * \param buf This is the address of a pointer to a struct ast_str which should
674  *      have been retrieved using ast_str_thread_get.  It will need to
675  *      be updated in the case that the buffer has to be reallocated to
676  *      accomodate a longer string than what it currently has space for.
677  * \param max_len This is the maximum length to allow the string buffer to grow
678  *      to.  If this is set to 0, then there is no maximum length.
679  *      If set to -1, we are bound to the current maximum length.
680  * \param fmt This is the format string (printf style)
681  *
682  * \return The return value of this function is the same as that of the printf
683  *         family of functions.
684  *
685  * All the rest is the same as ast_str_set_va()
686  */
687 AST_INLINE_API(
688 int __attribute__ ((format (printf, 3, 4))) ast_str_set(
689         struct ast_str **buf, size_t max_len, const char *fmt, ...),
690 {
691         int res;
692         va_list ap;
693
694         va_start(ap, fmt);
695         res = ast_str_set_va(buf, max_len, fmt, ap);
696         va_end(ap);
697
698         return res;
699 }
700 )
701
702 /*!
703  * \brief Append to a thread local dynamic string
704  *
705  * The arguments, return values, and usage of this function are the same as
706  * ast_str_set(), but the new data is appended to the current value.
707  */
708 AST_INLINE_API(
709 int __attribute__ ((format (printf, 3, 4))) ast_str_append(
710         struct ast_str **buf, size_t max_len, const char *fmt, ...),
711 {
712         int res;
713         va_list ap;
714
715         va_start(ap, fmt);
716         res = ast_str_append_va(buf, max_len, fmt, ap);
717         va_end(ap);
718
719         return res;
720 }
721 )
722
723 /*!
724  * \brief Compute a hash value on a string
725  *
726  * This famous hash algorithm was written by Dan Bernstein and is
727  * commonly used.
728  *
729  * http://www.cse.yorku.ca/~oz/hash.html
730  */
731 static force_inline int ast_str_hash(const char *str)
732 {
733         int hash = 5381;
734
735         while (*str)
736                 hash = hash * 33 ^ *str++;
737
738         return abs(hash);
739 }
740
741 #endif /* _ASTERISK_STRINGS_H */