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  * Copyright (c) 2000-2006 CollabNet. All rights reserved.
5  *
6  * This software is licensed as described in the file COPYING, which
7  * you should have received as part of this distribution. The terms
8  * are also available at http://subversion.tigris.org/license-1.html.
9  * If newer versions of this license are posted there, you may use a
10  * newer version instead, at your option.
11  *
12  * This software consists of voluntary contributions made by many
13  * individuals. For exact contribution history, see the revision
14  * history and logs, available at http://subversion.tigris.org/.
15  * ====================================================================
16  * @endcopyright
17  *
18  * @file svn_string.h
19  * @brief Counted-length strings for Subversion, plus some C string goodies.
20  *
21  * There are two string datatypes: @c svn_string_t and @c svn_stringbuf_t.
22  * The former is a simple pointer/length pair useful for passing around
23  * strings (or arbitrary bytes) with a counted length. @c svn_stringbuf_t is
24  * buffered to enable efficient appending of strings without an allocation
25  * and copy for each append operation.
26  *
27  * @c svn_string_t contains a <tt>const char *</tt> for its data, so it is
28  * most appropriate for constant data and for functions which expect constant,
29  * counted data. Functions should generally use <tt>const @c svn_string_t
30  * *</tt> as their parameter to indicate they are expecting a constant,
31  * counted string.
32  *
33  * @c svn_stringbuf_t uses a plain <tt>char *</tt> for its data, so it is
34  * most appropriate for modifiable data.
35  *
36  * <h3>Invariants</h3>
37  *
38  * 1. Null termination:
39  *
40  * Both structures maintain a significant invariant:
41  *
42  * <tt>s->data[s->len] == '\\0'</tt>
43  *
44  * The functions defined within this header file will maintain
45  * the invariant (which does imply that memory is
46  * allocated/defined as @c len+1 bytes). If code outside of the
47  * @c svn_string.h functions manually builds these structures,
48  * then they must enforce this invariant.
49  *
50  * Note that an @c svn_string(buf)_t may contain binary data,
51  * which means that strlen(s->data) does not have to equal @c
52  * s->len. The NULL terminator is provided to make it easier to
53  * pass @c s->data to C string interfaces.
54  *
55  *
56  * 2. Non-NULL input:
57  *
58  * All the functions assume their input data is non-NULL,
59  * unless otherwise documented, and may seg fault if passed
60  * NULL. The input data may *contain* null bytes, of course, just
61  * the data pointer itself must not be NULL.
62  *
63  * <h3>Memory allocation</h3>
64  *
65  * All the functions make a deep copy of all input data, and never store
66  * a pointer to the original input data.
67  */
68 
69 
70 #ifndef SVN_STRING_H
71 #define SVN_STRING_H
72 
73 #include <apr.h> /* for apr_size_t */
74 #include <apr_pools.h> /* for apr_pool_t */
75 #include <apr_tables.h> /* for apr_array_header_t */
76 
77 #include "svn_types.h" /* for svn_boolean_t, svn_error_t */
78 
79 #ifdef __cplusplus
80 extern "C" {
81 #endif /* __cplusplus */
82 
83 /**
84  * @defgroup svn_string String handling
85  * @{
86  */
87 
88 
89 
90 /** A simple counted string. */
91 typedef struct svn_string_t
92 {
93  const char *data; /**< pointer to the bytestring */
94  apr_size_t len; /**< length of bytestring */
95 } svn_string_t;
96 
97 /** A buffered string, capable of appending without an allocation and copy
98  * for each append. */
99 typedef struct svn_stringbuf_t
100 {
101  /** a pool from which this string was originally allocated, and is not
102  * necessarily specific to this string. This is used only for allocating
103  * more memory from when the string needs to grow.
104  */
105  apr_pool_t *pool;
106 
107  /** pointer to the bytestring */
108  char *data;
109 
110  /** length of bytestring */
111  apr_size_t len;
112 
113  /** total size of buffer allocated */
114  apr_size_t blocksize;
116 
117 
118 /** svn_string_t functions.
119  *
120  * @defgroup svn_string_svn_string_t svn_string_t functions
121  * @{
122  */
123 
124 /** Create a new bytestring containing a C string (NULL-terminated). */
125 svn_string_t *
126 svn_string_create(const char *cstring, apr_pool_t *pool);
127 
128 /** Create a new bytestring containing a generic string of bytes
129  * (NOT NULL-terminated) */
130 svn_string_t *
131 svn_string_ncreate(const char *bytes, apr_size_t size, apr_pool_t *pool);
132 
133 /** Create a new string with the contents of the given stringbuf */
134 svn_string_t *
135 svn_string_create_from_buf(const svn_stringbuf_t *strbuf, apr_pool_t *pool);
136 
137 /** Create a new bytestring by formatting @a cstring (NULL-terminated)
138  * from varargs, which are as appropriate for apr_psprintf().
139  */
140 svn_string_t *
141 svn_string_createf(apr_pool_t *pool, const char *fmt, ...)
142  __attribute__((format(printf, 2, 3)));
143 
144 /** Create a new bytestring by formatting @a cstring (NULL-terminated)
145  * from a @c va_list (see svn_stringbuf_createf()).
146  */
147 svn_string_t *
148 svn_string_createv(apr_pool_t *pool, const char *fmt, va_list ap)
149  __attribute__((format(printf, 2, 0)));
150 
151 /** Return TRUE if a bytestring is empty (has length zero). */
153 svn_string_isempty(const svn_string_t *str);
154 
155 /** Return a duplicate of @a original_string. */
156 svn_string_t *
157 svn_string_dup(const svn_string_t *original_string, apr_pool_t *pool);
158 
159 /** Return @c TRUE iff @a str1 and @a str2 have identical length and data. */
161 svn_string_compare(const svn_string_t *str1, const svn_string_t *str2);
162 
163 /** Return offset of first non-whitespace character in @a str, or return
164  * @a str->len if none.
165  */
166 apr_size_t
168 
169 /** Return position of last occurrence of @a ch in @a str, or return
170  * @a str->len if no occurrence.
171  */
172 apr_size_t
173 svn_string_find_char_backward(const svn_string_t *str, char ch);
174 
175 /** @} */
176 
177 
178 /** svn_stringbuf_t functions.
179  *
180  * @defgroup svn_string_svn_stringbuf_t svn_stringbuf_t functions
181  * @{
182  */
183 
184 /** Create a new bytestring containing a C string (NULL-terminated). */
186 svn_stringbuf_create(const char *cstring, apr_pool_t *pool);
187 /** Create a new bytestring containing a generic string of bytes
188  * (NON-NULL-terminated)
189  */
191 svn_stringbuf_ncreate(const char *bytes, apr_size_t size, apr_pool_t *pool);
192 /** Create a new empty bytestring with at least @a minimum_size bytes of
193  * space available in the memory block.
194  *
195  * The allocated string buffer will be one byte larger then @a size to account
196  * for a final '\0'.
197  *
198  * @since New in 1.6.
199  */
201 svn_stringbuf_create_ensure(apr_size_t minimum_size, apr_pool_t *pool);
202 
203 /** Create a new stringbuf with the contents of the given string */
205 svn_stringbuf_create_from_string(const svn_string_t *str, apr_pool_t *pool);
206 
207 /** Create a new bytestring by formatting @a cstring (NULL-terminated)
208  * from varargs, which are as appropriate for apr_psprintf().
209  */
211 svn_stringbuf_createf(apr_pool_t *pool, const char *fmt, ...)
212  __attribute__((format(printf, 2, 3)));
213 
214 /** Create a new bytestring by formatting @a cstring (NULL-terminated)
215  * from a @c va_list (see svn_stringbuf_createf()).
216  */
218 svn_stringbuf_createv(apr_pool_t *pool, const char *fmt, va_list ap)
219  __attribute__((format(printf, 2, 0)));
220 
221 /** Make sure that the string @a str has at least @a minimum_size bytes of
222  * space available in the memory block.
223  *
224  * (@a minimum_size should include space for the terminating NULL character.)
225  */
226 void
227 svn_stringbuf_ensure(svn_stringbuf_t *str, apr_size_t minimum_size);
228 
229 /** Set a bytestring @a str to @a value */
230 void
231 svn_stringbuf_set(svn_stringbuf_t *str, const char *value);
232 
233 /** Set a bytestring @a str to empty (0 length). */
234 void
236 
237 /** Return @c TRUE if a bytestring is empty (has length zero). */
240 
241 /** Chop @a nbytes bytes off end of @a str, but not more than @a str->len. */
242 void
243 svn_stringbuf_chop(svn_stringbuf_t *str, apr_size_t nbytes);
244 
245 /** Fill bytestring @a str with character @a c. */
246 void
247 svn_stringbuf_fillchar(svn_stringbuf_t *str, unsigned char c);
248 
249 /** Append an array of bytes onto @a targetstr.
250  *
251  * reallocs if necessary. @a targetstr is affected, nothing else is.
252  */
253 void
255  const char *bytes,
256  apr_size_t count);
257 
258 /** Append an @c svn_stringbuf_t onto @a targetstr.
259  *
260  * reallocs if necessary. @a targetstr is affected, nothing else is.
261  */
262 void
264  const svn_stringbuf_t *appendstr);
265 
266 /** Append a C string onto @a targetstr.
267  *
268  * reallocs if necessary. @a targetstr is affected, nothing else is.
269  */
270 void
272  const char *cstr);
273 
274 /** Return a duplicate of @a original_string. */
276 svn_stringbuf_dup(const svn_stringbuf_t *original_string, apr_pool_t *pool);
277 
278 /** Return @c TRUE iff @a str1 and @a str2 have identical length and data. */
281  const svn_stringbuf_t *str2);
282 
283 /** Return offset of first non-whitespace character in @a str, or return
284  * @a str->len if none.
285  */
286 apr_size_t
288 
289 /** Strip whitespace from both sides of @a str (modified in place). */
290 void
292 
293 /** Return position of last occurrence of @a ch in @a str, or return
294  * @a str->len if no occurrence.
295  */
296 apr_size_t
298 
299 /** Return @c TRUE iff @a str1 and @a str2 have identical length and data. */
302  const svn_stringbuf_t *str2);
303 
304 /** @} */
305 
306 
307 /** C strings.
308  *
309  * @defgroup svn_string_cstrings c string functions
310  * @{
311  */
312 
313 /** Divide @a input into substrings along @a sep_chars boundaries, return an
314  * array of copies of those substrings, allocating both the array and
315  * the copies in @a pool.
316  *
317  * None of the elements added to the array contain any of the
318  * characters in @a sep_chars, and none of the new elements are empty
319  * (thus, it is possible that the returned array will have length
320  * zero).
321  *
322  * If @a chop_whitespace is TRUE, then remove leading and trailing
323  * whitespace from the returned strings.
324  */
325 apr_array_header_t *
326 svn_cstring_split(const char *input,
327  const char *sep_chars,
328  svn_boolean_t chop_whitespace,
329  apr_pool_t *pool);
330 
331 /** Like svn_cstring_split(), but append to existing @a array instead of
332  * creating a new one. Allocate the copied substrings in @a pool
333  * (i.e., caller decides whether or not to pass @a array->pool as @a pool).
334  */
335 void
336 svn_cstring_split_append(apr_array_header_t *array,
337  const char *input,
338  const char *sep_chars,
339  svn_boolean_t chop_whitespace,
340  apr_pool_t *pool);
341 
342 
343 /** Return @c TRUE iff @a str matches any of the elements of @a list, a list
344  * of zero or more glob patterns.
345  */
347 svn_cstring_match_glob_list(const char *str, apr_array_header_t *list);
348 
349 /**
350  * Return the number of line breaks in @a msg, allowing any kind of newline
351  * termination (CR, LF, CRLF, or LFCR), even inconsistent.
352  *
353  * @since New in 1.2.
354  */
355 int
356 svn_cstring_count_newlines(const char *msg);
357 
358 /**
359  * Return a cstring which is the concatenation of @a strings (an array
360  * of char *) each followed by @a separator (that is, @a separator
361  * will also end the resulting string). Allocate the result in @a pool.
362  * If @a strings is empty, then return the empty string.
363  *
364  * @since New in 1.2.
365  */
366 char *
367 svn_cstring_join(const apr_array_header_t *strings,
368  const char *separator,
369  apr_pool_t *pool);
370 
371 /**
372  * Compare two strings @a atr1 and @a atr2, treating case-equivalent
373  * unaccented Latin (ASCII subset) letters as equal.
374  *
375  * Returns in integer greater than, equal to, or less than 0,
376  * according to whether @a str1 is considered greater than, equal to,
377  * or less than @a str2.
378  *
379  * @since New in 1.5.
380  */
381 int
382 svn_cstring_casecmp(const char *str1, const char *str2);
383 
384 
385 /** @} */
386 
387 /** @} */
388 
389 
390 #ifdef __cplusplus
391 }
392 #endif /* __cplusplus */
393 
394 #endif /* SVN_STRING_H */