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

Generated on Sun Dec 14 02:22:43 2008 for Subversion by  doxygen 1.4.7