Mercurial > hg > ucx / changeset

--- 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)  

--- a/src/ucx/string.h	Tue May 29 10:02:55 2018 +0200
+++ b/src/ucx/string.h	Tue May 29 11:05:12 2018 +0200
@@ -52,17 +52,33 @@
 #include "allocator.h"
 #include <stddef.h>
 
-/** Shortcut for a <code>sstr_t struct</code> literal. */
-#define ST(s) { (char*)s, sizeof(s)-1 }
+/*
+ * Use this macro to disable the shortcuts if you experience macro collision.
+ */
+#ifndef UCX_NO_SSTR_SHORTCUTS
+/**
+ * Shortcut for a <code>sstr_t struct</code>
+ * or <code>scstr_t struct</code> literal.
+ */
+#define ST(s) { s, sizeof(s)-1 }
 
 /** Shortcut for the conversion of a C string to a <code>sstr_t</code>. */
-#define S(s) sstrn((char*)s, sizeof(s)-1)
+#define S(s) sstrn(s, sizeof(s)-1)
 
+/** Shortcut for the conversion of a C string to a <code>scstr_t</code>. */
+#define SC(s) scstrn(s, sizeof(s)-1)
+#endif /* UCX_NO_SSTR_SHORTCUTS */
+
+/*
+ * Use this macro to disable the format macros.
+ */
+#ifndef UCX_NO_SSTR_FORMAT_MACROS
 /** Expands a sstr_t or scstr_t to printf arguments. */
 #define SFMT(s) (int) (s).length, (s).ptr
 
 /** Format specifier for a sstr_t or scstr_t. */
 #define PRIsstr ".*s"
+#endif /* UCX_NO_SSTR_FORMAT_MACROS */
 
 #ifdef	__cplusplus
 extern "C" {