1.1 --- a/src/ucx/string.h Mon May 14 18:27:23 2018 +0200
1.2 +++ b/src/ucx/string.h Mon May 14 19:24:34 2018 +0200
1.3 @@ -58,10 +58,10 @@
1.4 /** Shortcut for the conversion of a C string to a <code>sstr_t</code>. */
1.5 #define S(s) sstrn((char*)s, sizeof(s)-1)
1.6
1.7 -/** Expands a sstr_t to printf arguments. */
1.8 +/** Expands a sstr_t or scstr_t to printf arguments. */
1.9 #define SFMT(s) (int) (s).length, (s).ptr
1.10
1.11 -/** Format specifier for a sstr_t. */
1.12 +/** Format specifier for a sstr_t or scstr_t. */
1.13 #define PRIsstr ".*s"
1.14
1.15 #ifdef __cplusplus
1.16 @@ -71,16 +71,22 @@
1.17 * The UCX string structure.
1.18 */
1.19 typedef struct {
1.20 - /** A reference to the string (<b>not necessarily <code>NULL</code>
1.21 - * -terminated</b>) */
1.22 - char *ptr;
1.23 + /** A pointer to the string
1.24 + * (<b>not necessarily <code>NULL</code>-terminated</b>) */
1.25 + char *ptr;
1.26 /** The length of the string */
1.27 size_t length;
1.28 } sstr_t;
1.29
1.30 +/**
1.31 + * The UCX string structure for immutable (constant) strings.
1.32 + */
1.33 typedef struct {
1.34 + /** A constant pointer to the immutable string
1.35 + * (<b>not necessarily <code>NULL</code>-terminated</b>) */
1.36 const char *ptr;
1.37 - size_t length;
1.38 + /** The length of the string */
1.39 + size_t length;
1.40 } scstr_t;
1.41
1.42 #ifdef __cplusplus
1.43 @@ -101,24 +107,78 @@
1.44 #define SCSTR s2scstr
1.45 #else
1.46
1.47 -scstr_t ucx_sc2sc(scstr_t c);
1.48 +/**
1.49 + * One of two type adjustment functions that return a scstr_t.
1.50 + *
1.51 + * Used internally to cast a UCX string to an immutable UCX string.
1.52 + * This variant is used, when the string is already immutable and no operation
1.53 + * needs to be performed.
1.54 + *
1.55 + * @param str some scstr_t
1.56 + * @return the argument itself
1.57 + */
1.58 +scstr_t ucx_sc2sc(scstr_t str);
1.59 +
1.60 +/**
1.61 + * One of two type adjustment functions that return a scstr_t.
1.62 + *
1.63 + * Used internally to cast a UCX string to an immutable UCX string.
1.64 + *
1.65 + * @param str some sstr_t
1.66 + * @return an immutable (scstr_t) version of the provided string.
1.67 + */
1.68 scstr_t ucx_ss2sc(sstr_t str);
1.69 +
1.70 #if __STDC_VERSION__ >= 201112L
1.71 +/**
1.72 + * Casts a UCX string to an immutable UCX string (scstr_t).
1.73 + * @param str some UCX string
1.74 + * @return the an immutable version of the provided string
1.75 + */
1.76 #define SCSTR(str) _Generic(str, sstr_t: ucx_ss2sc, scstr_t: ucx_sc2sc)(str)
1.77 +
1.78 #elif defined(__GNUC__) || defined(__clang__)
1.79 +
1.80 +/**
1.81 + * Casts a UCX string to an immutable UCX string (scstr_t).
1.82 + * @param str some UCX string
1.83 + * @return the an immutable version of the provided string
1.84 + */
1.85 #define SCSTR(str) __builtin_choose_expr( \
1.86 __builtin_types_compatible_p(typeof(str), sstr_t), \
1.87 ucx_ss2sc, \
1.88 ucx_sc2sc)(str)
1.89 +
1.90 #elif defined(__sun)
1.91 +
1.92 +/**
1.93 + * Casts a UCX string to an immutable UCX string (scstr_t).
1.94 + * @param str some UCX string
1.95 + * @return the an immutable version of the provided string
1.96 + */
1.97 #define SCSTR(str) ({typeof(str) ucx_tmp_var_str = str; \
1.98 scstr_t ucx_tmp_var_c; \
1.99 ucx_tmp_var_c.ptr = ucx_tmp_var_str.ptr;\
1.100 ucx_tmp_var_c.length = ucx_tmp_var_str.length;\
1.101 ucx_tmp_var_c; })
1.102 -#else
1.103 +#else /* no generics and no builtins */
1.104 +
1.105 +/**
1.106 + * Casts a UCX string to an immutable UCX string (scstr_t).
1.107 + *
1.108 + * This internal function (ab)uses the C standard an expects one single
1.109 + * argument which is then implicitly casted to scstr_t without a warning.
1.110 + *
1.111 + * @return the an immutable version of the provided string
1.112 + */
1.113 scstr_t ucx_ss2c_s();
1.114 -#define SCSTR ucx_ss2c_s
1.115 +
1.116 +/**
1.117 + * Casts a UCX string to an immutable UCX string (scstr_t).
1.118 + * @param str some UCX string
1.119 + * @return the an immutable version of the provided string
1.120 + */
1.121 +#define SCSTR(str) ucx_ss2c_s(str)
1.122 #endif /* C11 feature test */
1.123
1.124 #endif /* C++ */
1.125 @@ -136,6 +196,8 @@
1.126 * <b>Note:</b> the sstr_t will hold a <i>reference</i> to the C string. If you
1.127 * do want a copy, use sstrdup() on the return value of this function.
1.128 *
1.129 + * If you need to wrap a constant string, use scstr().
1.130 + *
1.131 * @param cstring the C string to wrap
1.132 * @return a new sstr_t containing the C string
1.133 *
1.134 @@ -149,6 +211,8 @@
1.135 * <b>Note:</b> the sstr_t will hold a <i>reference</i> to the C string. If you
1.136 * do want a copy, use sstrdup() on the return value of this function.
1.137 *
1.138 + * If you need to wrap a constant string, use scstrn().
1.139 + *
1.140 * @param cstring the C string to wrap
1.141 * @param length the length of the string
1.142 * @return a new sstr_t containing the C string
1.143 @@ -158,8 +222,35 @@
1.144 */
1.145 sstr_t sstrn(char *cstring, size_t length);
1.146
1.147 +/**
1.148 + * Creates a new scstr_t based on a constant C string.
1.149 + *
1.150 + * The length is implicitly inferred by using a call to <code>strlen()</code>.
1.151 + *
1.152 + * <b>Note:</b> the scstr_t will hold a <i>reference</i> to the C string. If you
1.153 + * do want a copy, use scstrdup() on the return value of this function.
1.154 + *
1.155 + * @param cstring the C string to wrap
1.156 + * @return a new scstr_t containing the C string
1.157 + *
1.158 + * @see scstrn()
1.159 + */
1.160 +scstr_t scstr(const char *cstring);
1.161
1.162 -scstr_t scstr(const char *cstring);
1.163 +
1.164 +/**
1.165 + * Creates a new scstr_t of the specified length based on a constant C string.
1.166 + *
1.167 + * <b>Note:</b> the scstr_t will hold a <i>reference</i> to the C string. If you
1.168 + * do want a copy, use scstrdup() on the return value of this function.
1.169 + *
1.170 + *
1.171 + * @param cstring the C string to wrap
1.172 + * @param length the length of the string
1.173 + * @return a new scstr_t containing the C string
1.174 + *
1.175 + * @see scstr()
1.176 + */
1.177 scstr_t scstrn(const char *cstring, size_t length);
1.178
1.179 /**
1.180 @@ -433,7 +524,7 @@
1.181 * <code>free()</code>.
1.182 *
1.183 * The sstr_t.ptr of the return value will <i>always</i> be <code>NULL</code>-
1.184 - * terminated.
1.185 + * terminated and mutable.
1.186 *
1.187 * @param string the string to duplicate
1.188 * @return a duplicate of the string
