Fri Aug 24 02:22:17 2007

Asterisk developer's documentation


strings.h

Go to the documentation of this file.
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 && *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) && *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 && *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 */

Generated on Fri Aug 24 02:22:17 2007 for Asterisk - the Open Source PBX by  doxygen 1.5.1