Asterisk.org: Developer Documentation (28 Oct 2009)

Wed Oct 28 15:47:56 2009

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