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