src/TortoiseMerge/svninclude/svn_string.h

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