docs/Writerside/topics/string.h.md

# String

<warning>
Outdated - Rewrite!
</warning>

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.

## Undocumented Symbols (TODO)
### cx_mutstr
### cx_mutstrn
### cx_str
### cx_strcasecmp
### cx_strcasecmp_p
### cx_strcaseprefix
### cx_strcasesuffix
### cx_strcat_ma
### cx_strchr
### cx_strchr_m
### cx_strcmp
### cx_strcmp_p
### cx_strdup_a_
### cx_strfree
### cx_strfree_a
### cx_strlen
### cx_strlower
### cx_strn
### cx_strprefix
### cx_strrchr
### cx_strrchr_m
### cx_strreplacen_a
### cx_strsplit
### cx_strsplit_a
### cx_strsplit_m
### cx_strsplit_ma
### cx_strstr
### cx_strstr_m
### cx_strstr_sbo_size
### cx_strsubs
### cx_strsubsl
### cx_strsubsl_m
### cx_strsubs_m
### cx_strsuffix
### cx_strtod_lc_
### cx_strtof_lc_
### cx_strtoi16_lc_
### cx_strtoi32_lc_
### cx_strtoi64_lc_
### cx_strtoi8_lc_
### cx_strtoi_lc_
### cx_strtok_
### cx_strtok_delim
### cx_strtok_next
### cx_strtok_next_m
### cx_strtol_lc_
### cx_strtoll_lc_
### cx_strtos_lc_
### cx_strtou16_lc_
### cx_strtou32_lc_
### cx_strtou64_lc_
### cx_strtou8_lc_
### cx_strtou_lc_
### cx_strtoul_lc_
### cx_strtoull_lc_
### cx_strtous_lc_
### cx_strtouz_lc_
### cx_strtoz_lc_
### cx_strtrim
### cx_strtrim_m
### cx_strupper