add API function for parsing strings to time_t (issue #6320, with mods)
[asterisk/asterisk.git] / 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 <string.h>
27 #include <stdarg.h>
28
29 #include "asterisk/inline_api.h"
30 #include "asterisk/compiler.h"
31 #include "asterisk/compat.h"
32
33 static force_inline int ast_strlen_zero(const char *s)
34 {
35         return (!s || (*s == '\0'));
36 }
37
38 /*!
39   \brief Gets a pointer to the first non-whitespace character in a string.
40   \param ast_skip_blanks function being used
41   \param str the input string
42   \return a pointer to the first non-whitespace character
43  */
44 AST_INLINE_API(
45 char *ast_skip_blanks(const char *str),
46 {
47         while (*str && *str < 33)
48                 str++;
49         return (char *)str;
50 }
51 )
52
53 /*!
54   \brief Trims trailing whitespace characters from a string.
55   \param ast_trim_blanks function being used
56   \param str the input string
57   \return a pointer to the modified string
58  */
59 AST_INLINE_API(
60 char *ast_trim_blanks(char *str),
61 {
62         char *work = str;
63
64         if (work) {
65                 work += strlen(work) - 1;
66                 /* It's tempting to only want to erase after we exit this loop, 
67                    but since ast_trim_blanks *could* receive a constant string
68                    (which we presumably wouldn't have to touch), we shouldn't
69                    actually set anything unless we must, and it's easier just
70                    to set each position to \0 than to keep track of a variable
71                    for it */
72                 while ((work >= str) && *work < 33)
73                         *(work--) = '\0';
74         }
75         return str;
76 }
77 )
78
79 /*!
80   \brief Gets a pointer to first whitespace character in a string.
81   \param ast_skip_noblanks function being used
82   \param str the input string
83   \return a pointer to the first whitespace character
84  */
85 AST_INLINE_API(
86 char *ast_skip_nonblanks(char *str),
87 {
88         while (*str && *str > 32)
89                 str++;
90         return str;
91 }
92 )
93   
94 /*!
95   \brief Strip leading/trailing whitespace from a string.
96   \param s The string to be stripped (will be modified).
97   \return The stripped string.
98
99   This functions strips all leading and trailing whitespace
100   characters from the input string, and returns a pointer to
101   the resulting string. The string is modified in place.
102 */
103 AST_INLINE_API(
104 char *ast_strip(char *s),
105 {
106         s = ast_skip_blanks(s);
107         if (s)
108                 ast_trim_blanks(s);
109         return s;
110
111 )
112
113 /*!
114   \brief Strip leading/trailing whitespace and quotes from a string.
115   \param s The string to be stripped (will be modified).
116   \param beg_quotes The list of possible beginning quote characters.
117   \param end_quotes The list of matching ending quote characters.
118   \return The stripped string.
119
120   This functions strips all leading and trailing whitespace
121   characters from the input string, and returns a pointer to
122   the resulting string. The string is modified in place.
123
124   It can also remove beginning and ending quote (or quote-like)
125   characters, in matching pairs. If the first character of the
126   string matches any character in beg_quotes, and the last
127   character of the string is the matching character in
128   end_quotes, then they are removed from the string.
129
130   Examples:
131   \code
132   ast_strip_quoted(buf, "\"", "\"");
133   ast_strip_quoted(buf, "'", "'");
134   ast_strip_quoted(buf, "[{(", "]})");
135   \endcode
136  */
137 char *ast_strip_quoted(char *s, const char *beg_quotes, const char *end_quotes);
138
139 /*!
140   \brief Size-limited null-terminating string copy.
141   \param ast_copy_string function being used
142   \param dst The destination buffer.
143   \param src The source string
144   \param size The size of the destination buffer
145   \return Nothing.
146
147   This is similar to \a strncpy, with two important differences:
148     - the destination buffer will \b always be null-terminated
149     - the destination buffer is not filled with zeros past the copied string length
150   These differences make it slightly more efficient, and safer to use since it will
151   not leave the destination buffer unterminated. There is no need to pass an artificially
152   reduced buffer size to this function (unlike \a strncpy), and the buffer does not need
153   to be initialized to zeroes prior to calling this function.
154 */
155 AST_INLINE_API(
156 void ast_copy_string(char *dst, const char *src, size_t size),
157 {
158         while (*src && size) {
159                 *dst++ = *src++;
160                 size--;
161         }
162         if (__builtin_expect(!size, 0))
163                 dst--;
164         *dst = '\0';
165 }
166 )
167
168
169 /*!
170   \brief Build a string in a buffer, designed to be called repeatedly
171   
172   This is a wrapper for snprintf, that properly handles the buffer pointer
173   and buffer space available.
174
175   \param buffer current position in buffer to place string into (will be updated on return)
176   \param space remaining space in buffer (will be updated on return)
177   \param fmt printf-style format string
178   \return 0 on success, non-zero on failure.
179 */
180 int ast_build_string(char **buffer, size_t *space, const char *fmt, ...) __attribute__ ((format (printf, 3, 4)));
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   \return 0 on success, non-zero on failure.
189   \param buffer current position in buffer to place string into (will be updated on return)
190   \param space remaining space in buffer (will be updated on return)
191   \param fmt printf-style format string
192   \param ap varargs list of arguments for format
193 */
194 int ast_build_string_va(char **buffer, size_t *space, const char *fmt, va_list ap);
195
196 /*! Make sure something is true */
197 /*!
198  * Determine if a string containing a boolean value is "true".
199  * 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".  
200  *
201  * Returns 0 if val is a NULL pointer, -1 if "true", and 0 otherwise.
202  */
203 int ast_true(const char *val);
204
205 /*! Make sure something is false */
206 /*!
207  * Determine if a string containing a boolean value is "false".
208  * 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".  
209  *
210  * Returns 0 if val is a NULL pointer, -1 if "false", and 0 otherwise.
211  */
212 int ast_false(const char *val);
213
214 /*
215   \brief Join an array of strings into a single string.
216   \param s the resulting string buffer
217   \param len the length of the result buffer, s
218   \param w an array of strings to join
219
220   This function will join all of the strings in the array 'w' into a single
221   string.  It will also place a space in the result buffer in between each
222   string from 'w'.
223 */
224 void ast_join(char *s, size_t len, char * const w[]);
225
226 /*
227   \brief Parse a time (integer) string.
228   \param src String to parse
229   \param dst Destination
230   \param _default Value to use if the string does not contain a valid time
231   \return zero on success, non-zero on failure
232 */
233 int ast_get_time_t(const char *src, time_t *dst, time_t _default);
234
235 /* The realloca lets us ast_restrdupa(), but you can't mix any other ast_strdup calls! */
236
237 struct ast_realloca {
238         char *ptr;
239         int alloclen;
240 };
241
242 #define ast_restrdupa(ra, s) \
243         ({ \
244                 if ((ra)->ptr && strlen(s) + 1 < (ra)->alloclen) { \
245                         strcpy((ra)->ptr, s); \
246                 } else { \
247                         (ra)->ptr = alloca(strlen(s) + 1 - (ra)->alloclen); \
248                         if ((ra)->ptr) (ra)->alloclen = strlen(s) + 1; \
249                 } \
250                 (ra)->ptr; \
251         })
252
253 #ifndef HAVE_STRCASESTR
254 char *strcasestr(const char *, const char *);
255 #endif
256
257 #if !defined(HAVE_STRNDUP) && !defined(__AST_DEBUG_MALLOC)
258 char *strndup(const char *, size_t);
259 #endif
260
261 #ifndef HAVE_STRNLEN
262 size_t strnlen(const char *, size_t);
263 #endif
264
265 #if !defined(HAVE_VASPRINTF) && !defined(__AST_DEBUG_MALLOC)
266 int vasprintf(char **strp, const char *fmt, va_list ap);
267 #endif
268
269 #ifndef HAVE_STRTOQ
270 uint64_t strtoq(const char *nptr, char **endptr, int base);
271 #endif
272
273 #endif /* _ASTERISK_STRINGS_H */