docs/Writerside/topics/string.h.md

# String

UCX strings store character arrays together with a length and come in two variants: immutable (`cxstring`) and mutable (`cxmutstr`).

In general, UCX strings are *not* necessarily zero-terminated.
If a function guarantees to return a zero-terminated string, it is explicitly mentioned in the documentation.
As a rule of thumb, you _should not_ pass a character array of a UCX string structure to another API without explicitly
ensuring that the string is zero-terminated.

## Basics

The following listing shows basic string functions.

> To simplify documentation, we introduce the pseudo-type `AnyStr` with the meaning that
> any UCX string and any C string are supported.
> The implementation is actually hidden behind a macro which uses `cx_strcast()` to guarantee compatibility.
> Similarly, we introduce `UcxStr` with the meaning that it is either a `cxstring` or a `cxmutstr`,
> created by `cx_strcast_m()`.
{style="note"}

```C
#include <cx/string.h>

struct cx_string_s {const char *ptr; size_t length;};

struct cx_mutstr_s {char *ptr; size_t length;};

typedef struct cx_string_s cxstring;

typedef struct cx_mutstr_s cxmutstr;

cxstring cx_str(const char *cstring);

cxstring cx_strn(const char *cstring, size_t length);

cxmutstr cx_mutstr(char *cstring);

cxmutstr cx_mutstrn(char *cstring, size_t length);

cxmutstr cx_strdup(AnyStr string);

cxmutstr cx_strdup_a(const CxAllocator *allocator, AnyStr string);

int cx_strcpy(cxmutstr *dest, AnyStr source);

int cx_strcpy_a(const CxAllocator *allocator,
        cxmutstr *dest, AnyStr source);

void cx_strfree(cxmutstr *str);

void cx_strfree_a(const CxAllocator *alloc, cxmutstr *str);


#define CX_NULLSTR       cx_mutstr(NULL)
#define CX_SFMT(s)       (int) (s).length, (s).ptr
#define CX_PRIstr        ".*s"
#define cx_strcast(s)    // converts any string to cxstring
#define cx_strcast_m(s)  // converts any string to a UcxStr
```

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()` (except for `NULL` in which case the length is set to zero).
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 allocator](allocator.h.md#default-allocator).

The functions `cx_strcpy_a()` and `cx_strcpy()` copy the contents of the `source` string to the `dest` string
and also guarantee zero-termination of the resulting string.
The memory in `dest` is either freshly allocated or re-allocated to fit the size of the string plus the terminator.

Allocated strings always have the 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 use a UCX string in a `printf`-like function, you can use the macro `CX_PRIstr` for the format specifier,
and the `CX_SFMT(s)` macro to expand the arguments.

The macros `cx_strcast()` and `cx_strcast_m()` take any supported string (`AnyStr`) and convert it either to a `cxstring` or a `cxmutstr`.
While `cx_strcast()` _always_ converts to a `cxstring`, `cx_strcast_m()` decides depending on the constness of the string to return either a `cxstring` or a `cxmutstr`.
You should rarely need those macros in your code, as most UCX functions are already implemented behind macros that do the conversions for you.

> When you want to convert a string _literal_ into a UCX string, you can also use the `cx_str()` function.
> With optimizations turned on, this function gets inlined and optimizes the call to `strlen()` out, giving
> you a `cxstring` structure at zero cost with the length calculated at compile-time.

## Comparison

```C
#include <cx/string.h>

int cx_strcmp(AnyStr s1, AnyStr s2);

int cx_strcmp_p(const void *s1, const void *s2);

int cx_strcasecmp_p(const void *s1, const void *s2);

bool cx_strprefix(AnyStr string, AnyStr prefix);

bool cx_strsuffix(AnyStr string, AnyStr suffix);

int cx_strcasecmp(AnyStr s1, AnyStr s2);

bool cx_strcaseprefix(AnyStr string, AnyStr prefix);

bool cx_strcasesuffix(AnyStr string, AnyStr suffix);
```

The `cx_strcmp()` function compares two strings lexicographically
and returns an integer greater than, equal to, or less than 0, if `s1` is greater than, equal to, or less than `s2`, respectively.

The `cx_strcmp_p()` function takes pointers to UCX strings (i.e., only to `cxstring` and `cxmutstr`), and the signature is compatible with `cx_compare_func`.
Use this as a compare function for lists or other data structures.

The functions `cx_strprefix()` and `cx_strsuffic()` check if `string` starts with `prefix` or ends with `suffix`, respectively.

The functions `cx_strcasecmp()`, `cx_strcasecmp_p()`, `cx_strcaseprefix()`, and `cx_strcasesuffix()` are equivalent,
except that they compare the strings case-insensitive.

> In the current version of UCX, case-insensitive comparisons are only guaranteed to work with ASCII characters.
{style="note"}

## Concatenation

```C
#include <cx/string.h>

cxmutstr cx_strcat(cxmutstr str, size_t count, ... );

cxmutstr cx_strcat_a(const CxAllocator *allocator,
        cxmutstr str, size_t count, ... );

size_t cx_strlen(size_t count, ...);
```

The `cx_strcat_a()` function takes `count` UCX strings (`cxstring` or `cxmutstr` - not pointers!),
reallocates the memory in `str` for a concatenation of those strings _with a single allocation_,
and appends the contents of the strings to `str`.
`cx_strcat()` is equivalent, except that it uses the [default allocator](allocator.h.md#default-allocator).

When there is no `str` where the other strings shall be appended to, you can pass `CX_NULLSTR` as the first argument.
In that case, a completely new string is allocated.

Example usage:
```C
cxmutstr str = cx_strcat(
        CX_NULLSTR, 2,
        cx_str("Hello, "),
        cx_str("World!")
);
```

The function `cx_strlen()` sums the length of the specified strings.

> There is no reason to use `cx_strlen()` for a single UCX string.
> You can access the `length` field of the structure directly. 

> You can mix `cxstring` and `cxmutstr` in the variadic arguments without the need of `cx_strcast()`.

## Find Characters and Substrings

```C
#include <cx/string.h>

char cx_strat(AnyStr str, off_t index);

UcxStr cx_strchr(AnyStr string, int chr);

UcxStr cx_strrchr(AnyStr string, int chr);

UcxStr cx_strstr(AnyStr string, AnyStr search);

UcxStr cx_strsubs(AnyStr string, size_t start);

UcxStr cx_strsubsl(AnyStr string, size_t start, size_t length);

UcxStr cx_strtrim(AnyStr string);
```

The function `cx_strat()` returns the character at the specified `index`.
When the `index` is negative, the characters are counted from the end of the string.
When the `index` is out of bounds, the zero-character is returned.

The functions `cx_strchr()`, `cx_strrchr()`, and `cx_strstr()`, behave like their stdlib counterparts.

The function `cx_strsubs()` returns the substring starting at the specified `start` index,
and `cx_strsubsl()` returns a substring with at most `length` bytes.

The function `cx_strtrim()` returns the substring that results when removing all leading and trailing
whitespace characters.

All functions with the `_m` suffix behave exactly the same as their counterparts without `_m` suffix,
except that they operate on a `cxmustr`.
In _both_ variants the functions return a view into the given `string`
and thus the returned strings must never be passed to `cx_strfree()`.

## Replace Substrings

```C
#include <cx/string.h>

cxmutstr cx_strreplace(AnyStr str,
        AnyStr search, AnyStr replacement);

cxmutstr cx_strreplace_a(const CxAllocator *allocator, AnyStr str,
        AnyStr search, AnyStr replacement);

cxmutstr cx_strreplacen(AnyStr str,
        AnyStr search, AnyStr replacement, size_t replmax);

cxmutstr cx_strreplacen_a(const CxAllocator *allocator, AnyStr str,
        AnyStr search, AnyStr replacement, size_t replmax);
```

The function `cx_strreplace()` allocates a new string which will contain a copy of `str`
where every occurrence of `search` is replaced with `replacement`.
The new string is guaranteed to be zero-terminated even if `str` is not.

The function `cx_strreplace_a()` uses the specified `allocator` to allocate the new string.

The functions `cx_strreplacen()` and `cx_strreplacen_a()` are equivalent, except that they stop
after `replmax` number of replacements.

## Basic Splitting

```C
#include <cx/string.h>

size_t cx_strsplit(UcxStr string, AnyStr delim,
        size_t limit, UcxStr *output);

size_t cx_strsplit_a(const CxAllocator *allocator,
        UcxStr string, AnyStr delim,
        size_t limit, UcxStr **output);
```

The `cx_strsplit()` function splits the input `string` using the specified delimiter `delim`
and writes the substrings into the pre-allocated `output` array.
The maximum number of resulting strings can be specified with `limit`.
That means, at most `limit-1` splits are performed.
The function returns the actual number of items written to `output`.

On the other hand, `cx_strsplit_a()` uses the specified `allocator` to allocate the output array
and writes the pointer to the allocated memory to `output`.

> The type of the `UcxStr` must the same for `string` and `output` (i.e., either both `cxstring` or both `cxmutstr`). 
> {style="note"}

> The `allocator` in `cx_strsplit_a()` is _only_ used to allocate the output array.
> The strings will always point into the original `string`,
> and you need to use `cx_strdup()` or `cx_strdup_a()` if you want copies or zero-terminated strings after performing the split.  
{style="note"}

## Complex Tokenization

```C
#include <cx/string.h>

CxStrtokCtx cx_strtok(AnyStr str, AnyStr delim, size_t limit);

void cx_strtok_delim(CxStrtokCtx *ctx,
        const cxstring *delim, size_t count);

bool cx_strtok_next(CxStrtokCtx *ctx, UcxStr* token);
```

You can tokenize a string by creating a _tokenization_ context with `cx_strtok()`
and calling `cx_strtok_next()` as long as it returns `true`.

The tokenization context is initialized with the string `str` to tokenize,
one delimiter `delim`, and a `limit` for the maximum number of tokens.
When `limit` is reached, the remaining part of `str` is returned as one single token.

You can add additional delimiters to the context by calling `cx_strtok_delim()` and
specifying an array of delimiters to use.

> Regardless of how the context was initialized, you can use `cx_strtok_next()`
> with pointers to `cxstring` or `cxmutstr`. However, keep in mind that modifying
> characters in a `cxmutstr` has only defined behavior, when the
> underlying `str` is also a `cxmutstr` that was not initalized with constant memory.

### Example

```C
#include <cx/string.h>

cxstring str = cx_str("an,arbitrarily;||separated;string");

// create the context
CxStrtokCtx ctx = cx_strtok(str, ",", 10);

// add two more delimters
cxstring delim_more[2] = {cx_str("||"), cx_str(";")};
cx_strtok_delim(&ctx, delim_more, 2);

// iterate over the tokens
cxstring tok;
while(cx_strtok_next(&ctx, &tok)) {
    // to something with the tokens
    // be aware that tok is NOT zero-terminated!
}
```

## Conversion to Numbers

For each integer type, as well as `float` and `double`, there are functions to convert a UCX string to a value of those types.

Integer conversion comes in two flavors:
```C
int cx_strtoi(AnyStr str, int *output, int base);

int cx_strtoi_lc(AnyStr str, int *output, int base,
        const char *groupsep);
```

The basic variant takes a string of any UCX string type, a pointer to the `output` integer, and the `base` (one of 2, 8, 10, or 16).
Conversion is attempted with respect to the specified `base` and respects possible special notations for that base.
Hexadecimal numbers may be prefixed with `0x`, `x`, or `#`, and binary numbers may be prefixed with `0b` or `b`.

The `_lc` versions of the integer conversion functions are equivalent, except that they allow the specification of an
array of group separator chars, each of which is simply ignored during conversion.
The default group separator for the basic version is a comma `,`.

The signature for the floating-point conversions is quite similar:
```C
int cx_strtof(AnyStr str, float *output);

int cx_strtof_lc(AnyStr str, float *output,
        char decsep, const char *groupsep);
```

The two differences are that the floating-point versions do not support different bases,
and the `_lc` variant allows specifying not only an array of group separators,
but also the character used for the decimal separator.

In the basic variant, the group separator is again a comma `,`, and the decimal separator is a dot `.`.

> The floating-point conversions of UCX 3.1 do not achieve the same precision as standard library implementations
> which usually use more sophisticated algorithms.
> The precision might increase in future UCX releases,
> but until then be aware of slight inaccuracies, in particular when working with `double`.
{style="warning"}

> The UCX string to number conversions are intentionally not considering any locale settings
> and are therefore independent of any global state.
{style="note"}

<seealso>
<category ref="apidoc">
<a href="https://ucx.sourceforge.io/api/string_8h.html">string.h</a>
</category>
</seealso>