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 /** svn_string_t functions.
00124  *
00125  * @defgroup svn_string_svn_string_t svn_string_t functions
00126  * @{
00127  */
00128 
00129 /** Create a new bytestring containing a C string (NULL-terminated). */
00130 svn_string_t *
00131 svn_string_create(const char *cstring, apr_pool_t *pool);
00132 
00133 /** Create a new bytestring containing a generic string of bytes
00134  * (NOT NULL-terminated) */
00135 svn_string_t *
00136 svn_string_ncreate(const char *bytes, apr_size_t size, apr_pool_t *pool);
00137 
00138 /** Create a new string with the contents of the given stringbuf */
00139 svn_string_t *
00140 svn_string_create_from_buf(const svn_stringbuf_t *strbuf, apr_pool_t *pool);
00141 
00142 /** Create a new bytestring by formatting @a cstring (NULL-terminated)
00143  * from varargs, which are as appropriate for apr_psprintf().
00144  */
00145 svn_string_t *
00146 svn_string_createf(apr_pool_t *pool, const char *fmt, ...)
00147   __attribute__((format(printf, 2, 3)));
00148 
00149 /** Create a new bytestring by formatting @a cstring (NULL-terminated)
00150  * from a @c va_list (see svn_stringbuf_createf()).
00151  */
00152 svn_string_t *
00153 svn_string_createv(apr_pool_t *pool, const char *fmt, va_list ap)
00154   __attribute__((format(printf, 2, 0)));
00155 
00156 /** Return TRUE if a bytestring is empty (has length zero). */
00157 svn_boolean_t
00158 svn_string_isempty(const svn_string_t *str);
00159 
00160 /** Return a duplicate of @a original_string. */
00161 svn_string_t *
00162 svn_string_dup(const svn_string_t *original_string, apr_pool_t *pool);
00163 
00164 /** Return @c TRUE iff @a str1 and @a str2 have identical length and data. */
00165 svn_boolean_t
00166 svn_string_compare(const svn_string_t *str1, const svn_string_t *str2);
00167 
00168 /** Return offset of first non-whitespace character in @a str, or return
00169  * @a str->len if none.
00170  */
00171 apr_size_t
00172 svn_string_first_non_whitespace(const svn_string_t *str);
00173 
00174 /** Return position of last occurrence of @a ch in @a str, or return
00175  * @a str->len if no occurrence.
00176  */
00177 apr_size_t
00178 svn_string_find_char_backward(const svn_string_t *str, char ch);
00179 
00180 /** @} */
00181 
00182 
00183 /** svn_stringbuf_t functions.
00184  *
00185  * @defgroup svn_string_svn_stringbuf_t svn_stringbuf_t functions
00186  * @{
00187  */
00188 
00189 /** Create a new bytestring containing a C string (NULL-terminated). */
00190 svn_stringbuf_t *
00191 svn_stringbuf_create(const char *cstring, apr_pool_t *pool);
00192 
00193 /** Create a new bytestring containing a generic string of bytes
00194  * (NON-NULL-terminated)
00195  */
00196 svn_stringbuf_t *
00197 svn_stringbuf_ncreate(const char *bytes, apr_size_t size, apr_pool_t *pool);
00198 
00199 /** Create a new empty bytestring with at least @a minimum_size bytes of
00200  * space available in the memory block.
00201  *
00202  * The allocated string buffer will be one byte larger then @a minimum_size
00203  * to account for a final '\\0'.
00204  *
00205  * @since New in 1.6.
00206  */
00207 svn_stringbuf_t *
00208 svn_stringbuf_create_ensure(apr_size_t minimum_size, apr_pool_t *pool);
00209 
00210 /** Create a new stringbuf with the contents of the given string */
00211 svn_stringbuf_t *
00212 svn_stringbuf_create_from_string(const svn_string_t *str, apr_pool_t *pool);
00213 
00214 /** Create a new bytestring by formatting @a cstring (NULL-terminated)
00215  * from varargs, which are as appropriate for apr_psprintf().
00216  */
00217 svn_stringbuf_t *
00218 svn_stringbuf_createf(apr_pool_t *pool, const char *fmt, ...)
00219   __attribute__((format(printf, 2, 3)));
00220 
00221 /** Create a new bytestring by formatting @a cstring (NULL-terminated)
00222  * from a @c va_list (see svn_stringbuf_createf()).
00223  */
00224 svn_stringbuf_t *
00225 svn_stringbuf_createv(apr_pool_t *pool, const char *fmt, va_list ap)
00226   __attribute__((format(printf, 2, 0)));
00227 
00228 /** Make sure that the string @a str has at least @a minimum_size bytes of
00229  * space available in the memory block.
00230  *
00231  * (@a minimum_size should include space for the terminating NULL character.)
00232  */
00233 void
00234 svn_stringbuf_ensure(svn_stringbuf_t *str, apr_size_t minimum_size);
00235 
00236 /** Set a bytestring @a str to @a value */
00237 void
00238 svn_stringbuf_set(svn_stringbuf_t *str, const char *value);
00239 
00240 /** Set a bytestring @a str to empty (0 length). */
00241 void
00242 svn_stringbuf_setempty(svn_stringbuf_t *str);
00243 
00244 /** Return @c TRUE if a bytestring is empty (has length zero). */
00245 svn_boolean_t
00246 svn_stringbuf_isempty(const svn_stringbuf_t *str);
00247 
00248 /** Chop @a nbytes bytes off end of @a str, but not more than @a str->len. */
00249 void
00250 svn_stringbuf_chop(svn_stringbuf_t *str, apr_size_t nbytes);
00251 
00252 /** Fill bytestring @a str with character @a c. */
00253 void
00254 svn_stringbuf_fillchar(svn_stringbuf_t *str, unsigned char c);
00255 
00256 /** Append an array of bytes onto @a targetstr.
00257  *
00258  * reallocs if necessary. @a targetstr is affected, nothing else is.
00259  */
00260 void
00261 svn_stringbuf_appendbytes(svn_stringbuf_t *targetstr,
00262                           const char *bytes,
00263                           apr_size_t count);
00264 
00265 /** Append an @c svn_stringbuf_t onto @a targetstr.
00266  *
00267  * reallocs if necessary. @a targetstr is affected, nothing else is.
00268  */
00269 void
00270 svn_stringbuf_appendstr(svn_stringbuf_t *targetstr,
00271                         const svn_stringbuf_t *appendstr);
00272 
00273 /** Append a C string onto @a targetstr.
00274  *
00275  * reallocs if necessary. @a targetstr is affected, nothing else is.
00276  */
00277 void
00278 svn_stringbuf_appendcstr(svn_stringbuf_t *targetstr,
00279                          const char *cstr);
00280 
00281 /** Return a duplicate of @a original_string. */
00282 svn_stringbuf_t *
00283 svn_stringbuf_dup(const svn_stringbuf_t *original_string, apr_pool_t *pool);
00284 
00285 /** Return @c TRUE iff @a str1 and @a str2 have identical length and data. */
00286 svn_boolean_t
00287 svn_stringbuf_compare(const svn_stringbuf_t *str1,
00288                       const svn_stringbuf_t *str2);
00289 
00290 /** Return offset of first non-whitespace character in @a str, or return
00291  * @a str->len if none.
00292  */
00293 apr_size_t
00294 svn_stringbuf_first_non_whitespace(const svn_stringbuf_t *str);
00295 
00296 /** Strip whitespace from both sides of @a str (modified in place). */
00297 void
00298 svn_stringbuf_strip_whitespace(svn_stringbuf_t *str);
00299 
00300 /** Return position of last occurrence of @a ch in @a str, or return
00301  * @a str->len if no occurrence.
00302  */
00303 apr_size_t
00304 svn_stringbuf_find_char_backward(const svn_stringbuf_t *str, char ch);
00305 
00306 /** Return @c TRUE iff @a str1 and @a str2 have identical length and data. */
00307 svn_boolean_t
00308 svn_string_compare_stringbuf(const svn_string_t *str1,
00309                              const svn_stringbuf_t *str2);
00310 
00311 /** @} */
00312 
00313 
00314 /** C strings.
00315  *
00316  * @defgroup svn_string_cstrings c string functions
00317  * @{
00318  */
00319 
00320 /** Divide @a input into substrings along @a sep_chars boundaries, return an
00321  * array of copies of those substrings, allocating both the array and
00322  * the copies in @a pool.
00323  *
00324  * None of the elements added to the array contain any of the
00325  * characters in @a sep_chars, and none of the new elements are empty
00326  * (thus, it is possible that the returned array will have length
00327  * zero).
00328  *
00329  * If @a chop_whitespace is TRUE, then remove leading and trailing
00330  * whitespace from the returned strings.
00331  */
00332 apr_array_header_t *
00333 svn_cstring_split(const char *input,
00334                   const char *sep_chars,
00335                   svn_boolean_t chop_whitespace,
00336                   apr_pool_t *pool);
00337 
00338 /** Like svn_cstring_split(), but append to existing @a array instead of
00339  * creating a new one.  Allocate the copied substrings in @a pool
00340  * (i.e., caller decides whether or not to pass @a array->pool as @a pool).
00341  */
00342 void
00343 svn_cstring_split_append(apr_array_header_t *array,
00344                          const char *input,
00345                          const char *sep_chars,
00346                          svn_boolean_t chop_whitespace,
00347                          apr_pool_t *pool);
00348 
00349 
00350 /** Return @c TRUE iff @a str matches any of the elements of @a list, a list
00351  * of zero or more glob patterns.
00352  */
00353 svn_boolean_t
00354 svn_cstring_match_glob_list(const char *str, const apr_array_header_t *list);
00355 
00356 /**
00357  * Return the number of line breaks in @a msg, allowing any kind of newline
00358  * termination (CR, LF, CRLF, or LFCR), even inconsistent.
00359  *
00360  * @since New in 1.2.
00361  */
00362 int
00363 svn_cstring_count_newlines(const char *msg);
00364 
00365 /**
00366  * Return a cstring which is the concatenation of @a strings (an array
00367  * of char *) each followed by @a separator (that is, @a separator
00368  * will also end the resulting string).  Allocate the result in @a pool.
00369  * If @a strings is empty, then return the empty string.
00370  *
00371  * @since New in 1.2.
00372  */
00373 char *
00374 svn_cstring_join(const apr_array_header_t *strings,
00375                  const char *separator,
00376                  apr_pool_t *pool);
00377 
00378 /**
00379  * Compare two strings @a atr1 and @a atr2, treating case-equivalent
00380  * unaccented Latin (ASCII subset) letters as equal.
00381  *
00382  * Returns in integer greater than, equal to, or less than 0,
00383  * according to whether @a str1 is considered greater than, equal to,
00384  * or less than @a str2.
00385  *
00386  * @since New in 1.5.
00387  */
00388 int
00389 svn_cstring_casecmp(const char *str1, const char *str2);
00390 
00391 
00392 /** @} */
00393 
00394 /** @} */
00395 
00396 
00397 #ifdef __cplusplus
00398 }
00399 #endif /* __cplusplus */
00400 
00401 #endif  /* SVN_STRING_H */

Generated on Sat Mar 20 04:06:12 2010 for Subversion by  doxygen 1.3.9.1