ucx/ucx/string.h

   1 /*
   2  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
   3  *
   4  * Copyright 2017 Mike Becker, Olaf Wintermann All rights reserved.
   5  *
   6  * Redistribution and use in source and binary forms, with or without
   7  * modification, are permitted provided that the following conditions are met:
   8  *
   9  *   1. Redistributions of source code must retain the above copyright
  10  *      notice, this list of conditions and the following disclaimer.
  11  *
  12  *   2. Redistributions in binary form must reproduce the above copyright
  13  *      notice, this list of conditions and the following disclaimer in the
  14  *      documentation and/or other materials provided with the distribution.
  15  *
  16  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
  17  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19  * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
  20  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  21  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  22  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  23  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  24  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  25  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  26  * POSSIBILITY OF SUCH DAMAGE.
  27  */
  28 /**
  29  * Bounded string implementation.
  30  *
  31  * The UCX strings (<code>sstr_t</code>) provide an alternative to C strings.
  32  * The main difference to C strings is, that <code>sstr_t</code> does <b>not
  33  * need to be <code>NULL</code>-terminated</b>. Instead the length is stored
  34  * within the structure.
  35  *
  36  * When using <code>sstr_t</code>, developers must be full aware of what type
  37  * of string (<code>NULL</code>-terminated) or not) they are using, when
  38  * accessing the <code>char* ptr</code> directly.
  39  *
  40  * The UCX string module provides some common string functions, known from
  41  * standard libc, working with <code>sstr_t</code>.
  42  *
  43  * @file   string.h
  44  * @author Mike Becker
  45  * @author Olaf Wintermann
  46  */
  47
  48 #ifndef UCX_STRING_H
  49 #define UCX_STRING_H
  50
  51 #include "ucx.h"
  52 #include "allocator.h"
  53 #include <stddef.h>
  54
  55 /*
  56  * Use this macro to disable the shortcuts if you experience macro collision.
  57  */
  58 #ifndef UCX_NO_SSTR_SHORTCUTS
  59 /**
  60  * Shortcut for a <code>sstr_t struct</code>
  61  * or <code>scstr_t struct</code> literal.
  62  */
  63 #define ST(s) { s, sizeof(s)-1 }
  64
  65 /** Shortcut for the conversion of a C string to a <code>sstr_t</code>. */
  66 #define S(s) sstrn(s, sizeof(s)-1)
  67
  68 /** Shortcut for the conversion of a C string to a <code>scstr_t</code>. */
  69 #define SC(s) scstrn(s, sizeof(s)-1)
  70 #endif /* UCX_NO_SSTR_SHORTCUTS */
  71
  72 /*
  73  * Use this macro to disable the format macros.
  74  */
  75 #ifndef UCX_NO_SSTR_FORMAT_MACROS
  76 /** Expands a sstr_t or scstr_t to printf arguments. */
  77 #define SFMT(s) (int) (s).length, (s).ptr
  78
  79 /** Format specifier for a sstr_t or scstr_t. */
  80 #define PRIsstr ".*s"
  81 #endif /* UCX_NO_SSTR_FORMAT_MACROS */
  82
  83 #ifdef  __cplusplus
  84 extern "C" {
  85 #endif
  86
  87 /**
  88  * The UCX string structure.
  89  */
  90 typedef struct {
  91    /** A pointer to the string
  92     * (<b>not necessarily <code>NULL</code>-terminated</b>) */
  93     char *ptr;
  94     /** The length of the string */
  95     size_t length;
  96 } sstr_t;
  97
  98 /**
  99  * The UCX string structure for immutable (constant) strings.
 100  */
 101 typedef struct {
 102     /** A constant pointer to the immutable string
 103      * (<b>not necessarily <code>NULL</code>-terminated</b>) */
 104     const char *ptr;
 105     /** The length of the string */
 106     size_t length;
 107 } scstr_t;
 108
 109 #ifdef  __cplusplus
 110 }
 111 #endif
 112
 113
 114 #ifdef __cplusplus
 115 /**
 116  * One of two type adjustment functions that return an scstr_t.
 117  *
 118  * Used <b>internally</b> to convert a UCX string to an immutable UCX string.
 119  *
 120  * <b>Do not use this function manually.</b>
 121  *
 122  * @param str some sstr_t
 123  * @return an immutable (scstr_t) version of the provided string.
 124  */
 125 inline scstr_t s2scstr(sstr_t s) {
 126     scstr_t c;
 127     c.ptr = s.ptr;
 128     c.length = s.length;
 129     return c;
 130 }
 131
 132 /**
 133  * One of two type adjustment functions that return an scstr_t.
 134  *
 135  * Used <b>internally</b> to convert a UCX string to an immutable UCX string.
 136  * This variant is used, when the string is already immutable and no operation
 137  * needs to be performed.
 138  *
 139  * <b>Do not use this function manually.</b>
 140  *
 141  * @param str some scstr_t
 142  * @return the argument itself
 143  */
 144 inline scstr_t s2scstr(scstr_t str) {
 145     return str;
 146 }
 147
 148 /**
 149  * Converts a UCX string to an immutable UCX string (scstr_t).
 150  * @param str some UCX string
 151  * @return an immutable version of the provided string
 152  */
 153 #define SCSTR(s) s2scstr(s)
 154 #else
 155
 156 /**
 157  * One of two type adjustment functions that return an scstr_t.
 158  *
 159  * Used <b>internally</b> to convert a UCX string to an immutable UCX string.
 160  * This variant is used, when the string is already immutable and no operation
 161  * needs to be performed.
 162  *
 163  * <b>Do not use this function manually.</b>
 164  *
 165  * @param str some scstr_t
 166  * @return the argument itself
 167  */
 168 scstr_t ucx_sc2sc(scstr_t str);
 169
 170 /**
 171  * One of two type adjustment functions that return an scstr_t.
 172  *
 173  * Used <b>internally</b> to convert a UCX string to an immutable UCX string.
 174  *
 175  * <b>Do not use this function manually.</b>
 176  *
 177  * @param str some sstr_t
 178  * @return an immutable (scstr_t) version of the provided string.
 179  */
 180 scstr_t ucx_ss2sc(sstr_t str);
 181
 182 #if __STDC_VERSION__ >= 201112L
 183 /**
 184  * Converts a UCX string to an immutable UCX string (scstr_t).
 185  * @param str some UCX string
 186  * @return an immutable version of the provided string
 187  */
 188 #define SCSTR(str) _Generic(str, sstr_t: ucx_ss2sc, scstr_t: ucx_sc2sc)(str)
 189
 190 #elif defined(__GNUC__) || defined(__clang__)
 191
 192 /**
 193  * Converts a UCX string to an immutable UCX string (scstr_t).
 194  * @param str some UCX string
 195  * @return an immutable version of the provided string
 196  */
 197 #define SCSTR(str) __builtin_choose_expr( \
 198         __builtin_types_compatible_p(typeof(str), sstr_t), \
 199         ucx_ss2sc, \
 200         ucx_sc2sc)(str)
 201
 202 #elif defined(__sun)
 203
 204 /**
 205  * Converts a UCX string to an immutable UCX string (scstr_t).
 206  * @param str some UCX string
 207  * @return the an immutable version of the provided string
 208  */
 209 #define SCSTR(str) ({typeof(str) ucx_tmp_var_str = str; \
 210         scstr_t ucx_tmp_var_c; \
 211         ucx_tmp_var_c.ptr = ucx_tmp_var_str.ptr;\
 212         ucx_tmp_var_c.length = ucx_tmp_var_str.length;\
 213         ucx_tmp_var_c; })
 214 #else /* no generics and no builtins */
 215
 216 /**
 217  * Converts a UCX string to an immutable UCX string (scstr_t).
 218  *
 219  * This <b>internal</b> function (ab)uses the C standard an expects one single
 220  * argument which is then implicitly converted to scstr_t without a warning.
 221  *
 222  * <b>Do not use this function manually.</b>
 223  *
 224  * @return the an immutable version of the provided string
 225  */
 226 scstr_t ucx_ss2c_s();
 227
 228 /**
 229  * Converts a UCX string to an immutable UCX string (scstr_t).
 230  * @param str some UCX string
 231  * @return the an immutable version of the provided string
 232  */
 233 #define SCSTR(str) ucx_ss2c_s(str)
 234 #endif /* C11 feature test */
 235
 236 #endif /* C++ */
 237
 238 #ifdef  __cplusplus
 239 extern "C" {
 240 #endif
 241
 242
 243 /**
 244  * Creates a new sstr_t based on a C string.
 245  *
 246  * The length is implicitly inferred by using a call to <code>strlen()</code>.
 247  *
 248  * <b>Note:</b> the sstr_t will share the specified pointer to the C string.
 249  * If you do want a copy, use sstrdup() on the return value of this function.
 250  *
 251  * If you need to wrap a constant string, use scstr().
 252  *
 253  * @param cstring the C string to wrap
 254  * @return a new sstr_t containing the C string
 255  *
 256  * @see sstrn()
 257  */
 258 sstr_t sstr(char *cstring);
 259
 260 /**
 261  * Creates a new sstr_t of the specified length based on a C string.
 262  *
 263  * <b>Note:</b> the sstr_t will share the specified pointer to the C string.
 264  * If you do want a copy, use sstrdup() on the return value of this function.
 265  *
 266  * If you need to wrap a constant string, use scstrn().
 267  *
 268  * @param cstring  the C string to wrap
 269  * @param length   the length of the string
 270  * @return a new sstr_t containing the C string
 271  *
 272  * @see sstr()
 273  * @see S()
 274  */
 275 sstr_t sstrn(char *cstring, size_t length);
 276
 277 /**
 278  * Creates a new scstr_t based on a constant C string.
 279  *
 280  * The length is implicitly inferred by using a call to <code>strlen()</code>.
 281  *
 282  * <b>Note:</b> the scstr_t will share the specified pointer to the C string.
 283  * If you do want a copy, use scstrdup() on the return value of this function.
 284  *
 285  * @param cstring the C string to wrap
 286  * @return a new scstr_t containing the C string
 287  *
 288  * @see scstrn()
 289  */
 290 scstr_t scstr(const char *cstring);
 291
 292
 293 /**
 294  * Creates a new scstr_t of the specified length based on a constant C string.
 295  *
 296  * <b>Note:</b> the scstr_t will share the specified pointer to the C string.
 297  * If you do want a copy, use scstrdup() on the return value of this function. *
 298  *
 299  * @param cstring  the C string to wrap
 300  * @param length   the length of the string
 301  * @return a new scstr_t containing the C string
 302  *
 303  * @see scstr()
 304  */
 305 scstr_t scstrn(const char *cstring, size_t length);
 306
 307 /**
 308  * Returns the accumulated length of all specified strings.
 309  *
 310  * <b>Attention:</b> if the count argument is larger than the count of the
 311  * specified strings, the behavior is undefined.
 312  *
 313  * @param count    the total number of specified strings
 314  * @param ...      all strings
 315  * @return the accumulated length of all strings
 316  */
 317 size_t scstrnlen(size_t count, ...);
 318
 319 /**
 320  * Returns the accumulated length of all specified strings.
 321  *
 322  * <b>Attention:</b> if the count argument is larger than the count of the
 323  * specified strings, the behavior is undefined.
 324  *
 325  * @param count    the total number of specified strings
 326  * @param ...      all strings
 327  * @return the cumulated length of all strings
 328  */
 329 #define sstrnlen(count, ...) scstrnlen(count, __VA_ARGS__)
 330
 331 /**
 332  * Concatenates two or more strings.
 333  *
 334  * The resulting string will be allocated by standard <code>malloc()</code>.
 335  * So developers <b>MUST</b> pass the sstr_t.ptr to <code>free()</code>.
 336  *
 337  * The sstr_t.ptr of the return value will <i>always</i> be <code>NULL</code>-
 338  * terminated.
 339  *
 340  * @param count   the total number of strings to concatenate
 341  * @param s1      first string
 342  * @param ...     all remaining strings
 343  * @return the concatenated string
 344  */
 345 sstr_t scstrcat(size_t count, scstr_t s1, ...);
 346
 347 /**
 348  * Concatenates two or more strings.
 349  *
 350  * The resulting string will be allocated by standard <code>malloc()</code>.
 351  * So developers <b>MUST</b> pass the sstr_t.ptr to <code>free()</code>.
 352  *
 353  * The sstr_t.ptr of the return value will <i>always</i> be <code>NULL</code>-
 354  * terminated.
 355  *
 356  * @param count   the total number of strings to concatenate
 357  * @param s1      first string
 358  * @param ...     all remaining strings
 359  * @return the concatenated string
 360  */
 361 #define sstrcat(count, s1, ...) scstrcat(count, SCSTR(s1), __VA_ARGS__)
 362
 363 /**
 364  * Concatenates two or more strings using a UcxAllocator.
 365  *
 366  * The resulting string must be freed by the allocators <code>free()</code>
 367  * implementation.
 368  *
 369  * The sstr_t.ptr of the return value will <i>always</i> be <code>NULL</code>-
 370  * terminated.
 371  *
 372  * @param alloc   the allocator to use
 373  * @param count   the total number of strings to concatenate
 374  * @param s1      first string
 375  * @param ...     all remaining strings
 376  * @return the concatenated string
 377  *
 378  * @see scstrcat()
 379  */
 380 sstr_t scstrcat_a(UcxAllocator *alloc, size_t count, scstr_t s1, ...);
 381
 382 /**
 383  * Concatenates two or more strings using a UcxAllocator.
 384  *
 385  * The resulting string must be freed by the allocators <code>free()</code>
 386  * implementation.
 387  *
 388  * The sstr_t.ptr of the return value will <i>always</i> be <code>NULL</code>-
 389  * terminated.
 390  *
 391  * @param alloc   the allocator to use
 392  * @param count   the total number of strings to concatenate
 393  * @param s1      first string
 394  * @param ...     all remaining strings
 395  * @return the concatenated string
 396  *
 397  * @see sstrcat()
 398  */
 399 #define sstrcat_a(alloc, count, s1, ...) \
 400     scstrcat_a(alloc, count, SCSTR(s1), __VA_ARGS__)
 401
 402 /**
 403  * Returns a substring starting at the specified location.
 404  *
 405  * <b>Attention:</b> the new string references the same memory area as the
 406  * input string and is <b>NOT</b> required to be <code>NULL</code>-terminated.
 407  * Use sstrdup() to get a copy.
 408  *
 409  * @param string input string
 410  * @param start  start location of the substring
 411  * @return a substring of <code>string</code> starting at <code>start</code>
 412  *
 413  * @see sstrsubsl()
 414  * @see sstrchr()
 415  */
 416 sstr_t sstrsubs(sstr_t string, size_t start);
 417
 418 /**
 419  * Returns a substring with the given length starting at the specified location.
 420  *
 421  * <b>Attention:</b> the new string references the same memory area as the
 422  * input string and is <b>NOT</b> required to be <code>NULL</code>-terminated.
 423  * Use sstrdup() to get a copy.
 424  *
 425  * @param string input string
 426  * @param start  start location of the substring
 427  * @param length the maximum length of the substring
 428  * @return a substring of <code>string</code> starting at <code>start</code>
 429  * with a maximum length of <code>length</code>
 430  *
 431  * @see sstrsubs()
 432  * @see sstrchr()
 433  */
 434 sstr_t sstrsubsl(sstr_t string, size_t start, size_t length);
 435
 436 /**
 437  * Returns a substring of an immutable string starting at the specified
 438  * location.
 439  *
 440  * <b>Attention:</b> the new string references the same memory area as the
 441 * input string and is <b>NOT</b> required to be <code>NULL</code>-terminated.
 442  * Use scstrdup() to get a copy.
 443  *
 444  * @param string input string
 445  * @param start  start location of the substring
 446  * @return a substring of <code>string</code> starting at <code>start</code>
 447  *
 448  * @see scstrsubsl()
 449  * @see scstrchr()
 450  */
 451 scstr_t scstrsubs(scstr_t string, size_t start);
 452
 453 /**
 454  * Returns a substring of an immutable string with a maximum length starting
 455  * at the specified location.
 456  *
 457  * <b>Attention:</b> the new string references the same memory area as the
 458  * input string and is <b>NOT</b> required to be <code>NULL</code>-terminated.
 459  * Use scstrdup() to get a copy.
 460  *
 461  * @param string input string
 462  * @param start  start location of the substring
 463  * @param length the maximum length of the substring
 464  * @return a substring of <code>string</code> starting at <code>start</code>
 465  * with a maximum length of <code>length</code>
 466  *
 467  * @see scstrsubs()
 468  * @see scstrchr()
 469  */
 470 scstr_t scstrsubsl(scstr_t string, size_t start, size_t length);
 471
 472 /**
 473  * Returns a substring starting at the location of the first occurrence of the
 474  * specified character.
 475  *
 476  * If the string does not contain the character, an empty string is returned.
 477  *
 478  * @param string the string where to locate the character
 479  * @param chr    the character to locate
 480  * @return       a substring starting at the first location of <code>chr</code>
 481  *
 482  * @see sstrsubs()
 483  */
 484 sstr_t sstrchr(sstr_t string, int chr);
 485
 486 /**
 487  * Returns a substring starting at the location of the last occurrence of the
 488  * specified character.
 489  *
 490  * If the string does not contain the character, an empty string is returned.
 491  *
 492  * @param string the string where to locate the character
 493  * @param chr    the character to locate
 494  * @return       a substring starting at the last location of <code>chr</code>
 495  *
 496  * @see sstrsubs()
 497  */
 498 sstr_t sstrrchr(sstr_t string, int chr);
 499
 500 /**
 501  * Returns an immutable substring starting at the location of the first
 502  * occurrence of the specified character.
 503  *
 504  * If the string does not contain the character, an empty string is returned.
 505  *
 506  * @param string the string where to locate the character
 507  * @param chr    the character to locate
 508  * @return       a substring starting at the first location of <code>chr</code>
 509  *
 510  * @see scstrsubs()
 511  */
 512 scstr_t scstrchr(scstr_t string, int chr);
 513
 514 /**
 515  * Returns an immutable substring starting at the location of the last
 516  * occurrence of the specified character.
 517  *
 518  * If the string does not contain the character, an empty string is returned.
 519  *
 520  * @param string the string where to locate the character
 521  * @param chr    the character to locate
 522  * @return       a substring starting at the last location of <code>chr</code>
 523  *
 524  * @see scstrsubs()
 525  */
 526 scstr_t scstrrchr(scstr_t string, int chr);
 527
 528 /**
 529  * Returns a substring starting at the location of the first occurrence of the
 530  * specified string.
 531  *
 532  * If the string does not contain the other string, an empty string is returned.
 533  *
 534  * If <code>match</code> is an empty string, the complete <code>string</code> is
 535  * returned.
 536  *
 537  * @param string the string to be scanned
 538  * @param match  string containing the sequence of characters to match
 539  * @return       a substring starting at the first occurrence of
 540  *               <code>match</code>, or an empty string, if the sequence is not
 541  *               present in <code>string</code>
 542  */
 543 sstr_t scstrsstr(sstr_t string, scstr_t match);
 544
 545 /**
 546  * Returns a substring starting at the location of the first occurrence of the
 547  * specified string.
 548  *
 549  * If the string does not contain the other string, an empty string is returned.
 550  *
 551  * If <code>match</code> is an empty string, the complete <code>string</code> is
 552  * returned.
 553  *
 554  * @param string the string to be scanned
 555  * @param match  string containing the sequence of characters to match
 556  * @return       a substring starting at the first occurrence of
 557  *               <code>match</code>, or an empty string, if the sequence is not
 558  *               present in <code>string</code>
 559  */
 560 #define sstrstr(string, match) scstrsstr(string, SCSTR(match))
 561
 562 /**
 563  * Returns an immutable substring starting at the location of the
 564  * first occurrence of the specified immutable string.
 565  *
 566  * If the string does not contain the other string, an empty string is returned.
 567  *
 568  * If <code>match</code> is an empty string, the complete <code>string</code> is
 569  * returned.
 570  *
 571  * @param string the string to be scanned
 572  * @param match  string containing the sequence of characters to match
 573  * @return       a substring starting at the first occurrence of
 574  *               <code>match</code>, or an empty string, if the sequence is not
 575  *               present in <code>string</code>
 576  */
 577 scstr_t scstrscstr(scstr_t string, scstr_t match);
 578
 579 /**
 580  * Returns an immutable substring starting at the location of the
 581  * first occurrence of the specified immutable string.
 582  *
 583  * If the string does not contain the other string, an empty string is returned.
 584  *
 585  * If <code>match</code> is an empty string, the complete <code>string</code> is
 586  * returned.
 587  *
 588  * @param string the string to be scanned
 589  * @param match  string containing the sequence of characters to match
 590  * @return       a substring starting at the first occurrence of
 591  *               <code>match</code>, or an empty string, if the sequence is not
 592  *               present in <code>string</code>
 593  */
 594 #define sstrscstr(string, match) scstrscstr(string, SCSTR(match))
 595
 596 /**
 597  * Splits a string into parts by using a delimiter string.
 598  *
 599  * This function will return <code>NULL</code>, if one of the following happens:
 600  * <ul>
 601  *   <li>the string length is zero</li>
 602  *   <li>the delimeter length is zero</li>
 603  *   <li>the string equals the delimeter</li>
 604  *   <li>memory allocation fails</li>
 605  * </ul>
 606  *
 607  * The integer referenced by <code>count</code> is used as input and determines
 608  * the maximum size of the resulting array, i.e. the maximum count of splits to
 609  * perform + 1.
 610  *
 611  * The integer referenced by <code>count</code> is also used as output and is
 612  * set to
 613  * <ul>
 614  *   <li>-2, on memory allocation errors</li>
 615  *   <li>-1, if either the string or the delimiter is an empty string</li>
 616  *   <li>0, if the string equals the delimiter</li>
 617  *   <li>1, if the string does not contain the delimiter</li>
 618  *   <li>the count of array items, otherwise</li>
 619  * </ul>
 620  *
 621  * If the string starts with the delimiter, the first item of the resulting
 622  * array will be an empty string.
 623  *
 624  * If the string ends with the delimiter and the maximum list size is not
 625  * exceeded, the last array item will be an empty string.
 626  * In case the list size would be exceeded, the last array item will be the
 627  * remaining string after the last split, <i>including</i> the terminating
 628  * delimiter.
 629  *
 630  * <b>Attention:</b> The array pointer <b>AND</b> all sstr_t.ptr of the array
 631  * items must be manually passed to <code>free()</code>. Use scstrsplit_a() with
 632  * an allocator to managed memory, to avoid this.
 633  *
 634  * @param string the string to split
 635  * @param delim  the delimiter string
 636  * @param count  IN: the maximum size of the resulting array (0 = no limit),
 637  *               OUT: the actual size of the array
 638  * @return a sstr_t array containing the split strings or
 639  * <code>NULL</code> on error
 640  *
 641  * @see scstrsplit_a()
 642  */
 643 sstr_t* scstrsplit(scstr_t string, scstr_t delim, ssize_t *count);
 644
 645 /**
 646  * Splits a string into parts by using a delimiter string.
 647  *
 648  * This function will return <code>NULL</code>, if one of the following happens:
 649  * <ul>
 650  *   <li>the string length is zero</li>
 651  *   <li>the delimeter length is zero</li>
 652  *   <li>the string equals the delimeter</li>
 653  *   <li>memory allocation fails</li>
 654  * </ul>
 655  *
 656  * The integer referenced by <code>count</code> is used as input and determines
 657  * the maximum size of the resulting array, i.e. the maximum count of splits to
 658  * perform + 1.
 659  *
 660  * The integer referenced by <code>count</code> is also used as output and is
 661  * set to
 662  * <ul>
 663  *   <li>-2, on memory allocation errors</li>
 664  *   <li>-1, if either the string or the delimiter is an empty string</li>
 665  *   <li>0, if the string equals the delimiter</li>
 666  *   <li>1, if the string does not contain the delimiter</li>
 667  *   <li>the count of array items, otherwise</li>
 668  * </ul>
 669  *
 670  * If the string starts with the delimiter, the first item of the resulting
 671  * array will be an empty string.
 672  *
 673  * If the string ends with the delimiter and the maximum list size is not
 674  * exceeded, the last array item will be an empty string.
 675  * In case the list size would be exceeded, the last array item will be the
 676  * remaining string after the last split, <i>including</i> the terminating
 677  * delimiter.
 678  *
 679  * <b>Attention:</b> The array pointer <b>AND</b> all sstr_t.ptr of the array
 680  * items must be manually passed to <code>free()</code>. Use sstrsplit_a() with
 681  * an allocator to managed memory, to avoid this.
 682  *
 683  * @param string the string to split
 684  * @param delim  the delimiter string
 685  * @param count  IN: the maximum size of the resulting array (0 = no limit),
 686  *               OUT: the actual size of the array
 687  * @return a sstr_t array containing the split strings or
 688  * <code>NULL</code> on error
 689  *
 690  * @see sstrsplit_a()
 691  */
 692 #define sstrsplit(string, delim, count) \
 693     scstrsplit(SCSTR(string), SCSTR(delim), count)
 694
 695 /**
 696  * Performing scstrsplit() using a UcxAllocator.
 697  *
 698  * <i>Read the description of scstrsplit() for details.</i>
 699  *
 700  * The memory for the sstr_t.ptr pointers of the array items and the memory for
 701  * the sstr_t array itself are allocated by using the UcxAllocator.malloc()
 702  * function.
 703  *
 704  * @param allocator the UcxAllocator used for allocating memory
 705  * @param string the string to split
 706  * @param delim  the delimiter string
 707  * @param count  IN: the maximum size of the resulting array (0 = no limit),
 708  *               OUT: the actual size of the array
 709  * @return a sstr_t array containing the split strings or
 710  * <code>NULL</code> on error
 711  *
 712  * @see scstrsplit()
 713  */
 714 sstr_t* scstrsplit_a(UcxAllocator *allocator, scstr_t string, scstr_t delim,
 715         ssize_t *count);
 716
 717 /**
 718  * Performing sstrsplit() using a UcxAllocator.
 719  *
 720  * <i>Read the description of sstrsplit() for details.</i>
 721  *
 722  * The memory for the sstr_t.ptr pointers of the array items and the memory for
 723  * the sstr_t array itself are allocated by using the UcxAllocator.malloc()
 724  * function.
 725  *
 726  * @param allocator the UcxAllocator used for allocating memory
 727  * @param string the string to split
 728  * @param delim  the delimiter string
 729  * @param count  IN: the maximum size of the resulting array (0 = no limit),
 730  *               OUT: the actual size of the array
 731  * @return a sstr_t array containing the split strings or
 732  * <code>NULL</code> on error
 733  *
 734  * @see sstrsplit()
 735  */
 736 #define sstrsplit_a(allocator, string, delim, count) \
 737     scstrsplit_a(allocator, SCSTR(string), SCSTR(delim), count)
 738
 739 /**
 740  * Compares two UCX strings with standard <code>memcmp()</code>.
 741  *
 742  * At first it compares the scstr_t.length attribute of the two strings. The
 743  * <code>memcmp()</code> function is called, if and only if the lengths match.
 744  *
 745  * @param s1 the first string
 746  * @param s2 the second string
 747  * @return -1, if the length of s1 is less than the length of s2 or 1, if the
 748  * length of s1 is greater than the length of s2 or the result of
 749  * <code>memcmp()</code> otherwise (i.e. 0 if the strings match)
 750  */
 751 int scstrcmp(scstr_t s1, scstr_t s2);
 752
 753 /**
 754  * Compares two UCX strings with standard <code>memcmp()</code>.
 755  *
 756  * At first it compares the sstr_t.length attribute of the two strings. The
 757  * <code>memcmp()</code> function is called, if and only if the lengths match.
 758  *
 759  * @param s1 the first string
 760  * @param s2 the second string
 761  * @return -1, if the length of s1 is less than the length of s2 or 1, if the
 762  * length of s1 is greater than the length of s2 or the result of
 763  * <code>memcmp()</code> otherwise (i.e. 0 if the strings match)
 764  */
 765 #define sstrcmp(s1, s2) scstrcmp(SCSTR(s1), SCSTR(s2))
 766
 767 /**
 768  * Compares two UCX strings ignoring the case.
 769  *
 770  * At first it compares the scstr_t.length attribute of the two strings. If and
 771  * only if the lengths match, both strings are compared char by char ignoring
 772  * the case.
 773  *
 774  * @param s1 the first string
 775  * @param s2 the second string
 776  * @return -1, if the length of s1 is less than the length of s2 or 1, if the
 777  * length of s1 is greater than the length of s2 or the result of the platform
 778  * specific string comparison function ignoring the case.
 779  */
 780 int scstrcasecmp(scstr_t s1, scstr_t s2);
 781
 782 /**
 783  * Compares two UCX strings ignoring the case.
 784  *
 785  * At first it compares the sstr_t.length attribute of the two strings. If and
 786  * only if the lengths match, both strings are compared char by char ignoring
 787  * the case.
 788  *
 789  * @param s1 the first string
 790  * @param s2 the second string
 791  * @return -1, if the length of s1 is less than the length of s2 or 1, if the
 792  * length of s1 is greater than the length of s2 or the result of the platform
 793  * specific string comparison function ignoring the case.
 794  */
 795 #define sstrcasecmp(s1, s2) scstrcasecmp(SCSTR(s1), SCSTR(s2))
 796
 797 /**
 798  * Creates a duplicate of the specified string.
 799  *
 800  * The new sstr_t will contain a copy allocated by standard
 801  * <code>malloc()</code>. So developers <b>MUST</b> pass the sstr_t.ptr to
 802  * <code>free()</code>.
 803  *
 804  * The sstr_t.ptr of the return value will <i>always</i> be <code>NULL</code>-
 805  * terminated and mutable, regardless of the argument.
 806  *
 807  * @param string the string to duplicate
 808  * @return a duplicate of the string
 809  * @see scstrdup_a()
 810  */
 811 sstr_t scstrdup(scstr_t string);
 812
 813 /**
 814  * Creates a duplicate of the specified string.
 815  *
 816  * The new sstr_t will contain a copy allocated by standard
 817  * <code>malloc()</code>. So developers <b>MUST</b> pass the sstr_t.ptr to
 818  * <code>free()</code>.
 819  *
 820  * The sstr_t.ptr of the return value will <i>always</i> be <code>NULL</code>-
 821  * terminated, regardless of the argument.
 822  *
 823  * @param string the string to duplicate
 824  * @return a duplicate of the string
 825  * @see sstrdup_a()
 826  */
 827 #define sstrdup(string) scstrdup(SCSTR(string))
 828
 829 /**
 830  * Creates a duplicate of the specified string using a UcxAllocator.
 831  *
 832  * The new sstr_t will contain a copy allocated by the allocators
 833  * UcxAllocator.malloc() function. So it is implementation depended, whether the
 834  * returned sstr_t.ptr pointer must be passed to the allocators
 835  * UcxAllocator.free() function manually.
 836  *
 837  * The sstr_t.ptr of the return value will <i>always</i> be <code>NULL</code>-
 838  * terminated and mutable, regardless of the argument.
 839  *
 840  * @param allocator a valid instance of a UcxAllocator
 841  * @param string the string to duplicate
 842  * @return a duplicate of the string
 843  * @see scstrdup()
 844  */
 845 sstr_t scstrdup_a(UcxAllocator *allocator, scstr_t string);
 846
 847 /**
 848  * Creates a duplicate of the specified string using a UcxAllocator.
 849  *
 850  * The new sstr_t will contain a copy allocated by the allocators
 851  * UcxAllocator.malloc() function. So it is implementation depended, whether the
 852  * returned sstr_t.ptr pointer must be passed to the allocators
 853  * UcxAllocator.free() function manually.
 854  *
 855  * The sstr_t.ptr of the return value will <i>always</i> be <code>NULL</code>-
 856  * terminated, regardless of the argument.
 857  *
 858  * @param allocator a valid instance of a UcxAllocator
 859  * @param string the string to duplicate
 860  * @return a duplicate of the string
 861  * @see scstrdup()
 862  */
 863 #define sstrdup_a(allocator, string) scstrdup_a(allocator, SCSTR(string))
 864
 865
 866 /**
 867  * Omits leading and trailing spaces.
 868  *
 869  * This function returns a new sstr_t containing a trimmed version of the
 870  * specified string.
 871  *
 872  * <b>Note:</b> the new sstr_t references the same memory, thus you
 873  * <b>MUST NOT</b> pass the sstr_t.ptr of the return value to
 874  * <code>free()</code>. It is also highly recommended to avoid assignments like
 875  * <code>mystr = sstrtrim(mystr);</code> as you lose the reference to the
 876  * source string. Assignments of this type are only permitted, if the
 877  * sstr_t.ptr of the source string does not need to be freed or if another
 878  * reference to the source string exists.
 879  *
 880  * @param string the string that shall be trimmed
 881  * @return a new sstr_t containing the trimmed string
 882  */
 883 sstr_t sstrtrim(sstr_t string);
 884
 885 /**
 886  * Omits leading and trailing spaces.
 887  *
 888  * This function returns a new scstr_t containing a trimmed version of the
 889  * specified string.
 890  *
 891  * <b>Note:</b> the new scstr_t references the same memory, thus you
 892  * <b>MUST NOT</b> pass the scstr_t.ptr of the return value to
 893  * <code>free()</code>. It is also highly recommended to avoid assignments like
 894  * <code>mystr = scstrtrim(mystr);</code> as you lose the reference to the
 895  * source string. Assignments of this type are only permitted, if the
 896  * scstr_t.ptr of the source string does not need to be freed or if another
 897  * reference to the source string exists.
 898  *
 899  * @param string the string that shall be trimmed
 900  * @return a new scstr_t containing the trimmed string
 901  */
 902 scstr_t scstrtrim(scstr_t string);
 903
 904 /**
 905  * Checks, if a string has a specific prefix.
 906  *
 907  * @param string the string to check
 908  * @param prefix the prefix the string should have
 909  * @return 1, if and only if the string has the specified prefix, 0 otherwise
 910  */
 911 int scstrprefix(scstr_t string, scstr_t prefix);
 912
 913 /**
 914  * Checks, if a string has a specific prefix.
 915  *
 916  * @param string the string to check
 917  * @param prefix the prefix the string should have
 918  * @return 1, if and only if the string has the specified prefix, 0 otherwise
 919  */
 920 #define sstrprefix(string, prefix) scstrprefix(SCSTR(string), SCSTR(prefix))
 921
 922 /**
 923  * Checks, if a string has a specific suffix.
 924  *
 925  * @param string the string to check
 926  * @param suffix the suffix the string should have
 927  * @return 1, if and only if the string has the specified suffix, 0 otherwise
 928  */
 929 int scstrsuffix(scstr_t string, scstr_t suffix);
 930
 931 /**
 932  * Checks, if a string has a specific suffix.
 933  *
 934  * @param string the string to check
 935  * @param suffix the suffix the string should have
 936  * @return 1, if and only if the string has the specified suffix, 0 otherwise
 937  */
 938 #define sstrsuffix(string, suffix) scstrsuffix(SCSTR(string), SCSTR(suffix))
 939
 940 /**
 941  * Checks, if a string has a specific prefix, ignoring the case.
 942  *
 943  * @param string the string to check
 944  * @param prefix the prefix the string should have
 945  * @return 1, if and only if the string has the specified prefix, 0 otherwise
 946  */
 947 int scstrcaseprefix(scstr_t string, scstr_t prefix);
 948
 949 /**
 950  * Checks, if a string has a specific prefix, ignoring the case.
 951  *
 952  * @param string the string to check
 953  * @param prefix the prefix the string should have
 954  * @return 1, if and only if the string has the specified prefix, 0 otherwise
 955  */
 956 #define sstrcaseprefix(string, prefix) \
 957   scstrcaseprefix(SCSTR(string), SCSTR(prefix))
 958
 959 /**
 960  * Checks, if a string has a specific suffix, ignoring the case.
 961  *
 962  * @param string the string to check
 963  * @param suffix the suffix the string should have
 964  * @return 1, if and only if the string has the specified suffix, 0 otherwise
 965  */
 966 int scstrcasesuffix(scstr_t string, scstr_t suffix);
 967
 968 /**
 969  * Checks, if a string has a specific suffix, ignoring the case.
 970  *
 971  * @param string the string to check
 972  * @param suffix the suffix the string should have
 973  * @return 1, if and only if the string has the specified suffix, 0 otherwise
 974  */
 975 #define sstrcasesuffix(string, suffix) \
 976   scstrcasesuffix(SCSTR(string), SCSTR(suffix))
 977
 978 /**
 979  * Returns a lower case version of a string.
 980  *
 981  * This function creates a duplicate of the input string, first
 982  * (see scstrdup()).
 983  *
 984  * @param string the input string
 985  * @return the resulting lower case string
 986  * @see scstrdup()
 987  */
 988 sstr_t scstrlower(scstr_t string);
 989
 990 /**
 991  * Returns a lower case version of a string.
 992  *
 993  * This function creates a duplicate of the input string, first
 994  * (see sstrdup()).
 995  *
 996  * @param string the input string
 997  * @return the resulting lower case string
 998  */
 999 #define sstrlower(string) scstrlower(SCSTR(string))
1000
1001 /**
1002  * Returns a lower case version of a string.
1003  *
1004   * This function creates a duplicate of the input string, first
1005  * (see scstrdup_a()).
1006  *
1007  * @param allocator the allocator used for duplicating the string
1008  * @param string the input string
1009  * @return the resulting lower case string
1010  * @see scstrdup_a()
1011  */
1012 sstr_t scstrlower_a(UcxAllocator *allocator, scstr_t string);
1013
1014
1015 /**
1016  * Returns a lower case version of a string.
1017  *
1018  * This function creates a duplicate of the input string, first
1019  * (see sstrdup_a()).
1020  *
1021  * @param allocator the allocator used for duplicating the string
1022  * @param string the input string
1023  * @return the resulting lower case string
1024  */
1025 #define sstrlower_a(allocator, string) scstrlower_a(allocator, SCSTR(string))
1026
1027 /**
1028  * Returns a upper case version of a string.
1029  *
1030  * This function creates a duplicate of the input string, first
1031  * (see scstrdup()).
1032  *
1033  * @param string the input string
1034  * @return the resulting upper case string
1035  * @see scstrdup()
1036  */
1037 sstr_t scstrupper(scstr_t string);
1038
1039 /**
1040  * Returns a upper case version of a string.
1041  *
1042  * This function creates a duplicate of the input string, first
1043  * (see sstrdup()).
1044  *
1045  * @param string the input string
1046  * @return the resulting upper case string
1047  */
1048 #define sstrupper(string) scstrupper(SCSTR(string))
1049
1050 /**
1051  * Returns a upper case version of a string.
1052  *
1053  * This function creates a duplicate of the input string, first
1054  * (see scstrdup_a()).
1055  *
1056  * @param allocator the allocator used for duplicating the string
1057  * @param string the input string
1058  * @return the resulting upper case string
1059  * @see scstrdup_a()
1060  */
1061 sstr_t scstrupper_a(UcxAllocator *allocator, scstr_t string);
1062
1063 /**
1064  * Returns a upper case version of a string.
1065  *
1066  * This function creates a duplicate of the input string, first
1067  * (see sstrdup_a()).
1068  *
1069  * @param allocator the allocator used for duplicating the string
1070  * @param string the input string
1071  * @return the resulting upper case string
1072  */
1073 #define sstrupper_a(allocator, string) scstrupper_a(allocator, string)
1074
1075
1076 /**
1077  * Replaces a pattern in a string with another string.
1078  *
1079  * The pattern is taken literally and is no regular expression.
1080  * Replaces at most <code>replmax</code> occurrences.
1081  *
1082  * The resulting string is allocated by the specified allocator. I.e. it
1083  * depends on the used allocator, whether the sstr_t.ptr must be freed
1084  * manually.
1085  *
1086  * If allocation fails, the sstr_t.ptr of the return value is NULL.
1087  *
1088  * @param allocator the allocator to use
1089  * @param str the string where replacements should be applied
1090  * @param pattern the pattern to search for
1091  * @param replacement the replacement string
1092  * @param replmax maximum number of replacements
1093  * @return the resulting string after applying the replacements
1094  */
1095 sstr_t scstrreplacen_a(UcxAllocator *allocator, scstr_t str,
1096         scstr_t pattern, scstr_t replacement, size_t replmax);
1097
1098 /**
1099  * Replaces a pattern in a string with another string.
1100  *
1101  * The pattern is taken literally and is no regular expression.
1102  * Replaces at most <code>replmax</code> occurrences.
1103  *
1104  * The sstr_t.ptr of the resulting string must be freed manually.
1105  *
1106  * If allocation fails, the sstr_t.ptr of the return value is NULL.
1107  *
1108  * @param str the string where replacements should be applied
1109  * @param pattern the pattern to search for
1110  * @param replacement the replacement string
1111  * @param replmax maximum number of replacements
1112  * @return the resulting string after applying the replacements
1113  */
1114 sstr_t scstrreplacen(scstr_t str, scstr_t pattern,
1115         scstr_t replacement, size_t replmax);
1116
1117 /**
1118  * Replaces a pattern in a string with another string.
1119  *
1120  * The pattern is taken literally and is no regular expression.
1121  * Replaces at most <code>replmax</code> occurrences.
1122  *
1123  * The resulting string is allocated by the specified allocator. I.e. it
1124  * depends on the used allocator, whether the sstr_t.ptr must be freed
1125  * manually.
1126  *
1127  * @param allocator the allocator to use
1128  * @param str the string where replacements should be applied
1129  * @param pattern the pattern to search for
1130  * @param replacement the replacement string
1131  * @param replmax maximum number of replacements
1132  * @return the resulting string after applying the replacements
1133  */
1134 #define sstrreplacen_a(allocator, str, pattern, replacement, replmax) \
1135         scstrreplacen_a(allocator, SCSTR(str), SCSTR(pattern), \
1136             SCSTR(replacement), replmax)
1137
1138 /**
1139  * Replaces a pattern in a string with another string.
1140  *
1141  * The pattern is taken literally and is no regular expression.
1142  * Replaces at most <code>replmax</code> occurrences.
1143  *
1144  * The sstr_t.ptr of the resulting string must be freed manually.
1145  *
1146  * If allocation fails, the sstr_t.ptr of the return value is NULL.
1147  *
1148  * @param str the string where replacements should be applied
1149  * @param pattern the pattern to search for
1150  * @param replacement the replacement string
1151  * @param replmax maximum number of replacements
1152  * @return the resulting string after applying the replacements
1153  */
1154 #define sstrreplacen(str, pattern, replacement, replmax) \
1155         scstrreplacen(SCSTR(str), SCSTR(pattern), SCSTR(replacement), replmax)
1156
1157 /**
1158  * Replaces a pattern in a string with another string.
1159  *
1160  * The pattern is taken literally and is no regular expression.
1161  * Replaces at most <code>replmax</code> occurrences.
1162  *
1163  * The resulting string is allocated by the specified allocator. I.e. it
1164  * depends on the used allocator, whether the sstr_t.ptr must be freed
1165  * manually.
1166  *
1167  * If allocation fails, the sstr_t.ptr of the return value is NULL.
1168  *
1169  * @param allocator the allocator to use
1170  * @param str the string where replacements should be applied
1171  * @param pattern the pattern to search for
1172  * @param replacement the replacement string
1173  * @return the resulting string after applying the replacements
1174  */
1175 #define sstrreplace_a(allocator, str, pattern, replacement) \
1176         scstrreplacen_a(allocator, SCSTR(str), SCSTR(pattern), \
1177             SCSTR(replacement), SIZE_MAX)
1178
1179 /**
1180  * Replaces a pattern in a string with another string.
1181  *
1182  * The pattern is taken literally and is no regular expression.
1183  * Replaces at most <code>replmax</code> occurrences.
1184  *
1185  * The sstr_t.ptr of the resulting string must be freed manually.
1186  *
1187  * If allocation fails, the sstr_t.ptr of the return value is NULL.
1188  *
1189  * @param str the string where replacements should be applied
1190  * @param pattern the pattern to search for
1191  * @param replacement the replacement string
1192  * @return the resulting string after applying the replacements
1193  */
1194 #define sstrreplace(str, pattern, replacement) \
1195         scstrreplacen(SCSTR(str), SCSTR(pattern), SCSTR(replacement), SIZE_MAX)
1196
1197 #ifdef  __cplusplus
1198 }
1199 #endif
1200
1201 #endif  /* UCX_STRING_H */