Wed Aug 18 22:33:56 2010

Asterisk developer's documentation


strings.h

Go to the documentation of this file.
00001 /*
00002  * Asterisk -- An open source telephony toolkit.
00003  *
00004  * Copyright (C) 1999 - 2006, Digium, Inc.
00005  *
00006  * Mark Spencer <markster@digium.com>
00007  *
00008  * See http://www.asterisk.org for more information about
00009  * the Asterisk project. Please do not directly contact
00010  * any of the maintainers of this project for assistance;
00011  * the project provides a web site, mailing lists and IRC
00012  * channels for your use.
00013  *
00014  * This program is free software, distributed under the terms of
00015  * the GNU General Public License Version 2. See the LICENSE file
00016  * at the top of the source tree.
00017  */
00018 
00019 /*! \file
00020  * \brief String manipulation functions
00021  */
00022 
00023 #ifndef _ASTERISK_STRINGS_H
00024 #define _ASTERISK_STRINGS_H
00025 
00026 #include <ctype.h>
00027 
00028 #include "asterisk/inline_api.h"
00029 #include "asterisk/utils.h"
00030 #include "asterisk/threadstorage.h"
00031 
00032 /* You may see casts in this header that may seem useless but they ensure this file is C++ clean */
00033 
00034 #ifdef AST_DEVMODE
00035 #define ast_strlen_zero(foo)  _ast_strlen_zero(foo, __FILE__, __PRETTY_FUNCTION__, __LINE__)
00036 static force_inline int _ast_strlen_zero(const char *s, const char *file, const char *function, int line)
00037 {
00038    if (!s || (*s == '\0')) {
00039       return 1;
00040    }
00041    if (!strcmp(s, "(null)")) {
00042       ast_log(__LOG_WARNING, file, line, function, "Possible programming error: \"(null)\" is not NULL!\n");
00043    }
00044    return 0;
00045 }
00046 
00047 #else
00048 static force_inline int ast_strlen_zero(const char *s)
00049 {
00050    return (!s || (*s == '\0'));
00051 }
00052 #endif
00053 
00054 /*! \brief returns the equivalent of logic or for strings:
00055  * first one if not empty, otherwise second one.
00056  */
00057 #define S_OR(a, b)           (!ast_strlen_zero(a) ? (a) : (b))
00058 
00059 /*! \brief returns the equivalent of logic or for strings, with an additional boolean check:
00060  * second one if not empty and first one is true, otherwise third one.
00061  * example: S_COR(usewidget, widget, "<no widget>")
00062  */
00063 #define S_COR(a, b, c)   ((a && !ast_strlen_zero(b)) ? (b) : (c))
00064 
00065 /*!
00066   \brief Gets a pointer to the first non-whitespace character in a string.
00067   \param str the input string
00068   \return a pointer to the first non-whitespace character
00069  */
00070 AST_INLINE_API(
00071 char *ast_skip_blanks(const char *str),
00072 {
00073    while (*str && ((unsigned char) *str) < 33)
00074       str++;
00075    return (char *)str;
00076 }
00077 )
00078 
00079 /*!
00080   \brief Trims trailing whitespace characters from a string.
00081   \param str the input string
00082   \return a pointer to the modified string
00083  */
00084 AST_INLINE_API(
00085 char *ast_trim_blanks(char *str),
00086 {
00087    char *work = str;
00088 
00089    if (work) {
00090       work += strlen(work) - 1;
00091       /* It's tempting to only want to erase after we exit this loop, 
00092          but since ast_trim_blanks *could* receive a constant string
00093          (which we presumably wouldn't have to touch), we shouldn't
00094          actually set anything unless we must, and it's easier just
00095          to set each position to \0 than to keep track of a variable
00096          for it */
00097       while ((work >= str) && ((unsigned char) *work) < 33)
00098          *(work--) = '\0';
00099    }
00100    return str;
00101 }
00102 )
00103 
00104 /*!
00105   \brief Gets a pointer to first whitespace character in a string.
00106   \param str the input string
00107   \return a pointer to the first whitespace character
00108  */
00109 AST_INLINE_API(
00110 char *ast_skip_nonblanks(char *str),
00111 {
00112    while (*str && ((unsigned char) *str) > 32)
00113       str++;
00114    return str;
00115 }
00116 )
00117   
00118 /*!
00119   \brief Strip leading/trailing whitespace from a string.
00120   \param s The string to be stripped (will be modified).
00121   \return The stripped string.
00122 
00123   This functions strips all leading and trailing whitespace
00124   characters from the input string, and returns a pointer to
00125   the resulting string. The string is modified in place.
00126 */
00127 AST_INLINE_API(
00128 char *ast_strip(char *s),
00129 {
00130    s = ast_skip_blanks(s);
00131    if (s)
00132       ast_trim_blanks(s);
00133    return s;
00134 } 
00135 )
00136 
00137 /*!
00138   \brief Strip leading/trailing whitespace and quotes from a string.
00139   \param s The string to be stripped (will be modified).
00140   \param beg_quotes The list of possible beginning quote characters.
00141   \param end_quotes The list of matching ending quote characters.
00142   \return The stripped string.
00143 
00144   This functions strips all leading and trailing whitespace
00145   characters from the input string, and returns a pointer to
00146   the resulting string. The string is modified in place.
00147 
00148   It can also remove beginning and ending quote (or quote-like)
00149   characters, in matching pairs. If the first character of the
00150   string matches any character in beg_quotes, and the last
00151   character of the string is the matching character in
00152   end_quotes, then they are removed from the string.
00153 
00154   Examples:
00155   \code
00156   ast_strip_quoted(buf, "\"", "\"");
00157   ast_strip_quoted(buf, "'", "'");
00158   ast_strip_quoted(buf, "[{(", "]})");
00159   \endcode
00160  */
00161 char *ast_strip_quoted(char *s, const char *beg_quotes, const char *end_quotes);
00162 
00163 /*!
00164   \brief Strip backslash for "escaped" semicolons, 
00165    the string to be stripped (will be modified).
00166   \return The stripped string.
00167  */
00168 char *ast_unescape_semicolon(char *s);
00169 
00170 /*!
00171   \brief Convert some C escape sequences  \verbatim (\b\f\n\r\t) \endverbatim into the
00172    equivalent characters. The string to be converted (will be modified).
00173   \return The converted string.
00174  */
00175 char *ast_unescape_c(char *s);
00176 
00177 /*!
00178   \brief Size-limited null-terminating string copy.
00179   \param dst The destination buffer.
00180   \param src The source string
00181   \param size The size of the destination buffer
00182   \return Nothing.
00183 
00184   This is similar to \a strncpy, with two important differences:
00185     - the destination buffer will \b always be null-terminated
00186     - the destination buffer is not filled with zeros past the copied string length
00187   These differences make it slightly more efficient, and safer to use since it will
00188   not leave the destination buffer unterminated. There is no need to pass an artificially
00189   reduced buffer size to this function (unlike \a strncpy), and the buffer does not need
00190   to be initialized to zeroes prior to calling this function.
00191 */
00192 AST_INLINE_API(
00193 void ast_copy_string(char *dst, const char *src, size_t size),
00194 {
00195    while (*src && size) {
00196       *dst++ = *src++;
00197       size--;
00198    }
00199    if (__builtin_expect(!size, 0))
00200       dst--;
00201    *dst = '\0';
00202 }
00203 )
00204 
00205 
00206 /*!
00207   \brief Build a string in a buffer, designed to be called repeatedly
00208   
00209   \note This method is not recommended. New code should use ast_str_*() instead.
00210 
00211   This is a wrapper for snprintf, that properly handles the buffer pointer
00212   and buffer space available.
00213 
00214   \param buffer current position in buffer to place string into (will be updated on return)
00215   \param space remaining space in buffer (will be updated on return)
00216   \param fmt printf-style format string
00217   \retval 0 on success
00218   \retval non-zero on failure.
00219 */
00220 int ast_build_string(char **buffer, size_t *space, const char *fmt, ...) __attribute__((format(printf, 3, 4)));
00221 
00222 /*!
00223   \brief Build a string in a buffer, designed to be called repeatedly
00224   
00225   This is a wrapper for snprintf, that properly handles the buffer pointer
00226   and buffer space available.
00227 
00228   \return 0 on success, non-zero on failure.
00229   \param buffer current position in buffer to place string into (will be updated on return)
00230   \param space remaining space in buffer (will be updated on return)
00231   \param fmt printf-style format string
00232   \param ap varargs list of arguments for format
00233 */
00234 int ast_build_string_va(char **buffer, size_t *space, const char *fmt, va_list ap) __attribute__((format(printf, 3, 0)));
00235 
00236 /*! 
00237  * \brief Make sure something is true.
00238  * Determine if a string containing a boolean value is "true".
00239  * This function checks to see whether a string passed to it is an indication of an "true" value.  
00240  * It checks to see if the string is "yes", "true", "y", "t", "on" or "1".  
00241  *
00242  * \retval 0 if val is a NULL pointer.
00243  * \retval -1 if "true".
00244  * \retval 0 otherwise.
00245  */
00246 int ast_true(const char *val);
00247 
00248 /*! 
00249  * \brief Make sure something is false.
00250  * Determine if a string containing a boolean value is "false".
00251  * This function checks to see whether a string passed to it is an indication of an "false" value.  
00252  * It checks to see if the string is "no", "false", "n", "f", "off" or "0".  
00253  *
00254  * \retval 0 if val is a NULL pointer.
00255  * \retval -1 if "true".
00256  * \retval 0 otherwise.
00257  */
00258 int ast_false(const char *val);
00259 
00260 /*
00261  *  \brief Join an array of strings into a single string.
00262  * \param s the resulting string buffer
00263  * \param len the length of the result buffer, s
00264  * \param w an array of strings to join.
00265  *
00266  * This function will join all of the strings in the array 'w' into a single
00267  * string.  It will also place a space in the result buffer in between each
00268  * string from 'w'.
00269 */
00270 void ast_join(char *s, size_t len, char * const w[]);
00271 
00272 /*
00273   \brief Parse a time (integer) string.
00274   \param src String to parse
00275   \param dst Destination
00276   \param _default Value to use if the string does not contain a valid time
00277   \param consumed The number of characters 'consumed' in the string by the parse (see 'man sscanf' for details)
00278   \retval 0 on success
00279   \retval non-zero on failure.
00280 */
00281 int ast_get_time_t(const char *src, time_t *dst, time_t _default, int *consumed);
00282 
00283 /*
00284   \brief Parse a time (float) string.
00285   \param src String to parse
00286   \param dst Destination
00287   \param _default Value to use if the string does not contain a valid time
00288   \param consumed The number of characters 'consumed' in the string by the parse (see 'man sscanf' for details)
00289   \return zero on success, non-zero on failure
00290 */
00291 int ast_get_timeval(const char *src, struct timeval *tv, struct timeval _default, int *consumed);
00292 
00293 /*!
00294  * Support for dynamic strings.
00295  *
00296  * A dynamic string is just a C string prefixed by a few control fields
00297  * that help setting/appending/extending it using a printf-like syntax.
00298  *
00299  * One should never declare a variable with this type, but only a pointer
00300  * to it, e.g.
00301  *
00302  * struct ast_str *ds;
00303  *
00304  * The pointer can be initialized with the following:
00305  *
00306  * ds = ast_str_create(init_len);
00307  *    creates a malloc()'ed dynamic string;
00308  *
00309  * ds = ast_str_alloca(init_len);
00310  *    creates a string on the stack (not very dynamic!).
00311  *
00312  * ds = ast_str_thread_get(ts, init_len)
00313  *    creates a malloc()'ed dynamic string associated to
00314  *    the thread-local storage key ts
00315  *
00316  * Finally, the string can be manipulated with the following:
00317  *
00318  * ast_str_set(&buf, max_len, fmt, ...)
00319  * ast_str_append(&buf, max_len, fmt, ...)
00320  *
00321  * and their varargs variant
00322  *
00323  * ast_str_set_va(&buf, max_len, ap)
00324  * ast_str_append_va(&buf, max_len, ap)
00325  *
00326  * \param max_len The maximum allowed capacity of the ast_str. Note that
00327  *  if the value of max_len is less than the current capacity of the
00328  *  ast_str (as returned by ast_str_size), then the parameter is effectively
00329  *  ignored.
00330  *    0 means unlimited, -1 means "at most the available space"
00331  *
00332  * \return All the functions return <0 in case of error, or the
00333  * length of the string added to the buffer otherwise. Note that
00334  * in most cases where an error is returned, characters ARE written
00335  * to the ast_str.
00336  */
00337 
00338 /*! \brief The descriptor of a dynamic string
00339  *  XXX storage will be optimized later if needed
00340  * We use the ts field to indicate the type of storage.
00341  * Three special constants indicate malloc, alloca() or static
00342  * variables, all other values indicate a
00343  * struct ast_threadstorage pointer.
00344  */
00345 struct ast_str {
00346    size_t len; /*!< The current maximum length of the string */
00347    size_t used;   /*!< Amount of space used */
00348    struct ast_threadstorage *ts; /*!< What kind of storage is this ? */
00349 #define DS_MALLOC ((struct ast_threadstorage *)1)
00350 #define DS_ALLOCA ((struct ast_threadstorage *)2)
00351 #define DS_STATIC ((struct ast_threadstorage *)3)  /* not supported yet */
00352    char str[0];   /*!< The string buffer */
00353 };
00354 
00355 #define ast_str_size(a) ((a)->len)
00356 #define  ast_str_strlen(a) ((a)->used)
00357 #define  ast_str_buffer(a) ((a)->str)
00358 #define  ast_str_update(a) (a)->used = strlen((a)->str)
00359 
00360 /*!
00361  * \brief Create a malloc'ed dynamic length string
00362  *
00363  * \param init_len This is the initial length of the string buffer
00364  *
00365  * \return This function returns a pointer to the dynamic string length.  The
00366  *         result will be NULL in the case of a memory allocation error.
00367  *
00368  * \note The result of this function is dynamically allocated memory, and must
00369  *       be free()'d after it is no longer needed.
00370  */
00371 AST_INLINE_API(
00372 struct ast_str * attribute_malloc ast_str_create(size_t init_len),
00373 {
00374    struct ast_str *buf;
00375 
00376    buf = (struct ast_str *)ast_calloc(1, sizeof(*buf) + init_len);
00377    if (buf == NULL)
00378       return NULL;
00379    
00380    buf->len = init_len;
00381    buf->used = 0;
00382    buf->ts = DS_MALLOC;
00383 
00384    return buf;
00385 }
00386 )
00387 
00388 /*! \brief Reset the content of a dynamic string.
00389  * Useful before a series of ast_str_append.
00390  */
00391 AST_INLINE_API(
00392 void ast_str_reset(struct ast_str *buf),
00393 {
00394    if (buf) {
00395       buf->used = 0;
00396       if (buf->len)
00397          buf->str[0] = '\0';
00398    }
00399 }
00400 )
00401 
00402 /*
00403  * AST_INLINE_API() is a macro that takes a block of code as an argument.
00404  * Using preprocessor #directives in the argument is not supported by all
00405  * compilers, and it is a bit of an obfuscation anyways, so avoid it.
00406  * As a workaround, define a macro that produces either its argument
00407  * or nothing, and use that instead of #ifdef/#endif within the
00408  * argument to AST_INLINE_API().
00409  */
00410 #if defined(DEBUG_THREADLOCALS)
00411 #define  _DB1(x)  x
00412 #else
00413 #define _DB1(x)
00414 #endif
00415 
00416 /*!
00417  * Make space in a new string (e.g. to read in data from a file)
00418  */
00419 #if (defined(MALLOC_DEBUG) && !defined(STANDALONE))
00420 AST_INLINE_API(
00421 int _ast_str_make_space(struct ast_str **buf, size_t new_len, const char *file, int lineno, const char *function),
00422 {
00423    struct ast_str *old_buf = *buf;
00424 
00425    if (new_len <= (*buf)->len) 
00426       return 0;   /* success */
00427    if ((*buf)->ts == DS_ALLOCA || (*buf)->ts == DS_STATIC)
00428       return -1;  /* cannot extend */
00429    *buf = (struct ast_str *)__ast_realloc(*buf, new_len + sizeof(struct ast_str), file, lineno, function);
00430    if (*buf == NULL) {
00431       *buf = old_buf;
00432       return -1;
00433    }
00434    if ((*buf)->ts != DS_MALLOC) {
00435       pthread_setspecific((*buf)->ts->key, *buf);
00436       _DB1(__ast_threadstorage_object_replace(old_buf, *buf, new_len + sizeof(struct ast_str));)
00437    }
00438 
00439    (*buf)->len = new_len;
00440    return 0;
00441 }
00442 )
00443 #define ast_str_make_space(a,b)  _ast_str_make_space(a,b,__FILE__,__LINE__,__PRETTY_FUNCTION__)
00444 #else
00445 AST_INLINE_API(
00446 int ast_str_make_space(struct ast_str **buf, size_t new_len),
00447 {
00448    struct ast_str *old_buf = *buf;
00449 
00450    if (new_len <= (*buf)->len) 
00451       return 0;   /* success */
00452    if ((*buf)->ts == DS_ALLOCA || (*buf)->ts == DS_STATIC)
00453       return -1;  /* cannot extend */
00454    *buf = (struct ast_str *)ast_realloc(*buf, new_len + sizeof(struct ast_str));
00455    if (*buf == NULL) {
00456       *buf = old_buf;
00457       return -1;
00458    }
00459    if ((*buf)->ts != DS_MALLOC) {
00460       pthread_setspecific((*buf)->ts->key, *buf);
00461       _DB1(__ast_threadstorage_object_replace(old_buf, *buf, new_len + sizeof(struct ast_str));)
00462    }
00463 
00464         (*buf)->len = new_len;
00465         return 0;
00466 }
00467 )
00468 #endif
00469 
00470 #define ast_str_alloca(init_len)       \
00471    ({                \
00472       struct ast_str *__ast_str_buf;         \
00473       __ast_str_buf = alloca(sizeof(*__ast_str_buf) + init_len);  \
00474       __ast_str_buf->len = init_len;         \
00475       __ast_str_buf->used = 0;            \
00476       __ast_str_buf->ts = DS_ALLOCA;         \
00477       __ast_str_buf->str[0] = '\0';       \
00478       (__ast_str_buf);              \
00479    })
00480 
00481 /*!
00482  * \brief Retrieve a thread locally stored dynamic string
00483  *
00484  * \param ts This is a pointer to the thread storage structure declared by using
00485  *      the AST_THREADSTORAGE macro.  If declared with 
00486  *      AST_THREADSTORAGE(my_buf, my_buf_init), then this argument would be 
00487  *      (&my_buf).
00488  * \param init_len This is the initial length of the thread's dynamic string. The
00489  *      current length may be bigger if previous operations in this thread have
00490  *      caused it to increase.
00491  *
00492  * \return This function will return the thread locally stored dynamic string
00493  *         associated with the thread storage management variable passed as the
00494  *         first argument.
00495  *         The result will be NULL in the case of a memory allocation error.
00496  *
00497  * Example usage:
00498  * \code
00499  * AST_THREADSTORAGE(my_str, my_str_init);
00500  * #define MY_STR_INIT_SIZE   128
00501  * ...
00502  * void my_func(const char *fmt, ...)
00503  * {
00504  *      struct ast_str *buf;
00505  *
00506  *      if (!(buf = ast_str_thread_get(&my_str, MY_STR_INIT_SIZE)))
00507  *           return;
00508  *      ...
00509  * }
00510  * \endcode
00511  */
00512 #if !defined(DEBUG_THREADLOCALS)
00513 AST_INLINE_API(
00514 struct ast_str *ast_str_thread_get(struct ast_threadstorage *ts,
00515    size_t init_len),
00516 {
00517    struct ast_str *buf;
00518 
00519    buf = (struct ast_str *)ast_threadstorage_get(ts, sizeof(*buf) + init_len);
00520    if (buf == NULL)
00521       return NULL;
00522    
00523    if (!buf->len) {
00524       buf->len = init_len;
00525       buf->used = 0;
00526       buf->ts = ts;
00527    }
00528 
00529    return buf;
00530 }
00531 )
00532 #else /* defined(DEBUG_THREADLOCALS) */
00533 AST_INLINE_API(
00534 struct ast_str *__ast_str_thread_get(struct ast_threadstorage *ts,
00535    size_t init_len, const char *file, const char *function, unsigned int line),
00536 {
00537    struct ast_str *buf;
00538 
00539    buf = (struct ast_str *)__ast_threadstorage_get(ts, sizeof(*buf) + init_len, file, function, line);
00540    if (buf == NULL)
00541       return NULL;
00542    
00543    if (!buf->len) {
00544       buf->len = init_len;
00545       buf->used = 0;
00546       buf->ts = ts;
00547    }
00548 
00549    return buf;
00550 }
00551 )
00552 
00553 #define ast_str_thread_get(ts, init_len) __ast_str_thread_get(ts, init_len, __FILE__, __PRETTY_FUNCTION__, __LINE__)
00554 #endif /* defined(DEBUG_THREADLOCALS) */
00555 
00556 /*!
00557  * \brief Error codes from __ast_str_helper()
00558  * The undelying processing to manipulate dynamic string is done
00559  * by __ast_str_helper(), which can return a success or a
00560  * permanent failure (e.g. no memory).
00561  */
00562 enum {
00563    /*! An error has occurred and the contents of the dynamic string
00564     *  are undefined */
00565    AST_DYNSTR_BUILD_FAILED = -1,
00566    /*! The buffer size for the dynamic string had to be increased, and
00567     *  __ast_str_helper() needs to be called again after
00568     *  a va_end() and va_start().  This return value is legacy and will
00569     *  no longer be used.
00570     */
00571    AST_DYNSTR_BUILD_RETRY = -2
00572 };
00573 
00574 /*!
00575  * \brief Core functionality of ast_str_(set|append)_va
00576  *
00577  * The arguments to this function are the same as those described for
00578  * ast_str_set_va except for an addition argument, append.
00579  * If append is non-zero, this will append to the current string instead of
00580  * writing over it.
00581  *
00582  * AST_DYNSTR_BUILD_RETRY is a legacy define.  It should probably never
00583  * again be used.
00584  *
00585  * A return of AST_DYNSTR_BUILD_FAILED indicates a memory allocation error.
00586  *
00587  * A return value greater than or equal to zero indicates the number of
00588  * characters that have been written, not including the terminating '\0'.
00589  * In the append case, this only includes the number of characters appended.
00590  *
00591  * \note This function should never need to be called directly.  It should
00592  *       through calling one of the other functions or macros defined in this
00593  *       file.
00594  */
00595 int __attribute__((format(printf, 4, 0))) __ast_str_helper(struct ast_str **buf, ssize_t max_len,
00596                         int append, const char *fmt, va_list ap);
00597 
00598 /*!
00599  * \brief Set a dynamic string from a va_list
00600  *
00601  * \param buf This is the address of a pointer to a struct ast_str.
00602  * If it is retrieved using ast_str_thread_get, the
00603    struct ast_threadstorage pointer will need to
00604  *      be updated in the case that the buffer has to be reallocated to
00605  *      accommodate a longer string than what it currently has space for.
00606  * \param max_len This is the maximum length to allow the string buffer to grow
00607  *      to.  If this is set to 0, then there is no maximum length.
00608  * \param fmt This is the format string (printf style)
00609  * \param ap This is the va_list
00610  *
00611  * \return The return value of this function is the same as that of the printf
00612  *         family of functions.
00613  *
00614  * Example usage (the first part is only for thread-local storage)
00615  * \code
00616  * AST_THREADSTORAGE(my_str, my_str_init);
00617  * #define MY_STR_INIT_SIZE   128
00618  * ...
00619  * void my_func(const char *fmt, ...)
00620  * {
00621  *      struct ast_str *buf;
00622  *      va_list ap;
00623  *
00624  *      if (!(buf = ast_str_thread_get(&my_str, MY_STR_INIT_SIZE)))
00625  *           return;
00626  *      ...
00627  *      va_start(fmt, ap);
00628  *      ast_str_set_va(&buf, 0, fmt, ap);
00629  *      va_end(ap);
00630  * 
00631  *      printf("This is the string we just built: %s\n", buf->str);
00632  *      ...
00633  * }
00634  * \endcode
00635  */
00636 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),
00637 {
00638    return __ast_str_helper(buf, max_len, 0, fmt, ap);
00639 }
00640 )
00641 
00642 /*!
00643  * \brief Append to a dynamic string using a va_list
00644  *
00645  * Same as ast_str_set_va(), but append to the current content.
00646  */
00647 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),
00648 {
00649    return __ast_str_helper(buf, max_len, 1, fmt, ap);
00650 }
00651 )
00652 
00653 /*!
00654  * \brief Set a dynamic string using variable arguments
00655  *
00656  * \param buf This is the address of a pointer to a struct ast_str which should
00657  *      have been retrieved using ast_str_thread_get.  It will need to
00658  *      be updated in the case that the buffer has to be reallocated to
00659  *      accomodate a longer string than what it currently has space for.
00660  * \param max_len This is the maximum length to allow the string buffer to grow
00661  *      to.  If this is set to 0, then there is no maximum length.
00662  * If set to -1, we are bound to the current maximum length.
00663  * \param fmt This is the format string (printf style)
00664  *
00665  * \return The return value of this function is the same as that of the printf
00666  *         family of functions.
00667  *
00668  * All the rest is the same as ast_str_set_va()
00669  */
00670 AST_INLINE_API(
00671 int __attribute__((format(printf, 3, 4))) ast_str_set(
00672    struct ast_str **buf, ssize_t max_len, const char *fmt, ...),
00673 {
00674    int res;
00675    va_list ap;
00676 
00677    va_start(ap, fmt);
00678    res = ast_str_set_va(buf, max_len, fmt, ap);
00679    va_end(ap);
00680 
00681    return res;
00682 }
00683 )
00684 
00685 /*!
00686  * \brief Append to a thread local dynamic string
00687  *
00688  * The arguments, return values, and usage of this function are the same as
00689  * ast_str_set(), but the new data is appended to the current value.
00690  */
00691 AST_INLINE_API(
00692 int __attribute__((format(printf, 3, 4))) ast_str_append(
00693    struct ast_str **buf, ssize_t max_len, const char *fmt, ...),
00694 {
00695    int res;
00696    va_list ap;
00697 
00698    va_start(ap, fmt);
00699    res = ast_str_append_va(buf, max_len, fmt, ap);
00700    va_end(ap);
00701 
00702    return res;
00703 }
00704 )
00705 
00706 /*!
00707  * \brief Compute a hash value on a string
00708  *
00709  * This famous hash algorithm was written by Dan Bernstein and is
00710  * commonly used.
00711  *
00712  * http://www.cse.yorku.ca/~oz/hash.html
00713  */
00714 static force_inline int ast_str_hash(const char *str)
00715 {
00716    int hash = 5381;
00717 
00718    while (*str)
00719       hash = hash * 33 ^ *str++;
00720 
00721    return abs(hash);
00722 }
00723 
00724 /*!
00725  * \brief Compute a hash value on a string
00726  *
00727  * \param[in] str The string to add to the hash
00728  * \param[in] hash The hash value to add to
00729  * 
00730  * \details
00731  * This version of the function is for when you need to compute a
00732  * string hash of more than one string.
00733  *
00734  * This famous hash algorithm was written by Dan Bernstein and is
00735  * commonly used.
00736  *
00737  * \sa http://www.cse.yorku.ca/~oz/hash.html
00738  */
00739 static force_inline int ast_str_hash_add(const char *str, int hash)
00740 {
00741    while (*str)
00742       hash = hash * 33 ^ *str++;
00743 
00744    return abs(hash);
00745 }
00746 
00747 /*!
00748  * \brief Compute a hash value on a case-insensitive string
00749  *
00750  * Uses the same hash algorithm as ast_str_hash, but converts
00751  * all characters to lowercase prior to computing a hash. This
00752  * allows for easy case-insensitive lookups in a hash table.
00753  */
00754 static force_inline int ast_str_case_hash(const char *str)
00755 {
00756    int hash = 5381;
00757 
00758    while (*str) {
00759       hash = hash * 33 ^ tolower(*str++);
00760    }
00761 
00762    return abs(hash);
00763 }
00764 #endif /* _ASTERISK_STRINGS_H */

Generated on Wed Aug 18 22:33:56 2010 for Asterisk - the Open Source PBX by  doxygen 1.4.7