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