diff -r 5b97de37aada -r be0f6bd10b52 src/ucx/string.h
--- 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 sstr_t
. */
#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 (not necessarily NULL
- * -terminated) */
- char *ptr;
+ /** A pointer to the string
+ * (not necessarily NULL
-terminated) */
+ 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
+ * (not necessarily NULL
-terminated) */
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 @@
* Note: the sstr_t will hold a reference 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 @@
* Note: the sstr_t will hold a reference 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 strlen()
.
+ *
+ * Note: the scstr_t will hold a reference 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.
+ *
+ * Note: the scstr_t will hold a reference 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 @@
* free()
.
*
* The sstr_t.ptr of the return value will always be NULL
-
- * terminated.
+ * terminated and mutable.
*
* @param string the string to duplicate
* @return a duplicate of the string