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

Generated on Sat Mar 10 01:54:27 2012 for Asterisk - The Open Source Telephony Project by  doxygen 1.4.7