Thu Jul 9 13:40:41 2009

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

Generated on Thu Jul 9 13:40:41 2009 for Asterisk - the Open Source PBX by  doxygen 1.4.7