00001 /* 00002 * Asterisk -- An open source telephony toolkit. 00003 * 00004 * Copyright (C) 1999 - 2005, 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 <string.h> 00027 #include <stdarg.h> 00028 00029 #include "asterisk/inline_api.h" 00030 #include "asterisk/compiler.h" 00031 #include "asterisk/compat.h" 00032 00033 static force_inline int ast_strlen_zero(const char *s) 00034 { 00035 return (!s || (*s == '\0')); 00036 } 00037 00038 /*! 00039 \brief Gets a pointer to the first non-whitespace character in a string. 00040 \param ast_skip_blanks function being used 00041 \param str the input string 00042 \return a pointer to the first non-whitespace character 00043 */ 00044 AST_INLINE_API( 00045 char *ast_skip_blanks(char *str), 00046 { 00047 while (*str && *str < 33) 00048 str++; 00049 return str; 00050 } 00051 ) 00052 00053 /*! 00054 \brief Trims trailing whitespace characters from a string. 00055 \param ast_trim_blanks function being used 00056 \param str the input string 00057 \return a pointer to the modified string 00058 */ 00059 AST_INLINE_API( 00060 char *ast_trim_blanks(char *str), 00061 { 00062 char *work = str; 00063 00064 if (work) { 00065 work += strlen(work) - 1; 00066 /* It's tempting to only want to erase after we exit this loop, 00067 but since ast_trim_blanks *could* receive a constant string 00068 (which we presumably wouldn't have to touch), we shouldn't 00069 actually set anything unless we must, and it's easier just 00070 to set each position to \0 than to keep track of a variable 00071 for it */ 00072 while ((work >= str) && *work < 33) 00073 *(work--) = '\0'; 00074 } 00075 return str; 00076 } 00077 ) 00078 00079 /*! 00080 \brief Gets a pointer to first whitespace character in a string. 00081 \param ast_skip_noblanks function being used 00082 \param str the input string 00083 \return a pointer to the first whitespace character 00084 */ 00085 AST_INLINE_API( 00086 char *ast_skip_nonblanks(char *str), 00087 { 00088 while (*str && *str > 32) 00089 str++; 00090 return str; 00091 } 00092 ) 00093 00094 /*! 00095 \brief Strip leading/trailing whitespace from a string. 00096 \param s The string to be stripped (will be modified). 00097 \return The stripped string. 00098 00099 This functions strips all leading and trailing whitespace 00100 characters from the input string, and returns a pointer to 00101 the resulting string. The string is modified in place. 00102 */ 00103 AST_INLINE_API( 00104 char *ast_strip(char *s), 00105 { 00106 s = ast_skip_blanks(s); 00107 if (s) 00108 ast_trim_blanks(s); 00109 return s; 00110 } 00111 ) 00112 00113 /*! 00114 \brief Strip leading/trailing whitespace and quotes from a string. 00115 \param s The string to be stripped (will be modified). 00116 \param beg_quotes The list of possible beginning quote characters. 00117 \param end_quotes The list of matching ending quote characters. 00118 \return The stripped string. 00119 00120 This functions strips all leading and trailing whitespace 00121 characters from the input string, and returns a pointer to 00122 the resulting string. The string is modified in place. 00123 00124 It can also remove beginning and ending quote (or quote-like) 00125 characters, in matching pairs. If the first character of the 00126 string matches any character in beg_quotes, and the last 00127 character of the string is the matching character in 00128 end_quotes, then they are removed from the string. 00129 00130 Examples: 00131 \code 00132 ast_strip_quoted(buf, "\"", "\""); 00133 ast_strip_quoted(buf, "'", "'"); 00134 ast_strip_quoted(buf, "[{(", "]})"); 00135 \endcode 00136 */ 00137 char *ast_strip_quoted(char *s, const char *beg_quotes, const char *end_quotes); 00138 00139 /*! 00140 \brief Size-limited null-terminating string copy. 00141 \param ast_copy_string function being used 00142 \param dst The destination buffer. 00143 \param src The source string 00144 \param size The size of the destination buffer 00145 \return Nothing. 00146 00147 This is similar to \a strncpy, with two important differences: 00148 - the destination buffer will \b always be null-terminated 00149 - the destination buffer is not filled with zeros past the copied string length 00150 These differences make it slightly more efficient, and safer to use since it will 00151 not leave the destination buffer unterminated. There is no need to pass an artificially 00152 reduced buffer size to this function (unlike \a strncpy), and the buffer does not need 00153 to be initialized to zeroes prior to calling this function. 00154 */ 00155 AST_INLINE_API( 00156 void ast_copy_string(char *dst, const char *src, size_t size), 00157 { 00158 while (*src && size) { 00159 *dst++ = *src++; 00160 size--; 00161 } 00162 if (__builtin_expect(!size, 0)) 00163 dst--; 00164 *dst = '\0'; 00165 } 00166 ) 00167 00168 /*! 00169 \brief Build a string in a buffer, designed to be called repeatedly 00170 00171 This is a wrapper for snprintf, that properly handles the buffer pointer 00172 and buffer space available. 00173 00174 \param buffer current position in buffer to place string into (will be updated on return) 00175 \param space remaining space in buffer (will be updated on return) 00176 \param fmt printf-style format string 00177 \return 0 on success, non-zero on failure. 00178 */ 00179 int ast_build_string(char **buffer, size_t *space, const char *fmt, ...) __attribute__ ((format (printf, 3, 4))); 00180 00181 /*! 00182 \brief Build a string in a buffer, designed to be called repeatedly 00183 00184 This is a wrapper for snprintf, that properly handles the buffer pointer 00185 and buffer space available. 00186 00187 \return 0 on success, non-zero on failure. 00188 \param buffer current position in buffer to place string into (will be updated on return) 00189 \param space remaining space in buffer (will be updated on return) 00190 \param fmt printf-style format string 00191 \param ap varargs list of arguments for format 00192 */ 00193 int ast_build_string_va(char **buffer, size_t *space, const char *fmt, va_list ap); 00194 00195 /*! Make sure something is true */ 00196 /*! 00197 * Determine if a string containing a boolean value is "true". 00198 * 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". 00199 * 00200 * Returns 0 if val is a NULL pointer, -1 if "true", and 0 otherwise. 00201 */ 00202 int ast_true(const char *val); 00203 00204 /*! Make sure something is false */ 00205 /*! 00206 * Determine if a string containing a boolean value is "false". 00207 * 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". 00208 * 00209 * Returns 0 if val is a NULL pointer, -1 if "false", and 0 otherwise. 00210 */ 00211 int ast_false(const char *val); 00212 00213 /* The realloca lets us ast_restrdupa(), but you can't mix any other ast_strdup calls! */ 00214 00215 struct ast_realloca { 00216 char *ptr; 00217 int alloclen; 00218 }; 00219 00220 #define ast_restrdupa(ra, s) \ 00221 ({ \ 00222 if ((ra)->ptr && strlen(s) + 1 < (ra)->alloclen) { \ 00223 strcpy((ra)->ptr, s); \ 00224 } else { \ 00225 (ra)->ptr = alloca(strlen(s) + 1 - (ra)->alloclen); \ 00226 if ((ra)->ptr) (ra)->alloclen = strlen(s) + 1; \ 00227 } \ 00228 (ra)->ptr; \ 00229 }) 00230 00231 #ifndef HAVE_STRCASESTR 00232 char *strcasestr(const char *, const char *); 00233 #endif 00234 00235 #if !defined(HAVE_STRNDUP) && !defined(__AST_DEBUG_MALLOC) 00236 char *strndup(const char *, size_t); 00237 #endif 00238 00239 #ifndef HAVE_STRNLEN 00240 size_t strnlen(const char *, size_t); 00241 #endif 00242 00243 #if !defined(HAVE_VASPRINTF) && !defined(__AST_DEBUG_MALLOC) 00244 int vasprintf(char **strp, const char *fmt, va_list ap); 00245 #endif 00246 00247 #ifndef HAVE_STRTOQ 00248 uint64_t strtoq(const char *nptr, char **endptr, int base); 00249 #endif 00250 00251 #endif /* _ASTERISK_STRINGS_H */