3 * ====================================================================
4 * Licensed to the Apache Software Foundation (ASF) under one
5 * or more contributor license agreements. See the NOTICE file
6 * distributed with this work for additional information
7 * regarding copyright ownership. The ASF licenses this file
8 * to you under the Apache License, Version 2.0 (the
9 * "License"); you may not use this file except in compliance
10 * with the License. You may obtain a copy of the License at
12 * http://www.apache.org/licenses/LICENSE-2.0
14 * Unless required by applicable law or agreed to in writing,
15 * software distributed under the License is distributed on an
16 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
17 * KIND, either express or implied. See the License for the
18 * specific language governing permissions and limitations
20 * ====================================================================
24 * @brief Counted-length strings for Subversion, plus some C string goodies.
26 * There are two string datatypes: @c svn_string_t and @c svn_stringbuf_t.
27 * The former is a simple pointer/length pair useful for passing around
28 * strings (or arbitrary bytes) with a counted length. @c svn_stringbuf_t is
29 * buffered to enable efficient appending of strings without an allocation
30 * and copy for each append operation.
32 * @c svn_string_t contains a <tt>const char *</tt> for its data, so it is
33 * most appropriate for constant data and for functions which expect constant,
34 * counted data. Functions should generally use <tt>const @c svn_string_t
35 * *</tt> as their parameter to indicate they are expecting a constant,
38 * @c svn_stringbuf_t uses a plain <tt>char *</tt> for its data, so it is
39 * most appropriate for modifiable data.
43 * 1. Null termination:
45 * Both structures maintain a significant invariant:
47 * <tt>s->data[s->len] == '\\0'</tt>
49 * The functions defined within this header file will maintain
50 * the invariant (which does imply that memory is
51 * allocated/defined as @c len+1 bytes). If code outside of the
52 * @c svn_string.h functions manually builds these structures,
53 * then they must enforce this invariant.
55 * Note that an @c svn_string(buf)_t may contain binary data,
56 * which means that strlen(s->data) does not have to equal @c
57 * s->len. The null terminator is provided to make it easier to
58 * pass @c s->data to C string interfaces.
63 * All the functions assume their input data pointer is non-NULL,
64 * unless otherwise documented, and may seg fault if passed
65 * NULL. The input data may *contain* null bytes, of course, just
66 * the data pointer itself must not be NULL.
68 * <h3>Memory allocation</h3>
70 * All the functions make a deep copy of all input data, and never store
71 * a pointer to the original input data.
78 #include <apr.h> /* for apr_size_t */
79 #include <apr_pools.h> /* for apr_pool_t */
80 #include <apr_tables.h> /* for apr_array_header_t */
82 #include "svn_types.h" /* for svn_boolean_t, svn_error_t */
86 #endif /* __cplusplus */
89 * @defgroup svn_string String handling
95 /** A simple counted string. */
96 typedef struct svn_string_t
98 const char *data; /**< pointer to the bytestring */
99 apr_size_t len; /**< length of bytestring */
102 /** A buffered string, capable of appending without an allocation and copy
103 * for each append. */
104 typedef struct svn_stringbuf_t
106 /** a pool from which this string was originally allocated, and is not
107 * necessarily specific to this string. This is used only for allocating
108 * more memory from when the string needs to grow.
112 /** pointer to the bytestring */
115 /** length of bytestring */
118 /** total size of buffer allocated */
119 apr_size_t blocksize;
124 * @defgroup svn_string_svn_string_t svn_string_t functions
128 /** Create a new string copied from the null-terminated C string @a cstring.
131 svn_string_create(const char *cstring, apr_pool_t *pool);
133 /** Create a new, empty string.
138 svn_string_create_empty(apr_pool_t *pool);
140 /** Create a new string copied from a generic string of bytes, @a bytes, of
141 * length @a size bytes. @a bytes is NOT assumed to be null-terminated, but
142 * the new string will be.
144 * @since Since 1.9, @a bytes can be NULL if @a size is zero.
147 svn_string_ncreate(const char *bytes, apr_size_t size, apr_pool_t *pool);
149 /** Create a new string copied from the stringbuf @a strbuf.
152 svn_string_create_from_buf(const svn_stringbuf_t *strbuf, apr_pool_t *pool);
154 /** Create a new string by printf-style formatting using @a fmt and the
155 * variable arguments, which are as appropriate for apr_psprintf().
158 svn_string_createf(apr_pool_t *pool, const char *fmt, ...)
159 __attribute__((format(printf, 2, 3)));
161 /** Create a new string by printf-style formatting using @c fmt and @a ap.
162 * This is the same as svn_string_createf() except for the different
163 * way of passing the variable arguments.
166 svn_string_createv(apr_pool_t *pool, const char *fmt, va_list ap)
167 __attribute__((format(printf, 2, 0)));
169 /** Return TRUE if @a str is empty (has length zero). */
171 svn_string_isempty(const svn_string_t *str);
173 /** Return a duplicate of @a original_string.
175 * @since Since 1.9, @a original_string can be NULL in which case NULL will
179 svn_string_dup(const svn_string_t *original_string, apr_pool_t *pool);
181 /** Return @c TRUE iff @a str1 and @a str2 have identical length and data. */
183 svn_string_compare(const svn_string_t *str1, const svn_string_t *str2);
185 /** Return offset of first non-whitespace character in @a str, or return
186 * @a str->len if none.
189 svn_string_first_non_whitespace(const svn_string_t *str);
191 /** Return position of last occurrence of @a ch in @a str, or return
192 * @a str->len if no occurrence.
195 svn_string_find_char_backward(const svn_string_t *str, char ch);
201 * @defgroup svn_string_svn_stringbuf_t svn_stringbuf_t functions
205 /** Create a new stringbuf copied from the null-terminated C string
209 svn_stringbuf_create(const char *cstring, apr_pool_t *pool);
211 /** Create a new stringbuf copied from the generic string of bytes, @a bytes,
212 * of length @a size bytes. @a bytes is NOT assumed to be null-terminated,
213 * but the new stringbuf will be.
215 * @since Since 1.9, @a bytes can be NULL if @a size is zero.
218 svn_stringbuf_ncreate(const char *bytes, apr_size_t size, apr_pool_t *pool);
220 /** Create a new, empty stringbuf.
225 svn_stringbuf_create_empty(apr_pool_t *pool);
227 /** Create a new, empty stringbuf with at least @a minimum_size bytes of
228 * space available in the memory block.
230 * The allocated string buffer will be at least one byte larger than
231 * @a minimum_size to account for a final '\\0'.
236 svn_stringbuf_create_ensure(apr_size_t minimum_size, apr_pool_t *pool);
238 /** Create a new stringbuf copied from the string @a str.
241 svn_stringbuf_create_from_string(const svn_string_t *str, apr_pool_t *pool);
243 /** Create a new stringbuf using the given @a str as initial buffer.
244 * Allocate the result in @a pool. In contrast to #svn_stringbuf_create,
245 * the contents of @a str may change when the stringbuf gets modified.
250 svn_stringbuf_create_wrap(char *str, apr_pool_t *pool);
252 /** Create a new stringbuf by printf-style formatting using @a fmt and the
253 * variable arguments, which are as appropriate for apr_psprintf().
256 svn_stringbuf_createf(apr_pool_t *pool, const char *fmt, ...)
257 __attribute__((format(printf, 2, 3)));
259 /** Create a new stringbuf by printf-style formatting using @c fmt and @a ap.
260 * This is the same as svn_stringbuf_createf() except for the different
261 * way of passing the variable arguments.
264 svn_stringbuf_createv(apr_pool_t *pool, const char *fmt, va_list ap)
265 __attribute__((format(printf, 2, 0)));
267 /** Make sure that @a str has at least @a minimum_size
268 * bytes of space available in the memory block.
270 * The allocated string buffer will be at least one byte larger than
271 * @a minimum_size to account for a final '\\0'.
273 * @note: Before Subversion 1.8 this function did not ensure space for
274 * one byte more than @a minimum_size. If compatibility with pre-1.8
275 * behaviour is required callers must assume space for only
276 * @a minimum_size-1 data bytes plus a final '\\0'.
279 svn_stringbuf_ensure(svn_stringbuf_t *str, apr_size_t minimum_size);
281 /** Set @a str to a copy of the null-terminated C string @a value. */
283 svn_stringbuf_set(svn_stringbuf_t *str, const char *value);
285 /** Set @a str to empty (zero length). */
287 svn_stringbuf_setempty(svn_stringbuf_t *str);
289 /** Return @c TRUE if @a str is empty (has length zero). */
291 svn_stringbuf_isempty(const svn_stringbuf_t *str);
293 /** Chop @a nbytes bytes off end of @a str, but not more than @a str->len. */
295 svn_stringbuf_chop(svn_stringbuf_t *str, apr_size_t nbytes);
297 /** Fill @a str with character @a c. */
299 svn_stringbuf_fillchar(svn_stringbuf_t *str, unsigned char c);
301 /** Append the single character @a byte onto @a targetstr.
303 * This is an optimized version of svn_stringbuf_appendbytes()
304 * that is much faster to call and execute. Gains vary with the ABI.
305 * The advantages extend beyond the actual call because the reduced
306 * register pressure allows for more optimization within the caller.
308 * Reallocs if necessary. @a targetstr is affected, nothing else is.
312 svn_stringbuf_appendbyte(svn_stringbuf_t *targetstr,
315 /** Append the array of bytes @a bytes of length @a count onto @a targetstr.
317 * Reallocs if necessary. @a targetstr is affected, nothing else is.
319 * @since 1.9 @a bytes can be NULL if @a count is zero.
322 svn_stringbuf_appendbytes(svn_stringbuf_t *targetstr,
326 /** Append @a byte @a count times onto @a targetstr.
328 * Reallocs if necessary. @a targetstr is affected, nothing else is.
332 svn_stringbuf_appendfill(svn_stringbuf_t *targetstr,
336 /** Append the stringbuf @c appendstr onto @a targetstr.
338 * Reallocs if necessary. @a targetstr is affected, nothing else is.
341 svn_stringbuf_appendstr(svn_stringbuf_t *targetstr,
342 const svn_stringbuf_t *appendstr);
344 /** Append the C string @a cstr onto @a targetstr.
346 * Reallocs if necessary. @a targetstr is affected, nothing else is.
349 svn_stringbuf_appendcstr(svn_stringbuf_t *targetstr,
352 /** Insert into @a str at position @a pos an array of bytes @a bytes
353 * which is @a count bytes long.
355 * The resulting string will be @c count+str->len bytes long. If
356 * @a pos is larger than or equal to @c str->len, simply append @a bytes.
358 * Reallocs if necessary. @a str is affected, nothing else is.
360 * @note The inserted string may be a sub-range of @a str.
364 * @since Since 1.9, @a bytes can be NULL if @a count is zero.
367 svn_stringbuf_insert(svn_stringbuf_t *str,
372 /** Remove @a count bytes from @a str, starting at position @a pos.
374 * If that range exceeds the current string data, truncate @a str at
375 * @a pos. If @a pos is larger than or equal to @c str->len, this will
376 * be a no-op. Otherwise, the resulting string will be @c str->len-count
382 svn_stringbuf_remove(svn_stringbuf_t *str,
386 /** Replace in @a str the substring which starts at @a pos and is @a
387 * old_count bytes long with a new substring @a bytes which is @a
388 * new_count bytes long.
390 * This is faster but functionally equivalent to the following sequence:
392 svn_stringbuf_remove(str, pos, old_count);
393 svn_stringbuf_insert(str, pos, bytes, new_count);
398 * @since Since 1.9, @a bytes can be NULL if @a new_count is zero.
401 svn_stringbuf_replace(svn_stringbuf_t *str,
403 apr_size_t old_count,
405 apr_size_t new_count);
407 /** Return a duplicate of @a original_string. */
409 svn_stringbuf_dup(const svn_stringbuf_t *original_string, apr_pool_t *pool);
411 /** Return @c TRUE iff @a str1 and @a str2 have identical length and data. */
413 svn_stringbuf_compare(const svn_stringbuf_t *str1,
414 const svn_stringbuf_t *str2);
416 /** Return offset of first non-whitespace character in @a str, or return
417 * @a str->len if none.
420 svn_stringbuf_first_non_whitespace(const svn_stringbuf_t *str);
422 /** Strip whitespace from both sides of @a str (modified in place). */
424 svn_stringbuf_strip_whitespace(svn_stringbuf_t *str);
426 /** Return position of last occurrence of @a ch in @a str, or return
427 * @a str->len if no occurrence.
430 svn_stringbuf_find_char_backward(const svn_stringbuf_t *str, char ch);
432 /** Return @c TRUE iff @a str1 and @a str2 have identical length and data. */
434 svn_string_compare_stringbuf(const svn_string_t *str1,
435 const svn_stringbuf_t *str2);
441 * @defgroup svn_string_cstrings C string functions
445 /** Divide @a input into substrings, interpreting any char from @a sep
446 * as a token separator.
448 * Return an array of copies of those substrings (plain const char*),
449 * allocating both the array and the copies in @a pool.
451 * None of the elements added to the array contain any of the
452 * characters in @a sep_chars, and none of the new elements are empty
453 * (thus, it is possible that the returned array will have length
456 * If @a chop_whitespace is TRUE, then remove leading and trailing
457 * whitespace from the returned strings.
460 svn_cstring_split(const char *input,
461 const char *sep_chars,
462 svn_boolean_t chop_whitespace,
465 /** Like svn_cstring_split(), but append to existing @a array instead of
466 * creating a new one. Allocate the copied substrings in @a pool
467 * (i.e., caller decides whether or not to pass @a array->pool as @a pool).
470 svn_cstring_split_append(apr_array_header_t *array,
472 const char *sep_chars,
473 svn_boolean_t chop_whitespace,
477 /** Return @c TRUE iff @a str matches any of the elements of @a list, a list
478 * of zero or more glob patterns.
481 svn_cstring_match_glob_list(const char *str, const apr_array_header_t *list);
483 /** Return @c TRUE iff @a str exactly matches any of the elements of @a list.
488 svn_cstring_match_list(const char *str, const apr_array_header_t *list);
491 * Get the next token from @a *str interpreting any char from @a sep as a
492 * token separator. Separators at the beginning of @a str will be skipped.
493 * Returns a pointer to the beginning of the first token in @a *str or NULL
494 * if no token is left. Modifies @a str such that the next call will return
497 * @note The content of @a *str may be modified by this function.
502 svn_cstring_tokenize(const char *sep, char **str);
505 * Return the number of line breaks in @a msg, allowing any kind of newline
506 * termination (CR, LF, CRLF, or LFCR), even inconsistent.
511 svn_cstring_count_newlines(const char *msg);
514 * Return a cstring which is the concatenation of @a strings (an array
515 * of char *) each followed by @a separator (that is, @a separator
516 * will also end the resulting string). Allocate the result in @a pool.
517 * If @a strings is empty, then return the empty string.
522 svn_cstring_join(const apr_array_header_t *strings,
523 const char *separator,
527 * Compare two strings @a atr1 and @a atr2, treating case-equivalent
528 * unaccented Latin (ASCII subset) letters as equal.
530 * Returns in integer greater than, equal to, or less than 0,
531 * according to whether @a str1 is considered greater than, equal to,
532 * or less than @a str2.
537 svn_cstring_casecmp(const char *str1, const char *str2);
540 * Parse the C string @a str into a 64 bit number, and return it in @a *n.
541 * Assume that the number is represented in base @a base.
542 * Raise an error if conversion fails (e.g. due to overflow), or if the
543 * converted number is smaller than @a minval or larger than @a maxval.
544 * Leading whitespace in @a str is skipped in a locale-dependent way.
549 svn_cstring_strtoi64(apr_int64_t *n, const char *str,
550 apr_int64_t minval, apr_int64_t maxval,
554 * Parse the C string @a str into a 64 bit number, and return it in @a *n.
555 * Assume that the number is represented in base 10.
556 * Raise an error if conversion fails (e.g. due to overflow).
557 * Leading whitespace in @a str is skipped in a locale-dependent way.
562 svn_cstring_atoi64(apr_int64_t *n, const char *str);
565 * Parse the C string @a str into a 32 bit number, and return it in @a *n.
566 * Assume that the number is represented in base 10.
567 * Raise an error if conversion fails (e.g. due to overflow).
568 * Leading whitespace in @a str is skipped in a locale-dependent way.
573 svn_cstring_atoi(int *n, const char *str);
576 * Parse the C string @a str into an unsigned 64 bit number, and return
577 * it in @a *n. Assume that the number is represented in base @a base.
578 * Raise an error if conversion fails (e.g. due to overflow), or if the
579 * converted number is smaller than @a minval or larger than @a maxval.
580 * Leading whitespace in @a str is skipped in a locale-dependent way.
585 svn_cstring_strtoui64(apr_uint64_t *n, const char *str,
586 apr_uint64_t minval, apr_uint64_t maxval,
590 * Parse the C string @a str into an unsigned 64 bit number, and return
591 * it in @a *n. Assume that the number is represented in base 10.
592 * Raise an error if conversion fails (e.g. due to overflow).
593 * Leading whitespace in @a str is skipped in a locale-dependent way.
598 svn_cstring_atoui64(apr_uint64_t *n, const char *str);
601 * Parse the C string @a str into an unsigned 32 bit number, and return
602 * it in @a *n. Assume that the number is represented in base 10.
603 * Raise an error if conversion fails (e.g. due to overflow).
604 * Leading whitespace in @a str is skipped in a locale-dependent way.
609 svn_cstring_atoui(unsigned int *n, const char *str);
612 * Skip the common prefix @a prefix from the C string @a str, and return
613 * a pointer to the next character after the prefix.
614 * Return @c NULL if @a str does not start with @a prefix.
619 svn_cstring_skip_prefix(const char *str, const char *prefix);
628 #endif /* __cplusplus */
630 #endif /* SVN_STRING_H */