Apache Portable Runtime
apr_cstr.h
Go to the documentation of this file.
1 /* ====================================================================
2  * Licensed to the Apache Software Foundation (ASF) under one
3  * or more contributor license agreements. See the NOTICE file
4  * distributed with this work for additional information
5  * regarding copyright ownership. The ASF licenses this file
6  * to you under the Apache License, Version 2.0 (the
7  * "License"); you may not use this file except in compliance
8  * with the License. You may obtain a copy of the License at
9  *
10  * http://www.apache.org/licenses/LICENSE-2.0
11  *
12  * Unless required by applicable law or agreed to in writing,
13  * software distributed under the License is distributed on an
14  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15  * KIND, either express or implied. See the License for the
16  * specific language governing permissions and limitations
17  * under the License.
18  * ====================================================================
19  */
20 
21 /**
22  * @file apr_cstr.h
23  * @brief C string goodies.
24  */
25 
26 #ifndef APR_CSTR_H
27 #define APR_CSTR_H
28 
29 #include <apr.h> /* for apr_size_t */
30 #include <apr_pools.h> /* for apr_pool_t */
31 #include <apr_tables.h> /* for apr_array_header_t */
32 
33 #ifdef __cplusplus
34 extern "C" {
35 #endif /* __cplusplus */
36 
37 /**
38  * @defgroup apr_cstr C (POSIX) locale string functions
39  * @ingroup apr_strings
40  *
41  * The apr_cstr_* functions provide traditional C char * string text handling,
42  * and notabilty they treat all text in the C (a.k.a. POSIX) locale using the
43  * minimal POSIX character set, represented in either ASCII or a corresponding
44  * EBCDIC subset.
45  *
46  * Character values outside of that set are treated as opaque bytes, and all
47  * multi-byte character sequences are handled as individual distinct octets.
48  *
49  * Multi-byte characters sequences whose octets fall in the ASCII range cause
50  * unexpected results, such as in the ISO-2022-JP code page where ASCII octets
51  * occur within both shift-state and multibyte sequences.
52  *
53  * In the case of the UTF-8 encoding, all multibyte characters all fall outside
54  * of the C/POSIX range of characters, so these functions are generally safe
55  * to use on UTF-8 strings. The programmer must be aware that each octet may
56  * not represent a distinct printable character in such encodings.
57  *
58  * The standard C99/POSIX string functions, rather than apr_cstr, should be
59  * used in all cases where the current locale and encoding of the text is
60  * significant.
61  * @{
62  */
63 
64 
65 /** Divide @a input into substrings, interpreting any char from @a sep
66  * as a token separator.
67  *
68  * Return an array of copies of those substrings (plain const char*),
69  * allocating both the array and the copies in @a pool.
70  *
71  * None of the elements added to the array contain any of the
72  * characters in @a sep_chars, and none of the new elements are empty
73  * (thus, it is possible that the returned array will have length
74  * zero).
75  *
76  * If @a chop_whitespace is TRUE, then remove leading and trailing
77  * whitespace from the returned strings.
78  *
79  * @since New in 1.6
80  */
81 apr_array_header_t * apr_cstr_split(const char *input,
82  const char *sep_chars,
83  int chop_whitespace,
84  apr_pool_t *pool);
85 
86 /** Like apr_cstr_split(), but append to existing @a array instead of
87  * creating a new one. Allocate the copied substrings in @a pool
88  * (i.e., caller decides whether or not to pass @a array->pool as @a pool).
89  *
90  * @since New in 1.6
91  */
93  const char *input,
94  const char *sep_chars,
95  int chop_whitespace,
96  apr_pool_t *pool);
97 
98 
99 /** Return @c TRUE iff @a str matches any of the elements of @a list, a list
100  * of zero or more glob patterns.
101  *
102  * @since New in 1.6
103  */
104 int apr_cstr_match_glob_list(const char *str, const apr_array_header_t *list);
105 
106 /** Return @c TRUE iff @a str exactly matches any of the elements of @a list.
107  *
108  * @since New in 1.6
109  */
110 int apr_cstr_match_list(const char *str, const apr_array_header_t *list);
111 
112 /**
113  * Get the next token from @a *str interpreting any char from @a sep as a
114  * token separator. Separators at the beginning of @a str will be skipped.
115  * Returns a pointer to the beginning of the first token in @a *str or NULL
116  * if no token is left. Modifies @a str such that the next call will return
117  * the next token.
118  *
119  * @note The content of @a *str may be modified by this function.
120  *
121  * @since New in 1.6.
122  */
123 char * apr_cstr_tokenize(const char *sep, char **str);
124 
125 /**
126  * Return the number of line breaks in @a msg, allowing any kind of newline
127  * termination (CR, LF, CRLF, or LFCR), even inconsistent.
128  *
129  * @since New in 1.6.
130  */
131 int apr_cstr_count_newlines(const char *msg);
132 
133 #if 0 /* XXX: stringbuf logic is not present in APR */
134 /**
135  * Return a cstring which is the concatenation of @a strings (an array
136  * of char *) each followed by @a separator (that is, @a separator
137  * will also end the resulting string). Allocate the result in @a pool.
138  * If @a strings is empty, then return the empty string.
139  *
140  * @since New in 1.6.
141  */
142 char * apr_cstr_join(const apr_array_header_t *strings,
143  const char *separator,
144  apr_pool_t *pool);
145 #endif
146 
147 /**
148  * Perform a case-insensitive comparison of two strings @a atr1 and @a atr2,
149  * treating upper and lower case values of the 26 standard C/POSIX alphabetic
150  * characters as equivalent. Extended latin characters outside of this set
151  * are treated as unique octets, irrespective of the current locale.
152  *
153  * Returns in integer greater than, equal to, or less than 0,
154  * according to whether @a str1 is considered greater than, equal to,
155  * or less than @a str2.
156  *
157  * @since New in 1.6.
158  */
159 int apr_cstr_casecmp(const char *str1, const char *str2);
160 
161 /**
162  * Perform a case-insensitive comparison of two strings @a atr1 and @a atr2,
163  * treating upper and lower case values of the 26 standard C/POSIX alphabetic
164  * characters as equivalent. Extended latin characters outside of this set
165  * are treated as unique octets, irrespective of the current locale.
166  *
167  * Returns in integer greater than, equal to, or less than 0,
168  * according to whether @a str1 is considered greater than, equal to,
169  * or less than @a str2.
170  *
171  * @since New in 1.6.
172  */
173 int apr_cstr_casecmpn(const char *str1, const char *str2, apr_size_t n);
174 
175 /**
176  * Parse the C string @a str into a 64 bit number, and return it in @a *n.
177  * Assume that the number is represented in base @a base.
178  * Raise an error if conversion fails (e.g. due to overflow), or if the
179  * converted number is smaller than @a minval or larger than @a maxval.
180  *
181  * Leading whitespace in @a str is skipped in a locale-dependent way.
182  * After that, the string may contain an optional '+' (positive, default)
183  * or '-' (negative) character, followed by an optional '0x' prefix if
184  * @a base is 0 or 16, followed by numeric digits appropriate for the base.
185  * If there are any more characters after the numeric digits, an error is
186  * returned.
187  *
188  * If @a base is zero, then a leading '0x' or '0X' prefix means hexadecimal,
189  * else a leading '0' means octal (implemented, though not documented, in
190  * apr_strtoi64() in APR 0.9.0 through 1.5.0), else use base ten.
191  *
192  * @since New in 1.6.
193  */
194 apr_status_t apr_cstr_strtoi64(apr_int64_t *n, const char *str,
195  apr_int64_t minval, apr_int64_t maxval,
196  int base);
197 
198 /**
199  * Parse the C string @a str into a 64 bit number, and return it in @a *n.
200  * Assume that the number is represented in base 10.
201  * Raise an error if conversion fails (e.g. due to overflow).
202  *
203  * The behaviour otherwise is as described for apr_cstr_strtoi64().
204  *
205  * @since New in 1.6.
206  */
207 apr_status_t apr_cstr_atoi64(apr_int64_t *n, const char *str);
208 
209 /**
210  * Parse the C string @a str into a 32 bit number, and return it in @a *n.
211  * Assume that the number is represented in base 10.
212  * Raise an error if conversion fails (e.g. due to overflow).
213  *
214  * The behaviour otherwise is as described for apr_cstr_strtoi64().
215  *
216  * @since New in 1.6.
217  */
218 apr_status_t apr_cstr_atoi(int *n, const char *str);
219 
220 /**
221  * Parse the C string @a str into an unsigned 64 bit number, and return
222  * it in @a *n. Assume that the number is represented in base @a base.
223  * Raise an error if conversion fails (e.g. due to overflow), or if the
224  * converted number is smaller than @a minval or larger than @a maxval.
225  *
226  * Leading whitespace in @a str is skipped in a locale-dependent way.
227  * After that, the string may contain an optional '+' (positive, default)
228  * or '-' (negative) character, followed by an optional '0x' prefix if
229  * @a base is 0 or 16, followed by numeric digits appropriate for the base.
230  * If there are any more characters after the numeric digits, an error is
231  * returned.
232  *
233  * If @a base is zero, then a leading '0x' or '0X' prefix means hexadecimal,
234  * else a leading '0' means octal (as implemented, though not documented, in
235  * apr_strtoi64(), else use base ten.
236  *
237  * @warning The implementation returns APR_ERANGE if the parsed number
238  * is greater than APR_INT64_MAX, even if it is not greater than @a maxval.
239  *
240  * @since New in 1.6.
241  */
242 apr_status_t apr_cstr_strtoui64(apr_uint64_t *n, const char *str,
243  apr_uint64_t minval, apr_uint64_t maxval,
244  int base);
245 
246 /**
247  * Parse the C string @a str into an unsigned 64 bit number, and return
248  * it in @a *n. Assume that the number is represented in base 10.
249  * Raise an error if conversion fails (e.g. due to overflow).
250  *
251  * The behaviour otherwise is as described for apr_cstr_strtoui64(),
252  * including the upper limit of APR_INT64_MAX.
253  *
254  * @since New in 1.6.
255  */
256 apr_status_t apr_cstr_atoui64(apr_uint64_t *n, const char *str);
257 
258 /**
259  * Parse the C string @a str into an unsigned 32 bit number, and return
260  * it in @a *n. Assume that the number is represented in base 10.
261  * Raise an error if conversion fails (e.g. due to overflow).
262  *
263  * The behaviour otherwise is as described for apr_cstr_strtoui64(),
264  * including the upper limit of APR_INT64_MAX.
265  *
266  * @since New in 1.6.
267  */
268 apr_status_t apr_cstr_atoui(unsigned int *n, const char *str);
269 
270 /**
271  * Skip the common prefix @a prefix from the C string @a str, and return
272  * a pointer to the next character after the prefix.
273  * Return @c NULL if @a str does not start with @a prefix.
274  *
275  * @since New in 1.6.
276  */
277 const char * apr_cstr_skip_prefix(const char *str, const char *prefix);
278 
279 /** @} */
280 
281 #ifdef __cplusplus
282 }
283 #endif /* __cplusplus */
284 
285 #endif /* SVN_STRING_H */
apr_status_t apr_cstr_atoi(int *n, const char *str)
Definition: apr_tables.h:62
char * apr_cstr_tokenize(const char *sep, char **str)
int apr_cstr_casecmp(const char *str1, const char *str2)
const char * apr_cstr_skip_prefix(const char *str, const char *prefix)
apr_status_t apr_cstr_atoui64(apr_uint64_t *n, const char *str)
int apr_cstr_casecmpn(const char *str1, const char *str2, apr_size_t n)
apr_status_t apr_cstr_strtoui64(apr_uint64_t *n, const char *str, apr_uint64_t minval, apr_uint64_t maxval, int base)
apr_array_header_t * apr_cstr_split(const char *input, const char *sep_chars, int chop_whitespace, apr_pool_t *pool)
int apr_cstr_match_list(const char *str, const apr_array_header_t *list)
void apr_cstr_split_append(apr_array_header_t *array, const char *input, const char *sep_chars, int chop_whitespace, apr_pool_t *pool)
APR memory allocation.
APR Table library.
apr_status_t apr_cstr_atoi64(apr_int64_t *n, const char *str)
APR Platform Definitions.
apr_status_t apr_cstr_strtoi64(apr_int64_t *n, const char *str, apr_int64_t minval, apr_int64_t maxval, int base)
apr_status_t apr_cstr_atoui(unsigned int *n, const char *str)
int apr_cstr_match_glob_list(const char *str, const apr_array_header_t *list)
struct apr_pool_t apr_pool_t
Definition: apr_pools.h:60
int apr_status_t
Definition: apr_errno.h:44
int apr_cstr_count_newlines(const char *msg)