Mercurial > hg > ucx / changeset

--- a/docs/Writerside/topics/string.h.md	Mon Feb 17 23:34:33 2025 +0100
+++ b/docs/Writerside/topics/string.h.md	Thu Feb 20 20:49:04 2025 +0100
@@ -35,7 +35,7 @@
 
 cxstring cx_strcast(AnyStr str);
 
-cxmutstr cx_strdupa(AnyStr string);
+cxmutstr cx_strdup(AnyStr string);
 
 cxmutstr cx_strdup_a(const CxAllocator *allocator, AnyStr string);
 
@@ -44,8 +44,18 @@
 void cx_strfree_a(const CxAllocator *alloc, cxmutstr *str);
 ```
 
-> Documentation work in progress.
->{style="warning"}
+The functions `cx_str()` and `cx_mutstr()` create a UCX string from a `const char*` or a `char*`
+and compute the length with a call to stdlib `strlen()`.
+In case you already know the length, or the string is not zero-terminated, you can use `cx_strn()` or `cx_mutstrn()`.
+
+The function `cx_strdup_a()` allocates new memory with the given `allocator` and copies the given `string`
+and guarantees that the result string is zero-terminated.
+The function `cx_strdup()` is equivalent to `cx_strdup_a()`, except that it uses the default stdlib allocator.
+
+Allocated strings are always of type `cxmutstr` and can be deallocated by a call to `cx_strfree()` or `cx_strfree_a()`.
+The caller must make sure to use the correct allocator for deallocating a string.
+It is safe to call these functions multiple times on a given string, as the pointer will be nulled and the length set to zero.
+It is also safe to call the functions with a `NULL`-pointer, just like any other `free()`-like function.
 
 > When you want to convert a string _literal_ into a UCX string, you can also use the `CX_STR(lit)` macro.
 > This macro uses the fact that `sizeof(lit)` for a string literal `lit` is always the string length plus one,