Mercurial > hg > ucx / changeset

--- a/docs/Writerside/topics/strings.md	Fri Feb 14 16:00:05 2025 +0100
+++ b/docs/Writerside/topics/strings.md	Sat Feb 15 16:36:29 2025 +0100
@@ -4,4 +4,20 @@
 UCX provides an API to work with structures that store a [string](string.h.md) together with its length,
 as well as a more sophisticated [buffer](buffer.h.md) API for working with text of dynamic or unknown length.
 
+Additionally, UCX offers several advanced [printf-like functions](printf.h.md) that also allow the convenient work
+with strings of unknown length.
+For example, one the more advanced functions is `cx_sprintf_sa()` which lets you format a string into an existing
+pre-allocated buffer (e.g. on the stack) and automatically switches to a fresh buffer allocated by a custom allocator
+when the existing buffer is not large enough.
 
+The string API is designed to work with _both_ mutable and constant strings.
+The possibility to work with constant strings is especially important, when you want to work with string literals
+without copying them into a separate memory region - e.g. when you want to obtain a substring.
+
+By default, UCX assumes strings are constant and stores them in a structure of type `cxstring`.
+Mutable strings are stored in a separate structure called `cxmutstr`.
+You can conveniently convert any UCX string to a `cxstring` by using `cx_strcast()`.
+Several macros throughout UCX already do that for you.
+Since this function is usually inlined, this comes with no additional cost when compiled with optimizations enabled.
+
+