Sat Aug 6 00:39:32 2011

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 #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 */

Generated on Sat Aug 6 00:39:32 2011 for Asterisk - the Open Source PBX by  doxygen 1.4.7