Mercurial > hg > ucx / changeset

     1.1 --- a/docs/src/features.md	Tue Jun 27 18:10:34 2023 +0200
     1.2 +++ b/docs/src/features.md	Tue Jun 27 18:24:28 2023 +0200
     1.3 @@ -57,6 +57,21 @@
     1.4  
     1.5  *Header file:* [string.h](api/string_8h.html)
     1.6  
     1.7 +UCX strings come in two variants: immutable (`cxstring`) and mutable (`cxmutstr`).
     1.8 +The functions of UCX are designed to work with immutable strings by default but in situations where it is necessary,
     1.9 +the API also provides alternative functions that work directly with mutable strings.
    1.10 +Functions that change a string in-place are, of course, only accepting mutable strings.
    1.11 +
    1.12 +When you are using UCX functions, or defining your own functions, you are sometimes facing the "problem",
    1.13 +that the function only accepts arguments of type `cxstring` but you only have a `cxmutstr` at hand.
    1.14 +In this case you _should not_ introduce a wrapper function that accepts the `cxmutstr`,
    1.15 +but instead you should use the `cx_strcast()` function to cast the argument to the correct type.
    1.16 +
    1.17 +In general, UCX strings are **not** necessarily zero-terminated. If a function guarantees to return zero-terminated
    1.18 +string, it is explicitly mentioned in the documentation of the respective function.
    1.19 +As a rule of thumb, you _should not_ pass the strings of a UCX string structure to another API without explicitly
    1.20 +ensuring that the string is zero-terminated.
    1.21 +
    1.22  ## Buffer
    1.23  
    1.24  *Header file:* [buffer.h](api/buffer_8h.html)