--- a/docs/Writerside/topics/string.h.md Sun Dec 28 14:10:14 2025 +0100
+++ b/docs/Writerside/topics/string.h.md Sun Dec 28 14:47:36 2025 +0100
@@ -14,6 +14,8 @@
> To simplify documentation, we introduce the pseudo-type `AnyStr` with the meaning that
> any UCX string and any C string are supported.
> The implementation is actually hidden behind a macro which uses `cx_strcast()` to guarantee compatibility.
+> Similarly we introduce `UcxStr` with the meaning that it is either a `cxstring` or a `cxmutstr`,
+> created by `cx_strcast_m()`.
{style="note"}
```C
@@ -49,10 +51,11 @@
void cx_strfree_a(const CxAllocator *alloc, cxmutstr *str);
-#define CX_NULLSTR cx_mutstr(NULL)
-#define CX_SFMT(s) (int) (s).length, (s).ptr
-#define CX_PRIstr ".*s"
-#define cx_strcast(s) // converts any string to cxstring
+#define CX_NULLSTR cx_mutstr(NULL)
+#define CX_SFMT(s) (int) (s).length, (s).ptr
+#define CX_PRIstr ".*s"
+#define cx_strcast(s) // converts any string to cxstring
+#define cx_strcast_m(s) // converts any string to a UcxStr
```
The functions `cx_str()` and `cx_mutstr()` create a UCX string from a `const char*` or a `char*`
@@ -75,6 +78,10 @@
When you want to use a UCX string in a `printf`-like function, you can use the macro `CX_PRIstr` for the format specifier,
and the `CX_SFMT(s)` macro to expand the arguments.
+The macros `cx_strcast()` and `cx_strcast_m()` take any supported string (`AnyStr`) and convert it either to a `cxstring` or a `cxmutstr`.
+While `cx_strcast()` _always_ converts to a `cxstring`, `cx_strcast_m()` decides depending on the constness of the string to return either a `cxstring` or a `cxmutstr`.
+You should rarely need those macros in your code, as most UCX functions are already implemented behind macros that do the conversions for you.
+
> When you want to convert a string _literal_ into a UCX string, you can also use the `cx_str()` function.
> With optimizations turned on, this function gets inlined and optimizes the call to `strlen()` out, giving
> you a `cxstring` structure at zero cost with the length calculated at compile-time.
@@ -154,31 +161,19 @@
```C
#include <cx/string.h>
-char cx_strat(cxstring str, off_t index);
-
-cxstring cx_strchr(cxstring string, int chr);
-
-cxstring cx_strrchr(cxstring string, int chr);
+char cx_strat(AnyStr str, off_t index);
-cxstring cx_strstr(cxstring string, AnyStr search);
+UcxStr cx_strchr(AnyStr string, int chr);
-cxstring cx_strsubs(cxstring string, size_t start);
-
-cxstring cx_strsubsl(cxstring string, size_t start, size_t length);
+UcxStr cx_strrchr(AnyStr string, int chr);
-cxstring cx_strtrim(cxstring string);
+UcxStr cx_strstr(AnyStr string, AnyStr search);
-cxmutstr cx_strchr_m(cxmutstr string, int chr);
-
-cxmutstr cx_strrchr_m(cxmutstr string, int chr);
+UcxStr cx_strsubs(AnyStr string, size_t start);
-cxmutstr cx_strstr_m(cxmutstr string, AnyStr search);
-
-cxmutstr cx_strsubs_m(cxmutstr string, size_t start);
+UcxStr cx_strsubsl(AnyStr string, size_t start, size_t length);
-cxmutstr cx_strsubsl_m(cxmutstr string, size_t start, size_t length);
-
-cxmutstr cx_strtrim_m(cxmutstr string);
+UcxStr cx_strtrim(AnyStr string);
```
The function `cx_strat()` returns the character at the specified `index`.