Mercurial > hg > ucx / changeset

     1.1 --- a/src/string.c	Mon May 14 18:27:23 2018 +0200
     1.2 +++ b/src/string.c	Mon May 14 19:24:34 2018 +0200
     1.3 @@ -624,9 +624,9 @@
     1.4      return ret;
     1.5  }
     1.6  
     1.7 -// private string conversion functions
     1.8 -scstr_t ucx_sc2sc(scstr_t c) {
     1.9 -    return c;
    1.10 +// type adjustment functions
    1.11 +scstr_t ucx_sc2sc(scstr_t str) {
    1.12 +    return str;
    1.13  }
    1.14  scstr_t ucx_ss2sc(sstr_t str) {
    1.15      scstr_t cs;

     2.1 --- a/src/ucx/string.h	Mon May 14 18:27:23 2018 +0200
     2.2 +++ b/src/ucx/string.h	Mon May 14 19:24:34 2018 +0200
     2.3 @@ -58,10 +58,10 @@
     2.4  /** Shortcut for the conversion of a C string to a <code>sstr_t</code>. */
     2.5  #define S(s) sstrn((char*)s, sizeof(s)-1)
     2.6  
     2.7 -/** Expands a sstr_t to printf arguments. */
     2.8 +/** Expands a sstr_t or scstr_t to printf arguments. */
     2.9  #define SFMT(s) (int) (s).length, (s).ptr
    2.10  
    2.11 -/** Format specifier for a sstr_t. */
    2.12 +/** Format specifier for a sstr_t or scstr_t. */
    2.13  #define PRIsstr ".*s"
    2.14  
    2.15  #ifdef	__cplusplus
    2.16 @@ -71,16 +71,22 @@
    2.17   * The UCX string structure.
    2.18   */
    2.19  typedef struct {
    2.20 -   /** A reference to the string (<b>not necessarily  <code>NULL</code>
    2.21 -    * -terminated</b>) */
    2.22 -    char   *ptr;
    2.23 +   /** A pointer to the string
    2.24 +    * (<b>not necessarily <code>NULL</code>-terminated</b>) */
    2.25 +    char *ptr;
    2.26      /** The length of the string */
    2.27      size_t length;
    2.28  } sstr_t;
    2.29  
    2.30 +/**
    2.31 + * The UCX string structure for immutable (constant) strings.
    2.32 + */
    2.33  typedef struct {
    2.34 +    /** A constant pointer to the immutable string
    2.35 +     * (<b>not necessarily <code>NULL</code>-terminated</b>) */
    2.36      const char *ptr;
    2.37 -    size_t     length;
    2.38 +    /** The length of the string */
    2.39 +    size_t length;
    2.40  } scstr_t;
    2.41  
    2.42  #ifdef	__cplusplus
    2.43 @@ -101,24 +107,78 @@
    2.44  #define SCSTR s2scstr
    2.45  #else
    2.46  
    2.47 -scstr_t ucx_sc2sc(scstr_t c);
    2.48 +/**
    2.49 + * One of two type adjustment functions that return a scstr_t.
    2.50 + * 
    2.51 + * Used internally to cast a UCX string to an immutable UCX string.
    2.52 + * This variant is used, when the string is already immutable and no operation
    2.53 + * needs to be performed.
    2.54 + * 
    2.55 + * @param str some scstr_t
    2.56 + * @return the argument itself
    2.57 + */
    2.58 +scstr_t ucx_sc2sc(scstr_t str);
    2.59 +
    2.60 +/**
    2.61 + * One of two type adjustment functions that return a scstr_t.
    2.62 + * 
    2.63 + * Used internally to cast a UCX string to an immutable UCX string.
    2.64 + * 
    2.65 + * @param str some sstr_t
    2.66 + * @return an immutable (scstr_t) version of the provided string.
    2.67 + */
    2.68  scstr_t ucx_ss2sc(sstr_t str);
    2.69 +
    2.70  #if __STDC_VERSION__ >= 201112L
    2.71 +/**
    2.72 + * Casts a UCX string to an immutable UCX string (scstr_t).
    2.73 + * @param str some UCX string
    2.74 + * @return the an immutable version of the provided string
    2.75 + */
    2.76  #define SCSTR(str) _Generic(str, sstr_t: ucx_ss2sc, scstr_t: ucx_sc2sc)(str)
    2.77 +
    2.78  #elif defined(__GNUC__) || defined(__clang__)
    2.79 +
    2.80 +/**
    2.81 + * Casts a UCX string to an immutable UCX string (scstr_t).
    2.82 + * @param str some UCX string
    2.83 + * @return the an immutable version of the provided string
    2.84 + */
    2.85  #define SCSTR(str) __builtin_choose_expr( \
    2.86          __builtin_types_compatible_p(typeof(str), sstr_t), \
    2.87          ucx_ss2sc, \
    2.88          ucx_sc2sc)(str)
    2.89 +
    2.90  #elif defined(__sun)
    2.91 +
    2.92 +/**
    2.93 + * Casts a UCX string to an immutable UCX string (scstr_t).
    2.94 + * @param str some UCX string
    2.95 + * @return the an immutable version of the provided string
    2.96 + */
    2.97  #define SCSTR(str) ({typeof(str) ucx_tmp_var_str = str; \
    2.98  	scstr_t ucx_tmp_var_c; \
    2.99  	ucx_tmp_var_c.ptr = ucx_tmp_var_str.ptr;\
   2.100  	ucx_tmp_var_c.length = ucx_tmp_var_str.length;\
   2.101  	ucx_tmp_var_c; })
   2.102 -#else
   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 + * 
   2.108 + * This internal function (ab)uses the C standard an expects one single
   2.109 + * argument which is then implicitly casted to scstr_t without a warning.
   2.110 + * 
   2.111 + * @return the an immutable version of the provided string
   2.112 + */
   2.113  scstr_t ucx_ss2c_s();
   2.114 -#define SCSTR ucx_ss2c_s
   2.115 +
   2.116 +/**
   2.117 + * Casts a UCX string to an immutable UCX string (scstr_t).
   2.118 + * @param str some UCX string
   2.119 + * @return the an immutable version of the provided string
   2.120 + */
   2.121 +#define SCSTR(str) ucx_ss2c_s(str)
   2.122  #endif /* C11 feature test */
   2.123  
   2.124  #endif /* C++ */
   2.125 @@ -136,6 +196,8 @@
   2.126   * <b>Note:</b> the sstr_t will hold a <i>reference</i> to the C string. If you
   2.127   * do want a copy, use sstrdup() on the return value of this function.
   2.128   * 
   2.129 + * If you need to wrap a constant string, use scstr().
   2.130 + * 
   2.131   * @param cstring the C string to wrap
   2.132   * @return a new sstr_t containing the C string
   2.133   * 
   2.134 @@ -149,6 +211,8 @@
   2.135   * <b>Note:</b> the sstr_t will hold a <i>reference</i> to the C string. If you
   2.136   * do want a copy, use sstrdup() on the return value of this function.
   2.137   * 
   2.138 + * If you need to wrap a constant string, use scstrn().
   2.139 + * 
   2.140   * @param cstring  the C string to wrap
   2.141   * @param length   the length of the string
   2.142   * @return a new sstr_t containing the C string
   2.143 @@ -158,8 +222,35 @@
   2.144   */
   2.145  sstr_t sstrn(char *cstring, size_t length);
   2.146  
   2.147 +/**
   2.148 + * Creates a new scstr_t based on a constant C string.
   2.149 + * 
   2.150 + * The length is implicitly inferred by using a call to <code>strlen()</code>.
   2.151 + *
   2.152 + * <b>Note:</b> the scstr_t will hold a <i>reference</i> to the C string. If you
   2.153 + * do want a copy, use scstrdup() on the return value of this function.
   2.154 + * 
   2.155 + * @param cstring the C string to wrap
   2.156 + * @return a new scstr_t containing the C string
   2.157 + * 
   2.158 + * @see scstrn()
   2.159 + */
   2.160 +scstr_t scstr(const char *cstring);
   2.161  
   2.162 -scstr_t scstr(const char *cstring);
   2.163 +
   2.164 +/**
   2.165 + * Creates a new scstr_t of the specified length based on a constant C string.
   2.166 + *
   2.167 + * <b>Note:</b> the scstr_t will hold a <i>reference</i> to the C string. If you
   2.168 + * do want a copy, use scstrdup() on the return value of this function.
   2.169 + * 
   2.170 + * 
   2.171 + * @param cstring  the C string to wrap
   2.172 + * @param length   the length of the string
   2.173 + * @return a new scstr_t containing the C string
   2.174 + * 
   2.175 + * @see scstr()
   2.176 + */
   2.177  scstr_t scstrn(const char *cstring, size_t length);
   2.178  
   2.179  /**
   2.180 @@ -433,7 +524,7 @@
   2.181   * <code>free()</code>.
   2.182   * 
   2.183   * The sstr_t.ptr of the return value will <i>always</i> be <code>NULL</code>-
   2.184 - * terminated.
   2.185 + * terminated and mutable.
   2.186   * 
   2.187   * @param string the string to duplicate
   2.188   * @return a duplicate of the string