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