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 <stdlib.h> 00027 #include <string.h> 00028 #include <stdarg.h> 00029 #include <ctype.h> 00030 00031 #include "asterisk/inline_api.h" 00032 #include "asterisk/compiler.h" 00033 #include "asterisk/compat.h" 00034 00035 static force_inline int ast_strlen_zero(const char *s) 00036 { 00037 return (!s || (*s == '\0')); 00038 } 00039 00040 /*! \brief returns the equivalent of logic or for strings: 00041 * first one if not empty, otherwise second one. 00042 */ 00043 #define S_OR(a, b) (!ast_strlen_zero(a) ? (a) : (b)) 00044 00045 /*! 00046 \brief Gets a pointer to the first non-whitespace character in a string. 00047 \param ast_skip_blanks function being used 00048 \param str the input string 00049 \return a pointer to the first non-whitespace character 00050 */ 00051 AST_INLINE_API( 00052 char *ast_skip_blanks(const char *str), 00053 { 00054 while (*str && ((unsigned char) *str) < 33) 00055 str++; 00056 return (char *)str; 00057 } 00058 ) 00059 00060 /*! 00061 \brief Trims trailing whitespace characters from a string. 00062 \param ast_trim_blanks function being used 00063 \param str the input string 00064 \return a pointer to the modified string 00065 */ 00066 AST_INLINE_API( 00067 char *ast_trim_blanks(char *str), 00068 { 00069 char *work = str; 00070 00071 if (work) { 00072 work += strlen(work) - 1; 00073 /* It's tempting to only want to erase after we exit this loop, 00074 but since ast_trim_blanks *could* receive a constant string 00075 (which we presumably wouldn't have to touch), we shouldn't 00076 actually set anything unless we must, and it's easier just 00077 to set each position to \0 than to keep track of a variable 00078 for it */ 00079 while ((work >= str) && ((unsigned char) *work) < 33) 00080 *(work--) = '\0'; 00081 } 00082 return str; 00083 } 00084 ) 00085 00086 /*! 00087 \brief Gets a pointer to first whitespace character in a string. 00088 \param ast_skip_noblanks function being used 00089 \param str the input string 00090 \return a pointer to the first whitespace character 00091 */ 00092 AST_INLINE_API( 00093 char *ast_skip_nonblanks(char *str), 00094 { 00095 while (*str && ((unsigned char) *str) > 32) 00096 str++; 00097 return str; 00098 } 00099 ) 00100 00101 /*! 00102 \brief Strip leading/trailing whitespace from a string. 00103 \param s The string to be stripped (will be modified). 00104 \return The stripped string. 00105 00106 This functions strips all leading and trailing whitespace 00107 characters from the input string, and returns a pointer to 00108 the resulting string. The string is modified in place. 00109 */ 00110 AST_INLINE_API( 00111 char *ast_strip(char *s), 00112 { 00113 s = ast_skip_blanks(s); 00114 if (s) 00115 ast_trim_blanks(s); 00116 return s; 00117 } 00118 ) 00119 00120 /*! 00121 \brief Strip leading/trailing whitespace and quotes from a string. 00122 \param s The string to be stripped (will be modified). 00123 \param beg_quotes The list of possible beginning quote characters. 00124 \param end_quotes The list of matching ending quote characters. 00125 \return The stripped string. 00126 00127 This functions strips all leading and trailing whitespace 00128 characters from the input string, and returns a pointer to 00129 the resulting string. The string is modified in place. 00130 00131 It can also remove beginning and ending quote (or quote-like) 00132 characters, in matching pairs. If the first character of the 00133 string matches any character in beg_quotes, and the last 00134 character of the string is the matching character in 00135 end_quotes, then they are removed from the string. 00136 00137 Examples: 00138 \code 00139 ast_strip_quoted(buf, "\"", "\""); 00140 ast_strip_quoted(buf, "'", "'"); 00141 ast_strip_quoted(buf, "[{(", "]})"); 00142 \endcode 00143 */ 00144 char *ast_strip_quoted(char *s, const char *beg_quotes, const char *end_quotes); 00145 00146 /*! 00147 \brief Strip backslash for "escaped" semicolons. 00148 \brief s The string to be stripped (will be modified). 00149 \return The stripped string. 00150 */ 00151 char *ast_unescape_semicolon(char *s); 00152 00153 /*! 00154 \brief Size-limited null-terminating string copy. 00155 \param ast_copy_string function being used 00156 \param dst The destination buffer. 00157 \param src The source string 00158 \param size The size of the destination buffer 00159 \return Nothing. 00160 00161 This is similar to \a strncpy, with two important differences: 00162 - the destination buffer will \b always be null-terminated 00163 - the destination buffer is not filled with zeros past the copied string length 00164 These differences make it slightly more efficient, and safer to use since it will 00165 not leave the destination buffer unterminated. There is no need to pass an artificially 00166 reduced buffer size to this function (unlike \a strncpy), and the buffer does not need 00167 to be initialized to zeroes prior to calling this function. 00168 */ 00169 AST_INLINE_API( 00170 void ast_copy_string(char *dst, const char *src, size_t size), 00171 { 00172 while (*src && size) { 00173 *dst++ = *src++; 00174 size--; 00175 } 00176 if (__builtin_expect(!size, 0)) 00177 dst--; 00178 *dst = '\0'; 00179 } 00180 ) 00181 00182 00183 /*! 00184 \brief Build a string in a buffer, designed to be called repeatedly 00185 00186 This is a wrapper for snprintf, that properly handles the buffer pointer 00187 and buffer space available. 00188 00189 \param buffer current position in buffer to place string into (will be updated on return) 00190 \param space remaining space in buffer (will be updated on return) 00191 \param fmt printf-style format string 00192 \return 0 on success, non-zero on failure. 00193 */ 00194 int ast_build_string(char **buffer, size_t *space, const char *fmt, ...) __attribute__((format(printf, 3, 4))); 00195 00196 /*! 00197 \brief Build a string in a buffer, designed to be called repeatedly 00198 00199 This is a wrapper for snprintf, that properly handles the buffer pointer 00200 and buffer space available. 00201 00202 \return 0 on success, non-zero on failure. 00203 \param buffer current position in buffer to place string into (will be updated on return) 00204 \param space remaining space in buffer (will be updated on return) 00205 \param fmt printf-style format string 00206 \param ap varargs list of arguments for format 00207 */ 00208 int ast_build_string_va(char **buffer, size_t *space, const char *fmt, va_list ap) __attribute__((format(printf, 3, 0))); 00209 00210 /*! Make sure something is true */ 00211 /*! 00212 * Determine if a string containing a boolean value is "true". 00213 * 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". 00214 * 00215 * Returns 0 if val is a NULL pointer, -1 if "true", and 0 otherwise. 00216 */ 00217 int ast_true(const char *val); 00218 00219 /*! Make sure something is false */ 00220 /*! 00221 * Determine if a string containing a boolean value is "false". 00222 * 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". 00223 * 00224 * Returns 0 if val is a NULL pointer, -1 if "false", and 0 otherwise. 00225 */ 00226 int ast_false(const char *val); 00227 00228 /* 00229 \brief Join an array of strings into a single string. 00230 \param s the resulting string buffer 00231 \param len the length of the result buffer, s 00232 \param w an array of strings to join 00233 00234 This function will join all of the strings in the array 'w' into a single 00235 string. It will also place a space in the result buffer in between each 00236 string from 'w'. 00237 */ 00238 void ast_join(char *s, size_t len, char * const w[]); 00239 00240 /* 00241 \brief Parse a time (integer) string. 00242 \param src String to parse 00243 \param dst Destination 00244 \param _default Value to use if the string does not contain a valid time 00245 \param consumed The number of characters 'consumed' in the string by the parse (see 'man sscanf' for details) 00246 \return zero on success, non-zero on failure 00247 */ 00248 int ast_get_time_t(const char *src, time_t *dst, time_t _default, int *consumed); 00249 00250 /* The realloca lets us ast_restrdupa(), but you can't mix any other ast_strdup calls! */ 00251 00252 struct ast_realloca { 00253 char *ptr; 00254 int alloclen; 00255 }; 00256 00257 #define ast_restrdupa(ra, s) \ 00258 ({ \ 00259 if ((ra)->ptr && strlen(s) + 1 < (ra)->alloclen) { \ 00260 strcpy((ra)->ptr, s); \ 00261 } else { \ 00262 (ra)->ptr = alloca(strlen(s) + 1 - (ra)->alloclen); \ 00263 if ((ra)->ptr) (ra)->alloclen = strlen(s) + 1; \ 00264 } \ 00265 (ra)->ptr; \ 00266 }) 00267 00268 /*! 00269 * \brief Compute a hash value on a string 00270 * 00271 * This famous hash algorithm was written by Dan Bernstein and is 00272 * commonly used. 00273 * 00274 * http://www.cse.yorku.ca/~oz/hash.html 00275 */ 00276 static force_inline int ast_str_hash(const char *str) 00277 { 00278 int hash = 5381; 00279 00280 while (*str) 00281 hash = hash * 33 ^ *str++; 00282 00283 return abs(hash); 00284 } 00285 00286 /*! 00287 * \brief Compute a hash value on a case-insensitive string 00288 * 00289 * Uses the same hash algorithm as ast_str_hash, but converts 00290 * all characters to lowercase prior to computing a hash. This 00291 * allows for easy case-insensitive lookups in a hash table. 00292 */ 00293 static force_inline int ast_str_case_hash(const char *str) 00294 { 00295 int hash = 5381; 00296 00297 while (*str) { 00298 hash = hash * 33 ^ tolower(*str++); 00299 } 00300 00301 return abs(hash); 00302 } 00303 00304 #endif /* _ASTERISK_STRINGS_H */