f6902ef1b3fbb27b9baaff795a3d67fcd859a555
[asterisk/asterisk.git] / include / asterisk / strings.h
1 /*
2  * Asterisk -- A telephony toolkit for Linux.
3  *
4  * String manipulation functions
5  *
6  * Copyright (C) 2005, Digium, Inc.
7  *
8  * This program is free software, distributed under the terms of
9  * the GNU General Public License
10  */
11
12 #ifndef _ASTERISK_STRINGS_H
13 #define _ASTERISK_STRINGS_H
14
15 #include <string.h>
16
17 #include "asterisk/inline_api.h"
18 #include "asterisk/compiler.h"
19
20 static inline int ast_strlen_zero(const char *s)
21 {
22         return (*s == '\0');
23 }
24
25 /*!
26   \brief Gets a pointer to the first non-whitespace character in a string.
27   \param str the input string
28   \return a pointer to the first non-whitespace character
29  */
30 AST_INLINE_API(
31 char *ast_skip_blanks(char *str),
32 {
33         while (*str && *str < 33)
34                 str++;
35         return str;
36 }
37 )
38
39 /*!
40   \brief Trims trailing whitespace characters from a string.
41   \param str the input string
42   \return a pointer to the NULL following the string
43  */
44 AST_INLINE_API(
45 char *ast_trim_blanks(char *str),
46 {
47         char *work = str;
48
49         if (work) {
50                 work += strlen(work) - 1;
51                 /* It's tempting to only want to erase after we exit this loop, 
52                    but since ast_trim_blanks *could* receive a constant string
53                    (which we presumably wouldn't have to touch), we shouldn't
54                    actually set anything unless we must, and it's easier just
55                    to set each position to \0 than to keep track of a variable
56                    for it */
57                 while ((work >= str) && *work < 33)
58                         *(work--) = '\0';
59         }
60         return str;
61 }
62 )
63
64 /*!
65   \brief Gets a pointer to first whitespace character in a string.
66   \param str the input string
67   \return a pointer to the first whitespace character
68  */
69 AST_INLINE_API(
70 char *ast_skip_nonblanks(char *str),
71 {
72         while (*str && *str > 32)
73                 str++;
74         return str;
75 }
76 )
77   
78 /*!
79   \brief Strip leading/trailing whitespace from a string.
80   \param s The string to be stripped (will be modified).
81   \return The stripped string.
82
83   This functions strips all leading and trailing whitespace
84   characters from the input string, and returns a pointer to
85   the resulting string. The string is modified in place.
86 */
87 AST_INLINE_API(
88 char *ast_strip(char *s),
89 {
90         s = ast_skip_blanks(s);
91         if (s)
92                 ast_trim_blanks(s);
93         return s;
94
95 )
96
97 /*!
98   \brief Strip leading/trailing whitespace and quotes from a string.
99   \param s The string to be stripped (will be modified).
100   \param beg_quotes The list of possible beginning quote characters.
101   \param end_quotes The list of matching ending quote characters.
102   \return The stripped string.
103
104   This functions strips all leading and trailing whitespace
105   characters from the input string, and returns a pointer to
106   the resulting string. The string is modified in place.
107
108   It can also remove beginning and ending quote (or quote-like)
109   characters, in matching pairs. If the first character of the
110   string matches any character in beg_quotes, and the last
111   character of the string is the matching character in
112   end_quotes, then they are removed from the string.
113
114   Examples:
115   \code
116   ast_strip_quoted(buf, "\"", "\"");
117   ast_strip_quoted(buf, "'", "'");
118   ast_strip_quoted(buf, "[{(", "]})");
119   \endcode
120  */
121 char *ast_strip_quoted(char *s, const char *beg_quotes, const char *end_quotes);
122
123 /*!
124   \brief Size-limited null-terminating string copy.
125   \param dst The destination buffer.
126   \param src The source string
127   \param size The size of the destination buffer
128   \return Nothing.
129
130   This is similar to \a strncpy, with two important differences:
131     - the destination buffer will \b always be null-terminated
132     - the destination buffer is not filled with zeros past the copied string length
133   These differences make it slightly more efficient, and safer to use since it will
134   not leave the destination buffer unterminated. There is no need to pass an artificially
135   reduced buffer size to this function (unlike \a strncpy), and the buffer does not need
136   to be initialized to zeroes prior to calling this function.
137 */
138 AST_INLINE_API(
139 void ast_copy_string(char *dst, const char *src, size_t size),
140 {
141         while (*src && size) {
142                 *dst++ = *src++;
143                 size--;
144         }
145         if (__builtin_expect(!size, 0))
146                 dst--;
147         *dst = '\0';
148 }
149 )
150
151 /*!
152   \brief Build a string in a buffer, designed to be called repeatedly
153   
154   This is a wrapper for snprintf, that properly handles the buffer pointer
155   and buffer space available.
156
157   \return 0 on success, non-zero on failure.
158   \param buffer current position in buffer to place string into (will be updated on return)
159   \param space remaining space in buffer (will be updated on return)
160   \param fmt printf-style format string
161 */
162 int ast_build_string(char **buffer, size_t *space, const char *fmt, ...) __attribute__ ((format (printf, 3, 4)));
163
164 /*! Make sure something is true */
165 /*!
166  * Determine if a string containing a boolean value is "true".
167  * 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".  
168  *
169  * Returns 0 if val is a NULL pointer, -1 if "true", and 0 otherwise.
170  */
171 int ast_true(const char *val);
172
173 /*! Make sure something is false */
174 /*!
175  * Determine if a string containing a boolean value is "false".
176  * 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".  
177  *
178  * Returns 0 if val is a NULL pointer, -1 if "false", and 0 otherwise.
179  */
180 int ast_false(const char *val);
181
182 /* The realloca lets us ast_restrdupa(), but you can't mix any other ast_strdup calls! */
183
184 struct ast_realloca {
185         char *ptr;
186         int alloclen;
187 };
188
189 #define ast_restrdupa(ra, s) \
190         ({ \
191                 if ((ra)->ptr && strlen(s) + 1 < (ra)->alloclen) { \
192                         strcpy((ra)->ptr, s); \
193                 } else { \
194                         (ra)->ptr = alloca(strlen(s) + 1 - (ra)->alloclen); \
195                         if ((ra)->ptr) (ra)->alloclen = strlen(s) + 1; \
196                 } \
197                 (ra)->ptr; \
198         })
199
200 #ifdef __linux__
201 #define ast_strcasestr strcasestr
202 #define ast_strndup     strndup
203 #define ast_strnlen     strnlen
204 #else /* !__linux__ */
205 char *ast_strcasestr(const char *, const char *);
206 char *ast_strndup(const char *, size_t);
207 size_t ast_strnlen(const char *, size_t);
208 #endif /* !__linux__ */
209
210 #endif /* _ASTERISK_STRINGS_H */