00001 /** 00002 * @copyright 00003 * ==================================================================== 00004 * Licensed to the Apache Software Foundation (ASF) under one 00005 * or more contributor license agreements. See the NOTICE file 00006 * distributed with this work for additional information 00007 * regarding copyright ownership. The ASF licenses this file 00008 * to you under the Apache License, Version 2.0 (the 00009 * "License"); you may not use this file except in compliance 00010 * with the License. You may obtain a copy of the License at 00011 * 00012 * http://www.apache.org/licenses/LICENSE-2.0 00013 * 00014 * Unless required by applicable law or agreed to in writing, 00015 * software distributed under the License is distributed on an 00016 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 00017 * KIND, either express or implied. See the License for the 00018 * specific language governing permissions and limitations 00019 * under the License. 00020 * ==================================================================== 00021 * @endcopyright 00022 * 00023 * @file svn_string.h 00024 * @brief Counted-length strings for Subversion, plus some C string goodies. 00025 * 00026 * There are two string datatypes: @c svn_string_t and @c svn_stringbuf_t. 00027 * The former is a simple pointer/length pair useful for passing around 00028 * strings (or arbitrary bytes) with a counted length. @c svn_stringbuf_t is 00029 * buffered to enable efficient appending of strings without an allocation 00030 * and copy for each append operation. 00031 * 00032 * @c svn_string_t contains a <tt>const char *</tt> for its data, so it is 00033 * most appropriate for constant data and for functions which expect constant, 00034 * counted data. Functions should generally use <tt>const @c svn_string_t 00035 * *</tt> as their parameter to indicate they are expecting a constant, 00036 * counted string. 00037 * 00038 * @c svn_stringbuf_t uses a plain <tt>char *</tt> for its data, so it is 00039 * most appropriate for modifiable data. 00040 * 00041 * <h3>Invariants</h3> 00042 * 00043 * 1. Null termination: 00044 * 00045 * Both structures maintain a significant invariant: 00046 * 00047 * <tt>s->data[s->len] == '\\0'</tt> 00048 * 00049 * The functions defined within this header file will maintain 00050 * the invariant (which does imply that memory is 00051 * allocated/defined as @c len+1 bytes). If code outside of the 00052 * @c svn_string.h functions manually builds these structures, 00053 * then they must enforce this invariant. 00054 * 00055 * Note that an @c svn_string(buf)_t may contain binary data, 00056 * which means that strlen(s->data) does not have to equal @c 00057 * s->len. The null terminator is provided to make it easier to 00058 * pass @c s->data to C string interfaces. 00059 * 00060 * 00061 * 2. Non-NULL input: 00062 * 00063 * All the functions assume their input data pointer is non-NULL, 00064 * unless otherwise documented, and may seg fault if passed 00065 * NULL. The input data may *contain* null bytes, of course, just 00066 * the data pointer itself must not be NULL. 00067 * 00068 * <h3>Memory allocation</h3> 00069 * 00070 * All the functions make a deep copy of all input data, and never store 00071 * a pointer to the original input data. 00072 */ 00073 00074 00075 #ifndef SVN_STRING_H 00076 #define SVN_STRING_H 00077 00078 #include <apr.h> /* for apr_size_t */ 00079 #include <apr_pools.h> /* for apr_pool_t */ 00080 #include <apr_tables.h> /* for apr_array_header_t */ 00081 00082 #include "svn_types.h" /* for svn_boolean_t, svn_error_t */ 00083 00084 #ifdef __cplusplus 00085 extern "C" { 00086 #endif /* __cplusplus */ 00087 00088 /** 00089 * @defgroup svn_string String handling 00090 * @{ 00091 */ 00092 00093 00094 00095 /** A simple counted string. */ 00096 typedef struct svn_string_t 00097 { 00098 const char *data; /**< pointer to the bytestring */ 00099 apr_size_t len; /**< length of bytestring */ 00100 } svn_string_t; 00101 00102 /** A buffered string, capable of appending without an allocation and copy 00103 * for each append. */ 00104 typedef struct svn_stringbuf_t 00105 { 00106 /** a pool from which this string was originally allocated, and is not 00107 * necessarily specific to this string. This is used only for allocating 00108 * more memory from when the string needs to grow. 00109 */ 00110 apr_pool_t *pool; 00111 00112 /** pointer to the bytestring */ 00113 char *data; 00114 00115 /** length of bytestring */ 00116 apr_size_t len; 00117 00118 /** total size of buffer allocated */ 00119 apr_size_t blocksize; 00120 } svn_stringbuf_t; 00121 00122 00123 /** 00124 * @defgroup svn_string_svn_string_t svn_string_t functions 00125 * @{ 00126 */ 00127 00128 /** Create a new string copied from the null-terminated C string @a cstring. 00129 */ 00130 svn_string_t * 00131 svn_string_create(const char *cstring, apr_pool_t *pool); 00132 00133 /** Create a new, empty string. 00134 * 00135 * @since New in 1.8. 00136 */ 00137 svn_string_t * 00138 svn_string_create_empty(apr_pool_t *pool); 00139 00140 /** Create a new string copied from a generic string of bytes, @a bytes, of 00141 * length @a size bytes. @a bytes is NOT assumed to be null-terminated, but 00142 * the new string will be. 00143 */ 00144 svn_string_t * 00145 svn_string_ncreate(const char *bytes, apr_size_t size, apr_pool_t *pool); 00146 00147 /** Create a new string copied from the stringbuf @a strbuf. 00148 */ 00149 svn_string_t * 00150 svn_string_create_from_buf(const svn_stringbuf_t *strbuf, apr_pool_t *pool); 00151 00152 /** Create a new string by printf-style formatting using @a fmt and the 00153 * variable arguments, which are as appropriate for apr_psprintf(). 00154 */ 00155 svn_string_t * 00156 svn_string_createf(apr_pool_t *pool, const char *fmt, ...) 00157 __attribute__((format(printf, 2, 3))); 00158 00159 /** Create a new string by printf-style formatting using @c fmt and @a ap. 00160 * This is the same as svn_string_createf() except for the different 00161 * way of passing the variable arguments. 00162 */ 00163 svn_string_t * 00164 svn_string_createv(apr_pool_t *pool, const char *fmt, va_list ap) 00165 __attribute__((format(printf, 2, 0))); 00166 00167 /** Return TRUE if @a str is empty (has length zero). */ 00168 svn_boolean_t 00169 svn_string_isempty(const svn_string_t *str); 00170 00171 /** Return a duplicate of @a original_string. */ 00172 svn_string_t * 00173 svn_string_dup(const svn_string_t *original_string, apr_pool_t *pool); 00174 00175 /** Return @c TRUE iff @a str1 and @a str2 have identical length and data. */ 00176 svn_boolean_t 00177 svn_string_compare(const svn_string_t *str1, const svn_string_t *str2); 00178 00179 /** Return offset of first non-whitespace character in @a str, or return 00180 * @a str->len if none. 00181 */ 00182 apr_size_t 00183 svn_string_first_non_whitespace(const svn_string_t *str); 00184 00185 /** Return position of last occurrence of @a ch in @a str, or return 00186 * @a str->len if no occurrence. 00187 */ 00188 apr_size_t 00189 svn_string_find_char_backward(const svn_string_t *str, char ch); 00190 00191 /** @} */ 00192 00193 00194 /** 00195 * @defgroup svn_string_svn_stringbuf_t svn_stringbuf_t functions 00196 * @{ 00197 */ 00198 00199 /** Create a new stringbuf copied from the null-terminated C string 00200 * @a cstring. 00201 */ 00202 svn_stringbuf_t * 00203 svn_stringbuf_create(const char *cstring, apr_pool_t *pool); 00204 00205 /** Create a new stringbuf copied from the generic string of bytes, @a bytes, 00206 * of length @a size bytes. @a bytes is NOT assumed to be null-terminated, 00207 * but the new stringbuf will be. 00208 */ 00209 svn_stringbuf_t * 00210 svn_stringbuf_ncreate(const char *bytes, apr_size_t size, apr_pool_t *pool); 00211 00212 /** Create a new, empty stringbuf. 00213 * 00214 * @since New in 1.8. 00215 */ 00216 svn_stringbuf_t * 00217 svn_stringbuf_create_empty(apr_pool_t *pool); 00218 00219 /** Create a new, empty stringbuf with at least @a minimum_size bytes of 00220 * space available in the memory block. 00221 * 00222 * The allocated string buffer will be at least one byte larger than 00223 * @a minimum_size to account for a final '\\0'. 00224 * 00225 * @since New in 1.6. 00226 */ 00227 svn_stringbuf_t * 00228 svn_stringbuf_create_ensure(apr_size_t minimum_size, apr_pool_t *pool); 00229 00230 /** Create a new stringbuf copied from the string @a str. 00231 */ 00232 svn_stringbuf_t * 00233 svn_stringbuf_create_from_string(const svn_string_t *str, apr_pool_t *pool); 00234 00235 /** Create a new stringbuf by printf-style formatting using @a fmt and the 00236 * variable arguments, which are as appropriate for apr_psprintf(). 00237 */ 00238 svn_stringbuf_t * 00239 svn_stringbuf_createf(apr_pool_t *pool, const char *fmt, ...) 00240 __attribute__((format(printf, 2, 3))); 00241 00242 /** Create a new stringbuf by printf-style formatting using @c fmt and @a ap. 00243 * This is the same as svn_stringbuf_createf() except for the different 00244 * way of passing the variable arguments. 00245 */ 00246 svn_stringbuf_t * 00247 svn_stringbuf_createv(apr_pool_t *pool, const char *fmt, va_list ap) 00248 __attribute__((format(printf, 2, 0))); 00249 00250 /** Make sure that @a str has at least @a minimum_size 00251 * bytes of space available in the memory block. 00252 * 00253 * The allocated string buffer will be at least one byte larger than 00254 * @a minimum_size to account for a final '\\0'. 00255 * 00256 * @note: Before Subversion 1.8 this function did not ensure space for 00257 * one byte more than @a minimum_size. If compatibility with pre-1.8 00258 * behaviour is required callers must assume space for only 00259 * @a minimum_size-1 data bytes plus a final '\\0'. 00260 */ 00261 void 00262 svn_stringbuf_ensure(svn_stringbuf_t *str, apr_size_t minimum_size); 00263 00264 /** Set @a str to a copy of the null-terminated C string @a value. */ 00265 void 00266 svn_stringbuf_set(svn_stringbuf_t *str, const char *value); 00267 00268 /** Set @a str to empty (zero length). */ 00269 void 00270 svn_stringbuf_setempty(svn_stringbuf_t *str); 00271 00272 /** Return @c TRUE if @a str is empty (has length zero). */ 00273 svn_boolean_t 00274 svn_stringbuf_isempty(const svn_stringbuf_t *str); 00275 00276 /** Chop @a nbytes bytes off end of @a str, but not more than @a str->len. */ 00277 void 00278 svn_stringbuf_chop(svn_stringbuf_t *str, apr_size_t nbytes); 00279 00280 /** Fill @a str with character @a c. */ 00281 void 00282 svn_stringbuf_fillchar(svn_stringbuf_t *str, unsigned char c); 00283 00284 /** Append the single character @a byte onto @a targetstr. 00285 * 00286 * This is an optimized version of svn_stringbuf_appendbytes() 00287 * that is much faster to call and execute. Gains vary with the ABI. 00288 * The advantages extend beyond the actual call because the reduced 00289 * register pressure allows for more optimization within the caller. 00290 * 00291 * reallocs if necessary. @a targetstr is affected, nothing else is. 00292 * @since New in 1.7. 00293 */ 00294 void 00295 svn_stringbuf_appendbyte(svn_stringbuf_t *targetstr, 00296 char byte); 00297 00298 /** Append an array of bytes onto @a targetstr. 00299 * 00300 * reallocs if necessary. @a targetstr is affected, nothing else is. 00301 */ 00302 void 00303 svn_stringbuf_appendbytes(svn_stringbuf_t *targetstr, 00304 const char *bytes, 00305 apr_size_t count); 00306 00307 /** Append the stringbuf @c appendstr onto @a targetstr. 00308 * 00309 * reallocs if necessary. @a targetstr is affected, nothing else is. 00310 */ 00311 void 00312 svn_stringbuf_appendstr(svn_stringbuf_t *targetstr, 00313 const svn_stringbuf_t *appendstr); 00314 00315 /** Append the C string @a cstr onto @a targetstr. 00316 * 00317 * reallocs if necessary. @a targetstr is affected, nothing else is. 00318 */ 00319 void 00320 svn_stringbuf_appendcstr(svn_stringbuf_t *targetstr, 00321 const char *cstr); 00322 00323 /** Read @a count bytes from @a bytes and insert them into @a str at 00324 * position @a pos and following. The resulting string will be 00325 * @c count+str->len bytes long. If @c pos is larger or equal to the 00326 * number of bytes currently used in @a str, simply append @a bytes. 00327 * 00328 * Reallocs if necessary. @a str is affected, nothing else is. 00329 * 00330 * @note The inserted string may be a sub-range if @a str. 00331 * 00332 * @since New in 1.8. 00333 */ 00334 void 00335 svn_stringbuf_insert(svn_stringbuf_t *str, 00336 apr_size_t pos, 00337 const char *bytes, 00338 apr_size_t count); 00339 00340 /** Removes @a count bytes from @a str, starting at position @a pos. 00341 * If that range exceeds the current string data, @a str gets truncated 00342 * at @a pos. If the latter is larger or equal to @c str->pos, this will 00343 * be a no-op. Otherwise, the resulting string will be @c str->len-count 00344 * bytes long. 00345 * 00346 * @since New in 1.8. 00347 */ 00348 void 00349 svn_stringbuf_remove(svn_stringbuf_t *str, 00350 apr_size_t pos, 00351 apr_size_t count); 00352 00353 /** Replace in @a str the substring which starts at @a pos and is @a 00354 * old_count bytes long with a new substring @a bytes (which is @a 00355 * new_count bytes long). 00356 * 00357 * This is faster but functionally equivalent to the following sequence: 00358 * @code 00359 svn_stringbuf_remove(str, pos, old_count); 00360 svn_stringbuf_insert(str, pos, bytes, new_count); 00361 * @endcode 00362 * 00363 * @since New in 1.8. 00364 */ 00365 void 00366 svn_stringbuf_replace(svn_stringbuf_t *str, 00367 apr_size_t pos, 00368 apr_size_t old_count, 00369 const char *bytes, 00370 apr_size_t new_count); 00371 00372 /** Return a duplicate of @a original_string. */ 00373 svn_stringbuf_t * 00374 svn_stringbuf_dup(const svn_stringbuf_t *original_string, apr_pool_t *pool); 00375 00376 /** Return @c TRUE iff @a str1 and @a str2 have identical length and data. */ 00377 svn_boolean_t 00378 svn_stringbuf_compare(const svn_stringbuf_t *str1, 00379 const svn_stringbuf_t *str2); 00380 00381 /** Return offset of first non-whitespace character in @a str, or return 00382 * @a str->len if none. 00383 */ 00384 apr_size_t 00385 svn_stringbuf_first_non_whitespace(const svn_stringbuf_t *str); 00386 00387 /** Strip whitespace from both sides of @a str (modified in place). */ 00388 void 00389 svn_stringbuf_strip_whitespace(svn_stringbuf_t *str); 00390 00391 /** Return position of last occurrence of @a ch in @a str, or return 00392 * @a str->len if no occurrence. 00393 */ 00394 apr_size_t 00395 svn_stringbuf_find_char_backward(const svn_stringbuf_t *str, char ch); 00396 00397 /** Return @c TRUE iff @a str1 and @a str2 have identical length and data. */ 00398 svn_boolean_t 00399 svn_string_compare_stringbuf(const svn_string_t *str1, 00400 const svn_stringbuf_t *str2); 00401 00402 /** @} */ 00403 00404 00405 /** 00406 * @defgroup svn_string_cstrings C string functions 00407 * @{ 00408 */ 00409 00410 /** Divide @a input into substrings along @a sep_chars boundaries, return an 00411 * array of copies of those substrings (plain const char*), allocating both 00412 * the array and the copies in @a pool. 00413 * 00414 * None of the elements added to the array contain any of the 00415 * characters in @a sep_chars, and none of the new elements are empty 00416 * (thus, it is possible that the returned array will have length 00417 * zero). 00418 * 00419 * If @a chop_whitespace is TRUE, then remove leading and trailing 00420 * whitespace from the returned strings. 00421 */ 00422 apr_array_header_t * 00423 svn_cstring_split(const char *input, 00424 const char *sep_chars, 00425 svn_boolean_t chop_whitespace, 00426 apr_pool_t *pool); 00427 00428 /** Like svn_cstring_split(), but append to existing @a array instead of 00429 * creating a new one. Allocate the copied substrings in @a pool 00430 * (i.e., caller decides whether or not to pass @a array->pool as @a pool). 00431 */ 00432 void 00433 svn_cstring_split_append(apr_array_header_t *array, 00434 const char *input, 00435 const char *sep_chars, 00436 svn_boolean_t chop_whitespace, 00437 apr_pool_t *pool); 00438 00439 00440 /** Return @c TRUE iff @a str matches any of the elements of @a list, a list 00441 * of zero or more glob patterns. 00442 */ 00443 svn_boolean_t 00444 svn_cstring_match_glob_list(const char *str, const apr_array_header_t *list); 00445 00446 /** Return @c TRUE iff @a str exactly matches any of the elements of @a list. 00447 * 00448 * @since new in 1.7 00449 */ 00450 svn_boolean_t 00451 svn_cstring_match_list(const char *str, const apr_array_header_t *list); 00452 00453 /** 00454 * Get the next token from @a *str interpreting any char from @a sep as a 00455 * token separator. Separators at the beginning of @a str will be skipped. 00456 * Returns a pointer to the beginning of the first token in @a *str or NULL 00457 * if no token is left. Modifies @a str such that the next call will return 00458 * the next token. 00459 * 00460 * @note The content of @a *str may be modified by this function. 00461 * 00462 * @since New in 1.8. 00463 */ 00464 char * 00465 svn_cstring_tokenize(const char *sep, char **str); 00466 00467 /** 00468 * Return the number of line breaks in @a msg, allowing any kind of newline 00469 * termination (CR, LF, CRLF, or LFCR), even inconsistent. 00470 * 00471 * @since New in 1.2. 00472 */ 00473 int 00474 svn_cstring_count_newlines(const char *msg); 00475 00476 /** 00477 * Return a cstring which is the concatenation of @a strings (an array 00478 * of char *) each followed by @a separator (that is, @a separator 00479 * will also end the resulting string). Allocate the result in @a pool. 00480 * If @a strings is empty, then return the empty string. 00481 * 00482 * @since New in 1.2. 00483 */ 00484 char * 00485 svn_cstring_join(const apr_array_header_t *strings, 00486 const char *separator, 00487 apr_pool_t *pool); 00488 00489 /** 00490 * Compare two strings @a atr1 and @a atr2, treating case-equivalent 00491 * unaccented Latin (ASCII subset) letters as equal. 00492 * 00493 * Returns in integer greater than, equal to, or less than 0, 00494 * according to whether @a str1 is considered greater than, equal to, 00495 * or less than @a str2. 00496 * 00497 * @since New in 1.5. 00498 */ 00499 int 00500 svn_cstring_casecmp(const char *str1, const char *str2); 00501 00502 /** 00503 * Parse the C string @a str into a 64 bit number, and return it in @a *n. 00504 * Assume that the number is represented in base @a base. 00505 * Raise an error if conversion fails (e.g. due to overflow), or if the 00506 * converted number is smaller than @a minval or larger than @a maxval. 00507 * 00508 * @since New in 1.7. 00509 */ 00510 svn_error_t * 00511 svn_cstring_strtoi64(apr_int64_t *n, const char *str, 00512 apr_int64_t minval, apr_int64_t maxval, 00513 int base); 00514 00515 /** 00516 * Parse the C string @a str into a 64 bit number, and return it in @a *n. 00517 * Assume that the number is represented in base 10. 00518 * Raise an error if conversion fails (e.g. due to overflow). 00519 * 00520 * @since New in 1.7. 00521 */ 00522 svn_error_t * 00523 svn_cstring_atoi64(apr_int64_t *n, const char *str); 00524 00525 /** 00526 * Parse the C string @a str into a 32 bit number, and return it in @a *n. 00527 * Assume that the number is represented in base 10. 00528 * Raise an error if conversion fails (e.g. due to overflow). 00529 * 00530 * @since New in 1.7. 00531 */ 00532 svn_error_t * 00533 svn_cstring_atoi(int *n, const char *str); 00534 00535 /** 00536 * Parse the C string @a str into an unsigned 64 bit number, and return 00537 * it in @a *n. Assume that the number is represented in base @a base. 00538 * Raise an error if conversion fails (e.g. due to overflow), or if the 00539 * converted number is smaller than @a minval or larger than @a maxval. 00540 * 00541 * @since New in 1.7. 00542 */ 00543 svn_error_t * 00544 svn_cstring_strtoui64(apr_uint64_t *n, const char *str, 00545 apr_uint64_t minval, apr_uint64_t maxval, 00546 int base); 00547 00548 /** 00549 * Parse the C string @a str into an unsigned 64 bit number, and return 00550 * it in @a *n. Assume that the number is represented in base 10. 00551 * Raise an error if conversion fails (e.g. due to overflow). 00552 * 00553 * @since New in 1.7. 00554 */ 00555 svn_error_t * 00556 svn_cstring_atoui64(apr_uint64_t *n, const char *str); 00557 00558 /** 00559 * Parse the C string @a str into an unsigned 32 bit number, and return 00560 * it in @a *n. Assume that the number is represented in base 10. 00561 * Raise an error if conversion fails (e.g. due to overflow). 00562 * 00563 * @since New in 1.7. 00564 */ 00565 svn_error_t * 00566 svn_cstring_atoui(unsigned int *n, const char *str); 00567 00568 /** @} */ 00569 00570 /** @} */ 00571 00572 00573 #ifdef __cplusplus 00574 } 00575 #endif /* __cplusplus */ 00576 00577 #endif /* SVN_STRING_H */