00001 /** 00002 * @copyright 00003 * ==================================================================== 00004 * Copyright (c) 2000-2006 CollabNet. All rights reserved. 00005 * 00006 * This software is licensed as described in the file COPYING, which 00007 * you should have received as part of this distribution. The terms 00008 * are also available at http://subversion.tigris.org/license-1.html. 00009 * If newer versions of this license are posted there, you may use a 00010 * newer version instead, at your option. 00011 * 00012 * This software consists of voluntary contributions made by many 00013 * individuals. For exact contribution history, see the revision 00014 * history and logs, available at http://subversion.tigris.org/. 00015 * ==================================================================== 00016 * @endcopyright 00017 * 00018 * @file svn_string.h 00019 * @brief Counted-length strings for Subversion, plus some C string goodies. 00020 * 00021 * There are two string datatypes: @c svn_string_t and @c svn_stringbuf_t. 00022 * The former is a simple pointer/length pair useful for passing around 00023 * strings (or arbitrary bytes) with a counted length. @c svn_stringbuf_t is 00024 * buffered to enable efficient appending of strings without an allocation 00025 * and copy for each append operation. 00026 * 00027 * @c svn_string_t contains a <tt>const char *</tt> for its data, so it is 00028 * most appropriate for constant data and for functions which expect constant, 00029 * counted data. Functions should generally use <tt>const @c svn_string_t 00030 * *</tt> as their parameter to indicate they are expecting a constant, 00031 * counted string. 00032 * 00033 * @c svn_stringbuf_t uses a plain <tt>char *</tt> for its data, so it is 00034 * most appropriate for modifiable data. 00035 * 00036 * <h3>Invariants</h3> 00037 * 00038 * 1. Null termination: 00039 * 00040 * Both structures maintain a significant invariant: 00041 * 00042 * <tt>s->data[s->len] == '\\0'</tt> 00043 * 00044 * The functions defined within this header file will maintain 00045 * the invariant (which does imply that memory is 00046 * allocated/defined as @c len+1 bytes). If code outside of the 00047 * @c svn_string.h functions manually builds these structures, 00048 * then they must enforce this invariant. 00049 * 00050 * Note that an @c svn_string(buf)_t may contain binary data, 00051 * which means that strlen(s->data) does not have to equal @c 00052 * s->len. The NULL terminator is provided to make it easier to 00053 * pass @c s->data to C string interfaces. 00054 * 00055 * 00056 * 2. Non-NULL input: 00057 * 00058 * All the functions assume their input data is non-NULL, 00059 * unless otherwise documented, and may seg fault if passed 00060 * NULL. The input data may *contain* null bytes, of course, just 00061 * the data pointer itself must not be NULL. 00062 */ 00063 00064 00065 #ifndef SVN_STRING_H 00066 #define SVN_STRING_H 00067 00068 #include <apr.h> 00069 #include <apr_tables.h> 00070 #include <apr_pools.h> /* APR memory pools for everyone. */ 00071 #include <apr_strings.h> 00072 00073 #include "svn_types.h" 00074 00075 #ifdef __cplusplus 00076 extern "C" { 00077 #endif /* __cplusplus */ 00078 00079 /** 00080 * @defgroup svn_string String handling 00081 * @{ 00082 */ 00083 00084 00085 00086 /** A simple counted string. */ 00087 typedef struct svn_string_t 00088 { 00089 const char *data; /**< pointer to the bytestring */ 00090 apr_size_t len; /**< length of bytestring */ 00091 } svn_string_t; 00092 00093 /** A buffered string, capable of appending without an allocation and copy 00094 * for each append. */ 00095 typedef struct svn_stringbuf_t 00096 { 00097 /** a pool from which this string was originally allocated, and is not 00098 * necessarily specific to this string. This is used only for allocating 00099 * more memory from when the string needs to grow. 00100 */ 00101 apr_pool_t *pool; 00102 00103 /** pointer to the bytestring */ 00104 char *data; 00105 00106 /** length of bytestring */ 00107 apr_size_t len; 00108 00109 /** total size of buffer allocated */ 00110 apr_size_t blocksize; 00111 } svn_stringbuf_t; 00112 00113 00114 /** svn_string_t functions. 00115 * 00116 * @defgroup svn_string_svn_string_t svn_string_t functions 00117 * @{ 00118 */ 00119 00120 /** Create a new bytestring containing a C string (NULL-terminated). */ 00121 svn_string_t *svn_string_create(const char *cstring, 00122 apr_pool_t *pool); 00123 00124 /** Create a new bytestring containing a generic string of bytes 00125 * (NOT NULL-terminated) */ 00126 svn_string_t *svn_string_ncreate(const char *bytes, 00127 apr_size_t size, 00128 apr_pool_t *pool); 00129 00130 /** Create a new string with the contents of the given stringbuf */ 00131 svn_string_t *svn_string_create_from_buf(const svn_stringbuf_t *strbuf, 00132 apr_pool_t *pool); 00133 00134 /** Create a new bytestring by formatting @a cstring (NULL-terminated) 00135 * from varargs, which are as appropriate for apr_psprintf(). 00136 */ 00137 svn_string_t *svn_string_createf(apr_pool_t *pool, 00138 const char *fmt, 00139 ...) 00140 __attribute__((format(printf, 2, 3))); 00141 00142 /** Create a new bytestring by formatting @a cstring (NULL-terminated) 00143 * from a @c va_list (see svn_stringbuf_createf()). 00144 */ 00145 svn_string_t *svn_string_createv(apr_pool_t *pool, 00146 const char *fmt, 00147 va_list ap) 00148 __attribute__((format(printf, 2, 0))); 00149 00150 /** Return TRUE if a bytestring is empty (has length zero). */ 00151 svn_boolean_t svn_string_isempty(const svn_string_t *str); 00152 00153 /** Return a duplicate of @a original_string. */ 00154 svn_string_t *svn_string_dup(const svn_string_t *original_string, 00155 apr_pool_t *pool); 00156 00157 /** Return @c TRUE iff @a str1 and @a str2 have identical length and data. */ 00158 svn_boolean_t svn_string_compare(const svn_string_t *str1, 00159 const svn_string_t *str2); 00160 00161 /** Return offset of first non-whitespace character in @a str, or return 00162 * @a str->len if none. 00163 */ 00164 apr_size_t svn_string_first_non_whitespace(const svn_string_t *str); 00165 00166 /** Return position of last occurrence of @a ch in @a str, or return 00167 * @a str->len if no occurrence. 00168 */ 00169 apr_size_t svn_string_find_char_backward(const svn_string_t *str, char ch); 00170 00171 /** @} */ 00172 00173 00174 /** svn_stringbuf_t functions. 00175 * 00176 * @defgroup svn_string_svn_stringbuf_t svn_stringbuf_t functions 00177 * @{ 00178 */ 00179 00180 /** Create a new bytestring containing a C string (NULL-terminated). */ 00181 svn_stringbuf_t *svn_stringbuf_create(const char *cstring, 00182 apr_pool_t *pool); 00183 /** Create a new bytestring containing a generic string of bytes 00184 * (NON-NULL-terminated) 00185 */ 00186 svn_stringbuf_t *svn_stringbuf_ncreate(const char *bytes, 00187 apr_size_t size, 00188 apr_pool_t *pool); 00189 00190 /** Create a new stringbuf with the contents of the given string */ 00191 svn_stringbuf_t *svn_stringbuf_create_from_string(const svn_string_t *str, 00192 apr_pool_t *pool); 00193 00194 /** Create a new bytestring by formatting @a cstring (NULL-terminated) 00195 * from varargs, which are as appropriate for apr_psprintf(). 00196 */ 00197 svn_stringbuf_t *svn_stringbuf_createf(apr_pool_t *pool, 00198 const char *fmt, 00199 ...) 00200 __attribute__((format(printf, 2, 3))); 00201 00202 /** Create a new bytestring by formatting @a cstring (NULL-terminated) 00203 * from a @c va_list (see svn_stringbuf_createf()). 00204 */ 00205 svn_stringbuf_t *svn_stringbuf_createv(apr_pool_t *pool, 00206 const char *fmt, 00207 va_list ap) 00208 __attribute__((format(printf, 2, 0))); 00209 00210 /** Make sure that the string @a str has at least @a minimum_size bytes of 00211 * space available in the memory block. 00212 * 00213 * (@a minimum_size should include space for the terminating NULL character.) 00214 */ 00215 void svn_stringbuf_ensure(svn_stringbuf_t *str, 00216 apr_size_t minimum_size); 00217 00218 /** Set a bytestring @a str to @a value */ 00219 void svn_stringbuf_set(svn_stringbuf_t *str, const char *value); 00220 00221 /** Set a bytestring @a str to empty (0 length). */ 00222 void svn_stringbuf_setempty(svn_stringbuf_t *str); 00223 00224 /** Return @c TRUE if a bytestring is empty (has length zero). */ 00225 svn_boolean_t svn_stringbuf_isempty(const svn_stringbuf_t *str); 00226 00227 /** Chop @a nbytes bytes off end of @a str, but not more than @a str->len. */ 00228 void svn_stringbuf_chop(svn_stringbuf_t *str, apr_size_t nbytes); 00229 00230 /** Fill bytestring @a str with character @a c. */ 00231 void svn_stringbuf_fillchar(svn_stringbuf_t *str, unsigned char c); 00232 00233 /** Append an array of bytes onto @a targetstr. 00234 * 00235 * reallocs if necessary. @a targetstr is affected, nothing else is. 00236 */ 00237 void svn_stringbuf_appendbytes(svn_stringbuf_t *targetstr, 00238 const char *bytes, 00239 apr_size_t count); 00240 00241 /** Append an @c svn_stringbuf_t onto @a targetstr. 00242 * 00243 * reallocs if necessary. @a targetstr is affected, nothing else is. 00244 */ 00245 void svn_stringbuf_appendstr(svn_stringbuf_t *targetstr, 00246 const svn_stringbuf_t *appendstr); 00247 00248 /** Append a C string onto @a targetstr. 00249 * 00250 * reallocs if necessary. @a targetstr is affected, nothing else is. 00251 */ 00252 void svn_stringbuf_appendcstr(svn_stringbuf_t *targetstr, 00253 const char *cstr); 00254 00255 /** Return a duplicate of @a original_string. */ 00256 svn_stringbuf_t *svn_stringbuf_dup(const svn_stringbuf_t *original_string, 00257 apr_pool_t *pool); 00258 00259 00260 /** Return @c TRUE iff @a str1 and @a str2 have identical length and data. */ 00261 svn_boolean_t svn_stringbuf_compare(const svn_stringbuf_t *str1, 00262 const svn_stringbuf_t *str2); 00263 00264 /** Return offset of first non-whitespace character in @a str, or return 00265 * @a str->len if none. 00266 */ 00267 apr_size_t svn_stringbuf_first_non_whitespace(const svn_stringbuf_t *str); 00268 00269 /** Strip whitespace from both sides of @a str (modified in place). */ 00270 void svn_stringbuf_strip_whitespace(svn_stringbuf_t *str); 00271 00272 /** Return position of last occurrence of @a ch in @a str, or return 00273 * @a str->len if no occurrence. 00274 */ 00275 apr_size_t svn_stringbuf_find_char_backward(const svn_stringbuf_t *str, 00276 char ch); 00277 00278 /** Return @c TRUE iff @a str1 and @a str2 have identical length and data. */ 00279 svn_boolean_t svn_string_compare_stringbuf(const svn_string_t *str1, 00280 const svn_stringbuf_t *str2); 00281 00282 /** @} */ 00283 00284 00285 /** C strings. 00286 * 00287 * @defgroup svn_string_cstrings c string functions 00288 * @{ 00289 */ 00290 00291 /** Divide @a input into substrings along @a sep_chars boundaries, return an 00292 * array of copies of those substrings, allocating both the array and 00293 * the copies in @a pool. 00294 * 00295 * None of the elements added to the array contain any of the 00296 * characters in @a sep_chars, and none of the new elements are empty 00297 * (thus, it is possible that the returned array will have length 00298 * zero). 00299 * 00300 * If @a chop_whitespace is TRUE, then remove leading and trailing 00301 * whitespace from the returned strings. 00302 */ 00303 apr_array_header_t *svn_cstring_split(const char *input, 00304 const char *sep_chars, 00305 svn_boolean_t chop_whitespace, 00306 apr_pool_t *pool); 00307 00308 /** Like svn_cstring_split(), but append to existing @a array instead of 00309 * creating a new one. Allocate the copied substrings in @a pool 00310 * (i.e., caller decides whether or not to pass @a array->pool as @a pool). 00311 */ 00312 void svn_cstring_split_append(apr_array_header_t *array, 00313 const char *input, 00314 const char *sep_chars, 00315 svn_boolean_t chop_whitespace, 00316 apr_pool_t *pool); 00317 00318 00319 /** Return @c TRUE iff @a str matches any of the elements of @a list, a list 00320 * of zero or more glob patterns. 00321 */ 00322 svn_boolean_t svn_cstring_match_glob_list(const char *str, 00323 apr_array_header_t *list); 00324 00325 /** 00326 * Return the number of line breaks in @a msg, allowing any kind of newline 00327 * termination (CR, LF, CRLF, or LFCR), even inconsistent. 00328 * 00329 * @since New in 1.2. 00330 */ 00331 int svn_cstring_count_newlines(const char *msg); 00332 00333 /** 00334 * Return a cstring which is the concatenation of @a strings (an array 00335 * of char *) each followed by @a separator (that is, @a separator 00336 * will also end the resulting string). Allocate the result in @a pool. 00337 * If @a strings is empty, then return the empty string. 00338 * 00339 * @since New in 1.2. 00340 */ 00341 char * 00342 svn_cstring_join(apr_array_header_t *strings, 00343 const char *separator, 00344 apr_pool_t *pool); 00345 00346 /** 00347 * Compare two strings @a atr1 and @a atr2, treating case-equivalent 00348 * unaccented Latin (ASCII subset) letters as equal. 00349 * 00350 * @since New in 1.5. 00351 */ 00352 int svn_cstring_casecmp(const char *str1, const char *str2); 00353 00354 00355 /** @} */ 00356 00357 /** @} */ 00358 00359 00360 #ifdef __cplusplus 00361 } 00362 #endif /* __cplusplus */ 00363 00364 #endif /* SVN_STRING_H */