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