# HG changeset patch # User Mike Becker # Date 1526318674 -7200 # Node ID be0f6bd10b52c6de07f631f2b289be356f56c3dc # Parent 5b97de37aada8aa111893ba506b7545898bd8f27 adjusts documentation of UCX string types, converters, and constructors diff -r 5b97de37aada -r be0f6bd10b52 src/string.c --- 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; 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