Mercurial > hg > ucx / changeset

     1.1 --- a/docs/src/modules.md	Wed May 16 19:01:21 2018 +0200
     1.2 +++ b/docs/src/modules.md	Wed May 16 19:27:45 2018 +0200
     1.3 @@ -589,6 +589,25 @@
     1.4  cases. If you know what you are doing, it can save you some performance,
     1.5  because you do not need the `strlen()` call.
     1.6  
     1.7 +### Handling immutable strings
     1.8 +
     1.9 +*(Since: UCX 2.0)*
    1.10 +
    1.11 +For immutable strings (i.e. `const char*` strings), UCX provides the `scstr_t`
    1.12 +type, which works exactly as the `sstr_t` type but with a pointer
    1.13 +to `const char`. All UCX string functions come in two flavors: one that enforces
    1.14 +the `scstr_t` type, and another that usually accepts both types and performs
    1.15 +a conversion automatically, if necessary.
    1.16 +
    1.17 +There are some exceptions to this rule, as the return type may depend on the
    1.18 +argument type.
    1.19 +E.g. the `sstrchr()` function returns a substring starting at
    1.20 +the first occurrence of the specified character.
    1.21 +Since this substring points to the memory of the argument string, it does not
    1.22 +accept `scstr_t` as input argument, because the return type would break the
    1.23 +constness.
    1.24 +
    1.25 +
    1.26  ### Finding the position of a substring
    1.27  
    1.28  The `sstrstr()` function gives you a new `sstr_t` object starting with the

     2.1 --- a/src/ucx/string.h	Wed May 16 19:01:21 2018 +0200
     2.2 +++ b/src/ucx/string.h	Wed May 16 19:27:45 2018 +0200
     2.3 @@ -95,25 +95,56 @@
     2.4  
     2.5  
     2.6  #ifdef __cplusplus
     2.7 +/**
     2.8 + * One of two type adjustment functions that return a scstr_t.
     2.9 + * 
    2.10 + * Used <b>internally</b> to convert a UCX string to an immutable UCX string.
    2.11 + * 
    2.12 + * <b>Do not use this function manually.</b>
    2.13 + * 
    2.14 + * @param str some sstr_t
    2.15 + * @return an immutable (scstr_t) version of the provided string.
    2.16 + */
    2.17  inline scstr_t s2scstr(sstr_t s) {
    2.18      scstr_t c;
    2.19      c.ptr = s.ptr;
    2.20      c.length = s.ptr;
    2.21      return c;
    2.22  }
    2.23 -inline scstr_t s2scstr(scstr_t c) {
    2.24 -    return c;
    2.25 +
    2.26 +/**
    2.27 + * One of two type adjustment functions that return a scstr_t.
    2.28 + * 
    2.29 + * Used <b>internally</b> to convert a UCX string to an immutable UCX string.
    2.30 + * This variant is used, when the string is already immutable and no operation
    2.31 + * needs to be performed.
    2.32 + * 
    2.33 + * <b>Do not use this function manually.</b>
    2.34 + * 
    2.35 + * @param str some scstr_t
    2.36 + * @return the argument itself
    2.37 + */
    2.38 +inline scstr_t s2scstr(scstr_t str) {
    2.39 +    return str;
    2.40  }
    2.41 -#define SCSTR s2scstr
    2.42 +
    2.43 +/**
    2.44 + * Converts a UCX string to an immutable UCX string (scstr_t).
    2.45 + * @param str some UCX string
    2.46 + * @return the an immutable version of the provided string
    2.47 + */
    2.48 +#define SCSTR(s) s2scstr(s)
    2.49  #else
    2.50  
    2.51  /**
    2.52   * One of two type adjustment functions that return a scstr_t.
    2.53   * 
    2.54 - * Used internally to convert a UCX string to an immutable UCX string.
    2.55 + * Used <b>internally</b> to convert a UCX string to an immutable UCX string.
    2.56   * This variant is used, when the string is already immutable and no operation
    2.57   * needs to be performed.
    2.58   * 
    2.59 + * <b>Do not use this function manually.</b>
    2.60 + * 
    2.61   * @param str some scstr_t
    2.62   * @return the argument itself
    2.63   */
    2.64 @@ -122,7 +153,9 @@
    2.65  /**
    2.66   * One of two type adjustment functions that return a scstr_t.
    2.67   * 
    2.68 - * Used internally to convert a UCX string to an immutable UCX string.
    2.69 + * Used <b>internally</b> to convert a UCX string to an immutable UCX string.
    2.70 + * 
    2.71 + * <b>Do not use this function manually.</b>
    2.72   * 
    2.73   * @param str some sstr_t
    2.74   * @return an immutable (scstr_t) version of the provided string.
    2.75 @@ -131,7 +164,7 @@
    2.76  
    2.77  #if __STDC_VERSION__ >= 201112L
    2.78  /**
    2.79 - * Casts a UCX string to an immutable UCX string (scstr_t).
    2.80 + * Converts a UCX string to an immutable UCX string (scstr_t).
    2.81   * @param str some UCX string
    2.82   * @return the an immutable version of the provided string
    2.83   */
    2.84 @@ -140,7 +173,7 @@
    2.85  #elif defined(__GNUC__) || defined(__clang__)
    2.86  
    2.87  /**
    2.88 - * Casts a UCX string to an immutable UCX string (scstr_t).
    2.89 + * Converts a UCX string to an immutable UCX string (scstr_t).
    2.90   * @param str some UCX string
    2.91   * @return the an immutable version of the provided string
    2.92   */
    2.93 @@ -152,7 +185,7 @@
    2.94  #elif defined(__sun)
    2.95  
    2.96  /**
    2.97 - * Casts a UCX string to an immutable UCX string (scstr_t).
    2.98 + * Converts a UCX string to an immutable UCX string (scstr_t).
    2.99   * @param str some UCX string
   2.100   * @return the an immutable version of the provided string
   2.101   */
   2.102 @@ -164,7 +197,7 @@
   2.103  #else /* no generics and no builtins */
   2.104  
   2.105  /**
   2.106 - * Casts a UCX string to an immutable UCX string (scstr_t).
   2.107 + * Converts a UCX string to an immutable UCX string (scstr_t).
   2.108   * 
   2.109   * This internal function (ab)uses the C standard an expects one single
   2.110   * argument which is then implicitly converted to scstr_t without a warning.
   2.111 @@ -174,7 +207,7 @@
   2.112  scstr_t ucx_ss2c_s();
   2.113  
   2.114  /**
   2.115 - * Casts a UCX string to an immutable UCX string (scstr_t).
   2.116 + * Converts a UCX string to an immutable UCX string (scstr_t).
   2.117   * @param str some UCX string
   2.118   * @return the an immutable version of the provided string
   2.119   */
   2.120 @@ -612,7 +645,7 @@
   2.121   * @see sstrsplit()
   2.122   */
   2.123  #define sstrsplit_a(allocator, string, delim, count) \
   2.124 -    scstrsplit_a(allocator, SCSTR(string), SCSTR(delim, count))
   2.125 +    scstrsplit_a(allocator, SCSTR(string), SCSTR(delim), count)
   2.126  
   2.127  /**
   2.128   * Compares two UCX strings with standard <code>memcmp()</code>.