Followup to r29625: fix getopt tests.
[svn.git] / subversion / include / svn_string.h
blob9f1d3d27e5b246d8ea0551aa83a9d1022a23c784
1 /**
2 * @copyright
3 * ====================================================================
4 * Copyright (c) 2000-2006 CollabNet. All rights reserved.
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.
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
18 * @file svn_string.h
19 * @brief Counted-length strings for Subversion, plus some C string goodies.
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.
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.
33 * @c svn_stringbuf_t uses a plain <tt>char *</tt> for its data, so it is
34 * most appropriate for modifiable data.
36 * <h3>Invariants</h3>
38 * 1. Null termination:
40 * Both structures maintain a significant invariant:
42 * <tt>s->data[s->len] == '\\0'</tt>
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.
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.
56 * 2. Non-NULL input:
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.
65 #ifndef SVN_STRING_H
66 #define SVN_STRING_H
68 #include <apr.h>
69 #include <apr_tables.h>
70 #include <apr_pools.h> /* APR memory pools for everyone. */
71 #include <apr_strings.h>
73 #include "svn_types.h"
75 #ifdef __cplusplus
76 extern "C" {
77 #endif /* __cplusplus */
79 /**
80 * @defgroup svn_string String handling
81 * @{
86 /** A simple counted string. */
87 typedef struct svn_string_t
89 const char *data; /**< pointer to the bytestring */
90 apr_size_t len; /**< length of bytestring */
91 } svn_string_t;
93 /** A buffered string, capable of appending without an allocation and copy
94 * for each append. */
95 typedef struct svn_stringbuf_t
97 /** a pool from which this string was originally allocated, and is not
98 * necessarily specific to this string. This is used only for allocating
99 * more memory from when the string needs to grow.
101 apr_pool_t *pool;
103 /** pointer to the bytestring */
104 char *data;
106 /** length of bytestring */
107 apr_size_t len;
109 /** total size of buffer allocated */
110 apr_size_t blocksize;
111 } svn_stringbuf_t;
114 /** svn_string_t functions.
116 * @defgroup svn_string_svn_string_t svn_string_t functions
117 * @{
120 /** Create a new bytestring containing a C string (NULL-terminated). */
121 svn_string_t *svn_string_create(const char *cstring,
122 apr_pool_t *pool);
124 /** Create a new bytestring containing a generic string of bytes
125 * (NOT NULL-terminated) */
126 svn_string_t *svn_string_ncreate(const char *bytes,
127 apr_size_t size,
128 apr_pool_t *pool);
130 /** Create a new string with the contents of the given stringbuf */
131 svn_string_t *svn_string_create_from_buf(const svn_stringbuf_t *strbuf,
132 apr_pool_t *pool);
134 /** Create a new bytestring by formatting @a cstring (NULL-terminated)
135 * from varargs, which are as appropriate for apr_psprintf().
137 svn_string_t *svn_string_createf(apr_pool_t *pool,
138 const char *fmt,
139 ...)
140 __attribute__((format(printf, 2, 3)));
142 /** Create a new bytestring by formatting @a cstring (NULL-terminated)
143 * from a @c va_list (see svn_stringbuf_createf()).
145 svn_string_t *svn_string_createv(apr_pool_t *pool,
146 const char *fmt,
147 va_list ap)
148 __attribute__((format(printf, 2, 0)));
150 /** Return TRUE if a bytestring is empty (has length zero). */
151 svn_boolean_t svn_string_isempty(const svn_string_t *str);
153 /** Return a duplicate of @a original_string. */
154 svn_string_t *svn_string_dup(const svn_string_t *original_string,
155 apr_pool_t *pool);
157 /** Return @c TRUE iff @a str1 and @a str2 have identical length and data. */
158 svn_boolean_t svn_string_compare(const svn_string_t *str1,
159 const svn_string_t *str2);
161 /** Return offset of first non-whitespace character in @a str, or return
162 * @a str->len if none.
164 apr_size_t svn_string_first_non_whitespace(const svn_string_t *str);
166 /** Return position of last occurrence of @a ch in @a str, or return
167 * @a str->len if no occurrence.
169 apr_size_t svn_string_find_char_backward(const svn_string_t *str, char ch);
171 /** @} */
174 /** svn_stringbuf_t functions.
176 * @defgroup svn_string_svn_stringbuf_t svn_stringbuf_t functions
177 * @{
180 /** Create a new bytestring containing a C string (NULL-terminated). */
181 svn_stringbuf_t *svn_stringbuf_create(const char *cstring,
182 apr_pool_t *pool);
183 /** Create a new bytestring containing a generic string of bytes
184 * (NON-NULL-terminated)
186 svn_stringbuf_t *svn_stringbuf_ncreate(const char *bytes,
187 apr_size_t size,
188 apr_pool_t *pool);
189 /** Create a new empty bytestring with at least @a minimum_size bytes of
190 * space available in the memory block.
192 * (@a minimum_size should include space for the terminating NULL character.)
194 * @since New in 1.6.
196 svn_stringbuf_t *svn_stringbuf_create_ensure(apr_size_t minimum_size,
197 apr_pool_t *pool);
199 /** Create a new stringbuf with the contents of the given string */
200 svn_stringbuf_t *svn_stringbuf_create_from_string(const svn_string_t *str,
201 apr_pool_t *pool);
203 /** Create a new bytestring by formatting @a cstring (NULL-terminated)
204 * from varargs, which are as appropriate for apr_psprintf().
206 svn_stringbuf_t *svn_stringbuf_createf(apr_pool_t *pool,
207 const char *fmt,
208 ...)
209 __attribute__((format(printf, 2, 3)));
211 /** Create a new bytestring by formatting @a cstring (NULL-terminated)
212 * from a @c va_list (see svn_stringbuf_createf()).
214 svn_stringbuf_t *svn_stringbuf_createv(apr_pool_t *pool,
215 const char *fmt,
216 va_list ap)
217 __attribute__((format(printf, 2, 0)));
219 /** Make sure that the string @a str has at least @a minimum_size bytes of
220 * space available in the memory block.
222 * (@a minimum_size should include space for the terminating NULL character.)
224 void svn_stringbuf_ensure(svn_stringbuf_t *str,
225 apr_size_t minimum_size);
227 /** Set a bytestring @a str to @a value */
228 void svn_stringbuf_set(svn_stringbuf_t *str, const char *value);
230 /** Set a bytestring @a str to empty (0 length). */
231 void svn_stringbuf_setempty(svn_stringbuf_t *str);
233 /** Return @c TRUE if a bytestring is empty (has length zero). */
234 svn_boolean_t svn_stringbuf_isempty(const svn_stringbuf_t *str);
236 /** Chop @a nbytes bytes off end of @a str, but not more than @a str->len. */
237 void svn_stringbuf_chop(svn_stringbuf_t *str, apr_size_t nbytes);
239 /** Fill bytestring @a str with character @a c. */
240 void svn_stringbuf_fillchar(svn_stringbuf_t *str, unsigned char c);
242 /** Append an array of bytes onto @a targetstr.
244 * reallocs if necessary. @a targetstr is affected, nothing else is.
246 void svn_stringbuf_appendbytes(svn_stringbuf_t *targetstr,
247 const char *bytes,
248 apr_size_t count);
250 /** Append an @c svn_stringbuf_t onto @a targetstr.
252 * reallocs if necessary. @a targetstr is affected, nothing else is.
254 void svn_stringbuf_appendstr(svn_stringbuf_t *targetstr,
255 const svn_stringbuf_t *appendstr);
257 /** Append a C string onto @a targetstr.
259 * reallocs if necessary. @a targetstr is affected, nothing else is.
261 void svn_stringbuf_appendcstr(svn_stringbuf_t *targetstr,
262 const char *cstr);
264 /** Return a duplicate of @a original_string. */
265 svn_stringbuf_t *svn_stringbuf_dup(const svn_stringbuf_t *original_string,
266 apr_pool_t *pool);
269 /** Return @c TRUE iff @a str1 and @a str2 have identical length and data. */
270 svn_boolean_t svn_stringbuf_compare(const svn_stringbuf_t *str1,
271 const svn_stringbuf_t *str2);
273 /** Return offset of first non-whitespace character in @a str, or return
274 * @a str->len if none.
276 apr_size_t svn_stringbuf_first_non_whitespace(const svn_stringbuf_t *str);
278 /** Strip whitespace from both sides of @a str (modified in place). */
279 void svn_stringbuf_strip_whitespace(svn_stringbuf_t *str);
281 /** Return position of last occurrence of @a ch in @a str, or return
282 * @a str->len if no occurrence.
284 apr_size_t svn_stringbuf_find_char_backward(const svn_stringbuf_t *str,
285 char ch);
287 /** Return @c TRUE iff @a str1 and @a str2 have identical length and data. */
288 svn_boolean_t svn_string_compare_stringbuf(const svn_string_t *str1,
289 const svn_stringbuf_t *str2);
291 /** @} */
294 /** C strings.
296 * @defgroup svn_string_cstrings c string functions
297 * @{
300 /** Divide @a input into substrings along @a sep_chars boundaries, return an
301 * array of copies of those substrings, allocating both the array and
302 * the copies in @a pool.
304 * None of the elements added to the array contain any of the
305 * characters in @a sep_chars, and none of the new elements are empty
306 * (thus, it is possible that the returned array will have length
307 * zero).
309 * If @a chop_whitespace is TRUE, then remove leading and trailing
310 * whitespace from the returned strings.
312 apr_array_header_t *svn_cstring_split(const char *input,
313 const char *sep_chars,
314 svn_boolean_t chop_whitespace,
315 apr_pool_t *pool);
317 /** Like svn_cstring_split(), but append to existing @a array instead of
318 * creating a new one. Allocate the copied substrings in @a pool
319 * (i.e., caller decides whether or not to pass @a array->pool as @a pool).
321 void svn_cstring_split_append(apr_array_header_t *array,
322 const char *input,
323 const char *sep_chars,
324 svn_boolean_t chop_whitespace,
325 apr_pool_t *pool);
328 /** Return @c TRUE iff @a str matches any of the elements of @a list, a list
329 * of zero or more glob patterns.
331 svn_boolean_t svn_cstring_match_glob_list(const char *str,
332 apr_array_header_t *list);
335 * Return the number of line breaks in @a msg, allowing any kind of newline
336 * termination (CR, LF, CRLF, or LFCR), even inconsistent.
338 * @since New in 1.2.
340 int svn_cstring_count_newlines(const char *msg);
343 * Return a cstring which is the concatenation of @a strings (an array
344 * of char *) each followed by @a separator (that is, @a separator
345 * will also end the resulting string). Allocate the result in @a pool.
346 * If @a strings is empty, then return the empty string.
348 * @since New in 1.2.
350 char *
351 svn_cstring_join(apr_array_header_t *strings,
352 const char *separator,
353 apr_pool_t *pool);
356 * Compare two strings @a atr1 and @a atr2, treating case-equivalent
357 * unaccented Latin (ASCII subset) letters as equal.
359 * @since New in 1.5.
361 int svn_cstring_casecmp(const char *str1, const char *str2);
364 /** @} */
366 /** @} */
369 #ifdef __cplusplus
371 #endif /* __cplusplus */
373 #endif /* SVN_STRING_H */