a8bc62b420ff65bf6b93578e1a4326c6bc7ffcd9
[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   This is a wrapper for snprintf, that properly handles the buffer pointer
180   and buffer space available.
181
182   \param buffer current position in buffer to place string into (will be updated on return)
183   \param space remaining space in buffer (will be updated on return)
184   \param fmt printf-style format string
185   \return 0 on success, non-zero on failure.
186 */
187 int ast_build_string(char **buffer, size_t *space, const char *fmt, ...) __attribute__ ((format (printf, 3, 4)));
188
189 /*!
190   \brief Build a string in a buffer, designed to be called repeatedly
191   
192   This is a wrapper for snprintf, that properly handles the buffer pointer
193   and buffer space available.
194
195   \return 0 on success, non-zero on failure.
196   \param buffer current position in buffer to place string into (will be updated on return)
197   \param space remaining space in buffer (will be updated on return)
198   \param fmt printf-style format string
199   \param ap varargs list of arguments for format
200 */
201 int ast_build_string_va(char **buffer, size_t *space, const char *fmt, va_list ap);
202
203 /*! Make sure something is true */
204 /*!
205  * Determine if a string containing a boolean value is "true".
206  * 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".  
207  *
208  * Returns 0 if val is a NULL pointer, -1 if "true", and 0 otherwise.
209  */
210 int ast_true(const char *val);
211
212 /*! Make sure something is false */
213 /*!
214  * Determine if a string containing a boolean value is "false".
215  * 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".  
216  *
217  * Returns 0 if val is a NULL pointer, -1 if "false", and 0 otherwise.
218  */
219 int ast_false(const char *val);
220
221 /*
222   \brief Join an array of strings into a single string.
223   \param s the resulting string buffer
224   \param len the length of the result buffer, s
225   \param w an array of strings to join
226
227   This function will join all of the strings in the array 'w' into a single
228   string.  It will also place a space in the result buffer in between each
229   string from 'w'.
230 */
231 void ast_join(char *s, size_t len, char * const w[]);
232
233 /*
234   \brief Parse a time (integer) string.
235   \param src String to parse
236   \param dst Destination
237   \param _default Value to use if the string does not contain a valid time
238   \param consumed The number of characters 'consumed' in the string by the parse (see 'man sscanf' for details)
239   \return zero on success, non-zero on failure
240 */
241 int ast_get_time_t(const char *src, time_t *dst, time_t _default, int *consumed);
242
243 /* The realloca lets us ast_restrdupa(), but you can't mix any other ast_strdup calls! */
244
245 struct ast_realloca {
246         char *ptr;
247         int alloclen;
248 };
249
250 #define ast_restrdupa(ra, s) \
251         ({ \
252                 if ((ra)->ptr && strlen(s) + 1 < (ra)->alloclen) { \
253                         strcpy((ra)->ptr, s); \
254                 } else { \
255                         (ra)->ptr = alloca(strlen(s) + 1 - (ra)->alloclen); \
256                         if ((ra)->ptr) (ra)->alloclen = strlen(s) + 1; \
257                 } \
258                 (ra)->ptr; \
259         })
260
261 /*!
262  * Support for dynamic strings.
263  *
264  * A dynamic string is just a C string prefixed by a few control fields
265  * that help setting/appending/extending it using a printf-like syntax.
266  *
267  * One should never declare a variable with this type, but only a pointer
268  * to it, e.g.
269  *
270  *      struct ast_dynamic_str *ds;
271  *
272  * The pointer can be initialized with the following:
273  *
274  *      ds = ast_dynamic_str_create(init_len);
275  *              creates a malloc()'ed dynamic string;
276  *
277  *      ds = ast_dynamic_str_alloca(init_len);
278  *              creates a string on the stack (not very dynamic!).
279  *
280  *      ds = ast_dynamic_str_thread_get(ts, init_len)
281  *              creates a malloc()'ed dynamic string associated to
282  *              the thread-local storage key ts
283  *
284  * Finally, the string can be manipulated with the following:
285  *
286  *      ast_dynamic_str_set(&buf, max_len, ts, fmt, ...)
287  *      ast_dynamic_str_append(&buf, max_len, ts, fmt, ...)
288  *      ast_dynamic_str_thread_set(&buf, max_len, ts, fmt, ...)
289  *      ast_dynamic_str_thread_append(&buf, max_len, ts, fmt, ...)
290  *
291  * and their varargs format.
292  *
293  * \arg max_len The maximum allowed length, reallocating if needed.
294  *      0 means unlimited, -1 means "at most the available space"
295  *
296  * XXX the [_thread] variants can be removed if we save the ts in the
297  * string descriptor.
298  */
299
300 /*! \brief type of storage used for dynamic string */
301 enum dynstr_type {
302         DS_MALLOC = 1,
303         DS_ALLOCA = 2,
304         DS_STATIC = 3,  /* XXX not supported yet */
305 };
306
307 /*! \brief The descriptor of a dynamic string
308  *  XXX storage will be optimized later if needed
309  */
310 struct ast_dynamic_str {
311         size_t len;     /*!< The current maximum length of the string */
312         size_t used;    /*!< Amount of space used */
313         enum dynstr_type type;  /*!< What kind of storage is this ? */
314         char str[0];    /*!< The string buffer */
315 };
316
317 /*!
318  * \brief Create a malloc'ed dynamic length string
319  *
320  * \arg init_len This is the initial length of the string buffer
321  *
322  * \return This function returns a pointer to the dynamic string length.  The
323  *         result will be NULL in the case of a memory allocation error.
324  *
325  * \note The result of this function is dynamically allocated memory, and must
326  *       be free()'d after it is no longer needed.
327  */
328 AST_INLINE_API(
329 struct ast_dynamic_str * attribute_malloc ast_dynamic_str_create(size_t init_len),
330 {
331         struct ast_dynamic_str *buf;
332
333         if (!(buf = ast_calloc(1, sizeof(*buf) + init_len)))
334                 return NULL;
335         
336         buf->len = init_len;
337         buf->used = 0;
338         buf->type = DS_MALLOC;
339
340         return buf;
341 }
342 )
343
344 #define ast_dynamic_str_alloca(init_len)                \
345         ({                                              \
346                 struct ast_dynamic_str *buf;            \
347                 buf = alloca(sizeof(*buf) + init_len);  \
348                 buf->len = init_len;                    \
349                 buf->used = 0;                          \
350                 buf->type = DS_ALLOCA;                  \
351                 buf->str[0] = '\0';                     \
352                 (buf);                                  \
353         })
354
355
356 /*!
357  * \brief Retrieve a thread locally stored dynamic string
358  *
359  * \arg ts This is a pointer to the thread storage structure declared by using
360  *      the AST_THREADSTORAGE macro.  If declared with 
361  *      AST_THREADSTORAGE(my_buf, my_buf_init), then this argument would be 
362  *      (&my_buf).
363  * \arg init_len This is the initial length of the thread's dynamic string. The
364  *      current length may be bigger if previous operations in this thread have
365  *      caused it to increase.
366  *
367  * \return This function will return the thread locally stored dynamic string
368  *         associated with the thread storage management variable passed as the
369  *         first argument.
370  *         The result will be NULL in the case of a memory allocation error.
371  *
372  * Example usage:
373  * \code
374  * AST_THREADSTORAGE(my_str, my_str_init);
375  * #define MY_STR_INIT_SIZE   128
376  * ...
377  * void my_func(const char *fmt, ...)
378  * {
379  *      struct ast_dynamic_str *buf;
380  *
381  *      if (!(buf = ast_dynamic_str_thread_get(&my_str, MY_STR_INIT_SIZE)))
382  *           return;
383  *      ...
384  * }
385  * \endcode
386  */
387 AST_INLINE_API(
388 struct ast_dynamic_str *ast_dynamic_str_thread_get(struct ast_threadstorage *ts,
389         size_t init_len),
390 {
391         struct ast_dynamic_str *buf;
392
393         if (!(buf = ast_threadstorage_get(ts, sizeof(*buf) + init_len)))
394                 return NULL;
395         
396         if (!buf->len) {
397                 buf->len = init_len;
398                 buf->used = 0;
399                 buf->type = DS_MALLOC;
400         }
401
402         return buf;
403 }
404 )
405
406 /*!
407  * \brief Error codes from __ast_dyn_str_helper()
408  * The undelying processing to manipulate dynamic string is done
409  * by __ast_dyn_str_helper(), which can return a success, a
410  * permanent failure (e.g. no memory), or a temporary one (when
411  * the string needs to be reallocated, and we must run va_start()
412  * again; XXX this convoluted interface is only here because
413  * FreeBSD 4 lacks va_copy, but this will be fixed and the
414  * interface simplified).
415  */
416 enum {
417         /*! An error has occured and the contents of the dynamic string
418          *  are undefined */
419         AST_DYNSTR_BUILD_FAILED = -1,
420         /*! The buffer size for the dynamic string had to be increased, and
421          *  ast_dynamic_str_thread_build_va() needs to be called again after
422          *  a va_end() and va_start().
423          */
424         AST_DYNSTR_BUILD_RETRY = -2
425 };
426
427 /*!
428  * \brief Set a thread locally stored dynamic string from a va_list
429  *
430  * \arg buf This is the address of a pointer to an ast_dynamic_str which should
431  *      have been retrieved using ast_dynamic_str_thread_get.  It will need to
432  *      be updated in the case that the buffer has to be reallocated to
433  *      accommodate a longer string than what it currently has space for.
434  * \arg max_len This is the maximum length to allow the string buffer to grow
435  *      to.  If this is set to 0, then there is no maximum length.
436  * \arg ts This is a pointer to the thread storage structure declared by using
437  *      the AST_THREADSTORAGE macro.  If declared with 
438  *      AST_THREADSTORAGE(my_buf, my_buf_init), then this argument would be 
439  *      (&my_buf).
440  * \arg fmt This is the format string (printf style)
441  * \arg ap This is the va_list
442  *
443  * \return The return value of this function is the same as that of the printf
444  *         family of functions.
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_dynamic_str *buf;
454  *      va_list ap;
455  *
456  *      if (!(buf = ast_dynamic_str_thread_get(&my_str, MY_STR_INIT_SIZE)))
457  *           return;
458  *      ...
459  *      va_start(fmt, ap);
460  *      ast_dynamic_str_thread_set_va(&buf, 0, &my_str, fmt, ap);
461  *      va_end(ap);
462  * 
463  *      printf("This is the string we just built: %s\n", buf->str);
464  *      ...
465  * }
466  * \endcode
467  *
468  * \note: the following two functions must be implemented as macros
469  *      because we must do va_end()/va_start() on the original arguments.
470  */
471 #define ast_dynamic_str_thread_set_va(buf, max_len, ts, fmt, ap)        \
472         ({                                                              \
473                 int __res;                                              \
474                 while ((__res = __ast_dyn_str_helper(buf, max_len,      \
475                         ts, 0, fmt, ap)) == AST_DYNSTR_BUILD_RETRY) {   \
476                         va_end(ap);                                     \
477                         va_start(ap, fmt);                              \
478                 }                                                       \
479                 (__res);                                                \
480         })
481
482 /*!
483  * \brief Append to a thread local dynamic string using a va_list
484  *
485  * The arguments, return values, and usage of this are the same as those for
486  * ast_dynamic_str_thread_set_va().  However, instead of setting a new value
487  * for the string, this will append to the current value.
488  */
489 #define ast_dynamic_str_thread_append_va(buf, max_len, ts, fmt, ap)     \
490         ({                                                              \
491                 int __res;                                              \
492                 while ((__res = __ast_dyn_str_helper(buf, max_len,      \
493                         ts, 1, fmt, ap)) == AST_DYNSTR_BUILD_RETRY) {   \
494                         va_end(ap);                                     \
495                         va_start(ap, fmt);                              \
496                 }                                                       \
497                 (__res);                                                \
498         })
499
500 /*!
501  * \brief Core functionality of ast_dynamic_str_[thread_](set|append)_va
502  *
503  * The arguments to this function are the same as those described for
504  * ast_dynamic_str_thread_set_va except for an addition argument, append.
505  * If append is non-zero, this will append to the current string instead of
506  * writing over it.
507  *
508  * In the case that this function is called and the buffer was not large enough
509  * to hold the result, the partial write will be truncated, and the result
510  * AST_DYNSTR_BUILD_RETRY will be returned to indicate that the buffer size
511  * was increased, and the function should be called a second time.
512  *
513  * A return of AST_DYNSTR_BUILD_FAILED indicates a memory allocation error.
514  *
515  * A return value greater than or equal to zero indicates the number of
516  * characters that have been written, not including the terminating '\0'.
517  * In the append case, this only includes the number of characters appended.
518  *
519  * \note This function should never need to be called directly.  It should
520  *       through calling one of the other functions or macros defined in this
521  *       file.
522  */
523 int __ast_dyn_str_helper(struct ast_dynamic_str **buf, size_t max_len,
524         struct ast_threadstorage *ts, int append, const char *fmt, va_list ap);
525
526 /*!
527  * \brief Set a thread locally stored dynamic string using variable arguments
528  *
529  * \arg buf This is the address of a pointer to an ast_dynamic_str which should
530  *      have been retrieved using ast_dynamic_str_thread_get.  It will need to
531  *      be updated in the case that the buffer has to be reallocated to
532  *      accomodate 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 ts This is a pointer to the thread storage structure declared by using
536  *      the AST_THREADSTORAGE macro.  If declared with 
537  *      AST_THREADSTORAGE(my_buf, my_buf_init), then this argument would be 
538  *      (&my_buf).
539  * \arg fmt This is the format string (printf style)
540  *
541  * \return The return value of this function is the same as that of the printf
542  *         family of functions.
543  *
544  * Example usage:
545  * \code
546  * AST_THREADSTORAGE(my_str, my_str_init);
547  * #define MY_STR_INIT_SIZE   128
548  * ...
549  * void my_func(int arg1, int arg2)
550  * {
551  *      struct ast_dynamic_str *buf;
552  *      va_list ap;
553  *
554  *      if (!(buf = ast_dynamic_str_thread_get(&my_str, MY_STR_INIT_SIZE)))
555  *           return;
556  *      ...
557  *      ast_dynamic_str_thread_set(&buf, 0, &my_str, "arg1: %d  arg2: %d\n",
558  *           arg1, arg2);
559  * 
560  *      printf("This is the string we just built: %s\n", buf->str);
561  *      ...
562  * }
563  * \endcode
564  */
565 AST_INLINE_API(
566 int __attribute__ ((format (printf, 4, 5))) ast_dynamic_str_thread_set(
567         struct ast_dynamic_str **buf, size_t max_len, 
568         struct ast_threadstorage *ts, const char *fmt, ...),
569 {
570         int res;
571         va_list ap;
572
573         va_start(ap, fmt);
574         res = ast_dynamic_str_thread_set_va(buf, max_len, ts, fmt, ap);
575         va_end(ap);
576
577         return res;
578 }
579 )
580
581 /*!
582  * \brief Append to a thread local dynamic string
583  *
584  * The arguments, return values, and usage of this function are the same as
585  * ast_dynamic_str_thread_set().  However, instead of setting a new value for
586  * the string, this function appends to the current value.
587  */
588 AST_INLINE_API(
589 int __attribute__ ((format (printf, 4, 5))) ast_dynamic_str_thread_append(
590         struct ast_dynamic_str **buf, size_t max_len, 
591         struct ast_threadstorage *ts, const char *fmt, ...),
592 {
593         int res;
594         va_list ap;
595
596         va_start(ap, fmt);
597         res = ast_dynamic_str_thread_append_va(buf, max_len, ts, fmt, ap);
598         va_end(ap);
599
600         return res;
601 }
602 )
603
604 /*!
605  * \brief Set a dynamic string
606  *
607  * \arg buf This is the address of a pointer to an ast_dynamic_str.  It will
608  *      need to be updated in the case that the buffer has to be reallocated to
609  *      accommodate a longer string than what it currently has space for.
610  * \arg max_len This is the maximum length to allow the string buffer to grow
611  *      to.  If this is set to 0, then there is no maximum length.
612  *
613  * \return The return value of this function is the same as that of the printf
614  *         family of functions.
615  */
616 AST_INLINE_API(
617 int __attribute__ ((format (printf, 3, 4))) ast_dynamic_str_set(
618         struct ast_dynamic_str **buf, size_t max_len,
619         const char *fmt, ...),
620 {
621         int res;
622         va_list ap;
623         
624         va_start(ap, fmt);
625         res = ast_dynamic_str_thread_set_va(buf, max_len, NULL, fmt, ap);
626         va_end(ap);
627
628         return res;
629 }
630 )
631
632 /*!
633  * \brief Append to a dynamic string
634  *
635  * The arguments, return values, and usage of this function are the same as
636  * ast_dynamic_str_set().  However, this function appends to the string instead
637  * of setting a new value.
638  */
639 AST_INLINE_API(
640 int __attribute__ ((format (printf, 3, 4))) ast_dynamic_str_append(
641         struct ast_dynamic_str **buf, size_t max_len,
642         const char *fmt, ...),
643 {
644         int res;
645         va_list ap;
646         
647         va_start(ap, fmt);
648         res = ast_dynamic_str_thread_append_va(buf, max_len, NULL, fmt, ap);
649         va_end(ap);
650
651         return res;
652 }
653 )
654
655 #endif /* _ASTERISK_STRINGS_H */