3 * ====================================================================
4 * Copyright (c) 2000-2004 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 * ====================================================================
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,
33 * @c svn_stringbuf_t uses a plain <tt>char *</tt> for its data, so it is
34 * most appropriate for modifiable data.
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.
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.
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"
77 #endif /* __cplusplus */
82 /** A simple counted string. */
83 typedef struct svn_string_t
85 const char *data
; /**< pointer to the bytestring */
86 apr_size_t len
; /**< length of bytestring */
89 /** A buffered string, capable of appending without an allocation and copy
91 typedef struct svn_stringbuf_t
93 /** a pool from which this string was originally allocated, and is not
94 * necessarily specific to this string. This is used only for allocating
95 * more memory from when the string needs to grow.
99 /** pointer to the bytestring */
102 /** length of bytestring */
105 /** total size of buffer allocated */
106 apr_size_t blocksize
;
110 /** svn_string_t functions.
112 * @defgroup svn_string_svn_string_t svn_string_t functions
116 /** Create a new bytestring containing a C string (null-terminated). */
117 svn_string_t
*svn_string_create(const char *cstring
,
120 /** Create a new bytestring containing a generic string of bytes
121 * (NOT null-terminated) */
122 svn_string_t
*svn_string_ncreate(const char *bytes
,
126 /** Create a new string with the contents of the given stringbuf */
127 svn_string_t
*svn_string_create_from_buf(const svn_stringbuf_t
*strbuf
,
130 /** Create a new bytestring by formatting @a cstring (null-terminated)
131 * from varargs, which are as appropriate for apr_psprintf().
133 svn_string_t
*svn_string_createf(apr_pool_t
*pool
,
136 __attribute__ ((format(printf
, 2, 3)));
138 /** Create a new bytestring by formatting @a cstring (null-terminated)
139 * from a @c va_list (see svn_stringbuf_createf()).
141 svn_string_t
*svn_string_createv(apr_pool_t
*pool
,
144 __attribute__ ((format(printf
, 2, 0)));
146 /** Return true if a bytestring is empty (has length zero). */
147 svn_boolean_t
svn_string_isempty(const svn_string_t
*str
);
149 /** Return a duplicate of @a original_string. */
150 svn_string_t
*svn_string_dup(const svn_string_t
*original_string
,
153 /** Return @c TRUE iff @a str1 and @c str2 have identical length and data. */
154 svn_boolean_t
svn_string_compare(const svn_string_t
*str1
,
155 const svn_string_t
*str2
);
157 /** Return offset of first non-whitespace character in @a str, or return
158 * @a str->len if none.
160 apr_size_t
svn_string_first_non_whitespace(const svn_string_t
*str
);
162 /** Return position of last occurrence of @a char in @a str, or return
163 * @a str->len if no occurrence.
165 apr_size_t
svn_string_find_char_backward(const svn_string_t
*str
, char ch
);
170 /** svn_stringbuf_t functions.
172 * @defgroup svn_string_svn_stringbuf_t svn_stringbuf_t functions
176 /** Create a new bytestring containing a C string (null-terminated). */
177 svn_stringbuf_t
*svn_stringbuf_create(const char *cstring
,
179 /** Create a new bytestring containing a generic string of bytes
180 * (NON-null-terminated)
182 svn_stringbuf_t
*svn_stringbuf_ncreate(const char *bytes
,
186 /** Create a new stringbuf with the contents of the given string */
187 svn_stringbuf_t
*svn_stringbuf_create_from_string(const svn_string_t
*str
,
190 /** Create a new bytestring by formatting @a cstring (null-terminated)
191 * from varargs, which are as appropriate for apr_psprintf().
193 svn_stringbuf_t
*svn_stringbuf_createf(apr_pool_t
*pool
,
196 __attribute__ ((format(printf
, 2, 3)));
198 /** Create a new bytestring by formatting @a cstring (null-terminated)
199 * from a @c va_list (see svn_stringbuf_createf()).
201 svn_stringbuf_t
*svn_stringbuf_createv(apr_pool_t
*pool
,
204 __attribute__ ((format(printf
, 2, 0)));
206 /** Make sure that the string @a str has at least @a minimum_size bytes of
207 * space available in the memory block.
209 * (@a minimum_size should include space for the terminating null character.)
211 void svn_stringbuf_ensure(svn_stringbuf_t
*str
,
212 apr_size_t minimum_size
);
214 /** Set a bytestring @a str to @a value */
215 void svn_stringbuf_set(svn_stringbuf_t
*str
, const char *value
);
217 /** Set a bytestring @a str to empty (0 length). */
218 void svn_stringbuf_setempty(svn_stringbuf_t
*str
);
220 /** Return @c TRUE if a bytestring is empty (has length zero). */
221 svn_boolean_t
svn_stringbuf_isempty(const svn_stringbuf_t
*str
);
223 /** Chop @a nbytes bytes off end of @a str, but not more than @a str->len. */
224 void svn_stringbuf_chop(svn_stringbuf_t
*str
, apr_size_t bytes
);
226 /** Fill bytestring @a str with character @a c. */
227 void svn_stringbuf_fillchar(svn_stringbuf_t
*str
, unsigned char c
);
229 /** Append an array of bytes onto @a targetstr.
231 * reallocs if necessary. @a targetstr is affected, nothing else is.
233 void svn_stringbuf_appendbytes(svn_stringbuf_t
*targetstr
,
237 /** Append an @c svn_stringbuf_t onto @a targetstr.
239 * reallocs if necessary. @a targetstr is affected, nothing else is.
241 void svn_stringbuf_appendstr(svn_stringbuf_t
*targetstr
,
242 const svn_stringbuf_t
*appendstr
);
244 /** Append a C string onto @a targetstr.
246 * reallocs if necessary. @a targetstr is affected, nothing else is.
248 void svn_stringbuf_appendcstr(svn_stringbuf_t
*targetstr
,
251 /** Return a duplicate of @a original_string. */
252 svn_stringbuf_t
*svn_stringbuf_dup(const svn_stringbuf_t
*original_string
,
256 /** Return @c TRUE iff @a str1 and @a str2 have identical length and data. */
257 svn_boolean_t
svn_stringbuf_compare(const svn_stringbuf_t
*str1
,
258 const svn_stringbuf_t
*str2
);
260 /** Return offset of first non-whitespace character in @a str, or return
261 * @a str->len if none.
263 apr_size_t
svn_stringbuf_first_non_whitespace(const svn_stringbuf_t
*str
);
265 /** Strip whitespace from both sides of @a str (modified in place). */
266 void svn_stringbuf_strip_whitespace(svn_stringbuf_t
*str
);
268 /** Return position of last occurrence of @a ch in @a str, or return
269 * @a str->len if no occurrence.
271 apr_size_t
svn_stringbuf_find_char_backward(const svn_stringbuf_t
*str
,
274 /** Return @c TRUE iff @a str1 and @a str2 have identical length and data. */
275 svn_boolean_t
svn_string_compare_stringbuf(const svn_string_t
*str1
,
276 const svn_stringbuf_t
*str2
);
283 * @defgroup svn_string_cstrings c string functions
287 /** Divide @a input into substrings along @a sep_char boundaries, return an
288 * array of copies of those substrings, allocating both the array and
289 * the copies in @a pool.
291 * None of the elements added to the array contain any of the
292 * characters in @a sep_chars, and none of the new elements are empty
293 * (thus, it is possible that the returned array will have length
296 * If @a chop_whitespace is true, then remove leading and trailing
297 * whitespace from the returned strings.
299 apr_array_header_t
*svn_cstring_split(const char *input
,
300 const char *sep_chars
,
301 svn_boolean_t chop_whitespace
,
304 /** Like svn_cstring_split(), but append to existing @a array instead of
305 * creating a new one. Allocate the copied substrings in @a pool
306 * (i.e., caller decides whether or not to pass @a array->pool as @a pool).
308 void svn_cstring_split_append(apr_array_header_t
*array
,
310 const char *sep_chars
,
311 svn_boolean_t chop_whitespace
,
315 /** Return @c TRUE iff @a str matches any of the elements of @a list, a list
316 * of zero or more glob patterns.
318 * Use @a pool for temporary allocation.
320 svn_boolean_t
svn_cstring_match_glob_list(const char *str
,
321 apr_array_header_t
*list
);
324 * Return the number of line breaks in @a msg, allowing any kind of newline
325 * termination (CR, LF, CRLF, or LFCR), even inconsistent.
329 int svn_cstring_count_newlines(const char *msg
);
332 * Return a cstring which is the concatenation of @a strings (an array
333 * of char *) each separated by @a separator. The returned string is
334 * allocated from @a pool.
339 svn_cstring_join(apr_array_header_t
*strings
,
340 const char *separator
,
348 #endif /* __cplusplus */
350 #endif /* SVN_STRING_H */