c91ecaec31e01edd5d8f75e5abb1b1f8b4e0d3b7
[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 #include "asterisk/utils.h"
33 #include "asterisk/threadstorage.h"
34
35 static force_inline int ast_strlen_zero(const char *s)
36 {
37         return (!s || (*s == '\0'));
38 }
39
40 /*! \brief returns the equivalent of logic or for strings:
41  * first one if not empty, otherwise second one.
42  */
43 #define S_OR(a, b)      (!ast_strlen_zero(a) ? (a) : (b))
44
45 /*!
46   \brief Gets a pointer to the first non-whitespace character in a string.
47   \param ast_skip_blanks function being used
48   \param str the input string
49   \return a pointer to the first non-whitespace character
50  */
51 AST_INLINE_API(
52 char *ast_skip_blanks(const char *str),
53 {
54         while (*str && *str < 33)
55                 str++;
56         return (char *)str;
57 }
58 )
59
60 /*!
61   \brief Trims trailing whitespace characters from a string.
62   \param ast_trim_blanks function being used
63   \param str the input string
64   \return a pointer to the modified string
65  */
66 AST_INLINE_API(
67 char *ast_trim_blanks(char *str),
68 {
69         char *work = str;
70
71         if (work) {
72                 work += strlen(work) - 1;
73                 /* It's tempting to only want to erase after we exit this loop, 
74                    but since ast_trim_blanks *could* receive a constant string
75                    (which we presumably wouldn't have to touch), we shouldn't
76                    actually set anything unless we must, and it's easier just
77                    to set each position to \0 than to keep track of a variable
78                    for it */
79                 while ((work >= str) && *work < 33)
80                         *(work--) = '\0';
81         }
82         return str;
83 }
84 )
85
86 /*!
87   \brief Gets a pointer to first whitespace character in a string.
88   \param ast_skip_noblanks function being used
89   \param str the input string
90   \return a pointer to the first whitespace character
91  */
92 AST_INLINE_API(
93 char *ast_skip_nonblanks(char *str),
94 {
95         while (*str && *str > 32)
96                 str++;
97         return str;
98 }
99 )
100   
101 /*!
102   \brief Strip leading/trailing whitespace from a string.
103   \param s The string to be stripped (will be modified).
104   \return The stripped string.
105
106   This functions strips all leading and trailing whitespace
107   characters from the input string, and returns a pointer to
108   the resulting string. The string is modified in place.
109 */
110 AST_INLINE_API(
111 char *ast_strip(char *s),
112 {
113         s = ast_skip_blanks(s);
114         if (s)
115                 ast_trim_blanks(s);
116         return s;
117
118 )
119
120 /*!
121   \brief Strip leading/trailing whitespace and quotes from a string.
122   \param s The string to be stripped (will be modified).
123   \param beg_quotes The list of possible beginning quote characters.
124   \param end_quotes The list of matching ending quote characters.
125   \return The stripped string.
126
127   This functions strips all leading and trailing whitespace
128   characters from the input string, and returns a pointer to
129   the resulting string. The string is modified in place.
130
131   It can also remove beginning and ending quote (or quote-like)
132   characters, in matching pairs. If the first character of the
133   string matches any character in beg_quotes, and the last
134   character of the string is the matching character in
135   end_quotes, then they are removed from the string.
136
137   Examples:
138   \code
139   ast_strip_quoted(buf, "\"", "\"");
140   ast_strip_quoted(buf, "'", "'");
141   ast_strip_quoted(buf, "[{(", "]})");
142   \endcode
143  */
144 char *ast_strip_quoted(char *s, const char *beg_quotes, const char *end_quotes);
145
146 /*!
147   \brief Size-limited null-terminating string copy.
148   \param ast_copy_string function being used
149   \param dst The destination buffer.
150   \param src The source string
151   \param size The size of the destination buffer
152   \return Nothing.
153
154   This is similar to \a strncpy, with two important differences:
155     - the destination buffer will \b always be null-terminated
156     - the destination buffer is not filled with zeros past the copied string length
157   These differences make it slightly more efficient, and safer to use since it will
158   not leave the destination buffer unterminated. There is no need to pass an artificially
159   reduced buffer size to this function (unlike \a strncpy), and the buffer does not need
160   to be initialized to zeroes prior to calling this function.
161 */
162 AST_INLINE_API(
163 void ast_copy_string(char *dst, const char *src, size_t size),
164 {
165         while (*src && size) {
166                 *dst++ = *src++;
167                 size--;
168         }
169         if (__builtin_expect(!size, 0))
170                 dst--;
171         *dst = '\0';
172 }
173 )
174
175
176 /*!
177   \brief Build a string in a buffer, designed to be called repeatedly
178   
179   \note This method is not recommended. New code should use ast_str_*() instead.
180
181   This is a wrapper for snprintf, that properly handles the buffer pointer
182   and buffer space available.
183
184   \param buffer current position in buffer to place string into (will be updated on return)
185   \param space remaining space in buffer (will be updated on return)
186   \param fmt printf-style format string
187   \return 0 on success, non-zero on failure.
188 */
189 int ast_build_string(char **buffer, size_t *space, const char *fmt, ...) __attribute__ ((format (printf, 3, 4)));
190
191 /*!
192   \brief Build a string in a buffer, designed to be called repeatedly
193   
194   This is a wrapper for snprintf, that properly handles the buffer pointer
195   and buffer space available.
196
197   \return 0 on success, non-zero on failure.
198   \param buffer current position in buffer to place string into (will be updated on return)
199   \param space remaining space in buffer (will be updated on return)
200   \param fmt printf-style format string
201   \param ap varargs list of arguments for format
202 */
203 int ast_build_string_va(char **buffer, size_t *space, const char *fmt, va_list ap);
204
205 /*! Make sure something is true */
206 /*!
207  * Determine if a string containing a boolean value is "true".
208  * 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".  
209  *
210  * Returns 0 if val is a NULL pointer, -1 if "true", and 0 otherwise.
211  */
212 int ast_true(const char *val);
213
214 /*! Make sure something is false */
215 /*!
216  * Determine if a string containing a boolean value is "false".
217  * 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".  
218  *
219  * Returns 0 if val is a NULL pointer, -1 if "false", and 0 otherwise.
220  */
221 int ast_false(const char *val);
222
223 /*
224   \brief Join an array of strings into a single string.
225   \param s the resulting string buffer
226   \param len the length of the result buffer, s
227   \param w an array of strings to join
228
229   This function will join all of the strings in the array 'w' into a single
230   string.  It will also place a space in the result buffer in between each
231   string from 'w'.
232 */
233 void ast_join(char *s, size_t len, char * const w[]);
234
235 /*
236   \brief Parse a time (integer) string.
237   \param src String to parse
238   \param dst Destination
239   \param _default Value to use if the string does not contain a valid time
240   \param consumed The number of characters 'consumed' in the string by the parse (see 'man sscanf' for details)
241   \return zero on success, non-zero on failure
242 */
243 int ast_get_time_t(const char *src, time_t *dst, time_t _default, int *consumed);
244
245 /* The realloca lets us ast_restrdupa(), but you can't mix any other ast_strdup calls! */
246
247 struct ast_realloca {
248         char *ptr;
249         int alloclen;
250 };
251
252 #define ast_restrdupa(ra, s) \
253         ({ \
254                 if ((ra)->ptr && strlen(s) + 1 < (ra)->alloclen) { \
255                         strcpy((ra)->ptr, s); \
256                 } else { \
257                         (ra)->ptr = alloca(strlen(s) + 1 - (ra)->alloclen); \
258                         if ((ra)->ptr) (ra)->alloclen = strlen(s) + 1; \
259                 } \
260                 (ra)->ptr; \
261         })
262
263 /*!
264  * Support for dynamic strings.
265  *
266  * A dynamic string is just a C string prefixed by a few control fields
267  * that help setting/appending/extending it using a printf-like syntax.
268  *
269  * One should never declare a variable with this type, but only a pointer
270  * to it, e.g.
271  *
272  *      struct ast_str *ds;
273  *
274  * The pointer can be initialized with the following:
275  *
276  *      ds = ast_str_create(init_len);
277  *              creates a malloc()'ed dynamic string;
278  *
279  *      ds = ast_str_alloca(init_len);
280  *              creates a string on the stack (not very dynamic!).
281  *
282  *      ds = ast_str_thread_get(ts, init_len)
283  *              creates a malloc()'ed dynamic string associated to
284  *              the thread-local storage key ts
285  *
286  * Finally, the string can be manipulated with the following:
287  *
288  *      ast_str_set(&buf, max_len, fmt, ...)
289  *      ast_str_append(&buf, max_len, fmt, ...)
290  *
291  * and their varargs variant
292  *
293  *      ast_str_set_va(&buf, max_len, ap)
294  *      ast_str_append_va(&buf, max_len, ap)
295  *
296  * \arg max_len The maximum allowed length, reallocating if needed.
297  *      0 means unlimited, -1 means "at most the available space"
298  *
299  * \return All the functions return <0 in case of error, or the
300  *      length of the string added to the buffer otherwise.
301  */
302
303 /*! \brief The descriptor of a dynamic string
304  *  XXX storage will be optimized later if needed
305  * We use the ts field to indicate the type of storage.
306  * Three special constants indicate malloc, alloca() or static
307  * variables, all other values indicate a
308  * struct ast_threadstorage pointer.
309  */
310 struct ast_str {
311         size_t len;     /*!< The current maximum length of the string */
312         size_t used;    /*!< Amount of space used */
313         struct ast_threadstorage *ts;   /*!< What kind of storage is this ? */
314 #define DS_MALLOC       ((struct ast_threadstorage *)1)
315 #define DS_ALLOCA       ((struct ast_threadstorage *)2)
316 #define DS_STATIC       ((struct ast_threadstorage *)3) /* not supported yet */
317         char str[0];    /*!< The string buffer */
318 };
319
320 /*!
321  * \brief Create a malloc'ed dynamic length string
322  *
323  * \arg init_len This is the initial length of the string buffer
324  *
325  * \return This function returns a pointer to the dynamic string length.  The
326  *         result will be NULL in the case of a memory allocation error.
327  *
328  * \note The result of this function is dynamically allocated memory, and must
329  *       be free()'d after it is no longer needed.
330  */
331 AST_INLINE_API(
332 struct ast_str * attribute_malloc ast_str_create(size_t init_len),
333 {
334         struct ast_str *buf;
335
336         buf = ast_calloc(1, sizeof(*buf) + init_len);
337         if (buf == NULL)
338                 return NULL;
339         
340         buf->len = init_len;
341         buf->used = 0;
342         buf->ts = DS_MALLOC;
343
344         return buf;
345 }
346 )
347
348 /*! \brief Reset the content of a dynamic string.
349  * Useful before a series of ast_str_append.
350  */
351 AST_INLINE_API(
352 void ast_str_reset(struct ast_str *buf),
353 {
354         if (buf) {
355                 buf->used = 0;
356                 if (buf->len)
357                         buf->str[0] = '\0';
358         }
359 }
360 )
361
362 /*!
363  * Make space in a new string (e.g. to read in data from a file)
364  */
365 AST_INLINE_API(
366 int ast_str_make_space(struct ast_str **buf, size_t new_len),
367 {
368 #if defined(DEBUG_THREADLOCALS)
369         struct ast_str *old_buf = *buf;
370 #endif /* defined(DEBUG_THREADLOCALS) */
371
372         if (new_len <= (*buf)->len) 
373                 return 0;       /* success */
374         if ((*buf)->ts == DS_ALLOCA || (*buf)->ts == DS_STATIC)
375                 return -1;      /* cannot extend */
376         *buf = ast_realloc(*buf, new_len + sizeof(struct ast_str));
377         if (*buf == NULL) /* XXX watch out, we leak memory here */
378                 return -1;
379         if ((*buf)->ts != DS_MALLOC) {
380                 pthread_setspecific((*buf)->ts->key, *buf);
381 #if defined(DEBUG_THREADLOCALS)
382                 __ast_threadstorage_object_replace(old_buf, *buf, new_len + sizeof(struct ast_str));
383 #endif /* defined(DEBUG_THREADLOCALS) */
384         }
385
386         (*buf)->len = new_len;
387         return 0;
388 }
389 )
390
391 #define ast_str_alloca(init_len)                        \
392         ({                                              \
393                 struct ast_str *buf;                    \
394                 buf = alloca(sizeof(*buf) + init_len);  \
395                 buf->len = init_len;                    \
396                 buf->used = 0;                          \
397                 buf->ts = DS_ALLOCA;                    \
398                 buf->str[0] = '\0';                     \
399                 (buf);                                  \
400         })
401
402
403 /*!
404  * \brief Retrieve a thread locally stored dynamic string
405  *
406  * \arg ts This is a pointer to the thread storage structure declared by using
407  *      the AST_THREADSTORAGE macro.  If declared with 
408  *      AST_THREADSTORAGE(my_buf, my_buf_init), then this argument would be 
409  *      (&my_buf).
410  * \arg init_len This is the initial length of the thread's dynamic string. The
411  *      current length may be bigger if previous operations in this thread have
412  *      caused it to increase.
413  *
414  * \return This function will return the thread locally stored dynamic string
415  *         associated with the thread storage management variable passed as the
416  *         first argument.
417  *         The result will be NULL in the case of a memory allocation error.
418  *
419  * Example usage:
420  * \code
421  * AST_THREADSTORAGE(my_str, my_str_init);
422  * #define MY_STR_INIT_SIZE   128
423  * ...
424  * void my_func(const char *fmt, ...)
425  * {
426  *      struct ast_str *buf;
427  *
428  *      if (!(buf = ast_str_thread_get(&my_str, MY_STR_INIT_SIZE)))
429  *           return;
430  *      ...
431  * }
432  * \endcode
433  */
434 #if !defined(DEBUG_THREADLOCALS)
435 AST_INLINE_API(
436 struct ast_str *ast_str_thread_get(struct ast_threadstorage *ts,
437         size_t init_len),
438 {
439         struct ast_str *buf;
440
441         buf = ast_threadstorage_get(ts, sizeof(*buf) + init_len);
442         if (buf == NULL)
443                 return NULL;
444         
445         if (!buf->len) {
446                 buf->len = init_len;
447                 buf->used = 0;
448                 buf->ts = ts;
449         }
450
451         return buf;
452 }
453 )
454 #else /* defined(DEBUG_THREADLOCALS) */
455 AST_INLINE_API(
456 struct ast_str *__ast_str_thread_get(struct ast_threadstorage *ts,
457         size_t init_len, const char *file, const char *function, unsigned int line),
458 {
459         struct ast_str *buf;
460
461         buf = __ast_threadstorage_get(ts, sizeof(*buf) + init_len, file, function, line);
462         if (buf == NULL)
463                 return NULL;
464         
465         if (!buf->len) {
466                 buf->len = init_len;
467                 buf->used = 0;
468                 buf->ts = ts;
469         }
470
471         return buf;
472 }
473 )
474
475 #define ast_str_thread_get(ts, init_len) __ast_str_thread_get(ts, init_len, __FILE__, __PRETTY_FUNCTION__, __LINE__)
476 #endif /* defined(DEBUG_THREADLOCALS) */
477
478 /*!
479  * \brief Error codes from __ast_str_helper()
480  * The undelying processing to manipulate dynamic string is done
481  * by __ast_str_helper(), which can return a success, a
482  * permanent failure (e.g. no memory), or a temporary one (when
483  * the string needs to be reallocated, and we must run va_start()
484  * again; XXX this convoluted interface is only here because
485  * FreeBSD 4 lacks va_copy, but this will be fixed and the
486  * interface simplified).
487  */
488 enum {
489         /*! An error has occured and the contents of the dynamic string
490          *  are undefined */
491         AST_DYNSTR_BUILD_FAILED = -1,
492         /*! The buffer size for the dynamic string had to be increased, and
493          *  __ast_str_helper() needs to be called again after
494          *  a va_end() and va_start().
495          */
496         AST_DYNSTR_BUILD_RETRY = -2
497 };
498
499 /*!
500  * \brief Set a dynamic string from a va_list
501  *
502  * \arg buf This is the address of a pointer to a struct ast_str.
503  *      If it is retrieved using ast_str_thread_get, the
504         struct ast_threadstorage pointer will need to
505  *      be updated in the case that the buffer has to be reallocated to
506  *      accommodate a longer string than what it currently has space for.
507  * \arg max_len This is the maximum length to allow the string buffer to grow
508  *      to.  If this is set to 0, then there is no maximum length.
509  * \arg fmt This is the format string (printf style)
510  * \arg ap This is the va_list
511  *
512  * \return The return value of this function is the same as that of the printf
513  *         family of functions.
514  *
515  * Example usage (the first part is only for thread-local storage)
516  * \code
517  * AST_THREADSTORAGE(my_str, my_str_init);
518  * #define MY_STR_INIT_SIZE   128
519  * ...
520  * void my_func(const char *fmt, ...)
521  * {
522  *      struct ast_str *buf;
523  *      va_list ap;
524  *
525  *      if (!(buf = ast_str_thread_get(&my_str, MY_STR_INIT_SIZE)))
526  *           return;
527  *      ...
528  *      va_start(fmt, ap);
529  *      ast_str_set_va(&buf, 0, fmt, ap);
530  *      va_end(ap);
531  * 
532  *      printf("This is the string we just built: %s\n", buf->str);
533  *      ...
534  * }
535  * \endcode
536  *
537  * \note: the following two functions must be implemented as macros
538  *      because we must do va_end()/va_start() on the original arguments.
539  */
540 #define ast_str_set_va(buf, max_len, fmt, ap)                   \
541         ({                                                              \
542                 int __res;                                              \
543                 while ((__res = __ast_str_helper(buf, max_len,          \
544                         0, fmt, ap)) == AST_DYNSTR_BUILD_RETRY) {       \
545                         va_end(ap);                                     \
546                         va_start(ap, fmt);                              \
547                 }                                                       \
548                 (__res);                                                \
549         })
550
551 /*!
552  * \brief Append to a dynamic string using a va_list
553  *
554  * Same as ast_str_set_va(), but append to the current content.
555  */
556 #define ast_str_append_va(buf, max_len, fmt, ap)                \
557         ({                                                              \
558                 int __res;                                              \
559                 while ((__res = __ast_str_helper(buf, max_len,          \
560                         1, fmt, ap)) == AST_DYNSTR_BUILD_RETRY) {       \
561                         va_end(ap);                                     \
562                         va_start(ap, fmt);                              \
563                 }                                                       \
564                 (__res);                                                \
565         })
566
567 /*!
568  * \brief Core functionality of ast_str_(set|append)_va
569  *
570  * The arguments to this function are the same as those described for
571  * ast_str_set_va except for an addition argument, append.
572  * If append is non-zero, this will append to the current string instead of
573  * writing over it.
574  *
575  * In the case that this function is called and the buffer was not large enough
576  * to hold the result, the partial write will be truncated, and the result
577  * AST_DYNSTR_BUILD_RETRY will be returned to indicate that the buffer size
578  * was increased, and the function should be called a second time.
579  *
580  * A return of AST_DYNSTR_BUILD_FAILED indicates a memory allocation error.
581  *
582  * A return value greater than or equal to zero indicates the number of
583  * characters that have been written, not including the terminating '\0'.
584  * In the append case, this only includes the number of characters appended.
585  *
586  * \note This function should never need to be called directly.  It should
587  *       through calling one of the other functions or macros defined in this
588  *       file.
589  */
590 int __ast_str_helper(struct ast_str **buf, size_t max_len,
591         int append, const char *fmt, va_list ap);
592
593 /*!
594  * \brief Set a dynamic string using variable arguments
595  *
596  * \arg buf This is the address of a pointer to a struct ast_str which should
597  *      have been retrieved using ast_str_thread_get.  It will need to
598  *      be updated in the case that the buffer has to be reallocated to
599  *      accomodate a longer string than what it currently has space for.
600  * \arg max_len This is the maximum length to allow the string buffer to grow
601  *      to.  If this is set to 0, then there is no maximum length.
602  *      If set to -1, we are bound to the current maximum length.
603  * \arg fmt This is the format string (printf style)
604  *
605  * \return The return value of this function is the same as that of the printf
606  *         family of functions.
607  *
608  * All the rest is the same as ast_str_set_va()
609  */
610 AST_INLINE_API(
611 int __attribute__ ((format (printf, 3, 4))) ast_str_set(
612         struct ast_str **buf, size_t max_len, const char *fmt, ...),
613 {
614         int res;
615         va_list ap;
616
617         va_start(ap, fmt);
618         res = ast_str_set_va(buf, max_len, fmt, ap);
619         va_end(ap);
620
621         return res;
622 }
623 )
624
625 /*!
626  * \brief Append to a thread local dynamic string
627  *
628  * The arguments, return values, and usage of this function are the same as
629  * ast_str_set(), but the new data is appended to the current value.
630  */
631 AST_INLINE_API(
632 int __attribute__ ((format (printf, 3, 4))) ast_str_append(
633         struct ast_str **buf, size_t max_len, const char *fmt, ...),
634 {
635         int res;
636         va_list ap;
637
638         va_start(ap, fmt);
639         res = ast_str_append_va(buf, max_len, fmt, ap);
640         va_end(ap);
641
642         return res;
643 }
644 )
645
646 #endif /* _ASTERISK_STRINGS_H */