Review Board 1.7.16


utils: Create ast_strsep function that ignores separators inside quotes.

Review Request #3989 - Created Sept. 10, 2014 and submitted

George Joseph
12
Reviewers
asterisk-dev
rmudgett
Asterisk
I'm going to need this for my imminent manager and config
enhancements but I thought I'd post this separately.

/*!
  \brief Act like strsep but ignore separators inside quotes.
  \param s Pointer to address of the the string to be processed.
  Will be modified and can't be constant.
  \param sep A single character delimiter.
  \param flags Controls post-processing of the result.
  AST_STRSEP_TRIM trims all leading and trailing whitespace from the result.
  AST_STRSEP_STRIP does a trim then strips the outermost quotes.  You may want
  to trim again after the strip.  Just OR both the TRIM and STRIP flags.
  AST_STRSEP_UNESCAPE unescapes '\' sequences.
  AST_STRSEP_ALL does all of the above processing.
  \return The next token or NULL if done or if there are more than 8 levels of
  nested quotes.

  This function acts like strsep with three exceptions...
  The separator is a single character instead of a string.
  Separators inside quotes are treated literally instead of like separators.
  You can elect to have leading and trailing whitespace and quotes
  stripped from the result and have '\' sequences unescaped.

  Like strsep, ast_strsep maintains no internal state and you can call it
  recursively using different separators on the same storage.

  Also like strsep, for consistent results, consecutive separators are not
  collapsed so you may get an empty string as a valid result.

  Examples:
  \code
	char *mystr = ast_strdupa("abc=def,ghi='zzz=yyy,456',jkl");
	char *token, *token2, *token3;

	while((token = ast_strsep(&mystr, ',', AST_SEP_STRIP))) {
		// 1st token will be aaa=def
		// 2nd token will be ghi='zzz=yyy,456'
		while((token2 = ast_strsep(&token, '=', AST_SEP_STRIP))) {
			// 1st token2 will be ghi
			// 2nd token2 will be zzz=yyy,456
			while((token3 = ast_strsep(&token2, ',', AST_SEP_STRIP))) {
				// 1st token3 will be zzz=yyy
				// 2nd token3 will be 456
				// and so on
			}
		}
		// 3rd token will be jkl
	}

  \endcode
 */
char *ast_strsep(char **s, const char sep, uint32_t flags);

 

Diff revision 4 (Latest)

1 2 3 4
1 2 3 4

  1. branches/12/include/asterisk/strings.h: Loading...
  2. branches/12/main/utils.c: Loading...
  3. branches/12/tests/test_strings.c: Loading...
branches/12/include/asterisk/strings.h
Revision 422963 New Change
1
/*
1
/*
2
 * Asterisk -- An open source telephony toolkit.
2
 * Asterisk -- An open source telephony toolkit.
3
 *
3
 *
4
 * Copyright (C) 1999 - 2006, Digium, Inc.
4
 * Copyright (C) 1999 - 2006, Digium, Inc.
5
 *
5
 *
6
 * Mark Spencer <markster@digium.com>
6
 * Mark Spencer <markster@digium.com>
7
 *
7
 *
8
 * See http://www.asterisk.org for more information about
8
 * See http://www.asterisk.org for more information about
9
 * the Asterisk project. Please do not directly contact
9
 * the Asterisk project. Please do not directly contact
10
 * any of the maintainers of this project for assistance;
10
 * any of the maintainers of this project for assistance;
11
 * the project provides a web site, mailing lists and IRC
11
 * the project provides a web site, mailing lists and IRC
12
 * channels for your use.
12
 * channels for your use.
13
 *
13
 *
14
 * This program is free software, distributed under the terms of
14
 * This program is free software, distributed under the terms of
15
 * the GNU General Public License Version 2. See the LICENSE file
15
 * the GNU General Public License Version 2. See the LICENSE file
16
 * at the top of the source tree.
16
 * at the top of the source tree.
17
 */
17
 */
18

    
   
18

   
19
/*! \file
19
/*! \file
20
 * \brief String manipulation functions
20
 * \brief String manipulation functions
21
 */
21
 */
22

    
   
22

   
23
#ifndef _ASTERISK_STRINGS_H
23
#ifndef _ASTERISK_STRINGS_H
24
#define _ASTERISK_STRINGS_H
24
#define _ASTERISK_STRINGS_H
25

    
   
25

   
26
/* #define DEBUG_OPAQUE */
26
/* #define DEBUG_OPAQUE */
27

    
   
27

   
28
#include <ctype.h>
28
#include <ctype.h>
29

    
   
29

   
30
#include "asterisk/utils.h"
30
#include "asterisk/utils.h"
31
#include "asterisk/threadstorage.h"
31
#include "asterisk/threadstorage.h"
32
#include "asterisk/astobj2.h"
32
#include "asterisk/astobj2.h"
33

    
   
33

   
34
#if defined(DEBUG_OPAQUE)
34
#if defined(DEBUG_OPAQUE)
35
#define __AST_STR_USED used2
35
#define __AST_STR_USED used2
36
#define __AST_STR_LEN len2
36
#define __AST_STR_LEN len2
37
#define __AST_STR_STR str2
37
#define __AST_STR_STR str2
38
#define __AST_STR_TS ts2
38
#define __AST_STR_TS ts2
39
#else
39
#else
40
#define __AST_STR_USED used
40
#define __AST_STR_USED used
41
#define __AST_STR_LEN len
41
#define __AST_STR_LEN len
42
#define __AST_STR_STR str
42
#define __AST_STR_STR str
43
#define __AST_STR_TS ts
43
#define __AST_STR_TS ts
44
#endif
44
#endif
45

    
   
45

   
46
/* You may see casts in this header that may seem useless but they ensure this file is C++ clean */
46
/* You may see casts in this header that may seem useless but they ensure this file is C++ clean */
47

    
   
47

   
48
#define AS_OR(a,b)	(a && ast_str_strlen(a)) ? ast_str_buffer(a) : (b)
48
#define AS_OR(a,b)	(a && ast_str_strlen(a)) ? ast_str_buffer(a) : (b)
49

    
   
49

   
50
#ifdef AST_DEVMODE
50
#ifdef AST_DEVMODE
51
#define ast_strlen_zero(foo)	_ast_strlen_zero(foo, __FILE__, __PRETTY_FUNCTION__, __LINE__)
51
#define ast_strlen_zero(foo)	_ast_strlen_zero(foo, __FILE__, __PRETTY_FUNCTION__, __LINE__)
52
static force_inline int _ast_strlen_zero(const char *s, const char *file, const char *function, int line)
52
static force_inline int _ast_strlen_zero(const char *s, const char *file, const char *function, int line)
53
{
53
{
54
	if (!s || (*s == '\0')) {
54
	if (!s || (*s == '\0')) {
55
		return 1;
55
		return 1;
56
	}
56
	}
57
	if (!strcmp(s, "(null)")) {
57
	if (!strcmp(s, "(null)")) {
58
		ast_log(__LOG_WARNING, file, line, function, "Possible programming error: \"(null)\" is not NULL!\n");
58
		ast_log(__LOG_WARNING, file, line, function, "Possible programming error: \"(null)\" is not NULL!\n");
59
	}
59
	}
60
	return 0;
60
	return 0;
61
}
61
}
62

    
   
62

   
63
#else
63
#else
64
static force_inline int attribute_pure ast_strlen_zero(const char *s)
64
static force_inline int attribute_pure ast_strlen_zero(const char *s)
65
{
65
{
66
	return (!s || (*s == '\0'));
66
	return (!s || (*s == '\0'));
67
}
67
}
68
#endif
68
#endif
69

    
   
69

   
70
#ifdef SENSE_OF_HUMOR
70
#ifdef SENSE_OF_HUMOR
71
#define ast_strlen_real(a)	(a) ? strlen(a) : 0
71
#define ast_strlen_real(a)	(a) ? strlen(a) : 0
72
#define ast_strlen_imaginary(a)	ast_random()
72
#define ast_strlen_imaginary(a)	ast_random()
73
#endif
73
#endif
74

    
   
74

   
75
/*! \brief returns the equivalent of logic or for strings:
75
/*! \brief returns the equivalent of logic or for strings:
76
 * first one if not empty, otherwise second one.
76
 * first one if not empty, otherwise second one.
77
 */
77
 */
78
#define S_OR(a, b) ({typeof(&((a)[0])) __x = (a); ast_strlen_zero(__x) ? (b) : __x;})
78
#define S_OR(a, b) ({typeof(&((a)[0])) __x = (a); ast_strlen_zero(__x) ? (b) : __x;})
79

    
   
79

   
80
/*! \brief returns the equivalent of logic or for strings, with an additional boolean check:
80
/*! \brief returns the equivalent of logic or for strings, with an additional boolean check:
81
 * second one if not empty and first one is true, otherwise third one.
81
 * second one if not empty and first one is true, otherwise third one.
82
 * example: S_COR(usewidget, widget, "<no widget>")
82
 * example: S_COR(usewidget, widget, "<no widget>")
83
 */
83
 */
84
#define S_COR(a, b, c) ({typeof(&((b)[0])) __x = (b); (a) && !ast_strlen_zero(__x) ? (__x) : (c);})
84
#define S_COR(a, b, c) ({typeof(&((b)[0])) __x = (b); (a) && !ast_strlen_zero(__x) ? (__x) : (c);})
85

    
   
85

   
86
/*
86
/*
87
  \brief Checks whether a string begins with another.
87
  \brief Checks whether a string begins with another.
88
  \since 12.0.0
88
  \since 12.0.0
89
  \param str String to check.
89
  \param str String to check.
90
  \param prefix Prefix to look for.
90
  \param prefix Prefix to look for.
91
  \param 1 if \a str begins with \a prefix, 0 otherwise.
91
  \param 1 if \a str begins with \a prefix, 0 otherwise.
92
 */
92
 */
93
static int force_inline attribute_pure ast_begins_with(const char *str, const char *prefix)
93
static int force_inline attribute_pure ast_begins_with(const char *str, const char *prefix)
94
{
94
{
95
	ast_assert(str != NULL);
95
	ast_assert(str != NULL);
96
	ast_assert(prefix != NULL);
96
	ast_assert(prefix != NULL);
97
	while (*str == *prefix && *prefix != '\0') {
97
	while (*str == *prefix && *prefix != '\0') {
98
		++str;
98
		++str;
99
		++prefix;
99
		++prefix;
100
	}
100
	}
101
	return *prefix == '\0';
101
	return *prefix == '\0';
102
}
102
}
103

    
   
103

   
104
/*
104
/*
105
  \brief Checks whether a string ends with another.
105
  \brief Checks whether a string ends with another.
106
  \since 12.0.0
106
  \since 12.0.0
107
  \param str String to check.
107
  \param str String to check.
108
  \param suffix Suffix to look for.
108
  \param suffix Suffix to look for.
109
  \param 1 if \a str ends with \a suffix, 0 otherwise.
109
  \param 1 if \a str ends with \a suffix, 0 otherwise.
110
 */
110
 */
111
static int force_inline attribute_pure ast_ends_with(const char *str, const char *suffix)
111
static int force_inline attribute_pure ast_ends_with(const char *str, const char *suffix)
112
{
112
{
113
	size_t str_len;
113
	size_t str_len;
114
	size_t suffix_len;
114
	size_t suffix_len;
115

    
   
115

   
116
	ast_assert(str != NULL);
116
	ast_assert(str != NULL);
117
	ast_assert(suffix != NULL);
117
	ast_assert(suffix != NULL);
118
	str_len = strlen(str);
118
	str_len = strlen(str);
119
	suffix_len = strlen(suffix);
119
	suffix_len = strlen(suffix);
120

    
   
120

   
121
	if (suffix_len > str_len) {
121
	if (suffix_len > str_len) {
122
		return 0;
122
		return 0;
123
	}
123
	}
124

    
   
124

   
125
	return strcmp(str + str_len - suffix_len, suffix) == 0;
125
	return strcmp(str + str_len - suffix_len, suffix) == 0;
126
}
126
}
127

    
   
127

   
128
/*!
128
/*!
129
 * \brief return Yes or No depending on the argument.
129
 * \brief return Yes or No depending on the argument.
130
 *
130
 *
131
 * Note that this macro is used my AMI, where a literal "Yes" and "No" are
131
 * Note that this macro is used my AMI, where a literal "Yes" and "No" are
132
 * expected, and translations would cause problems.
132
 * expected, and translations would cause problems.
133
 *
133
 *
134
 * \param x Boolean value
134
 * \param x Boolean value
135
 * \return "Yes" if x is true (non-zero)
135
 * \return "Yes" if x is true (non-zero)
136
 * \return "No" if x is false (zero)
136
 * \return "No" if x is false (zero)
137
 */
137
 */
138
#define AST_YESNO(x) ((x) ? "Yes" : "No")
138
#define AST_YESNO(x) ((x) ? "Yes" : "No")
139

    
   
139

   
140
/*!
140
/*!
141
  \brief Gets a pointer to the first non-whitespace character in a string.
141
  \brief Gets a pointer to the first non-whitespace character in a string.
142
  \param str the input string
142
  \param str the input string
143
  \return a pointer to the first non-whitespace character
143
  \return a pointer to the first non-whitespace character
144
 */
144
 */
145
AST_INLINE_API(
145
AST_INLINE_API(
146
char * attribute_pure ast_skip_blanks(const char *str),
146
char * attribute_pure ast_skip_blanks(const char *str),
147
{
147
{
148
	while (*str && ((unsigned char) *str) < 33)
148
	while (*str && ((unsigned char) *str) < 33)
149
		str++;
149
		str++;
150
	return (char *) str;
150
	return (char *) str;
151
}
151
}
152
)
152
)
153

    
   
153

   
154
/*!
154
/*!
155
  \brief Trims trailing whitespace characters from a string.
155
  \brief Trims trailing whitespace characters from a string.
156
  \param str the input string
156
  \param str the input string
157
  \return a pointer to the modified string
157
  \return a pointer to the modified string
158
 */
158
 */
159
AST_INLINE_API(
159
AST_INLINE_API(
160
char *ast_trim_blanks(char *str),
160
char *ast_trim_blanks(char *str),
161
{
161
{
162
	char *work = str;
162
	char *work = str;
163

    
   
163

   
164
	if (work) {
164
	if (work) {
165
		work += strlen(work) - 1;
165
		work += strlen(work) - 1;
166
		/* It's tempting to only want to erase after we exit this loop, 
166
		/* It's tempting to only want to erase after we exit this loop, 
167
		   but since ast_trim_blanks *could* receive a constant string
167
		   but since ast_trim_blanks *could* receive a constant string
168
		   (which we presumably wouldn't have to touch), we shouldn't
168
		   (which we presumably wouldn't have to touch), we shouldn't
169
		   actually set anything unless we must, and it's easier just
169
		   actually set anything unless we must, and it's easier just
170
		   to set each position to \0 than to keep track of a variable
170
		   to set each position to \0 than to keep track of a variable
171
		   for it */
171
		   for it */
172
		while ((work >= str) && ((unsigned char) *work) < 33)
172
		while ((work >= str) && ((unsigned char) *work) < 33)
173
			*(work--) = '\0';
173
			*(work--) = '\0';
174
	}
174
	}
175
	return str;
175
	return str;
176
}
176
}
177
)
177
)
178

    
   
178

   
179
/*!
179
/*!
180
  \brief Gets a pointer to first whitespace character in a string.
180
  \brief Gets a pointer to first whitespace character in a string.
181
  \param str the input string
181
  \param str the input string
182
  \return a pointer to the first whitespace character
182
  \return a pointer to the first whitespace character
183
 */
183
 */
184
AST_INLINE_API(
184
AST_INLINE_API(
185
char * attribute_pure ast_skip_nonblanks(const char *str),
185
char * attribute_pure ast_skip_nonblanks(const char *str),
186
{
186
{
187
	while (*str && ((unsigned char) *str) > 32)
187
	while (*str && ((unsigned char) *str) > 32)
188
		str++;
188
		str++;
189
	return (char *) str;
189
	return (char *) str;
190
}
190
}
191
)
191
)
192
  
192
  
193
/*!
193
/*!
194
  \brief Strip leading/trailing whitespace from a string.
194
  \brief Strip leading/trailing whitespace from a string.
195
  \param s The string to be stripped (will be modified).
195
  \param s The string to be stripped (will be modified).
196
  \return The stripped string.
196
  \return The stripped string.
197

    
   
197

   
198
  This functions strips all leading and trailing whitespace
198
  This functions strips all leading and trailing whitespace
199
  characters from the input string, and returns a pointer to
199
  characters from the input string, and returns a pointer to
200
  the resulting string. The string is modified in place.
200
  the resulting string. The string is modified in place.
201
*/
201
*/
202
AST_INLINE_API(
202
AST_INLINE_API(
203
char *ast_strip(char *s),
203
char *ast_strip(char *s),
204
{
204
{
205
	if ((s = ast_skip_blanks(s))) {
205
	if ((s = ast_skip_blanks(s))) {
206
		ast_trim_blanks(s);
206
		ast_trim_blanks(s);
207
	}
207
	}
208
	return s;
208
	return s;
209
} 
209
} 
210
)
210
)
211

    
   
211

   
212
/*!
212
/*!
213
  \brief Strip leading/trailing whitespace and quotes from a string.
213
  \brief Strip leading/trailing whitespace and quotes from a string.
214
  \param s The string to be stripped (will be modified).
214
  \param s The string to be stripped (will be modified).
215
  \param beg_quotes The list of possible beginning quote characters.
215
  \param beg_quotes The list of possible beginning quote characters.
216
  \param end_quotes The list of matching ending quote characters.
216
  \param end_quotes The list of matching ending quote characters.
217
  \return The stripped string.
217
  \return The stripped string.
218

    
   
218

   
219
  This functions strips all leading and trailing whitespace
219
  This functions strips all leading and trailing whitespace
220
  characters from the input string, and returns a pointer to
220
  characters from the input string, and returns a pointer to
221
  the resulting string. The string is modified in place.
221
  the resulting string. The string is modified in place.
222

    
   
222

   
223
  It can also remove beginning and ending quote (or quote-like)
223
  It can also remove beginning and ending quote (or quote-like)
224
  characters, in matching pairs. If the first character of the
224
  characters, in matching pairs. If the first character of the
225
  string matches any character in beg_quotes, and the last
225
  string matches any character in beg_quotes, and the last
226
  character of the string is the matching character in
226
  character of the string is the matching character in
227
  end_quotes, then they are removed from the string.
227
  end_quotes, then they are removed from the string.
228

    
   
228

   
229
  Examples:
229
  Examples:
230
  \code
230
  \code
231
  ast_strip_quoted(buf, "\"", "\"");
231
  ast_strip_quoted(buf, "\"", "\"");
232
  ast_strip_quoted(buf, "'", "'");
232
  ast_strip_quoted(buf, "'", "'");
233
  ast_strip_quoted(buf, "[{(", "]})");
233
  ast_strip_quoted(buf, "[{(", "]})");
234
  \endcode
234
  \endcode
235
 */
235
 */
236
char *ast_strip_quoted(char *s, const char *beg_quotes, const char *end_quotes);
236
char *ast_strip_quoted(char *s, const char *beg_quotes, const char *end_quotes);
237

    
   
237

   
238
/*!
238
/*!

    
   
239
  \brief Flags for ast_strsep

    
   
240
 */

    
   
241
enum ast_strsep_flags {

    
   
242
	AST_STRSEP_STRIP =    0x01, /*!< Trim, then strip quotes.  You may want to trim again */

    
   
243
	AST_STRSEP_TRIM =     0x02, /*!< Trim leading and trailing whitespace */

    
   
244
	AST_STRSEP_UNESCAPE = 0x04, /*!< Unescape '\' */

    
   
245
	AST_STRSEP_ALL =      0x07, /*!< Trim, strip, unescape */

    
   
246
};

    
   
247

   

    
   
248
/*!

    
   
249
  \brief Act like strsep but ignore separators inside quotes.

    
   
250
  \param s Pointer to address of the the string to be processed.

    
   
251
  Will be modified and can't be constant.

    
   
252
  \param sep A single character delimiter.

    
   
253
  \param flags Controls post-processing of the result.

    
   
254
  AST_STRSEP_TRIM trims all leading and trailing whitespace from the result.

    
   
255
  AST_STRSEP_STRIP does a trim then strips the outermost quotes.  You may want

    
   
256
  to trim again after the strip.  Just OR both the TRIM and STRIP flags.

    
   
257
  AST_STRSEP_UNESCAPE unescapes '\' sequences.

    
   
258
  AST_STRSEP_ALL does all of the above processing.

    
   
259
  \return The next token or NULL if done or if there are more than 8 levels of

    
   
260
  nested quotes.

    
   
261

   

    
   
262
  This function acts like strsep with three exceptions...

    
   
263
  The separator is a single character instead of a string.

    
   
264
  Separators inside quotes are treated literally instead of like separators.

    
   
265
  You can elect to have leading and trailing whitespace and quotes

    
   
266
  stripped from the result and have '\' sequences unescaped.

    
   
267

   

    
   
268
  Like strsep, ast_strsep maintains no internal state and you can call it

    
   
269
  recursively using different separators on the same storage.

    
   
270

   

    
   
271
  Also like strsep, for consistent results, consecutive separators are not

    
   
272
  collapsed so you may get an empty string as a valid result.

    
   
273

   

    
   
274
  Examples:

    
   
275
  \code

    
   
276
	char *mystr = ast_strdupa("abc=def,ghi='zzz=yyy,456',jkl");

    
   
277
	char *token, *token2, *token3;

    
   
278

   

    
   
279
	while((token = ast_strsep(&mystr, ',', AST_SEP_STRIP))) {

    
   
280
		// 1st token will be aaa=def

    
   
281
		// 2nd token will be ghi='zzz=yyy,456'

    
   
282
		while((token2 = ast_strsep(&token, '=', AST_SEP_STRIP))) {

    
   
283
			// 1st token2 will be ghi

    
   
284
			// 2nd token2 will be zzz=yyy,456

    
   
285
			while((token3 = ast_strsep(&token2, ',', AST_SEP_STRIP))) {

    
   
286
				// 1st token3 will be zzz=yyy

    
   
287
				// 2nd token3 will be 456

    
   
288
				// and so on

    
   
289
			}

    
   
290
		}

    
   
291
		// 3rd token will be jkl

    
   
292
	}

    
   
293

   

    
   
294
  \endcode

    
   
295
 */

    
   
296
char *ast_strsep(char **s, const char sep, uint32_t flags);

    
   
297

   

    
   
298
/*!
239
  \brief Strip backslash for "escaped" semicolons, 
299
  \brief Strip backslash for "escaped" semicolons, 
240
	the string to be stripped (will be modified).
300
	the string to be stripped (will be modified).
241
  \return The stripped string.
301
  \return The stripped string.
242
 */
302
 */
243
char *ast_unescape_semicolon(char *s);
303
char *ast_unescape_semicolon(char *s);
244

    
   
304

   
245
/*!
305
/*!
246
  \brief Convert some C escape sequences  \verbatim (\b\f\n\r\t) \endverbatim into the
306
  \brief Convert some C escape sequences  \verbatim (\b\f\n\r\t) \endverbatim into the
247
	equivalent characters. The string to be converted (will be modified).
307
	equivalent characters. The string to be converted (will be modified).
248
  \return The converted string.
308
  \return The converted string.
249
 */
309
 */
250
char *ast_unescape_c(char *s);
310
char *ast_unescape_c(char *s);
251

    
   
311

   
252
/*!
312
/*!
253
  \brief Size-limited null-terminating string copy.
313
  \brief Size-limited null-terminating string copy.
254
  \param dst The destination buffer.
314
  \param dst The destination buffer.
255
  \param src The source string
315
  \param src The source string
256
  \param size The size of the destination buffer
316
  \param size The size of the destination buffer
257
  \return Nothing.
317
  \return Nothing.
258

    
   
318

   
259
  This is similar to \a strncpy, with two important differences:
319
  This is similar to \a strncpy, with two important differences:
260
    - the destination buffer will \b always be null-terminated
320
    - the destination buffer will \b always be null-terminated
261
    - the destination buffer is not filled with zeros past the copied string length
321
    - the destination buffer is not filled with zeros past the copied string length
262
  These differences make it slightly more efficient, and safer to use since it will
322
  These differences make it slightly more efficient, and safer to use since it will
263
  not leave the destination buffer unterminated. There is no need to pass an artificially
323
  not leave the destination buffer unterminated. There is no need to pass an artificially
264
  reduced buffer size to this function (unlike \a strncpy), and the buffer does not need
324
  reduced buffer size to this function (unlike \a strncpy), and the buffer does not need
265
  to be initialized to zeroes prior to calling this function.
325
  to be initialized to zeroes prior to calling this function.
266
*/
326
*/
267
AST_INLINE_API(
327
AST_INLINE_API(
268
void ast_copy_string(char *dst, const char *src, size_t size),
328
void ast_copy_string(char *dst, const char *src, size_t size),
269
{
329
{
270
	while (*src && size) {
330
	while (*src && size) {
271
		*dst++ = *src++;
331
		*dst++ = *src++;
272
		size--;
332
		size--;
273
	}
333
	}
274
	if (__builtin_expect(!size, 0))
334
	if (__builtin_expect(!size, 0))
275
		dst--;
335
		dst--;
276
	*dst = '\0';
336
	*dst = '\0';
277
}
337
}
278
)
338
)
279

    
   
339

   
280
/*!
340
/*!
281
  \brief Build a string in a buffer, designed to be called repeatedly
341
  \brief Build a string in a buffer, designed to be called repeatedly
282
  
342
  
283
  \note This method is not recommended. New code should use ast_str_*() instead.
343
  \note This method is not recommended. New code should use ast_str_*() instead.
284

    
   
344

   
285
  This is a wrapper for snprintf, that properly handles the buffer pointer
345
  This is a wrapper for snprintf, that properly handles the buffer pointer
286
  and buffer space available.
346
  and buffer space available.
287

    
   
347

   
288
  \param buffer current position in buffer to place string into (will be updated on return)
348
  \param buffer current position in buffer to place string into (will be updated on return)
289
  \param space remaining space in buffer (will be updated on return)
349
  \param space remaining space in buffer (will be updated on return)
290
  \param fmt printf-style format string
350
  \param fmt printf-style format string
291
  \retval 0 on success
351
  \retval 0 on success
292
  \retval non-zero on failure.
352
  \retval non-zero on failure.
293
*/
353
*/
294
int ast_build_string(char **buffer, size_t *space, const char *fmt, ...) __attribute__((format(printf, 3, 4)));
354
int ast_build_string(char **buffer, size_t *space, const char *fmt, ...) __attribute__((format(printf, 3, 4)));
295

    
   
355

   
296
/*!
356
/*!
297
  \brief Build a string in a buffer, designed to be called repeatedly
357
  \brief Build a string in a buffer, designed to be called repeatedly
298
  
358
  
299
  This is a wrapper for snprintf, that properly handles the buffer pointer
359
  This is a wrapper for snprintf, that properly handles the buffer pointer
300
  and buffer space available.
360
  and buffer space available.
301

    
   
361

   
302
  \return 0 on success, non-zero on failure.
362
  \return 0 on success, non-zero on failure.
303
  \param buffer current position in buffer to place string into (will be updated on return)
363
  \param buffer current position in buffer to place string into (will be updated on return)
304
  \param space remaining space in buffer (will be updated on return)
364
  \param space remaining space in buffer (will be updated on return)
305
  \param fmt printf-style format string
365
  \param fmt printf-style format string
306
  \param ap varargs list of arguments for format
366
  \param ap varargs list of arguments for format
307
*/
367
*/
308
int ast_build_string_va(char **buffer, size_t *space, const char *fmt, va_list ap) __attribute__((format(printf, 3, 0)));
368
int ast_build_string_va(char **buffer, size_t *space, const char *fmt, va_list ap) __attribute__((format(printf, 3, 0)));
309

    
   
369

   
310
/*!
370
/*!
311
 * \brief Make sure something is true.
371
 * \brief Make sure something is true.
312
 * Determine if a string containing a boolean value is "true".
372
 * Determine if a string containing a boolean value is "true".
313
 * This function checks to see whether a string passed to it is an indication of an "true" value.
373
 * This function checks to see whether a string passed to it is an indication of an "true" value.
314
 * It checks to see if the string is "yes", "true", "y", "t", "on" or "1".
374
 * It checks to see if the string is "yes", "true", "y", "t", "on" or "1".
315
 *
375
 *
316
 * \retval 0 if val is a NULL pointer.
376
 * \retval 0 if val is a NULL pointer.
317
 * \retval -1 if "true".
377
 * \retval -1 if "true".
318
 * \retval 0 otherwise.
378
 * \retval 0 otherwise.
319
 */
379
 */
320
int attribute_pure ast_true(const char *val);
380
int attribute_pure ast_true(const char *val);
321

    
   
381

   
322
/*! 
382
/*! 
323
 * \brief Make sure something is false.
383
 * \brief Make sure something is false.
324
 * Determine if a string containing a boolean value is "false".
384
 * Determine if a string containing a boolean value is "false".
325
 * This function checks to see whether a string passed to it is an indication of an "false" value.  
385
 * This function checks to see whether a string passed to it is an indication of an "false" value.  
326
 * It checks to see if the string is "no", "false", "n", "f", "off" or "0".  
386
 * It checks to see if the string is "no", "false", "n", "f", "off" or "0".  
327
 *
387
 *
328
 * \retval 0 if val is a NULL pointer.
388
 * \retval 0 if val is a NULL pointer.
329
 * \retval -1 if "true".
389
 * \retval -1 if "true".
330
 * \retval 0 otherwise.
390
 * \retval 0 otherwise.
331
 */
391
 */
332
int attribute_pure ast_false(const char *val);
392
int attribute_pure ast_false(const char *val);
333

    
   
393

   
334
/*
394
/*
335
 * \brief Join an array of strings into a single string.
395
 * \brief Join an array of strings into a single string.
336
 * \param s the resulting string buffer
396
 * \param s the resulting string buffer
337
 * \param len the length of the result buffer, s
397
 * \param len the length of the result buffer, s
338
 * \param w an array of strings to join.
398
 * \param w an array of strings to join.
339
 * \param size the number of elements to join
399
 * \param size the number of elements to join
340
 * \param delim delimiter between elements
400
 * \param delim delimiter between elements
341
 *
401
 *
342
 * This function will join all of the strings in the array 'w' into a single
402
 * This function will join all of the strings in the array 'w' into a single
343
 * string.  It will also place 'delim' in the result buffer in between each
403
 * string.  It will also place 'delim' in the result buffer in between each
344
 * string from 'w'.
404
 * string from 'w'.
345
 * \since 12
405
 * \since 12
346
*/
406
*/
347
void ast_join_delim(char *s, size_t len, const char * const w[],
407
void ast_join_delim(char *s, size_t len, const char * const w[],
348
		    unsigned int size, char delim);
408
		    unsigned int size, char delim);
349

    
   
409

   
350
/*
410
/*
351
 * \brief Join an array of strings into a single string.
411
 * \brief Join an array of strings into a single string.
352
 * \param s the resulting string buffer
412
 * \param s the resulting string buffer
353
 * \param len the length of the result buffer, s
413
 * \param len the length of the result buffer, s
354
 * \param w an array of strings to join.
414
 * \param w an array of strings to join.
355
 *
415
 *
356
 * This function will join all of the strings in the array 'w' into a single
416
 * This function will join all of the strings in the array 'w' into a single
357
 * string.  It will also place a space in the result buffer in between each
417
 * string.  It will also place a space in the result buffer in between each
358
 * string from 'w'.
418
 * string from 'w'.
359
*/
419
*/
360
#define ast_join(s, len, w) ast_join_delim(s, len, w, -1, ' ')
420
#define ast_join(s, len, w) ast_join_delim(s, len, w, -1, ' ')
361

    
   
421

   
362
/*
422
/*
363
 * \brief Attempts to convert the given string to camel case using
423
 * \brief Attempts to convert the given string to camel case using
364
 *        the specified delimiter.
424
 *        the specified delimiter.
365
 *
425
 *
366
 * note - returned string needs to be freed
426
 * note - returned string needs to be freed
367
 *
427
 *
368
 * \param s the string to convert
428
 * \param s the string to convert
369
 * \param delim delimiter to parse out
429
 * \param delim delimiter to parse out
370
 *
430
 *
371
 * \retval The string converted to "CamelCase"
431
 * \retval The string converted to "CamelCase"
372
 * \since 12
432
 * \since 12
373
*/
433
*/
374
char *ast_to_camel_case_delim(const char *s, const char *delim);
434
char *ast_to_camel_case_delim(const char *s, const char *delim);
375

    
   
435

   
376
/*
436
/*
377
 * \brief Attempts to convert the given string to camel case using
437
 * \brief Attempts to convert the given string to camel case using
378
 *        an underscore as the specified delimiter.
438
 *        an underscore as the specified delimiter.
379
 *
439
 *
380
 * note - returned string needs to be freed
440
 * note - returned string needs to be freed
381
 *
441
 *
382
 * \param s the string to convert
442
 * \param s the string to convert
383
 *
443
 *
384
 * \retval The string converted to "CamelCase"
444
 * \retval The string converted to "CamelCase"
385
*/
445
*/
386
#define ast_to_camel_case(s) ast_to_camel_case_delim(s, "_")
446
#define ast_to_camel_case(s) ast_to_camel_case_delim(s, "_")
387

    
   
447

   
388
/*
448
/*
389
  \brief Parse a time (integer) string.
449
  \brief Parse a time (integer) string.
390
  \param src String to parse
450
  \param src String to parse
391
  \param dst Destination
451
  \param dst Destination
392
  \param _default Value to use if the string does not contain a valid time
452
  \param _default Value to use if the string does not contain a valid time
393
  \param consumed The number of characters 'consumed' in the string by the parse (see 'man sscanf' for details)
453
  \param consumed The number of characters 'consumed' in the string by the parse (see 'man sscanf' for details)
394
  \retval 0 on success
454
  \retval 0 on success
395
  \retval non-zero on failure.
455
  \retval non-zero on failure.
396
*/
456
*/
397
int ast_get_time_t(const char *src, time_t *dst, time_t _default, int *consumed);
457
int ast_get_time_t(const char *src, time_t *dst, time_t _default, int *consumed);
398

    
   
458

   
399
/*
459
/*
400
  \brief Parse a time (float) string.
460
  \brief Parse a time (float) string.
401
  \param src String to parse
461
  \param src String to parse
402
  \param dst Destination
462
  \param dst Destination
403
  \param _default Value to use if the string does not contain a valid time
463
  \param _default Value to use if the string does not contain a valid time
404
  \param consumed The number of characters 'consumed' in the string by the parse (see 'man sscanf' for details)
464
  \param consumed The number of characters 'consumed' in the string by the parse (see 'man sscanf' for details)
405
  \return zero on success, non-zero on failure
465
  \return zero on success, non-zero on failure
406
*/
466
*/
407
int ast_get_timeval(const char *src, struct timeval *tv, struct timeval _default, int *consumed);
467
int ast_get_timeval(const char *src, struct timeval *tv, struct timeval _default, int *consumed);
408

    
   
468

   
409
/*!
469
/*!
410
 * Support for dynamic strings.
470
 * Support for dynamic strings.
411
 *
471
 *
412
 * A dynamic string is just a C string prefixed by a few control fields
472
 * A dynamic string is just a C string prefixed by a few control fields
413
 * that help setting/appending/extending it using a printf-like syntax.
473
 * that help setting/appending/extending it using a printf-like syntax.
414
 *
474
 *
415
 * One should never declare a variable with this type, but only a pointer
475
 * One should never declare a variable with this type, but only a pointer
416
 * to it, e.g.
476
 * to it, e.g.
417
 *
477
 *
418
 *	struct ast_str *ds;
478
 *	struct ast_str *ds;
419
 *
479
 *
420
 * The pointer can be initialized with the following:
480
 * The pointer can be initialized with the following:
421
 *
481
 *
422
 *	ds = ast_str_create(init_len);
482
 *	ds = ast_str_create(init_len);
423
 *		creates a malloc()'ed dynamic string;
483
 *		creates a malloc()'ed dynamic string;
424
 *
484
 *
425
 *	ds = ast_str_alloca(init_len);
485
 *	ds = ast_str_alloca(init_len);
426
 *		creates a string on the stack (not very dynamic!).
486
 *		creates a string on the stack (not very dynamic!).
427
 *
487
 *
428
 *	ds = ast_str_thread_get(ts, init_len)
488
 *	ds = ast_str_thread_get(ts, init_len)
429
 *		creates a malloc()'ed dynamic string associated to
489
 *		creates a malloc()'ed dynamic string associated to
430
 *		the thread-local storage key ts
490
 *		the thread-local storage key ts
431
 *
491
 *
432
 * Finally, the string can be manipulated with the following:
492
 * Finally, the string can be manipulated with the following:
433
 *
493
 *
434
 *	ast_str_set(&buf, max_len, fmt, ...)
494
 *	ast_str_set(&buf, max_len, fmt, ...)
435
 *	ast_str_append(&buf, max_len, fmt, ...)
495
 *	ast_str_append(&buf, max_len, fmt, ...)
436
 *
496
 *
437
 * and their varargs variant
497
 * and their varargs variant
438
 *
498
 *
439
 *	ast_str_set_va(&buf, max_len, ap)
499
 *	ast_str_set_va(&buf, max_len, ap)
440
 *	ast_str_append_va(&buf, max_len, ap)
500
 *	ast_str_append_va(&buf, max_len, ap)
441
 *
501
 *
442
 * \param max_len The maximum allowed capacity of the ast_str. Note that
502
 * \param max_len The maximum allowed capacity of the ast_str. Note that
443
 *  if the value of max_len is less than the current capacity of the
503
 *  if the value of max_len is less than the current capacity of the
444
 *  ast_str (as returned by ast_str_size), then the parameter is effectively
504
 *  ast_str (as returned by ast_str_size), then the parameter is effectively
445
 *  ignored.
505
 *  ignored.
446
 * 	0 means unlimited, -1 means "at most the available space"
506
 * 	0 means unlimited, -1 means "at most the available space"
447
 *
507
 *
448
 * \return All the functions return <0 in case of error, or the
508
 * \return All the functions return <0 in case of error, or the
449
 *	length of the string added to the buffer otherwise. Note that
509
 *	length of the string added to the buffer otherwise. Note that
450
 *	in most cases where an error is returned, characters ARE written
510
 *	in most cases where an error is returned, characters ARE written
451
 *	to the ast_str.
511
 *	to the ast_str.
452
 */
512
 */
453

    
   
513

   
454
/*! \brief The descriptor of a dynamic string
514
/*! \brief The descriptor of a dynamic string
455
 *  XXX storage will be optimized later if needed
515
 *  XXX storage will be optimized later if needed
456
 * We use the ts field to indicate the type of storage.
516
 * We use the ts field to indicate the type of storage.
457
 * Three special constants indicate malloc, ast_alloca() or static
517
 * Three special constants indicate malloc, ast_alloca() or static
458
 * variables, all other values indicate a
518
 * variables, all other values indicate a
459
 * struct ast_threadstorage pointer.
519
 * struct ast_threadstorage pointer.
460
 */
520
 */
461
struct ast_str {
521
struct ast_str {
462
	size_t __AST_STR_LEN;			/*!< The current maximum length of the string */
522
	size_t __AST_STR_LEN;			/*!< The current maximum length of the string */
463
	size_t __AST_STR_USED;			/*!< Amount of space used */
523
	size_t __AST_STR_USED;			/*!< Amount of space used */
464
	struct ast_threadstorage *__AST_STR_TS;	/*!< What kind of storage is this ? */
524
	struct ast_threadstorage *__AST_STR_TS;	/*!< What kind of storage is this ? */
465
#define DS_MALLOC	((struct ast_threadstorage *)1)
525
#define DS_MALLOC	((struct ast_threadstorage *)1)
466
#define DS_ALLOCA	((struct ast_threadstorage *)2)
526
#define DS_ALLOCA	((struct ast_threadstorage *)2)
467
#define DS_STATIC	((struct ast_threadstorage *)3)	/* not supported yet */
527
#define DS_STATIC	((struct ast_threadstorage *)3)	/* not supported yet */
468
	char __AST_STR_STR[0];			/*!< The string buffer */
528
	char __AST_STR_STR[0];			/*!< The string buffer */
469
};
529
};
470

    
   
530

   
471
/*!
531
/*!
472
 * \brief Given a string regex_string in the form of "/regex/", convert it into the form of "regex"
532
 * \brief Given a string regex_string in the form of "/regex/", convert it into the form of "regex"
473
 *
533
 *
474
 * This function will trim one leading / and one trailing / from a given input string
534
 * This function will trim one leading / and one trailing / from a given input string
475
 * ast_str regex_pattern must be preallocated before calling this function
535
 * ast_str regex_pattern must be preallocated before calling this function
476
 *
536
 *
477
 * \return 0 on success, non-zero on failure.
537
 * \return 0 on success, non-zero on failure.
478
 * \return 1 if we only stripped a leading /
538
 * \return 1 if we only stripped a leading /
479
 * \return 2 if we only stripped a trailing /
539
 * \return 2 if we only stripped a trailing /
480
 * \return 3 if we did not strip any / characters
540
 * \return 3 if we did not strip any / characters
481
 * \param regex_string  the string containing /regex/
541
 * \param regex_string  the string containing /regex/
482
 * \param regex_pattern the destination ast_str which will contain "regex" after execution
542
 * \param regex_pattern the destination ast_str which will contain "regex" after execution
483
 */
543
 */
484
int ast_regex_string_to_regex_pattern(const char *regex_string, struct ast_str **regex_pattern);
544
int ast_regex_string_to_regex_pattern(const char *regex_string, struct ast_str **regex_pattern);
485

    
   
545

   
486
/*!
546
/*!
487
 * \brief Create a malloc'ed dynamic length string
547
 * \brief Create a malloc'ed dynamic length string
488
 *
548
 *
489
 * \param init_len This is the initial length of the string buffer
549
 * \param init_len This is the initial length of the string buffer
490
 *
550
 *
491
 * \return This function returns a pointer to the dynamic string length.  The
551
 * \return This function returns a pointer to the dynamic string length.  The
492
 *         result will be NULL in the case of a memory allocation error.
552
 *         result will be NULL in the case of a memory allocation error.
493
 *
553
 *
494
 * \note The result of this function is dynamically allocated memory, and must
554
 * \note The result of this function is dynamically allocated memory, and must
495
 *       be free()'d after it is no longer needed.
555
 *       be free()'d after it is no longer needed.
496
 */
556
 */
497
#if (defined(MALLOC_DEBUG) && !defined(STANDALONE))
557
#if (defined(MALLOC_DEBUG) && !defined(STANDALONE))
498
#define	ast_str_create(a)	_ast_str_create(a,__FILE__,__LINE__,__PRETTY_FUNCTION__)
558
#define	ast_str_create(a)	_ast_str_create(a,__FILE__,__LINE__,__PRETTY_FUNCTION__)
499
AST_INLINE_API(
559
AST_INLINE_API(
500
struct ast_str * attribute_malloc _ast_str_create(size_t init_len,
560
struct ast_str * attribute_malloc _ast_str_create(size_t init_len,
501
		const char *file, int lineno, const char *func),
561
		const char *file, int lineno, const char *func),
502
{
562
{
503
	struct ast_str *buf;
563
	struct ast_str *buf;
504

    
   
564

   
505
	buf = (struct ast_str *)__ast_calloc(1, sizeof(*buf) + init_len, file, lineno, func);
565
	buf = (struct ast_str *)__ast_calloc(1, sizeof(*buf) + init_len, file, lineno, func);
506
	if (buf == NULL)
566
	if (buf == NULL)
507
		return NULL;
567
		return NULL;
508

    
   
568

   
509
	buf->__AST_STR_LEN = init_len;
569
	buf->__AST_STR_LEN = init_len;
510
	buf->__AST_STR_USED = 0;
570
	buf->__AST_STR_USED = 0;
511
	buf->__AST_STR_TS = DS_MALLOC;
571
	buf->__AST_STR_TS = DS_MALLOC;
512

    
   
572

   
513
	return buf;
573
	return buf;
514
}
574
}
515
)
575
)
516
#else
576
#else
517
AST_INLINE_API(
577
AST_INLINE_API(
518
struct ast_str * attribute_malloc ast_str_create(size_t init_len),
578
struct ast_str * attribute_malloc ast_str_create(size_t init_len),
519
{
579
{
520
	struct ast_str *buf;
580
	struct ast_str *buf;
521

    
   
581

   
522
	buf = (struct ast_str *)ast_calloc(1, sizeof(*buf) + init_len);
582
	buf = (struct ast_str *)ast_calloc(1, sizeof(*buf) + init_len);
523
	if (buf == NULL)
583
	if (buf == NULL)
524
		return NULL;
584
		return NULL;
525

    
   
585

   
526
	buf->__AST_STR_LEN = init_len;
586
	buf->__AST_STR_LEN = init_len;
527
	buf->__AST_STR_USED = 0;
587
	buf->__AST_STR_USED = 0;
528
	buf->__AST_STR_TS = DS_MALLOC;
588
	buf->__AST_STR_TS = DS_MALLOC;
529

    
   
589

   
530
	return buf;
590
	return buf;
531
}
591
}
532
)
592
)
533
#endif
593
#endif
534

    
   
594

   
535
/*! \brief Reset the content of a dynamic string.
595
/*! \brief Reset the content of a dynamic string.
536
 * Useful before a series of ast_str_append.
596
 * Useful before a series of ast_str_append.
537
 */
597
 */
538
AST_INLINE_API(
598
AST_INLINE_API(
539
void ast_str_reset(struct ast_str *buf),
599
void ast_str_reset(struct ast_str *buf),
540
{
600
{
541
	if (buf) {
601
	if (buf) {
542
		buf->__AST_STR_USED = 0;
602
		buf->__AST_STR_USED = 0;
543
		if (buf->__AST_STR_LEN) {
603
		if (buf->__AST_STR_LEN) {
544
			buf->__AST_STR_STR[0] = '\0';
604
			buf->__AST_STR_STR[0] = '\0';
545
		}
605
		}
546
	}
606
	}
547
}
607
}
548
)
608
)
549

    
   
609

   
550
/*! \brief Update the length of the buffer, after using ast_str merely as a buffer.
610
/*! \brief Update the length of the buffer, after using ast_str merely as a buffer.
551
 *  \param buf A pointer to the ast_str string.
611
 *  \param buf A pointer to the ast_str string.
552
 */
612
 */
553
AST_INLINE_API(
613
AST_INLINE_API(
554
void ast_str_update(struct ast_str *buf),
614
void ast_str_update(struct ast_str *buf),
555
{
615
{
556
	buf->__AST_STR_USED = strlen(buf->__AST_STR_STR);
616
	buf->__AST_STR_USED = strlen(buf->__AST_STR_STR);
557
}
617
}
558
)
618
)
559

    
   
619

   
560
/*! \brief Trims trailing whitespace characters from an ast_str string.
620
/*! \brief Trims trailing whitespace characters from an ast_str string.
561
 *  \param buf A pointer to the ast_str string.
621
 *  \param buf A pointer to the ast_str string.
562
 */
622
 */
563
AST_INLINE_API(
623
AST_INLINE_API(
564
void ast_str_trim_blanks(struct ast_str *buf),
624
void ast_str_trim_blanks(struct ast_str *buf),
565
{
625
{
566
	if (!buf) {
626
	if (!buf) {
567
		return;
627
		return;
568
	}
628
	}
569
	while (buf->__AST_STR_USED && buf->__AST_STR_STR[buf->__AST_STR_USED - 1] < 33) {
629
	while (buf->__AST_STR_USED && buf->__AST_STR_STR[buf->__AST_STR_USED - 1] < 33) {
570
		buf->__AST_STR_STR[--(buf->__AST_STR_USED)] = '\0';
630
		buf->__AST_STR_STR[--(buf->__AST_STR_USED)] = '\0';
571
	}
631
	}
572
}
632
}
573
)
633
)
574

    
   
634

   
575
/*!\brief Returns the current length of the string stored within buf.
635
/*!\brief Returns the current length of the string stored within buf.
576
 * \param buf A pointer to the ast_str structure.
636
 * \param buf A pointer to the ast_str structure.
577
 */
637
 */
578
AST_INLINE_API(
638
AST_INLINE_API(
579
size_t attribute_pure ast_str_strlen(const struct ast_str *buf),
639
size_t attribute_pure ast_str_strlen(const struct ast_str *buf),
580
{
640
{
581
	return buf->__AST_STR_USED;
641
	return buf->__AST_STR_USED;
582
}
642
}
583
)
643
)
584

    
   
644

   
585
/*!\brief Returns the current maximum length (without reallocation) of the current buffer.
645
/*!\brief Returns the current maximum length (without reallocation) of the current buffer.
586
 * \param buf A pointer to the ast_str structure.
646
 * \param buf A pointer to the ast_str structure.
587
 * \retval Current maximum length of the buffer.
647
 * \retval Current maximum length of the buffer.
588
 */
648
 */
589
AST_INLINE_API(
649
AST_INLINE_API(
590
size_t attribute_pure ast_str_size(const struct ast_str *buf),
650
size_t attribute_pure ast_str_size(const struct ast_str *buf),
591
{
651
{
592
	return buf->__AST_STR_LEN;
652
	return buf->__AST_STR_LEN;
593
}
653
}
594
)
654
)
595

    
   
655

   
596
/*!\brief Returns the string buffer within the ast_str buf.
656
/*!\brief Returns the string buffer within the ast_str buf.
597
 * \param buf A pointer to the ast_str structure.
657
 * \param buf A pointer to the ast_str structure.
598
 * \retval A pointer to the enclosed string.
658
 * \retval A pointer to the enclosed string.
599
 */
659
 */
600
AST_INLINE_API(
660
AST_INLINE_API(
601
char * attribute_pure ast_str_buffer(const struct ast_str *buf),
661
char * attribute_pure ast_str_buffer(const struct ast_str *buf),
602
{
662
{
603
	/* for now, cast away the const qualifier on the pointer
663
	/* for now, cast away the const qualifier on the pointer
604
	 * being returned; eventually, it should become truly const
664
	 * being returned; eventually, it should become truly const
605
	 * and only be modified via accessor functions
665
	 * and only be modified via accessor functions
606
	 */
666
	 */
607
	return (char *) buf->__AST_STR_STR;
667
	return (char *) buf->__AST_STR_STR;
608
}
668
}
609
)
669
)
610

    
   
670

   
611
/*!\brief Truncates the enclosed string to the given length.
671
/*!\brief Truncates the enclosed string to the given length.
612
 * \param buf A pointer to the ast_str structure.
672
 * \param buf A pointer to the ast_str structure.
613
 * \param len Maximum length of the string. If len is larger than the
673
 * \param len Maximum length of the string. If len is larger than the
614
 *        current maximum length, things will explode. If it is negative
674
 *        current maximum length, things will explode. If it is negative
615
 *        at most -len characters will be trimmed off the end.
675
 *        at most -len characters will be trimmed off the end.
616
 * \retval A pointer to the resulting string.
676
 * \retval A pointer to the resulting string.
617
 */
677
 */
618
AST_INLINE_API(
678
AST_INLINE_API(
619
char *ast_str_truncate(struct ast_str *buf, ssize_t len),
679
char *ast_str_truncate(struct ast_str *buf, ssize_t len),
620
{
680
{
621
	if (len < 0) {
681
	if (len < 0) {
622
		if ((typeof(buf->__AST_STR_USED)) -len >= buf->__AST_STR_USED) {
682
		if ((typeof(buf->__AST_STR_USED)) -len >= buf->__AST_STR_USED) {
623
			buf->__AST_STR_USED = 0;
683
			buf->__AST_STR_USED = 0;
624
		} else {
684
		} else {
625
			buf->__AST_STR_USED += len;
685
			buf->__AST_STR_USED += len;
626
		}
686
		}
627
	} else {
687
	} else {
628
		buf->__AST_STR_USED = len;
688
		buf->__AST_STR_USED = len;
629
	}
689
	}
630
	buf->__AST_STR_STR[buf->__AST_STR_USED] = '\0';
690
	buf->__AST_STR_STR[buf->__AST_STR_USED] = '\0';
631
	return buf->__AST_STR_STR;
691
	return buf->__AST_STR_STR;
632
}
692
}
633
)
693
)
634
	
694
	
635
/*
695
/*
636
 * AST_INLINE_API() is a macro that takes a block of code as an argument.
696
 * AST_INLINE_API() is a macro that takes a block of code as an argument.
637
 * Using preprocessor #directives in the argument is not supported by all
697
 * Using preprocessor #directives in the argument is not supported by all
638
 * compilers, and it is a bit of an obfuscation anyways, so avoid it.
698
 * compilers, and it is a bit of an obfuscation anyways, so avoid it.
639
 * As a workaround, define a macro that produces either its argument
699
 * As a workaround, define a macro that produces either its argument
640
 * or nothing, and use that instead of #ifdef/#endif within the
700
 * or nothing, and use that instead of #ifdef/#endif within the
641
 * argument to AST_INLINE_API().
701
 * argument to AST_INLINE_API().
642
 */
702
 */
643
#if defined(DEBUG_THREADLOCALS)
703
#if defined(DEBUG_THREADLOCALS)
644
#define	_DB1(x)	x
704
#define	_DB1(x)	x
645
#else
705
#else
646
#define _DB1(x)
706
#define _DB1(x)
647
#endif
707
#endif
648

    
   
708

   
649
/*!
709
/*!
650
 * Make space in a new string (e.g. to read in data from a file)
710
 * Make space in a new string (e.g. to read in data from a file)
651
 */
711
 */
652
#if (defined(MALLOC_DEBUG) && !defined(STANDALONE))
712
#if (defined(MALLOC_DEBUG) && !defined(STANDALONE))
653
AST_INLINE_API(
713
AST_INLINE_API(
654
int _ast_str_make_space(struct ast_str **buf, size_t new_len, const char *file, int lineno, const char *function),
714
int _ast_str_make_space(struct ast_str **buf, size_t new_len, const char *file, int lineno, const char *function),
655
{
715
{
656
	struct ast_str *old_buf = *buf;
716
	struct ast_str *old_buf = *buf;
657

    
   
717

   
658
	if (new_len <= (*buf)->__AST_STR_LEN) 
718
	if (new_len <= (*buf)->__AST_STR_LEN) 
659
		return 0;	/* success */
719
		return 0;	/* success */
660
	if ((*buf)->__AST_STR_TS == DS_ALLOCA || (*buf)->__AST_STR_TS == DS_STATIC)
720
	if ((*buf)->__AST_STR_TS == DS_ALLOCA || (*buf)->__AST_STR_TS == DS_STATIC)
661
		return -1;	/* cannot extend */
721
		return -1;	/* cannot extend */
662
	*buf = (struct ast_str *)__ast_realloc(*buf, new_len + sizeof(struct ast_str), file, lineno, function);
722
	*buf = (struct ast_str *)__ast_realloc(*buf, new_len + sizeof(struct ast_str), file, lineno, function);
663
	if (*buf == NULL) {
723
	if (*buf == NULL) {
664
		*buf = old_buf;
724
		*buf = old_buf;
665
		return -1;
725
		return -1;
666
	}
726
	}
667
	if ((*buf)->__AST_STR_TS != DS_MALLOC) {
727
	if ((*buf)->__AST_STR_TS != DS_MALLOC) {
668
		pthread_setspecific((*buf)->__AST_STR_TS->key, *buf);
728
		pthread_setspecific((*buf)->__AST_STR_TS->key, *buf);
669
		_DB1(__ast_threadstorage_object_replace(old_buf, *buf, new_len + sizeof(struct ast_str));)
729
		_DB1(__ast_threadstorage_object_replace(old_buf, *buf, new_len + sizeof(struct ast_str));)
670
	}
730
	}
671

    
   
731

   
672
	(*buf)->__AST_STR_LEN = new_len;
732
	(*buf)->__AST_STR_LEN = new_len;
673
	return 0;
733
	return 0;
674
}
734
}
675
)
735
)
676
#define ast_str_make_space(a,b)	_ast_str_make_space(a,b,__FILE__,__LINE__,__PRETTY_FUNCTION__)
736
#define ast_str_make_space(a,b)	_ast_str_make_space(a,b,__FILE__,__LINE__,__PRETTY_FUNCTION__)
677
#else
737
#else
678
AST_INLINE_API(
738
AST_INLINE_API(
679
int ast_str_make_space(struct ast_str **buf, size_t new_len),
739
int ast_str_make_space(struct ast_str **buf, size_t new_len),
680
{
740
{
681
	struct ast_str *old_buf = *buf;
741
	struct ast_str *old_buf = *buf;
682

    
   
742

   
683
	if (new_len <= (*buf)->__AST_STR_LEN) 
743
	if (new_len <= (*buf)->__AST_STR_LEN) 
684
		return 0;	/* success */
744
		return 0;	/* success */
685
	if ((*buf)->__AST_STR_TS == DS_ALLOCA || (*buf)->__AST_STR_TS == DS_STATIC)
745
	if ((*buf)->__AST_STR_TS == DS_ALLOCA || (*buf)->__AST_STR_TS == DS_STATIC)
686
		return -1;	/* cannot extend */
746
		return -1;	/* cannot extend */
687
	*buf = (struct ast_str *)ast_realloc(*buf, new_len + sizeof(struct ast_str));
747
	*buf = (struct ast_str *)ast_realloc(*buf, new_len + sizeof(struct ast_str));
688
	if (*buf == NULL) {
748
	if (*buf == NULL) {
689
		*buf = old_buf;
749
		*buf = old_buf;
690
		return -1;
750
		return -1;
691
	}
751
	}
692
	if ((*buf)->__AST_STR_TS != DS_MALLOC) {
752
	if ((*buf)->__AST_STR_TS != DS_MALLOC) {
693
		pthread_setspecific((*buf)->__AST_STR_TS->key, *buf);
753
		pthread_setspecific((*buf)->__AST_STR_TS->key, *buf);
694
		_DB1(__ast_threadstorage_object_replace(old_buf, *buf, new_len + sizeof(struct ast_str));)
754
		_DB1(__ast_threadstorage_object_replace(old_buf, *buf, new_len + sizeof(struct ast_str));)
695
	}
755
	}
696

    
   
756

   
697
	(*buf)->__AST_STR_LEN = new_len;
757
	(*buf)->__AST_STR_LEN = new_len;
698
	return 0;
758
	return 0;
699
}
759
}
700
)
760
)
701
#endif
761
#endif
702

    
   
762

   
703
AST_INLINE_API(
763
AST_INLINE_API(
704
int ast_str_copy_string(struct ast_str **dst, struct ast_str *src),
764
int ast_str_copy_string(struct ast_str **dst, struct ast_str *src),
705
{
765
{
706

    
   
766

   
707
	/* make sure our destination is large enough */
767
	/* make sure our destination is large enough */
708
	if (src->__AST_STR_USED + 1 > (*dst)->__AST_STR_LEN) {
768
	if (src->__AST_STR_USED + 1 > (*dst)->__AST_STR_LEN) {
709
		if (ast_str_make_space(dst, src->__AST_STR_USED + 1)) {
769
		if (ast_str_make_space(dst, src->__AST_STR_USED + 1)) {
710
			return -1;
770
			return -1;
711
		}
771
		}
712
	}
772
	}
713

    
   
773

   
714
	memcpy((*dst)->__AST_STR_STR, src->__AST_STR_STR, src->__AST_STR_USED + 1);
774
	memcpy((*dst)->__AST_STR_STR, src->__AST_STR_STR, src->__AST_STR_USED + 1);
715
	(*dst)->__AST_STR_USED = src->__AST_STR_USED;
775
	(*dst)->__AST_STR_USED = src->__AST_STR_USED;
716
	return 0;
776
	return 0;
717
}
777
}
718
)
778
)
719

    
   
779

   
720
#define ast_str_alloca(init_len)			\
780
#define ast_str_alloca(init_len)			\
721
	({						\
781
	({						\
722
		struct ast_str *__ast_str_buf;			\
782
		struct ast_str *__ast_str_buf;			\
723
		__ast_str_buf = ast_alloca(sizeof(*__ast_str_buf) + init_len);	\
783
		__ast_str_buf = ast_alloca(sizeof(*__ast_str_buf) + init_len);	\
724
		__ast_str_buf->__AST_STR_LEN = init_len;			\
784
		__ast_str_buf->__AST_STR_LEN = init_len;			\
725
		__ast_str_buf->__AST_STR_USED = 0;				\
785
		__ast_str_buf->__AST_STR_USED = 0;				\
726
		__ast_str_buf->__AST_STR_TS = DS_ALLOCA;			\
786
		__ast_str_buf->__AST_STR_TS = DS_ALLOCA;			\
727
		__ast_str_buf->__AST_STR_STR[0] = '\0';			\
787
		__ast_str_buf->__AST_STR_STR[0] = '\0';			\
728
		(__ast_str_buf);					\
788
		(__ast_str_buf);					\
729
	})
789
	})
730

    
   
790

   
731
/*!
791
/*!
732
 * \brief Retrieve a thread locally stored dynamic string
792
 * \brief Retrieve a thread locally stored dynamic string
733
 *
793
 *
734
 * \param ts This is a pointer to the thread storage structure declared by using
794
 * \param ts This is a pointer to the thread storage structure declared by using
735
 *      the AST_THREADSTORAGE macro.  If declared with 
795
 *      the AST_THREADSTORAGE macro.  If declared with 
736
 *      AST_THREADSTORAGE(my_buf, my_buf_init), then this argument would be 
796
 *      AST_THREADSTORAGE(my_buf, my_buf_init), then this argument would be 
737
 *      (&my_buf).
797
 *      (&my_buf).
738
 * \param init_len This is the initial length of the thread's dynamic string. The
798
 * \param init_len This is the initial length of the thread's dynamic string. The
739
 *      current length may be bigger if previous operations in this thread have
799
 *      current length may be bigger if previous operations in this thread have
740
 *      caused it to increase.
800
 *      caused it to increase.
741
 *
801
 *
742
 * \return This function will return the thread locally stored dynamic string
802
 * \return This function will return the thread locally stored dynamic string
743
 *         associated with the thread storage management variable passed as the
803
 *         associated with the thread storage management variable passed as the
744
 *         first argument.
804
 *         first argument.
745
 *         The result will be NULL in the case of a memory allocation error.
805
 *         The result will be NULL in the case of a memory allocation error.
746
 *
806
 *
747
 * Example usage:
807
 * Example usage:
748
 * \code
808
 * \code
749
 * AST_THREADSTORAGE(my_str, my_str_init);
809
 * AST_THREADSTORAGE(my_str, my_str_init);
750
 * #define MY_STR_INIT_SIZE   128
810
 * #define MY_STR_INIT_SIZE   128
751
 * ...
811
 * ...
752
 * void my_func(const char *fmt, ...)
812
 * void my_func(const char *fmt, ...)
753
 * {
813
 * {
754
 *      struct ast_str *buf;
814
 *      struct ast_str *buf;
755
 *
815
 *
756
 *      if (!(buf = ast_str_thread_get(&my_str, MY_STR_INIT_SIZE)))
816
 *      if (!(buf = ast_str_thread_get(&my_str, MY_STR_INIT_SIZE)))
757
 *           return;
817
 *           return;
758
 *      ...
818
 *      ...
759
 * }
819
 * }
760
 * \endcode
820
 * \endcode
761
 */
821
 */
762
#if !defined(DEBUG_THREADLOCALS)
822
#if !defined(DEBUG_THREADLOCALS)
763
AST_INLINE_API(
823
AST_INLINE_API(
764
struct ast_str *ast_str_thread_get(struct ast_threadstorage *ts,
824
struct ast_str *ast_str_thread_get(struct ast_threadstorage *ts,
765
	size_t init_len),
825
	size_t init_len),
766
{
826
{
767
	struct ast_str *buf;
827
	struct ast_str *buf;
768

    
   
828

   
769
	buf = (struct ast_str *)ast_threadstorage_get(ts, sizeof(*buf) + init_len);
829
	buf = (struct ast_str *)ast_threadstorage_get(ts, sizeof(*buf) + init_len);
770
	if (buf == NULL)
830
	if (buf == NULL)
771
		return NULL;
831
		return NULL;
772

    
   
832

   
773
	if (!buf->__AST_STR_LEN) {
833
	if (!buf->__AST_STR_LEN) {
774
		buf->__AST_STR_LEN = init_len;
834
		buf->__AST_STR_LEN = init_len;
775
		buf->__AST_STR_USED = 0;
835
		buf->__AST_STR_USED = 0;
776
		buf->__AST_STR_TS = ts;
836
		buf->__AST_STR_TS = ts;
777
	}
837
	}
778

    
   
838

   
779
	return buf;
839
	return buf;
780
}
840
}
781
)
841
)
782
#else /* defined(DEBUG_THREADLOCALS) */
842
#else /* defined(DEBUG_THREADLOCALS) */
783
AST_INLINE_API(
843
AST_INLINE_API(
784
struct ast_str *__ast_str_thread_get(struct ast_threadstorage *ts,
844
struct ast_str *__ast_str_thread_get(struct ast_threadstorage *ts,
785
	size_t init_len, const char *file, const char *function, unsigned int line),
845
	size_t init_len, const char *file, const char *function, unsigned int line),
786
{
846
{
787
	struct ast_str *buf;
847
	struct ast_str *buf;
788

    
   
848

   
789
	buf = (struct ast_str *)__ast_threadstorage_get(ts, sizeof(*buf) + init_len, file, function, line);
849
	buf = (struct ast_str *)__ast_threadstorage_get(ts, sizeof(*buf) + init_len, file, function, line);
790
	if (buf == NULL)
850
	if (buf == NULL)
791
		return NULL;
851
		return NULL;
792

    
   
852

   
793
	if (!buf->__AST_STR_LEN) {
853
	if (!buf->__AST_STR_LEN) {
794
		buf->__AST_STR_LEN = init_len;
854
		buf->__AST_STR_LEN = init_len;
795
		buf->__AST_STR_USED = 0;
855
		buf->__AST_STR_USED = 0;
796
		buf->__AST_STR_TS = ts;
856
		buf->__AST_STR_TS = ts;
797
	}
857
	}
798

    
   
858

   
799
	return buf;
859
	return buf;
800
}
860
}
801
)
861
)
802

    
   
862

   
803
#define ast_str_thread_get(ts, init_len) __ast_str_thread_get(ts, init_len, __FILE__, __PRETTY_FUNCTION__, __LINE__)
863
#define ast_str_thread_get(ts, init_len) __ast_str_thread_get(ts, init_len, __FILE__, __PRETTY_FUNCTION__, __LINE__)
804
#endif /* defined(DEBUG_THREADLOCALS) */
864
#endif /* defined(DEBUG_THREADLOCALS) */
805

    
   
865

   
806
/*!
866
/*!
807
 * \brief Error codes from __ast_str_helper()
867
 * \brief Error codes from __ast_str_helper()
808
 * The undelying processing to manipulate dynamic string is done
868
 * The undelying processing to manipulate dynamic string is done
809
 * by __ast_str_helper(), which can return a success or a
869
 * by __ast_str_helper(), which can return a success or a
810
 * permanent failure (e.g. no memory).
870
 * permanent failure (e.g. no memory).
811
 */
871
 */
812
enum {
872
enum {
813
	/*! An error has occurred and the contents of the dynamic string
873
	/*! An error has occurred and the contents of the dynamic string
814
	 *  are undefined */
874
	 *  are undefined */
815
	AST_DYNSTR_BUILD_FAILED = -1,
875
	AST_DYNSTR_BUILD_FAILED = -1,
816
	/*! The buffer size for the dynamic string had to be increased, and
876
	/*! The buffer size for the dynamic string had to be increased, and
817
	 *  __ast_str_helper() needs to be called again after
877
	 *  __ast_str_helper() needs to be called again after
818
	 *  a va_end() and va_start().  This return value is legacy and will
878
	 *  a va_end() and va_start().  This return value is legacy and will
819
	 *  no longer be used.
879
	 *  no longer be used.
820
	 */
880
	 */
821
	AST_DYNSTR_BUILD_RETRY = -2
881
	AST_DYNSTR_BUILD_RETRY = -2
822
};
882
};
823

    
   
883

   
824
/*!
884
/*!
825
 * \brief Core functionality of ast_str_(set|append)_va
885
 * \brief Core functionality of ast_str_(set|append)_va
826
 *
886
 *
827
 * The arguments to this function are the same as those described for
887
 * The arguments to this function are the same as those described for
828
 * ast_str_set_va except for an addition argument, append.
888
 * ast_str_set_va except for an addition argument, append.
829
 * If append is non-zero, this will append to the current string instead of
889
 * If append is non-zero, this will append to the current string instead of
830
 * writing over it.
890
 * writing over it.
831
 *
891
 *
832
 * AST_DYNSTR_BUILD_RETRY is a legacy define.  It should probably never
892
 * AST_DYNSTR_BUILD_RETRY is a legacy define.  It should probably never
833
 * again be used.
893
 * again be used.
834
 *
894
 *
835
 * A return of AST_DYNSTR_BUILD_FAILED indicates a memory allocation error.
895
 * A return of AST_DYNSTR_BUILD_FAILED indicates a memory allocation error.
836
 *
896
 *
837
 * A return value greater than or equal to zero indicates the number of
897
 * A return value greater than or equal to zero indicates the number of
838
 * characters that have been written, not including the terminating '\0'.
898
 * characters that have been written, not including the terminating '\0'.
839
 * In the append case, this only includes the number of characters appended.
899
 * In the append case, this only includes the number of characters appended.
840
 *
900
 *
841
 * \note This function should never need to be called directly.  It should
901
 * \note This function should never need to be called directly.  It should
842
 *       through calling one of the other functions or macros defined in this
902
 *       through calling one of the other functions or macros defined in this
843
 *       file.
903
 *       file.
844
 */
904
 */
845
#if (defined(MALLOC_DEBUG) && !defined(STANDALONE))
905
#if (defined(MALLOC_DEBUG) && !defined(STANDALONE))
846
int __attribute__((format(printf, 4, 0))) __ast_debug_str_helper(struct ast_str **buf, ssize_t max_len,
906
int __attribute__((format(printf, 4, 0))) __ast_debug_str_helper(struct ast_str **buf, ssize_t max_len,
847
							   int append, const char *fmt, va_list ap, const char *file, int lineno, const char *func);
907
							   int append, const char *fmt, va_list ap, const char *file, int lineno, const char *func);
848
#define __ast_str_helper(a,b,c,d,e)	__ast_debug_str_helper(a,b,c,d,e,__FILE__,__LINE__,__PRETTY_FUNCTION__)
908
#define __ast_str_helper(a,b,c,d,e)	__ast_debug_str_helper(a,b,c,d,e,__FILE__,__LINE__,__PRETTY_FUNCTION__)
849
#else
909
#else
850
int __attribute__((format(printf, 4, 0))) __ast_str_helper(struct ast_str **buf, ssize_t max_len,
910
int __attribute__((format(printf, 4, 0))) __ast_str_helper(struct ast_str **buf, ssize_t max_len,
851
							   int append, const char *fmt, va_list ap);
911
							   int append, const char *fmt, va_list ap);
852
#endif
912
#endif
853
char *__ast_str_helper2(struct ast_str **buf, ssize_t max_len,
913
char *__ast_str_helper2(struct ast_str **buf, ssize_t max_len,
854
	const char *src, size_t maxsrc, int append, int escapecommas);
914
	const char *src, size_t maxsrc, int append, int escapecommas);
855

    
   
915

   
856
/*!
916
/*!
857
 * \brief Set a dynamic string from a va_list
917
 * \brief Set a dynamic string from a va_list
858
 *
918
 *
859
 * \param buf This is the address of a pointer to a struct ast_str.
919
 * \param buf This is the address of a pointer to a struct ast_str.
860
 *	If it is retrieved using ast_str_thread_get, the
920
 *	If it is retrieved using ast_str_thread_get, the
861
	struct ast_threadstorage pointer will need to
921
	struct ast_threadstorage pointer will need to
862
 *      be updated in the case that the buffer has to be reallocated to
922
 *      be updated in the case that the buffer has to be reallocated to
863
 *      accommodate a longer string than what it currently has space for.
923
 *      accommodate a longer string than what it currently has space for.
864
 * \param max_len This is the maximum length to allow the string buffer to grow
924
 * \param max_len This is the maximum length to allow the string buffer to grow
865
 *      to.  If this is set to 0, then there is no maximum length.
925
 *      to.  If this is set to 0, then there is no maximum length.
866
 * \param fmt This is the format string (printf style)
926
 * \param fmt This is the format string (printf style)
867
 * \param ap This is the va_list
927
 * \param ap This is the va_list
868
 *
928
 *
869
 * \return The return value of this function is the same as that of the printf
929
 * \return The return value of this function is the same as that of the printf
870
 *         family of functions.
930
 *         family of functions.
871
 *
931
 *
872
 * Example usage (the first part is only for thread-local storage)
932
 * Example usage (the first part is only for thread-local storage)
873
 * \code
933
 * \code
874
 * AST_THREADSTORAGE(my_str, my_str_init);
934
 * AST_THREADSTORAGE(my_str, my_str_init);
875
 * #define MY_STR_INIT_SIZE   128
935
 * #define MY_STR_INIT_SIZE   128
876
 * ...
936
 * ...
877
 * void my_func(const char *fmt, ...)
937
 * void my_func(const char *fmt, ...)
878
 * {
938
 * {
879
 *      struct ast_str *buf;
939
 *      struct ast_str *buf;
880
 *      va_list ap;
940
 *      va_list ap;
881
 *
941
 *
882
 *      if (!(buf = ast_str_thread_get(&my_str, MY_STR_INIT_SIZE)))
942
 *      if (!(buf = ast_str_thread_get(&my_str, MY_STR_INIT_SIZE)))
883
 *           return;
943
 *           return;
884
 *      ...
944
 *      ...
885
 *      va_start(fmt, ap);
945
 *      va_start(fmt, ap);
886
 *      ast_str_set_va(&buf, 0, fmt, ap);
946
 *      ast_str_set_va(&buf, 0, fmt, ap);
887
 *      va_end(ap);
947
 *      va_end(ap);
888
 * 
948
 * 
889
 *      printf("This is the string we just built: %s\n", buf->str);
949
 *      printf("This is the string we just built: %s\n", buf->str);
890
 *      ...
950
 *      ...
891
 * }
951
 * }
892
 * \endcode
952
 * \endcode
893
 *
953
 *
894
 * \note Care should be taken when using this function. The function can
954
 * \note Care should be taken when using this function. The function can
895
 * result in reallocating the ast_str. If a pointer to the ast_str is passed
955
 * result in reallocating the ast_str. If a pointer to the ast_str is passed
896
 * by value to a function that calls ast_str_set_va(), then the original ast_str
956
 * by value to a function that calls ast_str_set_va(), then the original ast_str
897
 * pointer may be invalidated due to a reallocation.
957
 * pointer may be invalidated due to a reallocation.
898
 *
958
 *
899
 */
959
 */
900
AST_INLINE_API(int __attribute__((format(printf, 3, 0))) ast_str_set_va(struct ast_str **buf, ssize_t max_len, const char *fmt, va_list ap),
960
AST_INLINE_API(int __attribute__((format(printf, 3, 0))) ast_str_set_va(struct ast_str **buf, ssize_t max_len, const char *fmt, va_list ap),
901
{
961
{
902
	return __ast_str_helper(buf, max_len, 0, fmt, ap);
962
	return __ast_str_helper(buf, max_len, 0, fmt, ap);
903
}
963
}
904
)
964
)
905

    
   
965

   
906
/*!
966
/*!
907
 * \brief Append to a dynamic string using a va_list
967
 * \brief Append to a dynamic string using a va_list
908
 *
968
 *
909
 * Same as ast_str_set_va(), but append to the current content.
969
 * Same as ast_str_set_va(), but append to the current content.
910
 *
970
 *
911
 * \note Care should be taken when using this function. The function can
971
 * \note Care should be taken when using this function. The function can
912
 * result in reallocating the ast_str. If a pointer to the ast_str is passed
972
 * result in reallocating the ast_str. If a pointer to the ast_str is passed
913
 * by value to a function that calls ast_str_append_va(), then the original ast_str
973
 * by value to a function that calls ast_str_append_va(), then the original ast_str
914
 * pointer may be invalidated due to a reallocation.
974
 * pointer may be invalidated due to a reallocation.
915
 *
975
 *
916
 * \param buf, max_len, fmt, ap
976
 * \param buf, max_len, fmt, ap
917
 */
977
 */
918
AST_INLINE_API(int __attribute__((format(printf, 3, 0))) ast_str_append_va(struct ast_str **buf, ssize_t max_len, const char *fmt, va_list ap),
978
AST_INLINE_API(int __attribute__((format(printf, 3, 0))) ast_str_append_va(struct ast_str **buf, ssize_t max_len, const char *fmt, va_list ap),
919
{
979
{
920
	return __ast_str_helper(buf, max_len, 1, fmt, ap);
980
	return __ast_str_helper(buf, max_len, 1, fmt, ap);
921
}
981
}
922
)
982
)
923

    
   
983

   
924
/*!\brief Set a dynamic string to a non-NULL terminated substring. */
984
/*!\brief Set a dynamic string to a non-NULL terminated substring. */
925
AST_INLINE_API(char *ast_str_set_substr(struct ast_str **buf, ssize_t maxlen, const char *src, size_t maxsrc),
985
AST_INLINE_API(char *ast_str_set_substr(struct ast_str **buf, ssize_t maxlen, const char *src, size_t maxsrc),
926
{
986
{
927
	return __ast_str_helper2(buf, maxlen, src, maxsrc, 0, 0);
987
	return __ast_str_helper2(buf, maxlen, src, maxsrc, 0, 0);
928
}
988
}
929
)
989
)
930

    
   
990

   
931
/*!\brief Append a non-NULL terminated substring to the end of a dynamic string. */
991
/*!\brief Append a non-NULL terminated substring to the end of a dynamic string. */
932
AST_INLINE_API(char *ast_str_append_substr(struct ast_str **buf, ssize_t maxlen, const char *src, size_t maxsrc),
992
AST_INLINE_API(char *ast_str_append_substr(struct ast_str **buf, ssize_t maxlen, const char *src, size_t maxsrc),
933
{
993
{
934
	return __ast_str_helper2(buf, maxlen, src, maxsrc, 1, 0);
994
	return __ast_str_helper2(buf, maxlen, src, maxsrc, 1, 0);
935
}
995
}
936
)
996
)
937

    
   
997

   
938
/*!\brief Set a dynamic string to a non-NULL terminated substring, with escaping of commas. */
998
/*!\brief Set a dynamic string to a non-NULL terminated substring, with escaping of commas. */
939
AST_INLINE_API(char *ast_str_set_escapecommas(struct ast_str **buf, ssize_t maxlen, const char *src, size_t maxsrc),
999
AST_INLINE_API(char *ast_str_set_escapecommas(struct ast_str **buf, ssize_t maxlen, const char *src, size_t maxsrc),
940
{
1000
{
941
	return __ast_str_helper2(buf, maxlen, src, maxsrc, 0, 1);
1001
	return __ast_str_helper2(buf, maxlen, src, maxsrc, 0, 1);
942
}
1002
}
943
)
1003
)
944

    
   
1004

   
945
/*!\brief Append a non-NULL terminated substring to the end of a dynamic string, with escaping of commas. */
1005
/*!\brief Append a non-NULL terminated substring to the end of a dynamic string, with escaping of commas. */
946
AST_INLINE_API(char *ast_str_append_escapecommas(struct ast_str **buf, ssize_t maxlen, const char *src, size_t maxsrc),
1006
AST_INLINE_API(char *ast_str_append_escapecommas(struct ast_str **buf, ssize_t maxlen, const char *src, size_t maxsrc),
947
{
1007
{
948
	return __ast_str_helper2(buf, maxlen, src, maxsrc, 1, 1);
1008
	return __ast_str_helper2(buf, maxlen, src, maxsrc, 1, 1);
949
}
1009
}
950
)
1010
)
951

    
   
1011

   
952
/*!
1012
/*!
953
 * \brief Set a dynamic string using variable arguments
1013
 * \brief Set a dynamic string using variable arguments
954
 *
1014
 *
955
 * \note Care should be taken when using this function. The function can
1015
 * \note Care should be taken when using this function. The function can
956
 * result in reallocating the ast_str. If a pointer to the ast_str is passed
1016
 * result in reallocating the ast_str. If a pointer to the ast_str is passed
957
 * by value to a function that calls ast_str_set(), then the original ast_str
1017
 * by value to a function that calls ast_str_set(), then the original ast_str
958
 * pointer may be invalidated due to a reallocation.
1018
 * pointer may be invalidated due to a reallocation.
959
 *
1019
 *
960
 * \param buf This is the address of a pointer to a struct ast_str which should
1020
 * \param buf This is the address of a pointer to a struct ast_str which should
961
 *      have been retrieved using ast_str_thread_get.  It will need to
1021
 *      have been retrieved using ast_str_thread_get.  It will need to
962
 *      be updated in the case that the buffer has to be reallocated to
1022
 *      be updated in the case that the buffer has to be reallocated to
963
 *      accomodate a longer string than what it currently has space for.
1023
 *      accomodate a longer string than what it currently has space for.
964
 * \param max_len This is the maximum length to allow the string buffer to grow
1024
 * \param max_len This is the maximum length to allow the string buffer to grow
965
 *      to.  If this is set to 0, then there is no maximum length.
1025
 *      to.  If this is set to 0, then there is no maximum length.
966
 *	If set to -1, we are bound to the current maximum length.
1026
 *	If set to -1, we are bound to the current maximum length.
967
 * \param fmt This is the format string (printf style)
1027
 * \param fmt This is the format string (printf style)
968
 *
1028
 *
969
 * \return The return value of this function is the same as that of the printf
1029
 * \return The return value of this function is the same as that of the printf
970
 *         family of functions.
1030
 *         family of functions.
971
 *
1031
 *
972
 * All the rest is the same as ast_str_set_va()
1032
 * All the rest is the same as ast_str_set_va()
973
 */
1033
 */
974
AST_INLINE_API(
1034
AST_INLINE_API(
975
int __attribute__((format(printf, 3, 4))) ast_str_set(
1035
int __attribute__((format(printf, 3, 4))) ast_str_set(
976
	struct ast_str **buf, ssize_t max_len, const char *fmt, ...),
1036
	struct ast_str **buf, ssize_t max_len, const char *fmt, ...),
977
{
1037
{
978
	int res;
1038
	int res;
979
	va_list ap;
1039
	va_list ap;
980

    
   
1040

   
981
	va_start(ap, fmt);
1041
	va_start(ap, fmt);
982
	res = ast_str_set_va(buf, max_len, fmt, ap);
1042
	res = ast_str_set_va(buf, max_len, fmt, ap);
983
	va_end(ap);
1043
	va_end(ap);
984

    
   
1044

   
985
	return res;
1045
	return res;
986
}
1046
}
987
)
1047
)
988

    
   
1048

   
989
/*!
1049
/*!
990
 * \brief Append to a thread local dynamic string
1050
 * \brief Append to a thread local dynamic string
991
 *
1051
 *
992
 * \note Care should be taken when using this function. The function can
1052
 * \note Care should be taken when using this function. The function can
993
 * result in reallocating the ast_str. If a pointer to the ast_str is passed
1053
 * result in reallocating the ast_str. If a pointer to the ast_str is passed
994
 * by value to a function that calls ast_str_append(), then the original ast_str
1054
 * by value to a function that calls ast_str_append(), then the original ast_str
995
 * pointer may be invalidated due to a reallocation.
1055
 * pointer may be invalidated due to a reallocation.
996
 *
1056
 *
997
 * The arguments, return values, and usage of this function are the same as
1057
 * The arguments, return values, and usage of this function are the same as
998
 * ast_str_set(), but the new data is appended to the current value.
1058
 * ast_str_set(), but the new data is appended to the current value.
999
 */
1059
 */
1000
AST_INLINE_API(
1060
AST_INLINE_API(
1001
int __attribute__((format(printf, 3, 4))) ast_str_append(
1061
int __attribute__((format(printf, 3, 4))) ast_str_append(
1002
	struct ast_str **buf, ssize_t max_len, const char *fmt, ...),
1062
	struct ast_str **buf, ssize_t max_len, const char *fmt, ...),
1003
{
1063
{
1004
	int res;
1064
	int res;
1005
	va_list ap;
1065
	va_list ap;
1006

    
   
1066

   
1007
	va_start(ap, fmt);
1067
	va_start(ap, fmt);
1008
	res = ast_str_append_va(buf, max_len, fmt, ap);
1068
	res = ast_str_append_va(buf, max_len, fmt, ap);
1009
	va_end(ap);
1069
	va_end(ap);
1010

    
   
1070

   
1011
	return res;
1071
	return res;
1012
}
1072
}
1013
)
1073
)
1014

    
   
1074

   
1015
/*!
1075
/*!
1016
 * \brief Check if a string is only digits
1076
 * \brief Check if a string is only digits
1017
 *
1077
 *
1018
 * \retval 1 The string contains only digits
1078
 * \retval 1 The string contains only digits
1019
 * \retval 0 The string contains non-digit characters
1079
 * \retval 0 The string contains non-digit characters
1020
 */
1080
 */
1021
AST_INLINE_API(
1081
AST_INLINE_API(
1022
int ast_check_digits(const char *arg),
1082
int ast_check_digits(const char *arg),
1023
{
1083
{
1024
	while (*arg) {
1084
	while (*arg) {
1025
		if (*arg < '0' || *arg > '9') {
1085
		if (*arg < '0' || *arg > '9') {
1026
			return 0;
1086
			return 0;
1027
		}
1087
		}
1028
		arg++;
1088
		arg++;
1029
	}
1089
	}
1030
	return 1;
1090
	return 1;
1031
}
1091
}
1032
)
1092
)
1033

    
   
1093

   
1034
/*!
1094
/*!
1035
 * \brief Convert the tech portion of a device string to upper case
1095
 * \brief Convert the tech portion of a device string to upper case
1036
 *
1096
 *
1037
 * \retval dev_str Returns the char* passed in for convenience
1097
 * \retval dev_str Returns the char* passed in for convenience
1038
 */
1098
 */
1039
AST_INLINE_API(
1099
AST_INLINE_API(
1040
char *ast_tech_to_upper(char *dev_str),
1100
char *ast_tech_to_upper(char *dev_str),
1041
{
1101
{
1042
	char *pos;
1102
	char *pos;
1043
	if (!dev_str || !strchr(dev_str, '/')) {
1103
	if (!dev_str || !strchr(dev_str, '/')) {
1044
		return dev_str;
1104
		return dev_str;
1045
	}
1105
	}
1046

    
   
1106

   
1047
	for (pos = dev_str; *pos && *pos != '/'; pos++) {
1107
	for (pos = dev_str; *pos && *pos != '/'; pos++) {
1048
		*pos = toupper(*pos);
1108
		*pos = toupper(*pos);
1049
	}
1109
	}
1050
	return dev_str;
1110
	return dev_str;
1051
}
1111
}
1052
)
1112
)
1053

    
   
1113

   
1054
/*!
1114
/*!
1055
 * \brief Compute a hash value on a string
1115
 * \brief Compute a hash value on a string
1056
 *
1116
 *
1057
 * This famous hash algorithm was written by Dan Bernstein and is
1117
 * This famous hash algorithm was written by Dan Bernstein and is
1058
 * commonly used.
1118
 * commonly used.
1059
 *
1119
 *
1060
 * http://www.cse.yorku.ca/~oz/hash.html
1120
 * http://www.cse.yorku.ca/~oz/hash.html
1061
 */
1121
 */
1062
static force_inline int attribute_pure ast_str_hash(const char *str)
1122
static force_inline int attribute_pure ast_str_hash(const char *str)
1063
{
1123
{
1064
	int hash = 5381;
1124
	int hash = 5381;
1065

    
   
1125

   
1066
	while (*str)
1126
	while (*str)
1067
		hash = hash * 33 ^ *str++;
1127
		hash = hash * 33 ^ *str++;
1068

    
   
1128

   
1069
	return abs(hash);
1129
	return abs(hash);
1070
}
1130
}
1071

    
   
1131

   
1072
/*!
1132
/*!
1073
 * \brief Compute a hash value on a string
1133
 * \brief Compute a hash value on a string
1074
 *
1134
 *
1075
 * \param[in] str The string to add to the hash
1135
 * \param[in] str The string to add to the hash
1076
 * \param[in] hash The hash value to add to
1136
 * \param[in] hash The hash value to add to
1077
 * 
1137
 * 
1078
 * \details
1138
 * \details
1079
 * This version of the function is for when you need to compute a
1139
 * This version of the function is for when you need to compute a
1080
 * string hash of more than one string.
1140
 * string hash of more than one string.
1081
 *
1141
 *
1082
 * This famous hash algorithm was written by Dan Bernstein and is
1142
 * This famous hash algorithm was written by Dan Bernstein and is
1083
 * commonly used.
1143
 * commonly used.
1084
 *
1144
 *
1085
 * \sa http://www.cse.yorku.ca/~oz/hash.html
1145
 * \sa http://www.cse.yorku.ca/~oz/hash.html
1086
 */
1146
 */
1087
static force_inline int ast_str_hash_add(const char *str, int hash)
1147
static force_inline int ast_str_hash_add(const char *str, int hash)
1088
{
1148
{
1089
	while (*str)
1149
	while (*str)
1090
		hash = hash * 33 ^ *str++;
1150
		hash = hash * 33 ^ *str++;
1091

    
   
1151

   
1092
	return abs(hash);
1152
	return abs(hash);
1093
}
1153
}
1094

    
   
1154

   
1095
/*!
1155
/*!
1096
 * \brief Compute a hash value on a case-insensitive string
1156
 * \brief Compute a hash value on a case-insensitive string
1097
 *
1157
 *
1098
 * Uses the same hash algorithm as ast_str_hash, but converts
1158
 * Uses the same hash algorithm as ast_str_hash, but converts
1099
 * all characters to lowercase prior to computing a hash. This
1159
 * all characters to lowercase prior to computing a hash. This
1100
 * allows for easy case-insensitive lookups in a hash table.
1160
 * allows for easy case-insensitive lookups in a hash table.
1101
 */
1161
 */
1102
static force_inline int attribute_pure ast_str_case_hash(const char *str)
1162
static force_inline int attribute_pure ast_str_case_hash(const char *str)
1103
{
1163
{
1104
	int hash = 5381;
1164
	int hash = 5381;
1105

    
   
1165

   
1106
	while (*str) {
1166
	while (*str) {
1107
		hash = hash * 33 ^ tolower(*str++);
1167
		hash = hash * 33 ^ tolower(*str++);
1108
	}
1168
	}
1109

    
   
1169

   
1110
	return abs(hash);
1170
	return abs(hash);
1111
}
1171
}
1112

    
   
1172

   
1113
/*!
1173
/*!
1114
 * \brief Convert a string to all lower-case
1174
 * \brief Convert a string to all lower-case
1115
 *
1175
 *
1116
 * \param str The string to be converted to lower case
1176
 * \param str The string to be converted to lower case
1117
 *
1177
 *
1118
 * \retval str for convenience
1178
 * \retval str for convenience
1119
 */
1179
 */
1120
static force_inline char *attribute_pure ast_str_to_lower(char *str)
1180
static force_inline char *attribute_pure ast_str_to_lower(char *str)
1121
{
1181
{
1122
	char *str_orig = str;
1182
	char *str_orig = str;
1123
	if (!str) {
1183
	if (!str) {
1124
		return str;
1184
		return str;
1125
	}
1185
	}
1126

    
   
1186

   
1127
	for (; *str; ++str) {
1187
	for (; *str; ++str) {
1128
		*str = tolower(*str);
1188
		*str = tolower(*str);
1129
	}
1189
	}
1130

    
   
1190

   
1131
	return str_orig;
1191
	return str_orig;
1132
}
1192
}
1133

    
   
1193

   
1134
/*!
1194
/*!
1135
 * \brief Convert a string to all upper-case
1195
 * \brief Convert a string to all upper-case
1136
 *
1196
 *
1137
 * \param str The string to be converted to upper case
1197
 * \param str The string to be converted to upper case
1138
 *
1198
 *
1139
 * \retval str for convenience
1199
 * \retval str for convenience
1140
 */
1200
 */
1141
static force_inline char *attribute_pure ast_str_to_upper(char *str)
1201
static force_inline char *attribute_pure ast_str_to_upper(char *str)
1142
{
1202
{
1143
	char *str_orig = str;
1203
	char *str_orig = str;
1144
	if (!str) {
1204
	if (!str) {
1145
		return str;
1205
		return str;
1146
	}
1206
	}
1147

    
   
1207

   
1148
	for (; *str; ++str) {
1208
	for (; *str; ++str) {
1149
		*str = toupper(*str);
1209
		*str = toupper(*str);
1150
	}
1210
	}
1151

    
   
1211

   
1152
	return str_orig;
1212
	return str_orig;
1153
}
1213
}
1154

    
   
1214

   
1155
/*!
1215
/*!
1156
 * \since 12
1216
 * \since 12
1157
 * \brief Allocates a hash container for bare strings
1217
 * \brief Allocates a hash container for bare strings
1158
 *
1218
 *
1159
 * \param buckets The number of buckets to use for the hash container
1219
 * \param buckets The number of buckets to use for the hash container
1160
 *
1220
 *
1161
 * \retval AO2 container for strings
1221
 * \retval AO2 container for strings
1162
 * \retval NULL if allocation failed
1222
 * \retval NULL if allocation failed
1163
 */
1223
 */
1164
#define ast_str_container_alloc(buckets) ast_str_container_alloc_options(AO2_ALLOC_OPT_LOCK_MUTEX, buckets)
1224
#define ast_str_container_alloc(buckets) ast_str_container_alloc_options(AO2_ALLOC_OPT_LOCK_MUTEX, buckets)
1165

    
   
1225

   
1166
/*!
1226
/*!
1167
 * \since 12
1227
 * \since 12
1168
 * \brief Allocates a hash container for bare strings
1228
 * \brief Allocates a hash container for bare strings
1169
 *
1229
 *
1170
 * \param opts Options to be provided to the container
1230
 * \param opts Options to be provided to the container
1171
 * \param buckets The number of buckets to use for the hash container
1231
 * \param buckets The number of buckets to use for the hash container
1172
 *
1232
 *
1173
 * \retval AO2 container for strings
1233
 * \retval AO2 container for strings
1174
 * \retval NULL if allocation failed
1234
 * \retval NULL if allocation failed
1175
 */
1235
 */
1176
struct ao2_container *ast_str_container_alloc_options(enum ao2_container_opts opts, int buckets);
1236
struct ao2_container *ast_str_container_alloc_options(enum ao2_container_opts opts, int buckets);
1177

    
   
1237

   
1178
/*!
1238
/*!
1179
 * \since 12
1239
 * \since 12
1180
 * \brief Adds a string to a string container allocated by ast_str_container_alloc
1240
 * \brief Adds a string to a string container allocated by ast_str_container_alloc
1181
 *
1241
 *
1182
 * \param str_container The container to which to add a string
1242
 * \param str_container The container to which to add a string
1183
 * \param add The string to add to the container
1243
 * \param add The string to add to the container
1184
 *
1244
 *
1185
 * \retval zero on success
1245
 * \retval zero on success
1186
 * \retval non-zero if the operation failed
1246
 * \retval non-zero if the operation failed
1187
 */
1247
 */
1188
int ast_str_container_add(struct ao2_container *str_container, const char *add);
1248
int ast_str_container_add(struct ao2_container *str_container, const char *add);
1189

    
   
1249

   
1190
/*!
1250
/*!
1191
 * \since 12
1251
 * \since 12
1192
 * \brief Removes a string from a string container allocated by ast_str_container_alloc
1252
 * \brief Removes a string from a string container allocated by ast_str_container_alloc
1193
 *
1253
 *
1194
 * \param str_container The container from which to remove a string
1254
 * \param str_container The container from which to remove a string
1195
 * \param remove The string to remove from the container
1255
 * \param remove The string to remove from the container
1196
 */
1256
 */
1197
void ast_str_container_remove(struct ao2_container *str_container, const char *remove);
1257
void ast_str_container_remove(struct ao2_container *str_container, const char *remove);
1198

    
   
1258

   
1199
#endif /* _ASTERISK_STRINGS_H */
1259
#endif /* _ASTERISK_STRINGS_H */
branches/12/main/utils.c
Revision 422963 New Change
 
branches/12/tests/test_strings.c
Revision 422963 New Change
 
  1. branches/12/include/asterisk/strings.h: Loading...
  2. branches/12/main/utils.c: Loading...
  3. branches/12/tests/test_strings.c: Loading...

https://reviewboard.asterisk.org/ runs on a server provided by Digium, Inc. and uses bandwidth donated to the open source Asterisk community by API Digital Communications in Huntsville, AL USA.
Please report problems with this site to asteriskteam@digium.com.