Mercurial > hg > ucx / changeset

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

--- a/src/ucx/string.h	Wed May 16 19:01:21 2018 +0200
+++ b/src/ucx/string.h	Wed May 16 19:27:45 2018 +0200
@@ -95,25 +95,56 @@
 
 
 #ifdef __cplusplus
+/**
+ * One of two type adjustment functions that return a scstr_t.
+ * 
+ * Used <b>internally</b> to convert a UCX string to an immutable UCX string.
+ * 
+ * <b>Do not use this function manually.</b>
+ * 
+ * @param str some sstr_t
+ * @return an immutable (scstr_t) version of the provided string.
+ */
 inline scstr_t s2scstr(sstr_t s) {
     scstr_t c;
     c.ptr = s.ptr;
     c.length = s.ptr;
     return c;
 }
-inline scstr_t s2scstr(scstr_t c) {
-    return c;
+
+/**
+ * One of two type adjustment functions that return a scstr_t.
+ * 
+ * Used <b>internally</b> to convert a UCX string to an immutable UCX string.
+ * This variant is used, when the string is already immutable and no operation
+ * needs to be performed.
+ * 
+ * <b>Do not use this function manually.</b>
+ * 
+ * @param str some scstr_t
+ * @return the argument itself
+ */
+inline scstr_t s2scstr(scstr_t str) {
+    return str;
 }
-#define SCSTR s2scstr
+
+/**
+ * Converts a UCX string to an immutable UCX string (scstr_t).
+ * @param str some UCX string
+ * @return the an immutable version of the provided string
+ */
+#define SCSTR(s) s2scstr(s)
 #else
 
 /**
  * One of two type adjustment functions that return a scstr_t.
  * 
- * Used internally to convert a UCX string to an immutable UCX string.
+ * Used <b>internally</b> to convert a UCX string to an immutable UCX string.
  * This variant is used, when the string is already immutable and no operation
  * needs to be performed.
  * 
+ * <b>Do not use this function manually.</b>
+ * 
  * @param str some scstr_t
  * @return the argument itself
  */
@@ -122,7 +153,9 @@
 /**
  * One of two type adjustment functions that return a scstr_t.
  * 
- * Used internally to convert a UCX string to an immutable UCX string.
+ * Used <b>internally</b> to convert a UCX string to an immutable UCX string.
+ * 
+ * <b>Do not use this function manually.</b>
  * 
  * @param str some sstr_t
  * @return an immutable (scstr_t) version of the provided string.
@@ -131,7 +164,7 @@
 
 #if __STDC_VERSION__ >= 201112L
 /**
- * Casts a UCX string to an immutable UCX string (scstr_t).
+ * Converts a UCX string to an immutable UCX string (scstr_t).
  * @param str some UCX string
  * @return the an immutable version of the provided string
  */
@@ -140,7 +173,7 @@
 #elif defined(__GNUC__) || defined(__clang__)
 
 /**
- * Casts a UCX string to an immutable UCX string (scstr_t).
+ * Converts a UCX string to an immutable UCX string (scstr_t).
  * @param str some UCX string
  * @return the an immutable version of the provided string
  */
@@ -152,7 +185,7 @@
 #elif defined(__sun)
 
 /**
- * Casts a UCX string to an immutable UCX string (scstr_t).
+ * Converts a UCX string to an immutable UCX string (scstr_t).
  * @param str some UCX string
  * @return the an immutable version of the provided string
  */
@@ -164,7 +197,7 @@
 #else /* no generics and no builtins */
 
 /**
- * Casts a UCX string to an immutable UCX string (scstr_t).
+ * Converts a UCX string to an immutable UCX string (scstr_t).
  * 
  * This internal function (ab)uses the C standard an expects one single
  * argument which is then implicitly converted to scstr_t without a warning.
@@ -174,7 +207,7 @@
 scstr_t ucx_ss2c_s();
 
 /**
- * Casts a UCX string to an immutable UCX string (scstr_t).
+ * Converts a UCX string to an immutable UCX string (scstr_t).
  * @param str some UCX string
  * @return the an immutable version of the provided string
  */
@@ -612,7 +645,7 @@
  * @see sstrsplit()
  */
 #define sstrsplit_a(allocator, string, delim, count) \
-    scstrsplit_a(allocator, SCSTR(string), SCSTR(delim, count))
+    scstrsplit_a(allocator, SCSTR(string), SCSTR(delim), count)
 
 /**
  * Compares two UCX strings with standard <code>memcmp()</code>.