Main Page   Modules   Data Structures   File List   Data Fields  

svn_string.h

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

Generated on Wed Jun 7 11:02:15 2006 for Subversion by doxygen1.2.14 written by Dimitri van Heesch, © 1997-2002