00001 /** 00002 * @copyright 00003 * ==================================================================== 00004 * Copyright (c) 2000-2004 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 @c 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 00081 00082 /** A simple counted string. */ 00083 typedef struct svn_string_t 00084 { 00085 const char *data; /**< pointer to the bytestring */ 00086 apr_size_t len; /**< length of bytestring */ 00087 } svn_string_t; 00088 00089 /** A buffered string, capable of appending without an allocation and copy 00090 * for each append. */ 00091 typedef struct svn_stringbuf_t 00092 { 00093 /** a pool from which this string was originally allocated, and is not 00094 * necessarily specific to this string. This is used only for allocating 00095 * more memory from when the string needs to grow. 00096 */ 00097 apr_pool_t *pool; 00098 00099 /** pointer to the bytestring */ 00100 char *data; 00101 00102 /** length of bytestring */ 00103 apr_size_t len; 00104 00105 /** total size of buffer allocated */ 00106 apr_size_t blocksize; 00107 } svn_stringbuf_t; 00108 00109 00110 /** svn_string_t functions. 00111 * 00112 * @defgroup svn_string_svn_string_t svn_string_t functions 00113 * @{ 00114 */ 00115 00116 /** Create a new bytestring containing a C string (null-terminated). */ 00117 svn_string_t *svn_string_create (const char *cstring, 00118 apr_pool_t *pool); 00119 00120 /** Create a new bytestring containing a generic string of bytes 00121 * (NOT null-terminated) */ 00122 svn_string_t *svn_string_ncreate (const char *bytes, 00123 apr_size_t size, 00124 apr_pool_t *pool); 00125 00126 /** Create a new string with the contents of the given stringbuf */ 00127 svn_string_t *svn_string_create_from_buf (const svn_stringbuf_t *strbuf, 00128 apr_pool_t *pool); 00129 00130 /** Create a new bytestring by formatting @a cstring (null-terminated) 00131 * from varargs, which are as appropriate for @c apr_psprintf. 00132 */ 00133 svn_string_t *svn_string_createf (apr_pool_t *pool, 00134 const char *fmt, 00135 ...) 00136 __attribute__ ((format (printf, 2, 3))); 00137 00138 /** Create a new bytestring by formatting @a cstring (null-terminated) 00139 * from a @c va_list (see @c svn_stringbuf_createf). 00140 */ 00141 svn_string_t *svn_string_createv (apr_pool_t *pool, 00142 const char *fmt, 00143 va_list ap) 00144 __attribute__ ((format (printf, 2, 0))); 00145 00146 /** Return true if a bytestring is empty (has length zero). */ 00147 svn_boolean_t svn_string_isempty (const svn_string_t *str); 00148 00149 /** Return a duplicate of @a original_string. */ 00150 svn_string_t *svn_string_dup (const svn_string_t *original_string, 00151 apr_pool_t *pool); 00152 00153 /** Return @c TRUE iff @a str1 and @c str2 have identical length and data. */ 00154 svn_boolean_t svn_string_compare (const svn_string_t *str1, 00155 const svn_string_t *str2); 00156 00157 /** Return offset of first non-whitespace character in @a str, or return 00158 * @a str->len if none. 00159 */ 00160 apr_size_t svn_string_first_non_whitespace (const svn_string_t *str); 00161 00162 /** Return position of last occurrence of @a char in @a str, or return 00163 * @a str->len if no occurrence. 00164 */ 00165 apr_size_t svn_string_find_char_backward (const svn_string_t *str, char ch); 00166 00167 /** @} */ 00168 00169 00170 /** svn_stringbuf_t functions. 00171 * 00172 * @defgroup svn_string_svn_stringbuf_t svn_stringbuf_t functions 00173 * @{ 00174 */ 00175 00176 /** Create a new bytestring containing a C string (null-terminated). */ 00177 svn_stringbuf_t *svn_stringbuf_create (const char *cstring, 00178 apr_pool_t *pool); 00179 /** Create a new bytestring containing a generic string of bytes 00180 * (NON-null-terminated) 00181 */ 00182 svn_stringbuf_t *svn_stringbuf_ncreate (const char *bytes, 00183 apr_size_t size, 00184 apr_pool_t *pool); 00185 00186 /** Create a new stringbuf with the contents of the given string */ 00187 svn_stringbuf_t *svn_stringbuf_create_from_string (const svn_string_t *str, 00188 apr_pool_t *pool); 00189 00190 /** Create a new bytestring by formatting @a cstring (null-terminated) 00191 * from varargs, which are as appropriate for @c apr_psprintf. 00192 */ 00193 svn_stringbuf_t *svn_stringbuf_createf (apr_pool_t *pool, 00194 const char *fmt, 00195 ...) 00196 __attribute__ ((format (printf, 2, 3))); 00197 00198 /** Create a new bytestring by formatting @a cstring (null-terminated) 00199 * from a @c va_list (see svn_stringbuf_createf). 00200 */ 00201 svn_stringbuf_t *svn_stringbuf_createv (apr_pool_t *pool, 00202 const char *fmt, 00203 va_list ap) 00204 __attribute__ ((format (printf, 2, 0))); 00205 00206 /** Make sure that the string @a str has at least @a minimum_size bytes of 00207 * space available in the memory block. 00208 * 00209 * (@a minimum_size should include space for the terminating null character.) 00210 */ 00211 void svn_stringbuf_ensure (svn_stringbuf_t *str, 00212 apr_size_t minimum_size); 00213 00214 /** Set a bytestring @a str to @a value */ 00215 void svn_stringbuf_set (svn_stringbuf_t *str, const char *value); 00216 00217 /** Set a bytestring @a str to empty (0 length). */ 00218 void svn_stringbuf_setempty (svn_stringbuf_t *str); 00219 00220 /** Return @c TRUE if a bytestring is empty (has length zero). */ 00221 svn_boolean_t svn_stringbuf_isempty (const svn_stringbuf_t *str); 00222 00223 /** Chop @a nbytes bytes off end of @a str, but not more than @a str->len. */ 00224 void svn_stringbuf_chop (svn_stringbuf_t *str, apr_size_t bytes); 00225 00226 /** Fill bytestring @a str with character @a c. */ 00227 void svn_stringbuf_fillchar (svn_stringbuf_t *str, unsigned char c); 00228 00229 /** Append an array of bytes onto @a targetstr. 00230 * 00231 * @c reallocs() if necessary. @a targetstr is affected, nothing else is. 00232 */ 00233 void svn_stringbuf_appendbytes (svn_stringbuf_t *targetstr, 00234 const char *bytes, 00235 apr_size_t count); 00236 00237 /** Append an @c svn_stringbuf_t onto @a targetstr. 00238 * 00239 * @c reallocs() if necessary. @a targetstr is affected, nothing else is. 00240 */ 00241 void svn_stringbuf_appendstr (svn_stringbuf_t *targetstr, 00242 const svn_stringbuf_t *appendstr); 00243 00244 /** Append a C string onto @a targetstr. 00245 * 00246 * @c reallocs() if necessary. @a targetstr is affected, nothing else is. 00247 */ 00248 void svn_stringbuf_appendcstr (svn_stringbuf_t *targetstr, 00249 const char *cstr); 00250 00251 /** Return a duplicate of @a original_string. */ 00252 svn_stringbuf_t *svn_stringbuf_dup (const svn_stringbuf_t *original_string, 00253 apr_pool_t *pool); 00254 00255 00256 /** Return @c TRUE iff @a str1 and @a str2 have identical length and data. */ 00257 svn_boolean_t svn_stringbuf_compare (const svn_stringbuf_t *str1, 00258 const svn_stringbuf_t *str2); 00259 00260 /** Return offset of first non-whitespace character in @a str, or return 00261 * @a str->len if none. 00262 */ 00263 apr_size_t svn_stringbuf_first_non_whitespace (const svn_stringbuf_t *str); 00264 00265 /** Strip whitespace from both sides of @a str (modified in place). */ 00266 void svn_stringbuf_strip_whitespace (svn_stringbuf_t *str); 00267 00268 /** Return position of last occurrence of @a ch in @a str, or return 00269 * @a str->len if no occurrence. 00270 */ 00271 apr_size_t svn_stringbuf_find_char_backward (const svn_stringbuf_t *str, 00272 char ch); 00273 00274 /** Return @c TRUE iff @a str1 and @a str2 have identical length and data. */ 00275 svn_boolean_t svn_string_compare_stringbuf (const svn_string_t *str1, 00276 const svn_stringbuf_t *str2); 00277 00278 /** @} */ 00279 00280 00281 /** C strings. 00282 * 00283 * @defgroup svn_string_cstrings c string functions 00284 * @{ 00285 */ 00286 00287 /** Divide @a input into substrings along @a sep_char boundaries, return an 00288 * array of copies of those substrings, allocating both the array and 00289 * the copies in @a pool. 00290 * 00291 * None of the elements added to the array contain any of the 00292 * characters in @a sep_chars, and none of the new elements are empty 00293 * (thus, it is possible that the returned array will have length 00294 * zero). 00295 * 00296 * If @a chop_whitespace is true, then remove leading and trailing 00297 * whitespace from the returned strings. 00298 */ 00299 apr_array_header_t *svn_cstring_split (const char *input, 00300 const char *sep_chars, 00301 svn_boolean_t chop_whitespace, 00302 apr_pool_t *pool); 00303 00304 /** Like @c svn_cstring_split(), but append to existing @a array instead of 00305 * creating a new one. Allocate the copied substrings in @a pool 00306 * (i.e., caller decides whether or not to pass @a array->pool as @a pool). 00307 */ 00308 void svn_cstring_split_append (apr_array_header_t *array, 00309 const char *input, 00310 const char *sep_chars, 00311 svn_boolean_t chop_whitespace, 00312 apr_pool_t *pool); 00313 00314 00315 /** Return @c TRUE iff @a str matches any of the elements of @a list, a list 00316 * of zero or more glob patterns. 00317 * 00318 * Use @a pool for temporary allocation. 00319 */ 00320 svn_boolean_t svn_cstring_match_glob_list (const char *str, 00321 apr_array_header_t *list); 00322 00323 /** @since New in 1.2. 00324 * 00325 * Return the number of line breaks in @a msg, allowing any kind of newline 00326 * termination (CR, LF, CRLF, or LFCR), even inconsistent. 00327 */ 00328 int svn_cstring_count_newlines (const char *msg); 00329 00330 /** @since New in 1.2. 00331 * 00332 * Return a cstring which is the concatenation of @a strings (an array 00333 * of char *) each separated by @a separator. The returned string is 00334 * allocated from @a pool. */ 00335 char * 00336 svn_cstring_join (apr_array_header_t *strings, 00337 const char *separator, 00338 apr_pool_t *pool); 00339 00340 /** @} */ 00341 00342 00343 #ifdef __cplusplus 00344 } 00345 #endif /* __cplusplus */ 00346 00347 #endif /* SVN_STRING_H */