diff -r 343bff4cc0b5 -r a3e63cb21e20 docs/src/modules.md --- a/docs/src/modules.md Tue May 29 10:02:55 2018 +0200 +++ b/docs/src/modules.md Tue May 29 11:05:12 2018 +0200 @@ -580,13 +580,17 @@ This version is especially useful for function arguments */ sstr_t c = S("hello"); -/* (4) ST() macro creates sstr_t struct literal using sizeof() */ -sstr_t d = ST("hello"); +/* (4) SC() macro works like S(), but makes the string immutable using scstr_t. + (available since UCX 2.0) */ +scstr_t d = SC("hello"); + +/* (5) ST() macro creates sstr_t struct literal using sizeof() */ +sstr_t e = ST("hello"); ``` -You should not use the `S()` or `ST()` macro with string of unknown origin, -since the `sizeof()` call might not coincide with the string length in those -cases. If you know what you are doing, it can save you some performance, +You should not use the `S()`, `SC()`, or `ST()` macro with string of unknown +origin, since the `sizeof()` call might not coincide with the string length in +those cases. If you know what you are doing, it can save you some performance, because you do not need the `strlen()` call. ### Handling immutable strings @@ -655,6 +659,19 @@ The memory pool ensures, that all strings are freed. +### Disabling convenience macros + +If you are experiencing any troubles with the short convenience macros `S()`, +`SC()`, or `ST()`, you can disable them by setting the macro +`UCX_NO_SSTR_SHORTCUTS` before including the header (or via a compiler option). +For the formatting macros `SFMT()` and `PRIsstr` you can use the macro +`UCX_NO_SSTR_FORMAT_MACROS` to disable them. + +Please keep in mind, that after disabling the macros, you cannot use them in +your code *and* foreign code that you might have included. +You should only disable the macros, if you are experiencing a nasty name clash +which cannot be otherwise resolved. + ## Testing *Header file:* [test.h](api/test_8h.html)