include/asterisk/strings.h

   1 /*
   2  * Asterisk -- An open source telephony toolkit.
   3  *
   4  * Copyright (C) 1999 - 2006, Digium, Inc.
   5  *
   6  * Mark Spencer <markster@digium.com>
   7  *
   8  * See http://www.asterisk.org for more information about
   9  * the Asterisk project. Please do not directly contact
  10  * any of the maintainers of this project for assistance;
  11  * the project provides a web site, mailing lists and IRC
  12  * channels for your use.
  13  *
  14  * This program is free software, distributed under the terms of
  15  * the GNU General Public License Version 2. See the LICENSE file
  16  * at the top of the source tree.
  17  */
  18
  19 /*! \file
  20  * \brief String manipulation functions
  21  */
  22
  23 #ifndef _ASTERISK_STRINGS_H
  24 #define _ASTERISK_STRINGS_H
  25
  26 #include <stdlib.h>
  27 #include <string.h>
  28 #include <stdarg.h>
  29
  30 #include "asterisk/inline_api.h"
  31 #include "asterisk/compiler.h"
  32 #include "asterisk/compat.h"
  33
  34 static force_inline int ast_strlen_zero(const char *s)
  35 {
  36         return (!s || (*s == '\0'));
  37 }
  38
  39 /*! \brief returns the equivalent of logic or for strings:
  40  * first one if not empty, otherwise second one.
  41  */
  42 #define S_OR(a, b)      (!ast_strlen_zero(a) ? (a) : (b))
  43
  44 /*!
  45   \brief Gets a pointer to the first non-whitespace character in a string.
  46   \param ast_skip_blanks function being used
  47   \param str the input string
  48   \return a pointer to the first non-whitespace character
  49  */
  50 AST_INLINE_API(
  51 char *ast_skip_blanks(const char *str),
  52 {
  53         while (*str && ((unsigned char) *str) < 33)
  54                 str++;
  55         return (char *)str;
  56 }
  57 )
  58
  59 /*!
  60   \brief Trims trailing whitespace characters from a string.
  61   \param ast_trim_blanks function being used
  62   \param str the input string
  63   \return a pointer to the modified string
  64  */
  65 AST_INLINE_API(
  66 char *ast_trim_blanks(char *str),
  67 {
  68         char *work = str;
  69
  70         if (work) {
  71                 work += strlen(work) - 1;
  72                 /* It's tempting to only want to erase after we exit this loop,
  73                    but since ast_trim_blanks *could* receive a constant string
  74                    (which we presumably wouldn't have to touch), we shouldn't
  75                    actually set anything unless we must, and it's easier just
  76                    to set each position to \0 than to keep track of a variable
  77                    for it */
  78                 while ((work >= str) && ((unsigned char) *work) < 33)
  79                         *(work--) = '\0';
  80         }
  81         return str;
  82 }
  83 )
  84
  85 /*!
  86   \brief Gets a pointer to first whitespace character in a string.
  87   \param ast_skip_noblanks function being used
  88   \param str the input string
  89   \return a pointer to the first whitespace character
  90  */
  91 AST_INLINE_API(
  92 char *ast_skip_nonblanks(char *str),
  93 {
  94         while (*str && ((unsigned char) *str) > 32)
  95                 str++;
  96         return str;
  97 }
  98 )
  99
 100 /*!
 101   \brief Strip leading/trailing whitespace from a string.
 102   \param s The string to be stripped (will be modified).
 103   \return The stripped string.
 104
 105   This functions strips all leading and trailing whitespace
 106   characters from the input string, and returns a pointer to
 107   the resulting string. The string is modified in place.
 108 */
 109 AST_INLINE_API(
 110 char *ast_strip(char *s),
 111 {
 112         s = ast_skip_blanks(s);
 113         if (s)
 114                 ast_trim_blanks(s);
 115         return s;
 116 }
 117 )
 118
 119 /*!
 120   \brief Strip leading/trailing whitespace and quotes from a string.
 121   \param s The string to be stripped (will be modified).
 122   \param beg_quotes The list of possible beginning quote characters.
 123   \param end_quotes The list of matching ending quote characters.
 124   \return The stripped string.
 125
 126   This functions strips all leading and trailing whitespace
 127   characters from the input string, and returns a pointer to
 128   the resulting string. The string is modified in place.
 129
 130   It can also remove beginning and ending quote (or quote-like)
 131   characters, in matching pairs. If the first character of the
 132   string matches any character in beg_quotes, and the last
 133   character of the string is the matching character in
 134   end_quotes, then they are removed from the string.
 135
 136   Examples:
 137   \code
 138   ast_strip_quoted(buf, "\"", "\"");
 139   ast_strip_quoted(buf, "'", "'");
 140   ast_strip_quoted(buf, "[{(", "]})");
 141   \endcode
 142  */
 143 char *ast_strip_quoted(char *s, const char *beg_quotes, const char *end_quotes);
 144
 145 /*!
 146   \brief Strip backslash for "escaped" semicolons.
 147   \brief s The string to be stripped (will be modified).
 148   \return The stripped string.
 149  */
 150 char *ast_unescape_semicolon(char *s);
 151
 152 /*!
 153   \brief Size-limited null-terminating string copy.
 154   \param ast_copy_string function being used
 155   \param dst The destination buffer.
 156   \param src The source string
 157   \param size The size of the destination buffer
 158   \return Nothing.
 159
 160   This is similar to \a strncpy, with two important differences:
 161     - the destination buffer will \b always be null-terminated
 162     - the destination buffer is not filled with zeros past the copied string length
 163   These differences make it slightly more efficient, and safer to use since it will
 164   not leave the destination buffer unterminated. There is no need to pass an artificially
 165   reduced buffer size to this function (unlike \a strncpy), and the buffer does not need
 166   to be initialized to zeroes prior to calling this function.
 167 */
 168 AST_INLINE_API(
 169 void ast_copy_string(char *dst, const char *src, size_t size),
 170 {
 171         while (*src && size) {
 172                 *dst++ = *src++;
 173                 size--;
 174         }
 175         if (__builtin_expect(!size, 0))
 176                 dst--;
 177         *dst = '\0';
 178 }
 179 )
 180
 181
 182 /*!
 183   \brief Build a string in a buffer, designed to be called repeatedly
 184
 185   This is a wrapper for snprintf, that properly handles the buffer pointer
 186   and buffer space available.
 187
 188   \param buffer current position in buffer to place string into (will be updated on return)
 189   \param space remaining space in buffer (will be updated on return)
 190   \param fmt printf-style format string
 191   \return 0 on success, non-zero on failure.
 192 */
 193 int ast_build_string(char **buffer, size_t *space, const char *fmt, ...) __attribute__ ((format (printf, 3, 4)));
 194
 195 /*!
 196   \brief Build a string in a buffer, designed to be called repeatedly
 197
 198   This is a wrapper for snprintf, that properly handles the buffer pointer
 199   and buffer space available.
 200
 201   \return 0 on success, non-zero on failure.
 202   \param buffer current position in buffer to place string into (will be updated on return)
 203   \param space remaining space in buffer (will be updated on return)
 204   \param fmt printf-style format string
 205   \param ap varargs list of arguments for format
 206 */
 207 int ast_build_string_va(char **buffer, size_t *space, const char *fmt, va_list ap);
 208
 209 /*! Make sure something is true */
 210 /*!
 211  * Determine if a string containing a boolean value is "true".
 212  * 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".
 213  *
 214  * Returns 0 if val is a NULL pointer, -1 if "true", and 0 otherwise.
 215  */
 216 int ast_true(const char *val);
 217
 218 /*! Make sure something is false */
 219 /*!
 220  * Determine if a string containing a boolean value is "false".
 221  * 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".
 222  *
 223  * Returns 0 if val is a NULL pointer, -1 if "false", and 0 otherwise.
 224  */
 225 int ast_false(const char *val);
 226
 227 /*
 228   \brief Join an array of strings into a single string.
 229   \param s the resulting string buffer
 230   \param len the length of the result buffer, s
 231   \param w an array of strings to join
 232
 233   This function will join all of the strings in the array 'w' into a single
 234   string.  It will also place a space in the result buffer in between each
 235   string from 'w'.
 236 */
 237 void ast_join(char *s, size_t len, char * const w[]);
 238
 239 /*
 240   \brief Parse a time (integer) string.
 241   \param src String to parse
 242   \param dst Destination
 243   \param _default Value to use if the string does not contain a valid time
 244   \param consumed The number of characters 'consumed' in the string by the parse (see 'man sscanf' for details)
 245   \return zero on success, non-zero on failure
 246 */
 247 int ast_get_time_t(const char *src, time_t *dst, time_t _default, int *consumed);
 248
 249 /* The realloca lets us ast_restrdupa(), but you can't mix any other ast_strdup calls! */
 250
 251 struct ast_realloca {
 252         char *ptr;
 253         int alloclen;
 254 };
 255
 256 #define ast_restrdupa(ra, s) \
 257         ({ \
 258                 if ((ra)->ptr && strlen(s) + 1 < (ra)->alloclen) { \
 259                         strcpy((ra)->ptr, s); \
 260                 } else { \
 261                         (ra)->ptr = alloca(strlen(s) + 1 - (ra)->alloclen); \
 262                         if ((ra)->ptr) (ra)->alloclen = strlen(s) + 1; \
 263                 } \
 264                 (ra)->ptr; \
 265         })
 266
 267 /*!
 268  * \brief Compute a hash value on a string
 269  *
 270  * This famous hash algorithm was written by Dan Bernstein and is
 271  * commonly used.
 272  *
 273  * http://www.cse.yorku.ca/~oz/hash.html
 274  */
 275 static force_inline int ast_str_hash(const char *str)
 276 {
 277         int hash = 5381;
 278
 279         while (*str)
 280                 hash = hash * 33 ^ *str++;
 281
 282         return abs(hash);
 283 }
 284
 285 #endif /* _ASTERISK_STRINGS_H */