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