src/TortoiseMerge/svninclude/svn_string.h

   1 /**
   2  * @copyright
   3  * ====================================================================
   4  * Copyright (c) 2000-2006 CollabNet.  All rights reserved.
   5  *
   6  * This software is licensed as described in the file COPYING, which
   7  * you should have received as part of this distribution.  The terms
   8  * are also available at http://subversion.tigris.org/license-1.html.
   9  * If newer versions of this license are posted there, you may use a
  10  * newer version instead, at your option.
  11  *
  12  * This software consists of voluntary contributions made by many
  13  * individuals.  For exact contribution history, see the revision
  14  * history and logs, available at http://subversion.tigris.org/.
  15  * ====================================================================
  16  * @endcopyright
  17  *
  18  * @file svn_string.h
  19  * @brief Counted-length strings for Subversion, plus some C string goodies.
  20  *
  21  * There are two string datatypes: @c svn_string_t and @c svn_stringbuf_t.
  22  * The former is a simple pointer/length pair useful for passing around
  23  * strings (or arbitrary bytes) with a counted length. @c svn_stringbuf_t is
  24  * buffered to enable efficient appending of strings without an allocation
  25  * and copy for each append operation.
  26  *
  27  * @c svn_string_t contains a <tt>const char *</tt> for its data, so it is
  28  * most appropriate for constant data and for functions which expect constant,
  29  * counted data. Functions should generally use <tt>const @c svn_string_t
  30  * *</tt> as their parameter to indicate they are expecting a constant,
  31  * counted string.
  32  *
  33  * @c svn_stringbuf_t uses a plain <tt>char *</tt> for its data, so it is
  34  * most appropriate for modifiable data.
  35  *
  36  * <h3>Invariants</h3>
  37  *
  38  *   1. Null termination:
  39  *
  40  *      Both structures maintain a significant invariant:
  41  *
  42  *         <tt>s->data[s->len] == '\\0'</tt>
  43  *
  44  *      The functions defined within this header file will maintain
  45  *      the invariant (which does imply that memory is
  46  *      allocated/defined as @c len+1 bytes).  If code outside of the
  47  *      @c svn_string.h functions manually builds these structures,
  48  *      then they must enforce this invariant.
  49  *
  50  *      Note that an @c svn_string(buf)_t may contain binary data,
  51  *      which means that strlen(s->data) does not have to equal @c
  52  *      s->len. The NULL terminator is provided to make it easier to
  53  *      pass @c s->data to C string interfaces.
  54  *
  55  *
  56  *   2. Non-NULL input:
  57  *
  58  *      All the functions assume their input data is non-NULL,
  59  *      unless otherwise documented, and may seg fault if passed
  60  *      NULL.  The input data may *contain* null bytes, of course, just
  61  *      the data pointer itself must not be NULL.
  62  *
  63  * <h3>Memory allocation</h3>
  64  *
  65  *   All the functions make a deep copy of all input data, and never store
  66  *   a pointer to the original input data.
  67  */
  68
  69
  70 #ifndef SVN_STRING_H
  71 #define SVN_STRING_H
  72
  73 #include <apr.h>
  74 #include <apr_tables.h>
  75 #include <apr_pools.h>       /* APR memory pools for everyone. */
  76 #include <apr_strings.h>
  77
  78 #include "svn_types.h"
  79
  80 #ifdef __cplusplus
  81 extern "C" {
  82 #endif /* __cplusplus */
  83
  84 /**
  85  * @defgroup svn_string String handling
  86  * @{
  87  */
  88
  89 \f
  90
  91 /** A simple counted string. */
  92 typedef struct svn_string_t
  93 {
  94   const char *data; /**< pointer to the bytestring */
  95   apr_size_t len;   /**< length of bytestring */
  96 } svn_string_t;
  97
  98 /** A buffered string, capable of appending without an allocation and copy
  99  * for each append. */
 100 typedef struct svn_stringbuf_t
 101 {
 102   /** a pool from which this string was originally allocated, and is not
 103    * necessarily specific to this string.  This is used only for allocating
 104    * more memory from when the string needs to grow.
 105    */
 106   apr_pool_t *pool;
 107
 108   /** pointer to the bytestring */
 109   char *data;
 110
 111   /** length of bytestring */
 112   apr_size_t len;
 113
 114   /** total size of buffer allocated */
 115   apr_size_t blocksize;
 116 } svn_stringbuf_t;
 117
 118 \f
 119 /** svn_string_t functions.
 120  *
 121  * @defgroup svn_string_svn_string_t svn_string_t functions
 122  * @{
 123  */
 124
 125 /** Create a new bytestring containing a C string (NULL-terminated). */
 126 svn_string_t *
 127 svn_string_create(const char *cstring, apr_pool_t *pool);
 128
 129 /** Create a new bytestring containing a generic string of bytes
 130  * (NOT NULL-terminated) */
 131 svn_string_t *
 132 svn_string_ncreate(const char *bytes, apr_size_t size, apr_pool_t *pool);
 133
 134 /** Create a new string with the contents of the given stringbuf */
 135 svn_string_t *
 136 svn_string_create_from_buf(const svn_stringbuf_t *strbuf, apr_pool_t *pool);
 137
 138 /** Create a new bytestring by formatting @a cstring (NULL-terminated)
 139  * from varargs, which are as appropriate for apr_psprintf().
 140  */
 141 svn_string_t *
 142 svn_string_createf(apr_pool_t *pool, const char *fmt, ...)
 143   __attribute__((format(printf, 2, 3)));
 144
 145 /** Create a new bytestring by formatting @a cstring (NULL-terminated)
 146  * from a @c va_list (see svn_stringbuf_createf()).
 147  */
 148 svn_string_t *
 149 svn_string_createv(apr_pool_t *pool, const char *fmt, va_list ap)
 150   __attribute__((format(printf, 2, 0)));
 151
 152 /** Return TRUE if a bytestring is empty (has length zero). */
 153 svn_boolean_t
 154 svn_string_isempty(const svn_string_t *str);
 155
 156 /** Return a duplicate of @a original_string. */
 157 svn_string_t *
 158 svn_string_dup(const svn_string_t *original_string, apr_pool_t *pool);
 159
 160 /** Return @c TRUE iff @a str1 and @a str2 have identical length and data. */
 161 svn_boolean_t
 162 svn_string_compare(const svn_string_t *str1, const svn_string_t *str2);
 163
 164 /** Return offset of first non-whitespace character in @a str, or return
 165  * @a str->len if none.
 166  */
 167 apr_size_t
 168 svn_string_first_non_whitespace(const svn_string_t *str);
 169
 170 /** Return position of last occurrence of @a ch in @a str, or return
 171  * @a str->len if no occurrence.
 172  */
 173 apr_size_t
 174 svn_string_find_char_backward(const svn_string_t *str, char ch);
 175
 176 /** @} */
 177
 178 \f
 179 /** svn_stringbuf_t functions.
 180  *
 181  * @defgroup svn_string_svn_stringbuf_t svn_stringbuf_t functions
 182  * @{
 183  */
 184
 185 /** Create a new bytestring containing a C string (NULL-terminated). */
 186 svn_stringbuf_t *
 187 svn_stringbuf_create(const char *cstring, apr_pool_t *pool);
 188 /** Create a new bytestring containing a generic string of bytes
 189  * (NON-NULL-terminated)
 190  */
 191 svn_stringbuf_t *
 192 svn_stringbuf_ncreate(const char *bytes, apr_size_t size, apr_pool_t *pool);
 193 /** Create a new empty bytestring with at least @a minimum_size bytes of
 194  * space available in the memory block.
 195  *
 196  * (@a minimum_size should include space for the terminating NULL character.)
 197  *
 198  * @since New in 1.6.
 199  */
 200 svn_stringbuf_t *
 201 svn_stringbuf_create_ensure(apr_size_t minimum_size, apr_pool_t *pool);
 202
 203 /** Create a new stringbuf with the contents of the given string */
 204 svn_stringbuf_t *
 205 svn_stringbuf_create_from_string(const svn_string_t *str, apr_pool_t *pool);
 206
 207 /** Create a new bytestring by formatting @a cstring (NULL-terminated)
 208  * from varargs, which are as appropriate for apr_psprintf().
 209  */
 210 svn_stringbuf_t *
 211 svn_stringbuf_createf(apr_pool_t *pool, const char *fmt, ...)
 212   __attribute__((format(printf, 2, 3)));
 213
 214 /** Create a new bytestring by formatting @a cstring (NULL-terminated)
 215  * from a @c va_list (see svn_stringbuf_createf()).
 216  */
 217 svn_stringbuf_t *
 218 svn_stringbuf_createv(apr_pool_t *pool, const char *fmt, va_list ap)
 219   __attribute__((format(printf, 2, 0)));
 220
 221 /** Make sure that the string @a str has at least @a minimum_size bytes of
 222  * space available in the memory block.
 223  *
 224  * (@a minimum_size should include space for the terminating NULL character.)
 225  */
 226 void
 227 svn_stringbuf_ensure(svn_stringbuf_t *str, apr_size_t minimum_size);
 228
 229 /** Set a bytestring @a str to @a value */
 230 void
 231 svn_stringbuf_set(svn_stringbuf_t *str, const char *value);
 232
 233 /** Set a bytestring @a str to empty (0 length). */
 234 void
 235 svn_stringbuf_setempty(svn_stringbuf_t *str);
 236
 237 /** Return @c TRUE if a bytestring is empty (has length zero). */
 238 svn_boolean_t
 239 svn_stringbuf_isempty(const svn_stringbuf_t *str);
 240
 241 /** Chop @a nbytes bytes off end of @a str, but not more than @a str->len. */
 242 void
 243 svn_stringbuf_chop(svn_stringbuf_t *str, apr_size_t nbytes);
 244
 245 /** Fill bytestring @a str with character @a c. */
 246 void
 247 svn_stringbuf_fillchar(svn_stringbuf_t *str, unsigned char c);
 248
 249 /** Append an array of bytes onto @a targetstr.
 250  *
 251  * reallocs if necessary. @a targetstr is affected, nothing else is.
 252  */
 253 void
 254 svn_stringbuf_appendbytes(svn_stringbuf_t *targetstr,
 255                           const char *bytes,
 256                           apr_size_t count);
 257
 258 /** Append an @c svn_stringbuf_t onto @a targetstr.
 259  *
 260  * reallocs if necessary. @a targetstr is affected, nothing else is.
 261  */
 262 void
 263 svn_stringbuf_appendstr(svn_stringbuf_t *targetstr,
 264                         const svn_stringbuf_t *appendstr);
 265
 266 /** Append a C string onto @a targetstr.
 267  *
 268  * reallocs if necessary. @a targetstr is affected, nothing else is.
 269  */
 270 void
 271 svn_stringbuf_appendcstr(svn_stringbuf_t *targetstr,
 272                          const char *cstr);
 273
 274 /** Return a duplicate of @a original_string. */
 275 svn_stringbuf_t *
 276 svn_stringbuf_dup(const svn_stringbuf_t *original_string, apr_pool_t *pool);
 277
 278 /** Return @c TRUE iff @a str1 and @a str2 have identical length and data. */
 279 svn_boolean_t
 280 svn_stringbuf_compare(const svn_stringbuf_t *str1,
 281                       const svn_stringbuf_t *str2);
 282
 283 /** Return offset of first non-whitespace character in @a str, or return
 284  * @a str->len if none.
 285  */
 286 apr_size_t
 287 svn_stringbuf_first_non_whitespace(const svn_stringbuf_t *str);
 288
 289 /** Strip whitespace from both sides of @a str (modified in place). */
 290 void
 291 svn_stringbuf_strip_whitespace(svn_stringbuf_t *str);
 292
 293 /** Return position of last occurrence of @a ch in @a str, or return
 294  * @a str->len if no occurrence.
 295  */
 296 apr_size_t
 297 svn_stringbuf_find_char_backward(const svn_stringbuf_t *str, char ch);
 298
 299 /** Return @c TRUE iff @a str1 and @a str2 have identical length and data. */
 300 svn_boolean_t
 301 svn_string_compare_stringbuf(const svn_string_t *str1,
 302                              const svn_stringbuf_t *str2);
 303
 304 /** @} */
 305
 306 \f
 307 /** C strings.
 308  *
 309  * @defgroup svn_string_cstrings c string functions
 310  * @{
 311  */
 312
 313 /** Divide @a input into substrings along @a sep_chars boundaries, return an
 314  * array of copies of those substrings, allocating both the array and
 315  * the copies in @a pool.
 316  *
 317  * None of the elements added to the array contain any of the
 318  * characters in @a sep_chars, and none of the new elements are empty
 319  * (thus, it is possible that the returned array will have length
 320  * zero).
 321  *
 322  * If @a chop_whitespace is TRUE, then remove leading and trailing
 323  * whitespace from the returned strings.
 324  */
 325
 326 apr_array_header_t *
 327 svn_cstring_split(const char *input,
 328                   const char *sep_chars,
 329                   svn_boolean_t chop_whitespace,
 330                   apr_pool_t *pool);
 331
 332 /** Like svn_cstring_split(), but append to existing @a array instead of
 333  * creating a new one.  Allocate the copied substrings in @a pool
 334  * (i.e., caller decides whether or not to pass @a array->pool as @a pool).
 335  */
 336 void
 337 svn_cstring_split_append(apr_array_header_t *array,
 338                          const char *input,
 339                          const char *sep_chars,
 340                          svn_boolean_t chop_whitespace,
 341                          apr_pool_t *pool);
 342
 343
 344 /** Return @c TRUE iff @a str matches any of the elements of @a list, a list
 345  * of zero or more glob patterns.
 346  */
 347 svn_boolean_t
 348 svn_cstring_match_glob_list(const char *str, apr_array_header_t *list);
 349
 350 /**
 351  * Return the number of line breaks in @a msg, allowing any kind of newline
 352  * termination (CR, LF, CRLF, or LFCR), even inconsistent.
 353  *
 354  * @since New in 1.2.
 355  */
 356 int
 357 svn_cstring_count_newlines(const char *msg);
 358
 359 /**
 360  * Return a cstring which is the concatenation of @a strings (an array
 361  * of char *) each followed by @a separator (that is, @a separator
 362  * will also end the resulting string).  Allocate the result in @a pool.
 363  * If @a strings is empty, then return the empty string.
 364  *
 365  * @since New in 1.2.
 366  */
 367 char *
 368 svn_cstring_join(apr_array_header_t *strings,
 369                  const char *separator,
 370                  apr_pool_t *pool);
 371
 372 /**
 373  * Compare two strings @a atr1 and @a atr2, treating case-equivalent
 374  * unaccented Latin (ASCII subset) letters as equal.
 375  *
 376  * Returns in integer greater than, equal to, or less than 0,
 377  * according to whether @a str1 is considered greater than, equal to,
 378  * or less than @a str2.
 379  *
 380  * @since New in 1.5.
 381  */
 382 int
 383 svn_cstring_casecmp(const char *str1, const char *str2);
 384
 385
 386 /** @} */
 387
 388 /** @} */
 389
 390 \f
 391 #ifdef __cplusplus
 392 }
 393 #endif /* __cplusplus */
 394
 395 #endif  /* SVN_STRING_H */