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