- Main Page
- Related Pages
- Modules
- Data Structures
- Files

- File List
- Globals

# svn_string.h

Go to the documentation of this file.

    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 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 bytestring containing a C string (NULL-terminated). */
    00129 svn_string_t *
    00130 svn_string_create(const char *cstring, apr_pool_t *pool);
    00131
    00132 /** Create a new bytestring containing a generic string of bytes
    00133  * (NOT NULL-terminated) */
    00134 svn_string_t *
    00135 svn_string_ncreate(const char *bytes, apr_size_t size, apr_pool_t *pool);
    00136
    00137 /** Create a new string with the contents of the given stringbuf */
    00138 svn_string_t *
    00139 svn_string_create_from_buf(const svn_stringbuf_t *strbuf, apr_pool_t *pool);
    00140
    00141 /** Create a new bytestring by formatting @a cstring (NULL-terminated)
    00142  * from varargs, which are as appropriate for apr_psprintf().
    00143  */
    00144 svn_string_t *
    00145 svn_string_createf(apr_pool_t *pool, const char *fmt, ...)
    00146   __attribute__((format(printf, 2, 3)));
    00147
    00148 /** Create a new bytestring by formatting @a cstring (NULL-terminated)
    00149  * from a @c va_list (see svn_stringbuf_createf()).
    00150  */
    00151 svn_string_t *
    00152 svn_string_createv(apr_pool_t *pool, const char *fmt, va_list ap)
    00153   __attribute__((format(printf, 2, 0)));
    00154
    00155 /** Return TRUE if a bytestring is empty (has length zero). */
    00156 svn_boolean_t
    00157 svn_string_isempty(const svn_string_t *str);
    00158
    00159 /** Return a duplicate of @a original_string. */
    00160 svn_string_t *
    00161 svn_string_dup(const svn_string_t *original_string, apr_pool_t *pool);
    00162
    00163 /** Return @c TRUE iff @a str1 and @a str2 have identical length and data. */
    00164 svn_boolean_t
    00165 svn_string_compare(const svn_string_t *str1, const svn_string_t *str2);
    00166
    00167 /** Return offset of first non-whitespace character in @a str, or return
    00168  * @a str->len if none.
    00169  */
    00170 apr_size_t
    00171 svn_string_first_non_whitespace(const svn_string_t *str);
    00172
    00173 /** Return position of last occurrence of @a ch in @a str, or return
    00174  * @a str->len if no occurrence.
    00175  */
    00176 apr_size_t
    00177 svn_string_find_char_backward(const svn_string_t *str, char ch);
    00178
    00179 /** @} */
    00180
    00181
    00182 /**
    00183  * @defgroup svn_string_svn_stringbuf_t svn_stringbuf_t functions
    00184  * @{
    00185  */
    00186
    00187 /** Create a new bytestring containing a C string (NULL-terminated). */
    00188 svn_stringbuf_t *
    00189 svn_stringbuf_create(const char *cstring, apr_pool_t *pool);
    00190
    00191 /** Create a new bytestring containing a generic string of bytes
    00192  * (NON-NULL-terminated)
    00193  */
    00194 svn_stringbuf_t *
    00195 svn_stringbuf_ncreate(const char *bytes, apr_size_t size, apr_pool_t *pool);
    00196
    00197 /** Create a new empty bytestring with at least @a minimum_size bytes of
    00198  * space available in the memory block.
    00199  *
    00200  * The allocated string buffer will be one byte larger than @a minimum_size
    00201  * to account for a final '\\0'.
    00202  *
    00203  * @since New in 1.6.
    00204  */
    00205 svn_stringbuf_t *
    00206 svn_stringbuf_create_ensure(apr_size_t minimum_size, apr_pool_t *pool);
    00207
    00208 /** Create a new stringbuf with the contents of the given string */
    00209 svn_stringbuf_t *
    00210 svn_stringbuf_create_from_string(const svn_string_t *str, apr_pool_t *pool);
    00211
    00212 /** Create a new bytestring by formatting @a cstring (NULL-terminated)
    00213  * from varargs, which are as appropriate for apr_psprintf().
    00214  */
    00215 svn_stringbuf_t *
    00216 svn_stringbuf_createf(apr_pool_t *pool, const char *fmt, ...)
    00217   __attribute__((format(printf, 2, 3)));
    00218
    00219 /** Create a new bytestring by formatting @a cstring (NULL-terminated)
    00220  * from a @c va_list (see svn_stringbuf_createf()).
    00221  */
    00222 svn_stringbuf_t *
    00223 svn_stringbuf_createv(apr_pool_t *pool, const char *fmt, va_list ap)
    00224   __attribute__((format(printf, 2, 0)));
    00225
    00226 /** Make sure that the string @a str has at least @a minimum_size bytes of
    00227  * space available in the memory block.
    00228  *
    00229  * (@a minimum_size should include space for the terminating NULL character.)
    00230  */
    00231 void
    00232 svn_stringbuf_ensure(svn_stringbuf_t *str, apr_size_t minimum_size);
    00233
    00234 /** Set a bytestring @a str to @a value */
    00235 void
    00236 svn_stringbuf_set(svn_stringbuf_t *str, const char *value);
    00237
    00238 /** Set a bytestring @a str to empty (0 length). */
    00239 void
    00240 svn_stringbuf_setempty(svn_stringbuf_t *str);
    00241
    00242 /** Return @c TRUE if a bytestring is empty (has length zero). */
    00243 svn_boolean_t
    00244 svn_stringbuf_isempty(const svn_stringbuf_t *str);
    00245
    00246 /** Chop @a nbytes bytes off end of @a str, but not more than @a str->len. */
    00247 void
    00248 svn_stringbuf_chop(svn_stringbuf_t *str, apr_size_t nbytes);
    00249
    00250 /** Fill bytestring @a str with character @a c. */
    00251 void
    00252 svn_stringbuf_fillchar(svn_stringbuf_t *str, unsigned char c);
    00253
    00254 /** Append a single character @a byte onto @a targetstr.
    00255  * This is an optimized version of svn_stringbuf_appendbytes()
    00256  * that is much faster to call and execute. Gains vary with the ABI.
    00257  * The advantages extend beyond the actual call because the reduced
    00258  * register pressure allows for more optimization within the caller.
    00259  *
    00260  * reallocs if necessary. @a targetstr is affected, nothing else is.
    00261  * @since New in 1.7.
    00262  */
    00263 void
    00264 svn_stringbuf_appendbyte(svn_stringbuf_t *targetstr,
    00265                          char byte);
    00266
    00267 /** Append an array of bytes onto @a targetstr.
    00268  *
    00269  * reallocs if necessary. @a targetstr is affected, nothing else is.
    00270  */
    00271 void
    00272 svn_stringbuf_appendbytes(svn_stringbuf_t *targetstr,
    00273                           const char *bytes,
    00274                           apr_size_t count);
    00275
    00276 /** Append an @c svn_stringbuf_t onto @a targetstr.
    00277  *
    00278  * reallocs if necessary. @a targetstr is affected, nothing else is.
    00279  */
    00280 void
    00281 svn_stringbuf_appendstr(svn_stringbuf_t *targetstr,
    00282                         const svn_stringbuf_t *appendstr);
    00283
    00284 /** Append a C string onto @a targetstr.
    00285  *
    00286  * reallocs if necessary. @a targetstr is affected, nothing else is.
    00287  */
    00288 void
    00289 svn_stringbuf_appendcstr(svn_stringbuf_t *targetstr,
    00290                          const char *cstr);
    00291
    00292 /** Return a duplicate of @a original_string. */
    00293 svn_stringbuf_t *
    00294 svn_stringbuf_dup(const svn_stringbuf_t *original_string, apr_pool_t *pool);
    00295
    00296 /** Return @c TRUE iff @a str1 and @a str2 have identical length and data. */
    00297 svn_boolean_t
    00298 svn_stringbuf_compare(const svn_stringbuf_t *str1,
    00299                       const svn_stringbuf_t *str2);
    00300
    00301 /** Return offset of first non-whitespace character in @a str, or return
    00302  * @a str->len if none.
    00303  */
    00304 apr_size_t
    00305 svn_stringbuf_first_non_whitespace(const svn_stringbuf_t *str);
    00306
    00307 /** Strip whitespace from both sides of @a str (modified in place). */
    00308 void
    00309 svn_stringbuf_strip_whitespace(svn_stringbuf_t *str);
    00310
    00311 /** Return position of last occurrence of @a ch in @a str, or return
    00312  * @a str->len if no occurrence.
    00313  */
    00314 apr_size_t
    00315 svn_stringbuf_find_char_backward(const svn_stringbuf_t *str, char ch);
    00316
    00317 /** Return @c TRUE iff @a str1 and @a str2 have identical length and data. */
    00318 svn_boolean_t
    00319 svn_string_compare_stringbuf(const svn_string_t *str1,
    00320                              const svn_stringbuf_t *str2);
    00321
    00322 /** @} */
    00323
    00324
    00325 /**
    00326  * @defgroup svn_string_cstrings C string functions
    00327  * @{
    00328  */
    00329
    00330 /** Divide @a input into substrings along @a sep_chars boundaries, return an
    00331  * array of copies of those substrings (plain const char*), allocating both
    00332  * the array and the copies in @a pool.
    00333  *
    00334  * None of the elements added to the array contain any of the
    00335  * characters in @a sep_chars, and none of the new elements are empty
    00336  * (thus, it is possible that the returned array will have length
    00337  * zero).
    00338  *
    00339  * If @a chop_whitespace is TRUE, then remove leading and trailing
    00340  * whitespace from the returned strings.
    00341  */
    00342 apr_array_header_t *
    00343 svn_cstring_split(const char *input,
    00344                   const char *sep_chars,
    00345                   svn_boolean_t chop_whitespace,
    00346                   apr_pool_t *pool);
    00347
    00348 /** Like svn_cstring_split(), but append to existing @a array instead of
    00349  * creating a new one.  Allocate the copied substrings in @a pool
    00350  * (i.e., caller decides whether or not to pass @a array->pool as @a pool).
    00351  */
    00352 void
    00353 svn_cstring_split_append(apr_array_header_t *array,
    00354                          const char *input,
    00355                          const char *sep_chars,
    00356                          svn_boolean_t chop_whitespace,
    00357                          apr_pool_t *pool);
    00358
    00359
    00360 /** Return @c TRUE iff @a str matches any of the elements of @a list, a list
    00361  * of zero or more glob patterns.
    00362  */
    00363 svn_boolean_t
    00364 svn_cstring_match_glob_list(const char *str, const apr_array_header_t *list);
    00365
    00366 /** Return @c TRUE iff @a str exactly matches any of the elements of @a list.
    00367  *
    00368  * @since new in 1.7
    00369  */
    00370 svn_boolean_t
    00371 svn_cstring_match_list(const char *str, const apr_array_header_t *list);
    00372
    00373 /**
    00374  * Return the number of line breaks in @a msg, allowing any kind of newline
    00375  * termination (CR, LF, CRLF, or LFCR), even inconsistent.
    00376  *
    00377  * @since New in 1.2.
    00378  */
    00379 int
    00380 svn_cstring_count_newlines(const char *msg);
    00381
    00382 /**
    00383  * Return a cstring which is the concatenation of @a strings (an array
    00384  * of char *) each followed by @a separator (that is, @a separator
    00385  * will also end the resulting string).  Allocate the result in @a pool.
    00386  * If @a strings is empty, then return the empty string.
    00387  *
    00388  * @since New in 1.2.
    00389  */
    00390 char *
    00391 svn_cstring_join(const apr_array_header_t *strings,
    00392                  const char *separator,
    00393                  apr_pool_t *pool);
    00394
    00395 /**
    00396  * Compare two strings @a atr1 and @a atr2, treating case-equivalent
    00397  * unaccented Latin (ASCII subset) letters as equal.
    00398  *
    00399  * Returns in integer greater than, equal to, or less than 0,
    00400  * according to whether @a str1 is considered greater than, equal to,
    00401  * or less than @a str2.
    00402  *
    00403  * @since New in 1.5.
    00404  */
    00405 int
    00406 svn_cstring_casecmp(const char *str1, const char *str2);
    00407
    00408 /**
    00409  * Parse the C string @a str into a 64 bit number, and return it in @a *n.
    00410  * Assume that the number is represented in base @a base.
    00411  * Raise an error if conversion fails (e.g. due to overflow), or if the
    00412  * converted number is smaller than @a minval or larger than @a maxval.
    00413  *
    00414  * @since New in 1.7.
    00415  */
    00416 svn_error_t *
    00417 svn_cstring_strtoi64(apr_int64_t *n, const char *str,
    00418                      apr_int64_t minval, apr_int64_t maxval,
    00419                      int base);
    00420
    00421 /**
    00422  * Parse the C string @a str into a 64 bit number, and return it in @a *n.
    00423  * Assume that the number is represented in base 10.
    00424  * Raise an error if conversion fails (e.g. due to overflow).
    00425  *
    00426  * @since New in 1.7.
    00427  */
    00428 svn_error_t *
    00429 svn_cstring_atoi64(apr_int64_t *n, const char *str);
    00430
    00431 /**
    00432  * Parse the C string @a str into a 32 bit number, and return it in @a *n.
    00433  * Assume that the number is represented in base 10.
    00434  * Raise an error if conversion fails (e.g. due to overflow).
    00435  *
    00436  * @since New in 1.7.
    00437  */
    00438 svn_error_t *
    00439 svn_cstring_atoi(int *n, const char *str);
    00440
    00441 /**
    00442  * Parse the C string @a str into an unsigned 64 bit number, and return
    00443  * it in @a *n. Assume that the number is represented in base @a base.
    00444  * Raise an error if conversion fails (e.g. due to overflow), or if the
    00445  * converted number is smaller than @a minval or larger than @a maxval.
    00446  *
    00447  * @since New in 1.7.
    00448  */
    00449 svn_error_t *
    00450 svn_cstring_strtoui64(apr_uint64_t *n, const char *str,
    00451                       apr_uint64_t minval, apr_uint64_t maxval,
    00452                       int base);
    00453
    00454 /**
    00455  * Parse the C string @a str into an unsigned 64 bit number, and return
    00456  * it in @a *n. Assume that the number is represented in base 10.
    00457  * Raise an error if conversion fails (e.g. due to overflow).
    00458  *
    00459  * @since New in 1.7.
    00460  */
    00461 svn_error_t *
    00462 svn_cstring_atoui64(apr_uint64_t *n, const char *str);
    00463
    00464 /**
    00465  * Parse the C string @a str into an unsigned 32 bit number, and return
    00466  * it in @a *n. Assume that the number is represented in base 10.
    00467  * Raise an error if conversion fails (e.g. due to overflow).
    00468  *
    00469  * @since New in 1.7.
    00470  */
    00471 svn_error_t *
    00472 svn_cstring_atoui(unsigned int *n, const char *str);
    00473
    00474 /** @} */
    00475
    00476 /** @} */
    00477
    00478
    00479 #ifdef __cplusplus
    00480 }
    00481 #endif /* __cplusplus */
    00482
    00483 #endif  /* SVN_STRING_H */

All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines