Mercurial > hg > ucx / changeset

--- a/src/string.c	Mon May 14 18:27:23 2018 +0200
+++ b/src/string.c	Mon May 14 19:24:34 2018 +0200
@@ -624,9 +624,9 @@
     return ret;
 }
 
-// private string conversion functions
-scstr_t ucx_sc2sc(scstr_t c) {
-    return c;
+// type adjustment functions
+scstr_t ucx_sc2sc(scstr_t str) {
+    return str;
 }
 scstr_t ucx_ss2sc(sstr_t str) {
     scstr_t cs;

--- a/src/ucx/string.h	Mon May 14 18:27:23 2018 +0200
+++ b/src/ucx/string.h	Mon May 14 19:24:34 2018 +0200
@@ -58,10 +58,10 @@
 /** Shortcut for the conversion of a C string to a <code>sstr_t</code>. */
 #define S(s) sstrn((char*)s, sizeof(s)-1)
 
-/** Expands a sstr_t to printf arguments. */
+/** Expands a sstr_t or scstr_t to printf arguments. */
 #define SFMT(s) (int) (s).length, (s).ptr
 
-/** Format specifier for a sstr_t. */
+/** Format specifier for a sstr_t or scstr_t. */
 #define PRIsstr ".*s"
 
 #ifdef	__cplusplus
@@ -71,16 +71,22 @@
  * The UCX string structure.
  */
 typedef struct {
-   /** A reference to the string (<b>not necessarily  <code>NULL</code>
-    * -terminated</b>) */
-    char   *ptr;
+   /** A pointer to the string
+    * (<b>not necessarily <code>NULL</code>-terminated</b>) */
+    char *ptr;
     /** The length of the string */
     size_t length;
 } sstr_t;
 
+/**
+ * The UCX string structure for immutable (constant) strings.
+ */
 typedef struct {
+    /** A constant pointer to the immutable string
+     * (<b>not necessarily <code>NULL</code>-terminated</b>) */
     const char *ptr;
-    size_t     length;
+    /** The length of the string */
+    size_t length;
 } scstr_t;
 
 #ifdef	__cplusplus
@@ -101,24 +107,78 @@
 #define SCSTR s2scstr
 #else
 
-scstr_t ucx_sc2sc(scstr_t c);
+/**
+ * One of two type adjustment functions that return a scstr_t.
+ * 
+ * Used internally to cast 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.
+ * 
+ * @param str some scstr_t
+ * @return the argument itself
+ */
+scstr_t ucx_sc2sc(scstr_t str);
+
+/**
+ * One of two type adjustment functions that return a scstr_t.
+ * 
+ * Used internally to cast a UCX string to an immutable UCX string.
+ * 
+ * @param str some sstr_t
+ * @return an immutable (scstr_t) version of the provided string.
+ */
 scstr_t ucx_ss2sc(sstr_t str);
+
 #if __STDC_VERSION__ >= 201112L
+/**
+ * Casts 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(str) _Generic(str, sstr_t: ucx_ss2sc, scstr_t: ucx_sc2sc)(str)
+
 #elif defined(__GNUC__) || defined(__clang__)
+
+/**
+ * Casts 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(str) __builtin_choose_expr( \
         __builtin_types_compatible_p(typeof(str), sstr_t), \
         ucx_ss2sc, \
         ucx_sc2sc)(str)
+
 #elif defined(__sun)
+
+/**
+ * Casts 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(str) ({typeof(str) ucx_tmp_var_str = str; \
 	scstr_t ucx_tmp_var_c; \
 	ucx_tmp_var_c.ptr = ucx_tmp_var_str.ptr;\
 	ucx_tmp_var_c.length = ucx_tmp_var_str.length;\
 	ucx_tmp_var_c; })
-#else
+#else /* no generics and no builtins */
+
+/**
+ * Casts 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 casted to scstr_t without a warning.
+ * 
+ * @return the an immutable version of the provided string
+ */
 scstr_t ucx_ss2c_s();
-#define SCSTR ucx_ss2c_s
+
+/**
+ * Casts 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(str) ucx_ss2c_s(str)
 #endif /* C11 feature test */
 
 #endif /* C++ */
@@ -136,6 +196,8 @@
  * <b>Note:</b> the sstr_t will hold a <i>reference</i> to the C string. If you
  * do want a copy, use sstrdup() on the return value of this function.
  * 
+ * If you need to wrap a constant string, use scstr().
+ * 
  * @param cstring the C string to wrap
  * @return a new sstr_t containing the C string
  * 
@@ -149,6 +211,8 @@
  * <b>Note:</b> the sstr_t will hold a <i>reference</i> to the C string. If you
  * do want a copy, use sstrdup() on the return value of this function.
  * 
+ * If you need to wrap a constant string, use scstrn().
+ * 
  * @param cstring  the C string to wrap
  * @param length   the length of the string
  * @return a new sstr_t containing the C string
@@ -158,8 +222,35 @@
  */
 sstr_t sstrn(char *cstring, size_t length);
 
+/**
+ * Creates a new scstr_t based on a constant C string.
+ * 
+ * The length is implicitly inferred by using a call to <code>strlen()</code>.
+ *
+ * <b>Note:</b> the scstr_t will hold a <i>reference</i> to the C string. If you
+ * do want a copy, use scstrdup() on the return value of this function.
+ * 
+ * @param cstring the C string to wrap
+ * @return a new scstr_t containing the C string
+ * 
+ * @see scstrn()
+ */
+scstr_t scstr(const char *cstring);
 
-scstr_t scstr(const char *cstring);
+
+/**
+ * Creates a new scstr_t of the specified length based on a constant C string.
+ *
+ * <b>Note:</b> the scstr_t will hold a <i>reference</i> to the C string. If you
+ * do want a copy, use scstrdup() on the return value of this function.
+ * 
+ * 
+ * @param cstring  the C string to wrap
+ * @param length   the length of the string
+ * @return a new scstr_t containing the C string
+ * 
+ * @see scstr()
+ */
 scstr_t scstrn(const char *cstring, size_t length);
 
 /**
@@ -433,7 +524,7 @@
  * <code>free()</code>.
  * 
  * The sstr_t.ptr of the return value will <i>always</i> be <code>NULL</code>-
- * terminated.
+ * terminated and mutable.
  * 
  * @param string the string to duplicate
  * @return a duplicate of the string