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 2

This is not the most recent revision of the diff. The latest diff is revision 4. See what's changed.

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.

    
   
260

   

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

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

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

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

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

    
   
266

   

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

    
   
268
  recursively using different separators on the same storage.

    
   
269

   

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

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

    
   
272

   

    
   
273
  Examples:

    
   
274
  \code

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

    
   
276
	char *token, *token2, *token3;

    
   
277

   

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

    
   
279
		// 1st token will be aaa=def

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

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

    
   
282
			// 1st token2 will be ghi

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

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

    
   
285
				// 1st token3 will be zzz=yyy

    
   
286
				// 2nd token3 will be 456

    
   
287
				// and so on

    
   
288
			}

    
   
289
		}

    
   
290
		// 3rd token will be jkl

    
   
291
	}

    
   
292

   

    
   
293
  \endcode

    
   
294
 */

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

    
   
296

   

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

    
   
303

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

    
   
310

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

    
   
317

   
259
  This is similar to \a strncpy, with two important differences:
318
  This is similar to \a strncpy, with two important differences:
260
    - the destination buffer will \b always be null-terminated
319
    - the destination buffer will \b always be null-terminated
261
    - the destination buffer is not filled with zeros past the copied string length
320
    - 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
321
  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
322
  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
323
  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.
324
  to be initialized to zeroes prior to calling this function.
266
*/
325
*/
267
AST_INLINE_API(
326
AST_INLINE_API(
268
void ast_copy_string(char *dst, const char *src, size_t size),
327
void ast_copy_string(char *dst, const char *src, size_t size),
269
{
328
{
270
	while (*src && size) {
329
	while (*src && size) {
271
		*dst++ = *src++;
330
		*dst++ = *src++;
272
		size--;
331
		size--;
273
	}
332
	}
274
	if (__builtin_expect(!size, 0))
333
	if (__builtin_expect(!size, 0))
275
		dst--;
334
		dst--;
276
	*dst = '\0';
335
	*dst = '\0';
277
}
336
}
278
)
337
)
279

    
   
338

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

    
   
343

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

    
   
346

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

    
   
354

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

    
   
360

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

    
   
368

   
310
/*!
369
/*!
311
 * \brief Make sure something is true.
370
 * \brief Make sure something is true.
312
 * Determine if a string containing a boolean value is "true".
371
 * 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.
372
 * 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".
373
 * It checks to see if the string is "yes", "true", "y", "t", "on" or "1".
315
 *
374
 *
316
 * \retval 0 if val is a NULL pointer.
375
 * \retval 0 if val is a NULL pointer.
317
 * \retval -1 if "true".
376
 * \retval -1 if "true".
318
 * \retval 0 otherwise.
377
 * \retval 0 otherwise.
319
 */
378
 */
320
int attribute_pure ast_true(const char *val);
379
int attribute_pure ast_true(const char *val);
321

    
   
380

   
322
/*! 
381
/*! 
323
 * \brief Make sure something is false.
382
 * \brief Make sure something is false.
324
 * Determine if a string containing a boolean value is "false".
383
 * 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.  
384
 * 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".  
385
 * It checks to see if the string is "no", "false", "n", "f", "off" or "0".  
327
 *
386
 *
328
 * \retval 0 if val is a NULL pointer.
387
 * \retval 0 if val is a NULL pointer.
329
 * \retval -1 if "true".
388
 * \retval -1 if "true".
330
 * \retval 0 otherwise.
389
 * \retval 0 otherwise.
331
 */
390
 */
332
int attribute_pure ast_false(const char *val);
391
int attribute_pure ast_false(const char *val);
333

    
   
392

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

    
   
408

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

    
   
420

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

    
   
434

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

    
   
446

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

    
   
457

   
399
/*
458
/*
400
  \brief Parse a time (float) string.
459
  \brief Parse a time (float) string.
401
  \param src String to parse
460
  \param src String to parse
402
  \param dst Destination
461
  \param dst Destination
403
  \param _default Value to use if the string does not contain a valid time
462
  \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)
463
  \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
464
  \return zero on success, non-zero on failure
406
*/
465
*/
407
int ast_get_timeval(const char *src, struct timeval *tv, struct timeval _default, int *consumed);
466
int ast_get_timeval(const char *src, struct timeval *tv, struct timeval _default, int *consumed);
408

    
   
467

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

    
   
512

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

    
   
529

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

    
   
544

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

    
   
563

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

    
   
567

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

    
   
571

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

    
   
580

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

    
   
584

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

    
   
588

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

    
   
593

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

    
   
608

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

    
   
618

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

    
   
633

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

    
   
643

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

    
   
654

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

    
   
669

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

    
   
707

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

    
   
716

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

    
   
730

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

    
   
741

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

    
   
755

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

    
   
761

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

    
   
765

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

    
   
772

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

    
   
778

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

    
   
789

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

    
   
827

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

    
   
831

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

    
   
837

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

    
   
847

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

    
   
851

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

    
   
857

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

    
   
861

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

    
   
864

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

    
   
882

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

    
   
914

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

    
   
964

   
906
/*!
965
/*!
907
 * \brief Append to a dynamic string using a va_list
966
 * \brief Append to a dynamic string using a va_list
908
 *
967
 *
909
 * Same as ast_str_set_va(), but append to the current content.
968
 * Same as ast_str_set_va(), but append to the current content.
910
 *
969
 *
911
 * \note Care should be taken when using this function. The function can
970
 * \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
971
 * 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
972
 * 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.
973
 * pointer may be invalidated due to a reallocation.
915
 *
974
 *
916
 * \param buf, max_len, fmt, ap
975
 * \param buf, max_len, fmt, ap
917
 */
976
 */
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),
977
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
{
978
{
920
	return __ast_str_helper(buf, max_len, 1, fmt, ap);
979
	return __ast_str_helper(buf, max_len, 1, fmt, ap);
921
}
980
}
922
)
981
)
923

    
   
982

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

    
   
989

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

    
   
996

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

    
   
1003

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

    
   
1010

   
952
/*!
1011
/*!
953
 * \brief Set a dynamic string using variable arguments
1012
 * \brief Set a dynamic string using variable arguments
954
 *
1013
 *
955
 * \note Care should be taken when using this function. The function can
1014
 * \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
1015
 * 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
1016
 * by value to a function that calls ast_str_set(), then the original ast_str
958
 * pointer may be invalidated due to a reallocation.
1017
 * pointer may be invalidated due to a reallocation.
959
 *
1018
 *
960
 * \param buf This is the address of a pointer to a struct ast_str which should
1019
 * \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
1020
 *      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
1021
 *      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.
1022
 *      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
1023
 * \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.
1024
 *      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.
1025
 *	If set to -1, we are bound to the current maximum length.
967
 * \param fmt This is the format string (printf style)
1026
 * \param fmt This is the format string (printf style)
968
 *
1027
 *
969
 * \return The return value of this function is the same as that of the printf
1028
 * \return The return value of this function is the same as that of the printf
970
 *         family of functions.
1029
 *         family of functions.
971
 *
1030
 *
972
 * All the rest is the same as ast_str_set_va()
1031
 * All the rest is the same as ast_str_set_va()
973
 */
1032
 */
974
AST_INLINE_API(
1033
AST_INLINE_API(
975
int __attribute__((format(printf, 3, 4))) ast_str_set(
1034
int __attribute__((format(printf, 3, 4))) ast_str_set(
976
	struct ast_str **buf, ssize_t max_len, const char *fmt, ...),
1035
	struct ast_str **buf, ssize_t max_len, const char *fmt, ...),
977
{
1036
{
978
	int res;
1037
	int res;
979
	va_list ap;
1038
	va_list ap;
980

    
   
1039

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

    
   
1043

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

    
   
1047

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

    
   
1065

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

    
   
1069

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

    
   
1073

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

    
   
1092

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

    
   
1105

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

    
   
1112

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

    
   
1124

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

    
   
1127

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

    
   
1130

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

    
   
1150

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

    
   
1153

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

    
   
1164

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

    
   
1168

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

    
   
1171

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

    
   
1185

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

    
   
1189

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

    
   
1192

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

    
   
1206

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

    
   
1210

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

    
   
1213

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

    
   
1224

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

    
   
1236

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

    
   
1248

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

    
   
1257

   
1199
#endif /* _ASTERISK_STRINGS_H */
1258
#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.