add new header files
[asterisk/asterisk.git] / include / asterisk / strings.h
1 /*
2  * Asterisk -- A telephony toolkit for Linux.
3  *
4  * String manipulation functions
5  *
6  * Copyright (C) 2005, Digium, Inc.
7  *
8  * This program is free software, distributed under the terms of
9  * the GNU General Public License
10  */
11
12 #ifndef _ASTERISK_STRINGS_H
13 #define _ASTERISK_STRINGS_H
14
15 #include <string.h>
16
17 #include "asterisk/compiler.h"
18
19 static inline int ast_strlen_zero(const char *s)
20 {
21         return (*s == '\0');
22 }
23
24 /*!
25   \brief Gets a pointer to the first non-whitespace character in a string.
26   \param str the input string
27   \return a pointer to the first non-whitespace character
28  */
29 char *ast_skip_blanks(char *str);
30 #if !defined(LOW_MEMORY) && !defined(AST_API_MODULE)
31 extern inline
32 #endif
33 #if !defined(LOW_MEMORY) || defined(AST_API_MODULE)
34 char *ast_skip_blanks(char *str)
35 {
36         while (*str && *str < 33)
37                 str++;
38         return str;
39 }
40 #endif
41
42 /*!
43   \brief Trims trailing whitespace characters from a string.
44   \param str the input string
45   \return a pointer to the NULL following the string
46  */
47 char *ast_trim_blanks(char *str);
48 #if !defined(LOW_MEMORY) && !defined(AST_API_MODULE)
49 extern inline
50 #endif
51 #if !defined(LOW_MEMORY) || defined(AST_API_MODULE)
52 char *ast_trim_blanks(char *str)
53 {
54         char *work = str;
55
56         if (work) {
57                 work += strlen(work) - 1;
58                 /* It's tempting to only want to erase after we exit this loop, 
59                    but since ast_trim_blanks *could* receive a constant string
60                    (which we presumably wouldn't have to touch), we shouldn't
61                    actually set anything unless we must, and it's easier just
62                    to set each position to \0 than to keep track of a variable
63                    for it */
64                 while ((work >= str) && *work < 33)
65                         *(work--) = '\0';
66         }
67         return str;
68 }
69 #endif
70
71 /*!
72   \brief Gets a pointer to first whitespace character in a string.
73   \param str the input string
74   \return a pointer to the first whitespace character
75  */
76 char *ast_skip_nonblanks(char *str);
77 #if !defined(LOW_MEMORY) && !defined(AST_API_MODULE)
78 extern inline
79 #endif
80 #if !defined(LOW_MEMORY) || defined(AST_API_MODULE)
81 char *ast_skip_nonblanks(char *str)
82 {
83         while (*str && *str > 32)
84                 str++;
85         return str;
86 }
87 #endif
88   
89 /*!
90   \brief Strip leading/trailing whitespace from a string.
91   \param s The string to be stripped (will be modified).
92   \return The stripped string.
93
94   This functions strips all leading and trailing whitespace
95   characters from the input string, and returns a pointer to
96   the resulting string. The string is modified in place.
97 */
98 char *ast_strip(char *s);
99 #if !defined(LOW_MEMORY) && !defined(AST_API_MODULE)
100 extern inline
101 #endif
102 #if !defined(LOW_MEMORY) || defined(AST_API_MODULE)
103 char *ast_strip(char *s)
104 {
105         s = ast_skip_blanks(s);
106         if (s)
107                 ast_trim_blanks(s);
108         return s;
109
110 #endif
111
112 /*!
113   \brief Strip leading/trailing whitespace and quotes from a string.
114   \param s The string to be stripped (will be modified).
115   \param beg_quotes The list of possible beginning quote characters.
116   \param end_quotes The list of matching ending quote characters.
117   \return The stripped string.
118
119   This functions strips all leading and trailing whitespace
120   characters from the input string, and returns a pointer to
121   the resulting string. The string is modified in place.
122
123   It can also remove beginning and ending quote (or quote-like)
124   characters, in matching pairs. If the first character of the
125   string matches any character in beg_quotes, and the last
126   character of the string is the matching character in
127   end_quotes, then they are removed from the string.
128
129   Examples:
130   \code
131   ast_strip_quoted(buf, "\"", "\"");
132   ast_strip_quoted(buf, "'", "'");
133   ast_strip_quoted(buf, "[{(", "]})");
134   \endcode
135  */
136 char *ast_strip_quoted(char *s, const char *beg_quotes, const char *end_quotes);
137
138 /*!
139   \brief Size-limited null-terminating string copy.
140   \param dst The destination buffer.
141   \param src The source string
142   \param size The size of the destination buffer
143   \return Nothing.
144
145   This is similar to \a strncpy, with two important differences:
146     - the destination buffer will \b always be null-terminated
147     - the destination buffer is not filled with zeros past the copied string length
148   These differences make it slightly more efficient, and safer to use since it will
149   not leave the destination buffer unterminated. There is no need to pass an artificially
150   reduced buffer size to this function (unlike \a strncpy), and the buffer does not need
151   to be initialized to zeroes prior to calling this function.
152 */
153 void ast_copy_string(char *dst, const char *src, size_t size);
154 #if !defined(LOW_MEMORY) && !defined(AST_API_MODULE)
155 extern inline
156 #endif
157 #if !defined(LOW_MEMORY) || defined(AST_API_MODULE)
158 void ast_copy_string(char *dst, const char *src, size_t size)
159 {
160         while (*src && size) {
161                 *dst++ = *src++;
162                 size--;
163         }
164         if (__builtin_expect(!size, 0))
165                 dst--;
166         *dst = '\0';
167 }
168 #endif
169
170 /*!
171   \brief Build a string in a buffer, designed to be called repeatedly
172   
173   This is a wrapper for snprintf, that properly handles the buffer pointer
174   and buffer space available.
175
176   \return 0 on success, non-zero on failure.
177   \param buffer current position in buffer to place string into (will be updated on return)
178   \param space remaining space in buffer (will be updated on return)
179   \param fmt printf-style format string
180 */
181 int ast_build_string(char **buffer, size_t *space, const char *fmt, ...) __attribute__ ((format (printf, 3, 4)));
182
183 /*! Make sure something is true */
184 /*!
185  * Determine if a string containing a boolean value is "true".
186  * 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".  
187  *
188  * Returns 0 if val is a NULL pointer, -1 if "true", and 0 otherwise.
189  */
190 int ast_true(const char *val);
191
192 /*! Make sure something is false */
193 /*!
194  * Determine if a string containing a boolean value is "false".
195  * 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".  
196  *
197  * Returns 0 if val is a NULL pointer, -1 if "false", and 0 otherwise.
198  */
199 int ast_false(const char *val);
200
201 /* The realloca lets us ast_restrdupa(), but you can't mix any other ast_strdup calls! */
202
203 struct ast_realloca {
204         char *ptr;
205         int alloclen;
206 };
207
208 #define ast_restrdupa(ra, s) \
209         ({ \
210                 if ((ra)->ptr && strlen(s) + 1 < (ra)->alloclen) { \
211                         strcpy((ra)->ptr, s); \
212                 } else { \
213                         (ra)->ptr = alloca(strlen(s) + 1 - (ra)->alloclen); \
214                         if ((ra)->ptr) (ra)->alloclen = strlen(s) + 1; \
215                 } \
216                 (ra)->ptr; \
217         })
218
219 #ifdef __linux__
220 #define ast_strcasestr strcasestr
221 #else
222 extern char *ast_strcasestr(const char *, const char *);
223 #endif /* __linux__ */
224
225 #undef AST_API_MODULE
226 #endif /* _ASTERISK_STRINGS_H */