1 | /* Licensed to the Apache Software Foundation (ASF) under one or more |
2 | * contributor license agreements. See the NOTICE file distributed with |
3 | * this work for additional information regarding copyright ownership. |
4 | * The ASF licenses this file to You under the Apache License, Version 2.0 |
5 | * (the "License"); you may not use this file except in compliance with |
6 | * the License. You may obtain a copy of the License at |
7 | * |
8 | * http://www.apache.org/licenses/LICENSE-2.0 |
9 | * |
10 | * Unless required by applicable law or agreed to in writing, software |
11 | * distributed under the License is distributed on an "AS IS" BASIS, |
12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
13 | * See the License for the specific language governing permissions and |
14 | * limitations under the License. |
15 | */ |
16 | |
17 | /* Portions of this file are covered by */ |
18 | /* -*- mode: c; c-file-style: "k&r" -*- |
19 | |
20 | strnatcmp.c -- Perform 'natural order' comparisons of strings in C. |
21 | Copyright (C) 2000 by Martin Pool <mbp@humbug.org.au> |
22 | |
23 | This software is provided 'as-is', without any express or implied |
24 | warranty. In no event will the authors be held liable for any damages |
25 | arising from the use of this software. |
26 | |
27 | Permission is granted to anyone to use this software for any purpose, |
28 | including commercial applications, and to alter it and redistribute it |
29 | freely, subject to the following restrictions: |
30 | |
31 | 1. The origin of this software must not be misrepresented; you must not |
32 | claim that you wrote the original software. If you use this software |
33 | in a product, an acknowledgment in the product documentation would be |
34 | appreciated but is not required. |
35 | 2. Altered source versions must be plainly marked as such, and must not be |
36 | misrepresented as being the original software. |
37 | 3. This notice may not be removed or altered from any source distribution. |
38 | */ |
39 | |
40 | #ifndef APR_STRINGS_H |
41 | #define APR_STRINGS_H |
42 | |
43 | /** |
44 | * @file apr_strings.h |
45 | * @brief APR Strings library |
46 | */ |
47 | |
48 | #include "apr.h" |
49 | #include "apr_errno.h" |
50 | #include "apr_pools.h" |
51 | #define APR_WANT_IOVEC |
52 | #include "apr_want.h" |
53 | |
54 | #if APR_HAVE_STDARG_H |
55 | #include <stdarg.h> |
56 | #endif |
57 | |
58 | #ifdef __cplusplus |
59 | extern "C" { |
60 | #endif /* __cplusplus */ |
61 | |
62 | /** |
63 | * @defgroup apr_strings String routines |
64 | * @ingroup APR |
65 | * @{ |
66 | */ |
67 | |
68 | /** |
69 | * Do a natural order comparison of two strings. |
70 | * @param a The first string to compare |
71 | * @param b The second string to compare |
72 | * @return Either <0, 0, or >0. If the first string is less than the second |
73 | * this returns <0, if they are equivalent it returns 0, and if the |
74 | * first string is greater than second string it retuns >0. |
75 | */ |
76 | APR_DECLARE(int) apr_strnatcmp(char const *a, char const *b); |
77 | |
78 | /** |
79 | * Do a natural order comparison of two strings ignoring the case of the |
80 | * strings. |
81 | * @param a The first string to compare |
82 | * @param b The second string to compare |
83 | * @return Either <0, 0, or >0. If the first string is less than the second |
84 | * this returns <0, if they are equivalent it returns 0, and if the |
85 | * first string is greater than second string it retuns >0. |
86 | */ |
87 | APR_DECLARE(int) apr_strnatcasecmp(char const *a, char const *b); |
88 | |
89 | /** |
90 | * duplicate a string into memory allocated out of a pool |
91 | * @param p The pool to allocate out of |
92 | * @param s The string to duplicate |
93 | * @return The new string or NULL if s == NULL |
94 | */ |
95 | APR_DECLARE(char *) apr_pstrdup(apr_pool_t *p, const char *s); |
96 | |
97 | /** |
98 | * Create a null-terminated string by making a copy of a sequence |
99 | * of characters and appending a null byte |
100 | * @param p The pool to allocate out of |
101 | * @param s The block of characters to duplicate |
102 | * @param n The number of characters to duplicate |
103 | * @return The new string or NULL if s == NULL |
104 | * @remark This is a faster alternative to apr_pstrndup, for use |
105 | * when you know that the string being duplicated really |
106 | * has 'n' or more characters. If the string might contain |
107 | * fewer characters, use apr_pstrndup. |
108 | */ |
109 | APR_DECLARE(char *) apr_pstrmemdup(apr_pool_t *p, const char *s, apr_size_t n) |
110 | #if defined(__GNUC__) && (__GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 4)) |
111 | __attribute__((alloc_size(3))) |
112 | #endif |
113 | ; |
114 | |
115 | /** |
116 | * Duplicate at most n characters of a string into memory allocated |
117 | * out of a pool; the new string will be NUL-terminated |
118 | * @param p The pool to allocate out of |
119 | * @param s The string to duplicate |
120 | * @param n The maximum number of characters to duplicate |
121 | * @return The new string or NULL if s == NULL |
122 | * @remark The amount of memory allocated from the pool is the length |
123 | * of the returned string including the NUL terminator |
124 | */ |
125 | APR_DECLARE(char *) apr_pstrndup(apr_pool_t *p, const char *s, apr_size_t n); |
126 | |
127 | /** |
128 | * Duplicate a block of memory. |
129 | * |
130 | * @param p The pool to allocate from |
131 | * @param m The memory to duplicate |
132 | * @param n The number of bytes to duplicate |
133 | * @return The new block of memory or NULL if m == NULL |
134 | */ |
135 | APR_DECLARE(void *) apr_pmemdup(apr_pool_t *p, const void *m, apr_size_t n) |
136 | #if defined(__GNUC__) && (__GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 4)) |
137 | __attribute__((alloc_size(3))) |
138 | #endif |
139 | ; |
140 | |
141 | /** |
142 | * Concatenate multiple strings, allocating memory out a pool |
143 | * @param p The pool to allocate out of |
144 | * @param ... The strings to concatenate. The final string must be NULL |
145 | * @return The new string |
146 | */ |
147 | APR_DECLARE_NONSTD(char *) apr_pstrcat(apr_pool_t *p, ...) |
148 | #if defined(__GNUC__) && __GNUC__ >= 4 |
149 | __attribute__((sentinel)) |
150 | #endif |
151 | ; |
152 | |
153 | /** |
154 | * Concatenate multiple strings specified in a writev-style vector |
155 | * @param p The pool from which to allocate |
156 | * @param vec The strings to concatenate |
157 | * @param nvec The number of strings to concatenate |
158 | * @param nbytes (output) strlen of new string (pass in NULL to omit) |
159 | * @return The new string |
160 | */ |
161 | APR_DECLARE(char *) apr_pstrcatv(apr_pool_t *p, const struct iovec *vec, |
162 | apr_size_t nvec, apr_size_t *nbytes); |
163 | |
164 | /** |
165 | * printf-style style printing routine. The data is output to a string |
166 | * allocated from a pool |
167 | * @param p The pool to allocate out of |
168 | * @param fmt The format of the string |
169 | * @param ap The arguments to use while printing the data |
170 | * @return The new string |
171 | */ |
172 | APR_DECLARE(char *) apr_pvsprintf(apr_pool_t *p, const char *fmt, va_list ap); |
173 | |
174 | /** |
175 | * printf-style style printing routine. The data is output to a string |
176 | * allocated from a pool |
177 | * @param p The pool to allocate out of |
178 | * @param fmt The format of the string |
179 | * @param ... The arguments to use while printing the data |
180 | * @return The new string |
181 | */ |
182 | APR_DECLARE_NONSTD(char *) apr_psprintf(apr_pool_t *p, const char *fmt, ...) |
183 | __attribute__((format(printf,2,3))); |
184 | |
185 | /** |
186 | * Copy up to dst_size characters from src to dst; does not copy |
187 | * past a NUL terminator in src, but always terminates dst with a NUL |
188 | * regardless. |
189 | * @param dst The destination string |
190 | * @param src The source string |
191 | * @param dst_size The space available in dst; dst always receives |
192 | * NUL termination, so if src is longer than |
193 | * dst_size, the actual number of characters copied is |
194 | * dst_size - 1. |
195 | * @return Pointer to the NUL terminator of the destination string, dst |
196 | * @remark |
197 | * <PRE> |
198 | * Note the differences between this function and strncpy(): |
199 | * 1) strncpy() doesn't always NUL terminate; apr_cpystrn() does. |
200 | * 2) strncpy() pads the destination string with NULs, which is often |
201 | * unnecessary; apr_cpystrn() does not. |
202 | * 3) strncpy() returns a pointer to the beginning of the dst string; |
203 | * apr_cpystrn() returns a pointer to the NUL terminator of dst, |
204 | * to allow a check for truncation. |
205 | * </PRE> |
206 | */ |
207 | APR_DECLARE(char *) apr_cpystrn(char *dst, const char *src, |
208 | apr_size_t dst_size); |
209 | |
210 | /** |
211 | * Remove all whitespace from a string |
212 | * @param dest The destination string. It is okay to modify the string |
213 | * in place. Namely dest == src |
214 | * @param src The string to rid the spaces from. |
215 | * @return A pointer to the destination string's null terminator. |
216 | */ |
217 | APR_DECLARE(char *) apr_collapse_spaces(char *dest, const char *src); |
218 | |
219 | /** |
220 | * Convert the arguments to a program from one string to an array of |
221 | * strings terminated by a NULL pointer |
222 | * @param arg_str The arguments to convert |
223 | * @param argv_out Output location. This is a pointer to an array of strings. |
224 | * @param token_context Pool to use. |
225 | */ |
226 | APR_DECLARE(apr_status_t) apr_tokenize_to_argv(const char *arg_str, |
227 | char ***argv_out, |
228 | apr_pool_t *token_context); |
229 | |
230 | /** |
231 | * Split a string into separate null-terminated tokens. The tokens are |
232 | * delimited in the string by one or more characters from the sep |
233 | * argument. |
234 | * @param str The string to separate; this should be specified on the |
235 | * first call to apr_strtok() for a given string, and NULL |
236 | * on subsequent calls. |
237 | * @param sep The set of delimiters |
238 | * @param last State saved by apr_strtok() between calls. |
239 | * @return The next token from the string |
240 | * @note the 'last' state points to the trailing NUL char of the final |
241 | * token, otherwise it points to the character following the current |
242 | * token (all successive or empty occurances of sep are skiped on the |
243 | * subsequent call to apr_strtok). Therefore it is possible to avoid |
244 | * a strlen() determination, with the following logic; |
245 | * toklen = last - retval; if (*last) --toklen; |
246 | */ |
247 | APR_DECLARE(char *) apr_strtok(char *str, const char *sep, char **last); |
248 | |
249 | /** |
250 | * @defgroup APR_Strings_Snprintf snprintf implementations |
251 | * @warning |
252 | * These are snprintf implementations based on apr_vformatter(). |
253 | * |
254 | * Note that various standards and implementations disagree on the return |
255 | * value of snprintf, and side-effects due to %n in the formatting string. |
256 | * apr_snprintf (and apr_vsnprintf) behaves as follows: |
257 | * |
258 | * Process the format string until the entire string is exhausted, or |
259 | * the buffer fills. If the buffer fills then stop processing immediately |
260 | * (so no further %n arguments are processed), and return the buffer |
261 | * length. In all cases the buffer is NUL terminated. It will return the |
262 | * number of characters inserted into the buffer, not including the |
263 | * terminating NUL. As a special case, if len is 0, apr_snprintf will |
264 | * return the number of characters that would have been inserted if |
265 | * the buffer had been infinite (in this case, *buffer can be NULL) |
266 | * |
267 | * In no event does apr_snprintf return a negative number. |
268 | * @{ |
269 | */ |
270 | |
271 | /** |
272 | * snprintf routine based on apr_vformatter. This means it understands the |
273 | * same extensions. |
274 | * @param buf The buffer to write to |
275 | * @param len The size of the buffer |
276 | * @param format The format string |
277 | * @param ... The arguments to use to fill out the format string. |
278 | */ |
279 | APR_DECLARE_NONSTD(int) apr_snprintf(char *buf, apr_size_t len, |
280 | const char *format, ...) |
281 | __attribute__((format(printf,3,4))); |
282 | |
283 | /** |
284 | * vsnprintf routine based on apr_vformatter. This means it understands the |
285 | * same extensions. |
286 | * @param buf The buffer to write to |
287 | * @param len The size of the buffer |
288 | * @param format The format string |
289 | * @param ap The arguments to use to fill out the format string. |
290 | */ |
291 | APR_DECLARE(int) apr_vsnprintf(char *buf, apr_size_t len, const char *format, |
292 | va_list ap); |
293 | /** @} */ |
294 | |
295 | /** |
296 | * create a string representation of an int, allocated from a pool |
297 | * @param p The pool from which to allocate |
298 | * @param n The number to format |
299 | * @return The string representation of the number |
300 | */ |
301 | APR_DECLARE(char *) apr_itoa(apr_pool_t *p, int n); |
302 | |
303 | /** |
304 | * create a string representation of a long, allocated from a pool |
305 | * @param p The pool from which to allocate |
306 | * @param n The number to format |
307 | * @return The string representation of the number |
308 | */ |
309 | APR_DECLARE(char *) apr_ltoa(apr_pool_t *p, long n); |
310 | |
311 | /** |
312 | * create a string representation of an apr_off_t, allocated from a pool |
313 | * @param p The pool from which to allocate |
314 | * @param n The number to format |
315 | * @return The string representation of the number |
316 | */ |
317 | APR_DECLARE(char *) apr_off_t_toa(apr_pool_t *p, apr_off_t n); |
318 | |
319 | /** |
320 | * Convert a numeric string into an apr_off_t numeric value. |
321 | * @param offset The value of the parsed string. |
322 | * @param buf The string to parse. It may contain optional whitespace, |
323 | * followed by an optional '+' (positive, default) or '-' (negative) |
324 | * character, followed by an optional '0x' prefix if base is 0 or 16, |
325 | * followed by numeric digits appropriate for base. |
326 | * @param end A pointer to the end of the valid character in buf. If |
327 | * not NULL, it is set to the first invalid character in buf. |
328 | * @param base A numeric base in the range between 2 and 36 inclusive, |
329 | * or 0. If base is zero, buf will be treated as base ten unless its |
330 | * digits are prefixed with '0x', in which case it will be treated as |
331 | * base 16. |
332 | * @bug *end breaks type safety; where *buf is const, *end needs to be |
333 | * declared as const in APR 2.0 |
334 | */ |
335 | APR_DECLARE(apr_status_t) apr_strtoff(apr_off_t *offset, const char *buf, |
336 | char **end, int base); |
337 | |
338 | /** |
339 | * parse a numeric string into a 64-bit numeric value |
340 | * @param buf The string to parse. It may contain optional whitespace, |
341 | * followed by an optional '+' (positive, default) or '-' (negative) |
342 | * character, followed by an optional '0x' prefix if base is 0 or 16, |
343 | * followed by numeric digits appropriate for base. |
344 | * @param end A pointer to the end of the valid character in buf. If |
345 | * not NULL, it is set to the first invalid character in buf. |
346 | * @param base A numeric base in the range between 2 and 36 inclusive, |
347 | * or 0. If base is zero, buf will be treated as base ten unless its |
348 | * digits are prefixed with '0x', in which case it will be treated as |
349 | * base 16. |
350 | * @return The numeric value of the string. On overflow, errno is set |
351 | * to ERANGE. On success, errno is set to 0. |
352 | */ |
353 | APR_DECLARE(apr_int64_t) apr_strtoi64(const char *buf, char **end, int base); |
354 | |
355 | /** |
356 | * parse a base-10 numeric string into a 64-bit numeric value. |
357 | * Equivalent to apr_strtoi64(buf, (char**)NULL, 10). |
358 | * @param buf The string to parse |
359 | * @return The numeric value of the string. On overflow, errno is set |
360 | * to ERANGE. On success, errno is set to 0. |
361 | */ |
362 | APR_DECLARE(apr_int64_t) apr_atoi64(const char *buf); |
363 | |
364 | /** |
365 | * Format a binary size (magnitiudes are 2^10 rather than 10^3) from an apr_off_t, |
366 | * as bytes, K, M, T, etc, to a four character compacted human readable string. |
367 | * @param size The size to format |
368 | * @param buf The 5 byte text buffer (counting the trailing null) |
369 | * @return The buf passed to apr_strfsize() |
370 | * @remark All negative sizes report ' - ', apr_strfsize only formats positive values. |
371 | */ |
372 | APR_DECLARE(char *) apr_strfsize(apr_off_t size, char *buf); |
373 | |
374 | /** @} */ |
375 | |
376 | #ifdef __cplusplus |
377 | } |
378 | #endif |
379 | |
380 | #endif /* !APR_STRINGS_H */ |
381 | |