diff options
Diffstat (limited to 'trunk/include/asterisk/strings.h')
| -rw-r--r-- | trunk/include/asterisk/strings.h | 691 |
1 files changed, 0 insertions, 691 deletions
diff --git a/trunk/include/asterisk/strings.h b/trunk/include/asterisk/strings.h deleted file mode 100644 index 9646e94c2..000000000 --- a/trunk/include/asterisk/strings.h +++ /dev/null @@ -1,691 +0,0 @@ -/* - * Asterisk -- An open source telephony toolkit. - * - * Copyright (C) 1999 - 2006, Digium, Inc. - * - * Mark Spencer <markster@digium.com> - * - * See http://www.asterisk.org for more information about - * the Asterisk project. Please do not directly contact - * any of the maintainers of this project for assistance; - * the project provides a web site, mailing lists and IRC - * channels for your use. - * - * This program is free software, distributed under the terms of - * the GNU General Public License Version 2. See the LICENSE file - * at the top of the source tree. - */ - -/*! \file - * \brief String manipulation functions - */ - -#ifndef _ASTERISK_STRINGS_H -#define _ASTERISK_STRINGS_H - -#include "asterisk/inline_api.h" -#include "asterisk/utils.h" -#include "asterisk/threadstorage.h" - -/* You may see casts in this header that may seem useless but they ensure this file is C++ clean */ - -static force_inline int ast_strlen_zero(const char *s) -{ - return (!s || (*s == '\0')); -} - -/*! \brief returns the equivalent of logic or for strings: - * first one if not empty, otherwise second one. - */ -#define S_OR(a, b) (!ast_strlen_zero(a) ? (a) : (b)) - -/*! \brief returns the equivalent of logic or for strings, with an additional boolean check: - * second one if not empty and first one is true, otherwise third one. - * example: S_COR(usewidget, widget, "<no widget>") - */ -#define S_COR(a, b, c) ((a && !ast_strlen_zero(b)) ? (b) : (c)) - -/*! - \brief Gets a pointer to the first non-whitespace character in a string. - \param ast_skip_blanks function being used - \arg str the input string - \return a pointer to the first non-whitespace character - */ -AST_INLINE_API( -char *ast_skip_blanks(const char *str), -{ - while (*str && ((unsigned char) *str) < 33) - str++; - return (char *)str; -} -) - -/*! - \brief Trims trailing whitespace characters from a string. - \param ast_skip_blanks function being used - \arg str the input string - \return a pointer to the modified string - */ -AST_INLINE_API( -char *ast_trim_blanks(char *str), -{ - char *work = str; - - if (work) { - work += strlen(work) - 1; - /* It's tempting to only want to erase after we exit this loop, - but since ast_trim_blanks *could* receive a constant string - (which we presumably wouldn't have to touch), we shouldn't - actually set anything unless we must, and it's easier just - to set each position to \0 than to keep track of a variable - for it */ - while ((work >= str) && ((unsigned char) *work) < 33) - *(work--) = '\0'; - } - return str; -} -) - -/*! - \brief Gets a pointer to first whitespace character in a string. - \param ast_skip_noblanks function being used - \arg str the input string - \return a pointer to the first whitespace character - */ -AST_INLINE_API( -char *ast_skip_nonblanks(char *str), -{ - while (*str && ((unsigned char) *str) > 32) - str++; - return str; -} -) - -/*! - \brief Strip leading/trailing whitespace from a string. - \param ast_strip function ast_strip being used. - \arg s The string to be stripped (will be modified). - \return The stripped string. - - This functions strips all leading and trailing whitespace - characters from the input string, and returns a pointer to - the resulting string. The string is modified in place. -*/ -AST_INLINE_API( -char *ast_strip(char *s), -{ - s = ast_skip_blanks(s); - if (s) - ast_trim_blanks(s); - return s; -} -) - -/*! - \brief Strip leading/trailing whitespace and quotes from a string. - \param s The string to be stripped (will be modified). - \param beg_quotes The list of possible beginning quote characters. - \param end_quotes The list of matching ending quote characters. - \return The stripped string. - - This functions strips all leading and trailing whitespace - characters from the input string, and returns a pointer to - the resulting string. The string is modified in place. - - It can also remove beginning and ending quote (or quote-like) - characters, in matching pairs. If the first character of the - string matches any character in beg_quotes, and the last - character of the string is the matching character in - end_quotes, then they are removed from the string. - - Examples: - \code - ast_strip_quoted(buf, "\"", "\""); - ast_strip_quoted(buf, "'", "'"); - ast_strip_quoted(buf, "[{(", "]})"); - \endcode - */ -char *ast_strip_quoted(char *s, const char *beg_quotes, const char *end_quotes); - -/*! - \brief Strip backslash for "escaped" semicolons. - \brief s The string to be stripped (will be modified). - \return The stripped string. - */ -char *ast_unescape_semicolon(char *s); - -/*! - \brief Convert some C escape sequences (\b\f\n\r\t) into the - equivalent characters. - \brief s The string to be converted (will be modified). - \return The converted string. - */ -char *ast_unescape_c(char *s); - -/*! - \brief Size-limited null-terminating string copy. - \arg dst The destination buffer. - \arg src The source string - \arg size The size of the destination buffer - \return Nothing. - - This is similar to \a strncpy, with two important differences: - - the destination buffer will \b always be null-terminated - - the destination buffer is not filled with zeros past the copied string length - These differences make it slightly more efficient, and safer to use since it will - not leave the destination buffer unterminated. There is no need to pass an artificially - reduced buffer size to this function (unlike \a strncpy), and the buffer does not need - to be initialized to zeroes prior to calling this function. -*/ -AST_INLINE_API( -void ast_copy_string(char *dst, const char *src, size_t size), -{ - while (*src && size) { - *dst++ = *src++; - size--; - } - if (__builtin_expect(!size, 0)) - dst--; - *dst = '\0'; -} -) - - -/*! - \brief Build a string in a buffer, designed to be called repeatedly - - \note This method is not recommended. New code should use ast_str_*() instead. - - This is a wrapper for snprintf, that properly handles the buffer pointer - and buffer space available. - - \arg buffer current position in buffer to place string into (will be updated on return) - \arg space remaining space in buffer (will be updated on return) - \arg fmt printf-style format string - \retval 0 on success - \retval non-zero on failure. -*/ -int ast_build_string(char **buffer, size_t *space, const char *fmt, ...) __attribute__ ((format (printf, 3, 4))); - -/*! - \brief Build a string in a buffer, designed to be called repeatedly - - This is a wrapper for snprintf, that properly handles the buffer pointer - and buffer space available. - - \return 0 on success, non-zero on failure. - \param buffer current position in buffer to place string into (will be updated on return) - \param space remaining space in buffer (will be updated on return) - \param fmt printf-style format string - \param ap varargs list of arguments for format -*/ -int ast_build_string_va(char **buffer, size_t *space, const char *fmt, va_list ap); - -/*! - * \brief Make sure something is true. - * Determine if a string containing a boolean value is "true". - * This function checks to see whether a string passed to it is an indication of an "true" value. - * It checks to see if the string is "yes", "true", "y", "t", "on" or "1". - * - * \retval 0 if val is a NULL pointer. - * \retval -1 if "true". - * \retval 0 otherwise. - */ -int ast_true(const char *val); - -/*! - * \brief Make sure something is false. - * Determine if a string containing a boolean value is "false". - * This function checks to see whether a string passed to it is an indication of an "false" value. - * It checks to see if the string is "no", "false", "n", "f", "off" or "0". - * - * \retval 0 if val is a NULL pointer. - * \retval -1 if "true". - * \retval 0 otherwise. - */ -int ast_false(const char *val); - -/* - * \brief Join an array of strings into a single string. - * \param s the resulting string buffer - * \param len the length of the result buffer, s - * \param w an array of strings to join. - * - * This function will join all of the strings in the array 'w' into a single - * string. It will also place a space in the result buffer in between each - * string from 'w'. -*/ -void ast_join(char *s, size_t len, char * const w[]); - -/* - \brief Parse a time (integer) string. - \param src String to parse - \param dst Destination - \param _default Value to use if the string does not contain a valid time - \param consumed The number of characters 'consumed' in the string by the parse (see 'man sscanf' for details) - \retval 0 on success - \retval non-zero on failure. -*/ -int ast_get_time_t(const char *src, time_t *dst, time_t _default, int *consumed); - -/* - \brief Parse a time (float) string. - \param src String to parse - \param dst Destination - \param _default Value to use if the string does not contain a valid time - \param consumed The number of characters 'consumed' in the string by the parse (see 'man sscanf' for details) - \return zero on success, non-zero on failure -*/ -int ast_get_timeval(const char *src, struct timeval *tv, struct timeval _default, int *consumed); - -/*! - * Support for dynamic strings. - * - * A dynamic string is just a C string prefixed by a few control fields - * that help setting/appending/extending it using a printf-like syntax. - * - * One should never declare a variable with this type, but only a pointer - * to it, e.g. - * - * struct ast_str *ds; - * - * The pointer can be initialized with the following: - * - * ds = ast_str_create(init_len); - * creates a malloc()'ed dynamic string; - * - * ds = ast_str_alloca(init_len); - * creates a string on the stack (not very dynamic!). - * - * ds = ast_str_thread_get(ts, init_len) - * creates a malloc()'ed dynamic string associated to - * the thread-local storage key ts - * - * Finally, the string can be manipulated with the following: - * - * ast_str_set(&buf, max_len, fmt, ...) - * ast_str_append(&buf, max_len, fmt, ...) - * - * and their varargs variant - * - * ast_str_set_va(&buf, max_len, ap) - * ast_str_append_va(&buf, max_len, ap) - * - * \arg max_len The maximum allowed length, reallocating if needed. - * 0 means unlimited, -1 means "at most the available space" - * - * \return All the functions return <0 in case of error, or the - * length of the string added to the buffer otherwise. - */ - -/*! \brief The descriptor of a dynamic string - * XXX storage will be optimized later if needed - * We use the ts field to indicate the type of storage. - * Three special constants indicate malloc, alloca() or static - * variables, all other values indicate a - * struct ast_threadstorage pointer. - */ -struct ast_str { - size_t len; /*!< The current maximum length of the string */ - size_t used; /*!< Amount of space used */ - struct ast_threadstorage *ts; /*!< What kind of storage is this ? */ -#define DS_MALLOC ((struct ast_threadstorage *)1) -#define DS_ALLOCA ((struct ast_threadstorage *)2) -#define DS_STATIC ((struct ast_threadstorage *)3) /* not supported yet */ - char str[0]; /*!< The string buffer */ -}; - -/*! - * \brief Create a malloc'ed dynamic length string - * - * \arg init_len This is the initial length of the string buffer - * - * \return This function returns a pointer to the dynamic string length. The - * result will be NULL in the case of a memory allocation error. - * - * \note The result of this function is dynamically allocated memory, and must - * be free()'d after it is no longer needed. - */ -AST_INLINE_API( -struct ast_str * attribute_malloc ast_str_create(size_t init_len), -{ - struct ast_str *buf; - - buf = (struct ast_str *)ast_calloc(1, sizeof(*buf) + init_len); - if (buf == NULL) - return NULL; - - buf->len = init_len; - buf->used = 0; - buf->ts = DS_MALLOC; - - return buf; -} -) - -/*! \brief Reset the content of a dynamic string. - * Useful before a series of ast_str_append. - */ -AST_INLINE_API( -void ast_str_reset(struct ast_str *buf), -{ - if (buf) { - buf->used = 0; - if (buf->len) - buf->str[0] = '\0'; - } -} -) - -/* - * AST_INLINE_API() is a macro that takes a block of code as an argument. - * Using preprocessor #directives in the argument is not supported by all - * compilers, and it is a bit of an obfuscation anyways, so avoid it. - * As a workaround, define a macro that produces either its argument - * or nothing, and use that instead of #ifdef/#endif within the - * argument to AST_INLINE_API(). - */ -#if defined(DEBUG_THREADLOCALS) -#define _DB1(x) x -#else -#define _DB1(x) -#endif - -/*! - * Make space in a new string (e.g. to read in data from a file) - */ -AST_INLINE_API( -int ast_str_make_space(struct ast_str **buf, size_t new_len), -{ - _DB1(struct ast_str *old_buf = *buf;) - - if (new_len <= (*buf)->len) - return 0; /* success */ - if ((*buf)->ts == DS_ALLOCA || (*buf)->ts == DS_STATIC) - return -1; /* cannot extend */ - *buf = (struct ast_str *)ast_realloc(*buf, new_len + sizeof(struct ast_str)); - if (*buf == NULL) /* XXX watch out, we leak memory here */ - return -1; - if ((*buf)->ts != DS_MALLOC) { - pthread_setspecific((*buf)->ts->key, *buf); - _DB1(__ast_threadstorage_object_replace(old_buf, *buf, new_len + sizeof(struct ast_str));) - } - - (*buf)->len = new_len; - return 0; -} -) - -#define ast_str_alloca(init_len) \ - ({ \ - struct ast_str *buf; \ - buf = alloca(sizeof(*buf) + init_len); \ - buf->len = init_len; \ - buf->used = 0; \ - buf->ts = DS_ALLOCA; \ - buf->str[0] = '\0'; \ - (buf); \ - }) - -/*! - * \brief Retrieve a thread locally stored dynamic string - * - * \arg ts This is a pointer to the thread storage structure declared by using - * the AST_THREADSTORAGE macro. If declared with - * AST_THREADSTORAGE(my_buf, my_buf_init), then this argument would be - * (&my_buf). - * \arg init_len This is the initial length of the thread's dynamic string. The - * current length may be bigger if previous operations in this thread have - * caused it to increase. - * - * \return This function will return the thread locally stored dynamic string - * associated with the thread storage management variable passed as the - * first argument. - * The result will be NULL in the case of a memory allocation error. - * - * Example usage: - * \code - * AST_THREADSTORAGE(my_str, my_str_init); - * #define MY_STR_INIT_SIZE 128 - * ... - * void my_func(const char *fmt, ...) - * { - * struct ast_str *buf; - * - * if (!(buf = ast_str_thread_get(&my_str, MY_STR_INIT_SIZE))) - * return; - * ... - * } - * \endcode - */ -#if !defined(DEBUG_THREADLOCALS) -AST_INLINE_API( -struct ast_str *ast_str_thread_get(struct ast_threadstorage *ts, - size_t init_len), -{ - struct ast_str *buf; - - buf = (struct ast_str *)ast_threadstorage_get(ts, sizeof(*buf) + init_len); - if (buf == NULL) - return NULL; - - if (!buf->len) { - buf->len = init_len; - buf->used = 0; - buf->ts = ts; - } - - return buf; -} -) -#else /* defined(DEBUG_THREADLOCALS) */ -AST_INLINE_API( -struct ast_str *__ast_str_thread_get(struct ast_threadstorage *ts, - size_t init_len, const char *file, const char *function, unsigned int line), -{ - struct ast_str *buf; - - buf = (struct ast_str *)__ast_threadstorage_get(ts, sizeof(*buf) + init_len, file, function, line); - if (buf == NULL) - return NULL; - - if (!buf->len) { - buf->len = init_len; - buf->used = 0; - buf->ts = ts; - } - - return buf; -} -) - -#define ast_str_thread_get(ts, init_len) __ast_str_thread_get(ts, init_len, __FILE__, __PRETTY_FUNCTION__, __LINE__) -#endif /* defined(DEBUG_THREADLOCALS) */ - -/*! - * \brief Error codes from __ast_str_helper() - * The undelying processing to manipulate dynamic string is done - * by __ast_str_helper(), which can return a success, a - * permanent failure (e.g. no memory), or a temporary one (when - * the string needs to be reallocated, and we must run va_start() - * again; XXX this convoluted interface is only here because - * FreeBSD 4 lacks va_copy, but this will be fixed and the - * interface simplified). - */ -enum { - /*! An error has occured and the contents of the dynamic string - * are undefined */ - AST_DYNSTR_BUILD_FAILED = -1, - /*! The buffer size for the dynamic string had to be increased, and - * __ast_str_helper() needs to be called again after - * a va_end() and va_start(). - */ - AST_DYNSTR_BUILD_RETRY = -2 -}; - -/*! - * \brief Set a dynamic string from a va_list - * - * \arg buf This is the address of a pointer to a struct ast_str. - * If it is retrieved using ast_str_thread_get, the - struct ast_threadstorage pointer will need to - * be updated in the case that the buffer has to be reallocated to - * accommodate a longer string than what it currently has space for. - * \arg max_len This is the maximum length to allow the string buffer to grow - * to. If this is set to 0, then there is no maximum length. - * \arg fmt This is the format string (printf style) - * \arg ap This is the va_list - * - * \return The return value of this function is the same as that of the printf - * family of functions. - * - * Example usage (the first part is only for thread-local storage) - * \code - * AST_THREADSTORAGE(my_str, my_str_init); - * #define MY_STR_INIT_SIZE 128 - * ... - * void my_func(const char *fmt, ...) - * { - * struct ast_str *buf; - * va_list ap; - * - * if (!(buf = ast_str_thread_get(&my_str, MY_STR_INIT_SIZE))) - * return; - * ... - * va_start(fmt, ap); - * ast_str_set_va(&buf, 0, fmt, ap); - * va_end(ap); - * - * printf("This is the string we just built: %s\n", buf->str); - * ... - * } - * \endcode - * - * \note: the following two functions must be implemented as macros - * because we must do va_end()/va_start() on the original arguments. - */ -#define ast_str_set_va(buf, max_len, fmt, ap) \ - ({ \ - int __res; \ - while ((__res = __ast_str_helper(buf, max_len, \ - 0, fmt, ap)) == AST_DYNSTR_BUILD_RETRY) { \ - va_end(ap); \ - va_start(ap, fmt); \ - } \ - (__res); \ - }) - -/*! - * \brief Append to a dynamic string using a va_list - * - * Same as ast_str_set_va(), but append to the current content. - */ -#define ast_str_append_va(buf, max_len, fmt, ap) \ - ({ \ - int __res; \ - while ((__res = __ast_str_helper(buf, max_len, \ - 1, fmt, ap)) == AST_DYNSTR_BUILD_RETRY) { \ - va_end(ap); \ - va_start(ap, fmt); \ - } \ - (__res); \ - }) - -/*! - * \brief Core functionality of ast_str_(set|append)_va - * - * The arguments to this function are the same as those described for - * ast_str_set_va except for an addition argument, append. - * If append is non-zero, this will append to the current string instead of - * writing over it. - * - * In the case that this function is called and the buffer was not large enough - * to hold the result, the partial write will be truncated, and the result - * AST_DYNSTR_BUILD_RETRY will be returned to indicate that the buffer size - * was increased, and the function should be called a second time. - * - * A return of AST_DYNSTR_BUILD_FAILED indicates a memory allocation error. - * - * A return value greater than or equal to zero indicates the number of - * characters that have been written, not including the terminating '\0'. - * In the append case, this only includes the number of characters appended. - * - * \note This function should never need to be called directly. It should - * through calling one of the other functions or macros defined in this - * file. - */ -int __ast_str_helper(struct ast_str **buf, size_t max_len, - int append, const char *fmt, va_list ap); - -/*! - * \brief Set a dynamic string using variable arguments - * - * \arg buf This is the address of a pointer to a struct ast_str which should - * have been retrieved using ast_str_thread_get. It will need to - * be updated in the case that the buffer has to be reallocated to - * accomodate a longer string than what it currently has space for. - * \arg max_len This is the maximum length to allow the string buffer to grow - * to. If this is set to 0, then there is no maximum length. - * If set to -1, we are bound to the current maximum length. - * \arg fmt This is the format string (printf style) - * - * \return The return value of this function is the same as that of the printf - * family of functions. - * - * All the rest is the same as ast_str_set_va() - */ -AST_INLINE_API( -int __attribute__ ((format (printf, 3, 4))) ast_str_set( - struct ast_str **buf, size_t max_len, const char *fmt, ...), -{ - int res; - va_list ap; - - va_start(ap, fmt); - res = ast_str_set_va(buf, max_len, fmt, ap); - va_end(ap); - - return res; -} -) - -/*! - * \brief Append to a thread local dynamic string - * - * The arguments, return values, and usage of this function are the same as - * ast_str_set(), but the new data is appended to the current value. - */ -AST_INLINE_API( -int __attribute__ ((format (printf, 3, 4))) ast_str_append( - struct ast_str **buf, size_t max_len, const char *fmt, ...), -{ - int res; - va_list ap; - - va_start(ap, fmt); - res = ast_str_append_va(buf, max_len, fmt, ap); - va_end(ap); - - return res; -} -) - -/*! - * \brief Compute a hash value on a string - * - * This famous hash algorithm was written by Dan Bernstein and is - * commonly used. - * - * http://www.cse.yorku.ca/~oz/hash.html - */ -static force_inline int ast_str_hash(const char *str) -{ - int hash = 5381; - - while (*str) - hash = hash * 33 ^ *str++; - - return abs(hash); -} - -#endif /* _ASTERISK_STRINGS_H */ |