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

Generated on Wed Aug 15 01:24:24 2007 for Asterisk - the Open Source PBX by  doxygen 1.5.3