Thu Oct 11 06:47:21 2012

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

Generated on Thu Oct 11 06:47:21 2012 for Asterisk - the Open Source PBX by  doxygen 1.5.6