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