Subversion 1.6.16

svn_string.h

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