Subversion
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
svn_string.h
Go to the documentation of this file.
1 /**
2  * @copyright
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
11  *
12  * http://www.apache.org/licenses/LICENSE-2.0
13  *
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
19  * under the License.
20  * ====================================================================
21  * @endcopyright
22  *
23  * @file svn_string.h
24  * @brief Counted-length strings for Subversion, plus some C string goodies.
25  *
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.
31  *
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,
36  * counted string.
37  *
38  * @c svn_stringbuf_t uses a plain <tt>char *</tt> for its data, so it is
39  * most appropriate for modifiable data.
40  *
41  * <h3>Invariants</h3>
42  *
43  * 1. Null termination:
44  *
45  * Both structures maintain a significant invariant:
46  *
47  * <tt>s->data[s->len] == '\\0'</tt>
48  *
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.
54  *
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.
59  *
60  *
61  * 2. Non-NULL input:
62  *
63  * All the functions assume their input data 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.
67  *
68  * <h3>Memory allocation</h3>
69  *
70  * All the functions make a deep copy of all input data, and never store
71  * a pointer to the original input data.
72  */
73 
74 
75 #ifndef SVN_STRING_H
76 #define SVN_STRING_H
77 
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 */
81 
82 #include "svn_types.h" /* for svn_boolean_t, svn_error_t */
83 
84 #ifdef __cplusplus
85 extern "C" {
86 #endif /* __cplusplus */
87 
88 /**
89  * @defgroup svn_string String handling
90  * @{
91  */
92 
93 
94 
95 /** A simple counted string. */
96 typedef struct svn_string_t
97 {
98  const char *data; /**< pointer to the bytestring */
99  apr_size_t len; /**< length of bytestring */
100 } svn_string_t;
101 
102 /** A buffered string, capable of appending without an allocation and copy
103  * for each append. */
104 typedef struct svn_stringbuf_t
105 {
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.
109  */
110  apr_pool_t *pool;
111 
112  /** pointer to the bytestring */
113  char *data;
114 
115  /** length of bytestring */
116  apr_size_t len;
117 
118  /** total size of buffer allocated */
119  apr_size_t blocksize;
121 
122 
123 /**
124  * @defgroup svn_string_svn_string_t svn_string_t functions
125  * @{
126  */
127 
128 /** Create a new bytestring containing a C string (NULL-terminated). */
129 svn_string_t *
130 svn_string_create(const char *cstring, apr_pool_t *pool);
131 
132 /** Create a new bytestring containing a generic string of bytes
133  * (NOT NULL-terminated) */
134 svn_string_t *
135 svn_string_ncreate(const char *bytes, apr_size_t size, apr_pool_t *pool);
136 
137 /** Create a new string with the contents of the given stringbuf */
138 svn_string_t *
139 svn_string_create_from_buf(const svn_stringbuf_t *strbuf, apr_pool_t *pool);
140 
141 /** Create a new bytestring by formatting @a cstring (NULL-terminated)
142  * from varargs, which are as appropriate for apr_psprintf().
143  */
144 svn_string_t *
145 svn_string_createf(apr_pool_t *pool, const char *fmt, ...)
146  __attribute__((format(printf, 2, 3)));
147 
148 /** Create a new bytestring by formatting @a cstring (NULL-terminated)
149  * from a @c va_list (see svn_stringbuf_createf()).
150  */
151 svn_string_t *
152 svn_string_createv(apr_pool_t *pool, const char *fmt, va_list ap)
153  __attribute__((format(printf, 2, 0)));
154 
155 /** Return TRUE if a bytestring is empty (has length zero). */
157 svn_string_isempty(const svn_string_t *str);
158 
159 /** Return a duplicate of @a original_string. */
160 svn_string_t *
161 svn_string_dup(const svn_string_t *original_string, apr_pool_t *pool);
162 
163 /** Return @c TRUE iff @a str1 and @a str2 have identical length and data. */
165 svn_string_compare(const svn_string_t *str1, const svn_string_t *str2);
166 
167 /** Return offset of first non-whitespace character in @a str, or return
168  * @a str->len if none.
169  */
170 apr_size_t
172 
173 /** Return position of last occurrence of @a ch in @a str, or return
174  * @a str->len if no occurrence.
175  */
176 apr_size_t
177 svn_string_find_char_backward(const svn_string_t *str, char ch);
178 
179 /** @} */
180 
181 
182 /**
183  * @defgroup svn_string_svn_stringbuf_t svn_stringbuf_t functions
184  * @{
185  */
186 
187 /** Create a new bytestring containing a C string (NULL-terminated). */
189 svn_stringbuf_create(const char *cstring, apr_pool_t *pool);
190 
191 /** Create a new bytestring containing a generic string of bytes
192  * (NON-NULL-terminated)
193  */
195 svn_stringbuf_ncreate(const char *bytes, apr_size_t size, apr_pool_t *pool);
196 
197 /** Create a new empty bytestring with at least @a minimum_size bytes of
198  * space available in the memory block.
199  *
200  * The allocated string buffer will be one byte larger than @a minimum_size
201  * to account for a final '\\0'.
202  *
203  * @since New in 1.6.
204  */
206 svn_stringbuf_create_ensure(apr_size_t minimum_size, apr_pool_t *pool);
207 
208 /** Create a new stringbuf with the contents of the given string */
210 svn_stringbuf_create_from_string(const svn_string_t *str, apr_pool_t *pool);
211 
212 /** Create a new bytestring by formatting @a cstring (NULL-terminated)
213  * from varargs, which are as appropriate for apr_psprintf().
214  */
216 svn_stringbuf_createf(apr_pool_t *pool, const char *fmt, ...)
217  __attribute__((format(printf, 2, 3)));
218 
219 /** Create a new bytestring by formatting @a cstring (NULL-terminated)
220  * from a @c va_list (see svn_stringbuf_createf()).
221  */
223 svn_stringbuf_createv(apr_pool_t *pool, const char *fmt, va_list ap)
224  __attribute__((format(printf, 2, 0)));
225 
226 /** Make sure that the string @a str has at least @a minimum_size bytes of
227  * space available in the memory block.
228  *
229  * (@a minimum_size should include space for the terminating NULL character.)
230  */
231 void
232 svn_stringbuf_ensure(svn_stringbuf_t *str, apr_size_t minimum_size);
233 
234 /** Set a bytestring @a str to @a value */
235 void
236 svn_stringbuf_set(svn_stringbuf_t *str, const char *value);
237 
238 /** Set a bytestring @a str to empty (0 length). */
239 void
241 
242 /** Return @c TRUE if a bytestring is empty (has length zero). */
245 
246 /** Chop @a nbytes bytes off end of @a str, but not more than @a str->len. */
247 void
248 svn_stringbuf_chop(svn_stringbuf_t *str, apr_size_t nbytes);
249 
250 /** Fill bytestring @a str with character @a c. */
251 void
252 svn_stringbuf_fillchar(svn_stringbuf_t *str, unsigned char c);
253 
254 /** Append a single character @a byte onto @a targetstr.
255  * This is an optimized version of svn_stringbuf_appendbytes()
256  * that is much faster to call and execute. Gains vary with the ABI.
257  * The advantages extend beyond the actual call because the reduced
258  * register pressure allows for more optimization within the caller.
259  *
260  * reallocs if necessary. @a targetstr is affected, nothing else is.
261  * @since New in 1.7.
262  */
263 void
265  char byte);
266 
267 /** Append an array of bytes onto @a targetstr.
268  *
269  * reallocs if necessary. @a targetstr is affected, nothing else is.
270  */
271 void
273  const char *bytes,
274  apr_size_t count);
275 
276 /** Append an @c svn_stringbuf_t onto @a targetstr.
277  *
278  * reallocs if necessary. @a targetstr is affected, nothing else is.
279  */
280 void
282  const svn_stringbuf_t *appendstr);
283 
284 /** Append a C string onto @a targetstr.
285  *
286  * reallocs if necessary. @a targetstr is affected, nothing else is.
287  */
288 void
290  const char *cstr);
291 
292 /** Return a duplicate of @a original_string. */
294 svn_stringbuf_dup(const svn_stringbuf_t *original_string, apr_pool_t *pool);
295 
296 /** Return @c TRUE iff @a str1 and @a str2 have identical length and data. */
299  const svn_stringbuf_t *str2);
300 
301 /** Return offset of first non-whitespace character in @a str, or return
302  * @a str->len if none.
303  */
304 apr_size_t
306 
307 /** Strip whitespace from both sides of @a str (modified in place). */
308 void
310 
311 /** Return position of last occurrence of @a ch in @a str, or return
312  * @a str->len if no occurrence.
313  */
314 apr_size_t
316 
317 /** Return @c TRUE iff @a str1 and @a str2 have identical length and data. */
320  const svn_stringbuf_t *str2);
321 
322 /** @} */
323 
324 
325 /**
326  * @defgroup svn_string_cstrings C string functions
327  * @{
328  */
329 
330 /** Divide @a input into substrings along @a sep_chars boundaries, return an
331  * array of copies of those substrings (plain const char*), allocating both
332  * the array and the copies in @a pool.
333  *
334  * None of the elements added to the array contain any of the
335  * characters in @a sep_chars, and none of the new elements are empty
336  * (thus, it is possible that the returned array will have length
337  * zero).
338  *
339  * If @a chop_whitespace is TRUE, then remove leading and trailing
340  * whitespace from the returned strings.
341  */
342 apr_array_header_t *
343 svn_cstring_split(const char *input,
344  const char *sep_chars,
345  svn_boolean_t chop_whitespace,
346  apr_pool_t *pool);
347 
348 /** Like svn_cstring_split(), but append to existing @a array instead of
349  * creating a new one. Allocate the copied substrings in @a pool
350  * (i.e., caller decides whether or not to pass @a array->pool as @a pool).
351  */
352 void
353 svn_cstring_split_append(apr_array_header_t *array,
354  const char *input,
355  const char *sep_chars,
356  svn_boolean_t chop_whitespace,
357  apr_pool_t *pool);
358 
359 
360 /** Return @c TRUE iff @a str matches any of the elements of @a list, a list
361  * of zero or more glob patterns.
362  */
364 svn_cstring_match_glob_list(const char *str, const apr_array_header_t *list);
365 
366 /** Return @c TRUE iff @a str exactly matches any of the elements of @a list.
367  *
368  * @since new in 1.7
369  */
371 svn_cstring_match_list(const char *str, const apr_array_header_t *list);
372 
373 /**
374  * Return the number of line breaks in @a msg, allowing any kind of newline
375  * termination (CR, LF, CRLF, or LFCR), even inconsistent.
376  *
377  * @since New in 1.2.
378  */
379 int
380 svn_cstring_count_newlines(const char *msg);
381 
382 /**
383  * Return a cstring which is the concatenation of @a strings (an array
384  * of char *) each followed by @a separator (that is, @a separator
385  * will also end the resulting string). Allocate the result in @a pool.
386  * If @a strings is empty, then return the empty string.
387  *
388  * @since New in 1.2.
389  */
390 char *
391 svn_cstring_join(const apr_array_header_t *strings,
392  const char *separator,
393  apr_pool_t *pool);
394 
395 /**
396  * Compare two strings @a atr1 and @a atr2, treating case-equivalent
397  * unaccented Latin (ASCII subset) letters as equal.
398  *
399  * Returns in integer greater than, equal to, or less than 0,
400  * according to whether @a str1 is considered greater than, equal to,
401  * or less than @a str2.
402  *
403  * @since New in 1.5.
404  */
405 int
406 svn_cstring_casecmp(const char *str1, const char *str2);
407 
408 /**
409  * Parse the C string @a str into a 64 bit number, and return it in @a *n.
410  * Assume that the number is represented in base @a base.
411  * Raise an error if conversion fails (e.g. due to overflow), or if the
412  * converted number is smaller than @a minval or larger than @a maxval.
413  *
414  * @since New in 1.7.
415  */
416 svn_error_t *
417 svn_cstring_strtoi64(apr_int64_t *n, const char *str,
418  apr_int64_t minval, apr_int64_t maxval,
419  int base);
420 
421 /**
422  * Parse the C string @a str into a 64 bit number, and return it in @a *n.
423  * Assume that the number is represented in base 10.
424  * Raise an error if conversion fails (e.g. due to overflow).
425  *
426  * @since New in 1.7.
427  */
428 svn_error_t *
429 svn_cstring_atoi64(apr_int64_t *n, const char *str);
430 
431 /**
432  * Parse the C string @a str into a 32 bit number, and return it in @a *n.
433  * Assume that the number is represented in base 10.
434  * Raise an error if conversion fails (e.g. due to overflow).
435  *
436  * @since New in 1.7.
437  */
438 svn_error_t *
439 svn_cstring_atoi(int *n, const char *str);
440 
441 /**
442  * Parse the C string @a str into an unsigned 64 bit number, and return
443  * it in @a *n. Assume that the number is represented in base @a base.
444  * Raise an error if conversion fails (e.g. due to overflow), or if the
445  * converted number is smaller than @a minval or larger than @a maxval.
446  *
447  * @since New in 1.7.
448  */
449 svn_error_t *
450 svn_cstring_strtoui64(apr_uint64_t *n, const char *str,
451  apr_uint64_t minval, apr_uint64_t maxval,
452  int base);
453 
454 /**
455  * Parse the C string @a str into an unsigned 64 bit number, and return
456  * it in @a *n. Assume that the number is represented in base 10.
457  * Raise an error if conversion fails (e.g. due to overflow).
458  *
459  * @since New in 1.7.
460  */
461 svn_error_t *
462 svn_cstring_atoui64(apr_uint64_t *n, const char *str);
463 
464 /**
465  * Parse the C string @a str into an unsigned 32 bit number, and return
466  * it in @a *n. Assume that the number is represented in base 10.
467  * Raise an error if conversion fails (e.g. due to overflow).
468  *
469  * @since New in 1.7.
470  */
471 svn_error_t *
472 svn_cstring_atoui(unsigned int *n, const char *str);
473 
474 /** @} */
475 
476 /** @} */
477 
478 
479 #ifdef __cplusplus
480 }
481 #endif /* __cplusplus */
482 
483 #endif /* SVN_STRING_H */