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