Mercurial > hg > ucx / file diff

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/Writerside/topics/string.h.md	Tue Feb 11 19:55:32 2025 +0100
@@ -0,0 +1,106 @@
+# 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.
+
+## Basics
+
+### cx_mutstr
+### cx_mutstrn
+### cx_str
+### cx_strn
+### cx_strcast
+### cx_strfree
+### cx_strfree_a
+### cx_strdup
+### cx_strdup_a
+### cx_strlen
+### cx_strtrim
+### cx_strtrim_m
+### cx_strlower
+### cx_strupper
+
+## Comparison
+
+### cx_strcmp
+### cx_strcmp_p
+### cx_strcasecmp
+### cx_strcasecmp_p
+### cx_strprefix
+### cx_strsuffix
+### cx_strcaseprefix
+### cx_strcasesuffix
+
+## Concatenation
+
+### cx_strcat_ma
+
+## Find Characters and Substrings
+
+### cx_strchr
+### cx_strchr_m
+### cx_strrchr
+### cx_strrchr_m
+### cx_strstr
+### cx_strstr_m
+### cx_strsubs
+### cx_strsubsl
+### cx_strsubsl_m
+### cx_strsubs_m
+
+## Replace Substrings
+
+### cx_strreplacen_a
+
+## Basic Splitting
+
+### cx_strsplit
+### cx_strsplit_a
+### cx_strsplit_m
+### cx_strsplit_ma
+
+## Complex Tokenization
+
+### cx_strtok_
+### cx_strtok_delim
+### cx_strtok_next
+### cx_strtok_next_m
+
+## Conversion to Numbers
+
+### cx_strtod_lc_
+### cx_strtof_lc_
+### cx_strtoi16_lc_
+### cx_strtoi32_lc_
+### cx_strtoi64_lc_
+### cx_strtoi8_lc_
+### cx_strtoi_lc_
+### 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