# HG changeset patch # User Mike Becker # Date 1687883068 -7200 # Node ID c33e0ac069dda47761a892a86b1ff9bd0660022f # Parent adc3c48dd3afa831bf30c6d4e7dd4c1ff17c40da add web documentation for strings diff -r adc3c48dd3af -r c33e0ac069dd docs/src/features.md --- a/docs/src/features.md Tue Jun 27 18:10:34 2023 +0200 +++ b/docs/src/features.md Tue Jun 27 18:24:28 2023 +0200 @@ -57,6 +57,21 @@ *Header file:* [string.h](api/string_8h.html) +UCX strings come in two variants: immutable (`cxstring`) and mutable (`cxmutstr`). +The functions of UCX are designed to work with immutable strings by default but in situations where it is necessary, +the API also provides alternative functions that work directly with mutable strings. +Functions that change a string in-place are, of course, only accepting mutable strings. + +When you are using UCX functions, or defining your own functions, you are sometimes facing the "problem", +that the function only accepts arguments of type `cxstring` but you only have a `cxmutstr` at hand. +In this case you _should not_ introduce a wrapper function that accepts the `cxmutstr`, +but instead you should use the `cx_strcast()` function to cast the argument to the correct type. + +In general, UCX strings are **not** necessarily zero-terminated. If a function guarantees to return zero-terminated +string, it is explicitly mentioned in the documentation of the respective function. +As a rule of thumb, you _should not_ pass the strings of a UCX string structure to another API without explicitly +ensuring that the string is zero-terminated. + ## Buffer *Header file:* [buffer.h](api/buffer_8h.html)