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