Mercurial > hg > ucx / changeset

     1.1 --- a/docs/src/modules.md	Tue May 29 10:02:55 2018 +0200
     1.2 +++ b/docs/src/modules.md	Tue May 29 11:05:12 2018 +0200
     1.3 @@ -580,13 +580,17 @@
     1.4         This version is especially useful for function arguments */
     1.5  sstr_t c = S("hello");
     1.6  
     1.7 -/* (4) ST() macro creates sstr_t struct literal using sizeof() */
     1.8 -sstr_t d = ST("hello");
     1.9 +/* (4) SC() macro works like S(), but makes the string immutable using scstr_t.
    1.10 +       (available since UCX 2.0) */
    1.11 +scstr_t d = SC("hello");
    1.12 +
    1.13 +/* (5) ST() macro creates sstr_t struct literal using sizeof() */
    1.14 +sstr_t e = ST("hello");
    1.15  ```
    1.16  
    1.17 -You should not use the `S()` or `ST()` macro with string of unknown origin,
    1.18 -since the `sizeof()` call might not coincide with the string length in those
    1.19 -cases. If you know what you are doing, it can save you some performance,
    1.20 +You should not use the `S()`, `SC()`, or `ST()` macro with string of unknown
    1.21 +origin, since the `sizeof()` call might not coincide with the string length in
    1.22 +those cases. If you know what you are doing, it can save you some performance,
    1.23  because you do not need the `strlen()` call.
    1.24  
    1.25  ### Handling immutable strings
    1.26 @@ -655,6 +659,19 @@
    1.27  
    1.28  The memory pool ensures, that all strings are freed.
    1.29  
    1.30 +### Disabling convenience macros
    1.31 +
    1.32 +If you are experiencing any troubles with the short convenience macros `S()`,
    1.33 +`SC()`, or `ST()`, you can disable them by setting the macro
    1.34 +`UCX_NO_SSTR_SHORTCUTS` before including the header (or via a compiler option).
    1.35 +For the formatting macros `SFMT()` and `PRIsstr` you can use the macro
    1.36 +`UCX_NO_SSTR_FORMAT_MACROS` to disable them.
    1.37 +
    1.38 +Please keep in mind, that after disabling the macros, you cannot use them in
    1.39 +your code *and* foreign code that you might have included.
    1.40 +You should only disable the macros, if you are experiencing a nasty name clash
    1.41 +which cannot be otherwise resolved.
    1.42 +
    1.43  ## Testing
    1.44  
    1.45  *Header file:* [test.h](api/test_8h.html)  

     2.1 --- a/src/ucx/string.h	Tue May 29 10:02:55 2018 +0200
     2.2 +++ b/src/ucx/string.h	Tue May 29 11:05:12 2018 +0200
     2.3 @@ -52,17 +52,33 @@
     2.4  #include "allocator.h"
     2.5  #include <stddef.h>
     2.6  
     2.7 -/** Shortcut for a <code>sstr_t struct</code> literal. */
     2.8 -#define ST(s) { (char*)s, sizeof(s)-1 }
     2.9 +/*
    2.10 + * Use this macro to disable the shortcuts if you experience macro collision.
    2.11 + */
    2.12 +#ifndef UCX_NO_SSTR_SHORTCUTS
    2.13 +/**
    2.14 + * Shortcut for a <code>sstr_t struct</code>
    2.15 + * or <code>scstr_t struct</code> literal.
    2.16 + */
    2.17 +#define ST(s) { s, sizeof(s)-1 }
    2.18  
    2.19  /** Shortcut for the conversion of a C string to a <code>sstr_t</code>. */
    2.20 -#define S(s) sstrn((char*)s, sizeof(s)-1)
    2.21 +#define S(s) sstrn(s, sizeof(s)-1)
    2.22  
    2.23 +/** Shortcut for the conversion of a C string to a <code>scstr_t</code>. */
    2.24 +#define SC(s) scstrn(s, sizeof(s)-1)
    2.25 +#endif /* UCX_NO_SSTR_SHORTCUTS */
    2.26 +
    2.27 +/*
    2.28 + * Use this macro to disable the format macros.
    2.29 + */
    2.30 +#ifndef UCX_NO_SSTR_FORMAT_MACROS
    2.31  /** Expands a sstr_t or scstr_t to printf arguments. */
    2.32  #define SFMT(s) (int) (s).length, (s).ptr
    2.33  
    2.34  /** Format specifier for a sstr_t or scstr_t. */
    2.35  #define PRIsstr ".*s"
    2.36 +#endif /* UCX_NO_SSTR_FORMAT_MACROS */
    2.37  
    2.38  #ifdef	__cplusplus
    2.39  extern "C" {