GNU libunistring

https://www.gnu.org/software/libunistring/manual/
Admin
GNU libunistring is a C library that provides functions for manipulating Unicode strings and C...
Tokens:173,980
Snippets:1,131
Trust Score:10
Update:5 days ago
Show doc for...
Tokens:
Raw
### u32_startswith

Source: https://www.gnu.org/software/libunistring/manual/libunistring.html

Checks if a Unicode string starts with a given prefix.

```APIDOC
## u32_startswith

### Description
Checks if a Unicode string starts with a given prefix.

### Function
`u32_startswith`

### Parameters
- `str` (const uint32_t*) - The string to check.
- `prefix` (const uint32_t*) - The prefix to look for.

### Return Value
Returns true if `str` starts with `prefix`, false otherwise.
```

--------------------------------

### u8_startswith

Source: https://www.gnu.org/software/libunistring/manual/libunistring.html

Checks if a UTF-8 string starts with a given prefix.

```APIDOC
## u8_startswith

### Description
Checks if a UTF-8 string starts with a given prefix.

### Function Signature
`bool u8_startswith (const uint8_t *str, const uint8_t *prefix);`

### Parameters
- `str` (const uint8_t *) - Input string.
- `prefix` (const uint8_t *) - Prefix to check.

### Return Value
`true` if `str` starts with `prefix`, `false` otherwise.
```

--------------------------------

### u8_startswith, u16_startswith, u32_startswith

Source: https://www.gnu.org/software/libunistring/manual/libunistring.html

Tests whether a NUL terminated Unicode string starts with a given prefix.

```APIDOC
## u8_startswith, u16_startswith, u32_startswith

### Description
Tests whether a NUL terminated Unicode string starts with a given prefix.

### Functions
- `bool u8_startswith(const uint8_t *str, const uint8_t *prefix)`
- `bool u16_startswith(const uint16_t *str, const uint16_t *prefix)`
- `bool u32_startswith(const uint32_t *str, const uint32_t *prefix)`

### Parameters
- `str` (const uint8_t*/uint16_t*/uint32_t*) - Required - Pointer to the NUL terminated Unicode string to test.
- `prefix` (const uint8_t*/uint16_t*/uint32_t*) - Required - Pointer to the NUL terminated Unicode prefix to check for.

### Return Value
- Returns `true` if `str` starts with `prefix`, otherwise `false`.
```

--------------------------------

### u16_startswith

Source: https://www.gnu.org/software/libunistring/manual/libunistring.html

Checks if a UTF-16 string starts with a given prefix. This function is part of the searching for a substring operations.

```APIDOC
## u16_startswith

### Description
Checks if a UTF-16 string starts with a given prefix.

### Header
unistr.h

### Parameters
- **str** (const uint16_t *) - Required - String to check
- **prefix** (const uint16_t *) - Required - Prefix to look for

### Return Value
Returns true if the string starts with the prefix, false otherwise.

```

--------------------------------

### uc_all_scripts

Source: https://www.gnu.org/software/libunistring/manual/libunistring.html

Get the list of all scripts. Stores a pointer to an array of all scripts in *scripts and the length of this array in *count.

```APIDOC
## uc_all_scripts

### Description
Get the list of all scripts. Stores a pointer to an array of all scripts in *scripts and the length of this array in *count.

### Function Signature
`void` **uc_all_scripts** `(const uc_script_t **scripts, size_t *count)`

### Parameters
- **scripts** (const uc_script_t **) - Required - Output parameter: pointer to an array of all scripts.
- **count** (size_t *) - Required - Output parameter: length of the array.

### Return Value
- **void** - No return value.

```

--------------------------------

### u32_grapheme_prev

Source: https://www.gnu.org/software/libunistring/manual/libunistring.html

Returns the start of the grapheme cluster preceding s, or start if no grapheme cluster break is encountered before it. Returns NULL if and only if s == start.

```APIDOC
## u32_grapheme_prev

### Description
Returns the start of the grapheme cluster preceding s, or start if no grapheme cluster break is encountered before it. Returns NULL if and only if s == start.

### Function Signature
const uint32_t *u32_grapheme_prev(const uint32_t *s, const uint32_t *start)

### Parameters
- **s** (const uint32_t *) - Required - Pointer to the current position in the string.
- **start** (const uint32_t *) - Required - Pointer to the start of the string.

### Return Value
- (const uint32_t *) - Pointer to the start of the preceding grapheme cluster, or start if no break is found, or NULL if s == start.

### Notes
- Does not handle cases where characters outside the range between start and s are needed to determine the boundary (e.g., Indic syllables or emojis). Use u32_grapheme_breaks for such cases.
- Works only on well-formed Unicode strings.
```

--------------------------------

### u8_grapheme_prev

Source: https://www.gnu.org/software/libunistring/manual/libunistring.html

Returns the start of the grapheme cluster preceding s, or start if no grapheme cluster break is encountered before it. Returns NULL if and only if s == start.

```APIDOC
## u8_grapheme_prev

### Description
Returns the start of the grapheme cluster preceding s, or start if no grapheme cluster break is encountered before it. Returns NULL if and only if s == start.

### Function Signature
const uint8_t *u8_grapheme_prev(const uint8_t *s, const uint8_t *start)

### Parameters
- **s** (const uint8_t *) - Required - Pointer to the current position in the string.
- **start** (const uint8_t *) - Required - Pointer to the start of the string.

### Return Value
- (const uint8_t *) - Pointer to the start of the preceding grapheme cluster, or start if no break is found, or NULL if s == start.

### Notes
- Does not handle cases where characters outside the range between start and s are needed to determine the boundary (e.g., Indic syllables or emojis). Use u8_grapheme_breaks for such cases.
- Works only on well-formed Unicode strings.
```

--------------------------------

### u16_grapheme_prev

Source: https://www.gnu.org/software/libunistring/manual/libunistring.html

Returns the start of the grapheme cluster preceding s, or start if no grapheme cluster break is encountered before it. Returns NULL if and only if s == start.

```APIDOC
## u16_grapheme_prev

### Description
Returns the start of the grapheme cluster preceding s, or start if no grapheme cluster break is encountered before it. Returns NULL if and only if s == start.

### Function Signature
const uint16_t *u16_grapheme_prev(const uint16_t *s, const uint16_t *start)

### Parameters
- **s** (const uint16_t *) - Required - Pointer to the current position in the string.
- **start** (const uint16_t *) - Required - Pointer to the start of the string.

### Return Value
- (const uint16_t *) - Pointer to the start of the preceding grapheme cluster, or start if no break is found, or NULL if s == start.

### Notes
- Does not handle cases where characters outside the range between start and s are needed to determine the boundary (e.g., Indic syllables or emojis). Use u16_grapheme_breaks for such cases.
- Works only on well-formed Unicode strings.
```

--------------------------------

### Output with Unicode strings <unistdio.h>

Source: https://www.gnu.org/software/libunistring/manual/libunistring.html

Provides functions for formatted output with Unicode strings.

```APIDOC
## Output with Unicode strings <unistdio.h>

### Description
Provides functions for formatted output with Unicode strings.

### Functions
- **u8_printf** - Print formatted output to stdout using UTF-8.
- **u16_printf** - Print formatted output to stdout using UTF-16.
- **u32_printf** - Print formatted output to stdout using UTF-32.
- **u8_fprintf** - Print formatted output to a stream using UTF-8.
- **u16_fprintf** - Print formatted output to a stream using UTF-16.
- **u32_fprintf** - Print formatted output to a stream using UTF-32.
- **u8_sprintf** - Format a string into a buffer using UTF-8.
- **u16_sprintf** - Format a string into a buffer using UTF-16.
- **u32_sprintf** - Format a string into a buffer using UTF-32.
```

--------------------------------

### u32_u32_asprintf

Source: https://www.gnu.org/software/libunistring/manual/libunistring.html

Formats a string with allocation.

```APIDOC
## u32_u32_asprintf

### Description
Formats a string with allocation.

### Function
`u32_u32_asprintf`

### Parameters
- `resultp` (uint32_t**) - Output buffer.
- `format` (const uint32_t*) - Format string.
- `...` - Arguments.

### Return Value
Returns the number of characters written, or -1 on error.
```

--------------------------------

### uc_is_property_id_start

Source: https://www.gnu.org/software/libunistring/manual/libunistring.html

Checks whether a Unicode character has the ID Start property.

```APIDOC
## uc_is_property_id_start

### Description
Checks whether a Unicode character has the ID Start property.

### Function Signature
`bool uc_is_property_id_start (ucs4_t uc)`

### Parameters
- `uc` (ucs4_t) - The Unicode character to test.

### Return Value
Returns `true` if the character has the ID Start property, `false` otherwise.

```

--------------------------------

### Conventions

Source: https://www.gnu.org/software/libunistring/manual/libunistring.html

Explains the conventions valid throughout the libunistring library, including type meanings, function prefixes, parameter conventions, error handling, and memory management for functions that return strings.

```APIDOC
## Conventions

### Description
This section explains conventions valid throughout the libunistring library.

### Type Conventions
- `char *` denotes C strings in locale encoding.
- `uint8_t *` denotes UTF-8 strings; units are bytes.
- `uint16_t *` denotes UTF-16 strings, without byte order mark; units are 2-byte words.
- `uint32_t *` denotes UTF-32 strings, without byte order mark; units are 4-byte words.
- Argument pairs `(s, n)` denote a string `s[0..n-1]` with exactly n units.

### Function Prefixes
- Functions with prefix `ulc_` operate on C strings in locale encoding.
- Functions with prefix `u8_` operate on UTF-8 strings.
- Functions with prefix `u16_` operate on UTF-16 strings.
- Functions with prefix `u32_` operate on UTF-32 strings.
- For every function with prefix `u8_`, there is a corresponding function with prefix `u16_` and `u32_`. Their descriptions are analogous; only the UTF-8 version is described for brevity.
- A declaration with a variable n denotes the three concrete declarations with n = 8, 16, 32.
- All parameters starting with `str` and parameters of functions starting with `u8_str`/`u16_str`/`u32_str` denote a NUL terminated string.

### Error Handling
- Error values are always returned through the `errno` variable, usually with a return value that indicates the presence of an error (NULL for functions that return a pointer, or -1 for functions that return an `int`).

### Memory Management for Functions Returning Strings
Functions returning a string result take a `(resultbuf, lengthp)` argument pair.
- If `resultbuf` is not NULL and the result fits into `*lengthp` units, it is put in `resultbuf`, and `resultbuf` is returned.
- Otherwise, a freshly allocated string is returned.
- In both cases, `*lengthp` is set to the length (number of units) of the returned string.
- In case of error, NULL is returned and `errno` is set.

#### Usage Steps
1. Decide whether to accept the overhead of a `malloc` invocation even for a small-sized result. If yes, pass NULL as `resultbuf`. If no, allocate an array of units on the stack (typically between 50 and 4000 bytes), pass this array as `resultbuf`, and initialize `*lengthp` to the number of units of this array.
2. Upon return, look at the return value: NULL means an error; look at the value of `errno` in this case. Otherwise, the return value is the result, with `*lengthp` units. Note that the function has not added an extra NUL character at the end.
3. Finally, do memory management. The result was `malloc`-allocated if it is `!= NULL` and `!= resultbuf`.
```

--------------------------------

### uc_is_property_id_compat_math_start

Source: https://www.gnu.org/software/libunistring/manual/libunistring.html

Checks whether a Unicode character has the ID Compat Math Start property.

```APIDOC
## uc_is_property_id_compat_math_start

### Description
Checks whether a Unicode character has the ID Compat Math Start property.

### Function Signature
`bool uc_is_property_id_compat_math_start (ucs4_t uc)`

### Parameters
- `uc` (ucs4_t) - The Unicode character to test.

### Return Value
Returns `true` if the character has the ID Compat Math Start property, `false` otherwise.

```

--------------------------------

### u8_asprintf

Source: https://www.gnu.org/software/libunistring/manual/libunistring.html

Formats a string with allocation.

```APIDOC
## u8_asprintf

### Description
Formats a string with allocation.

### Function
`u8_asprintf`

### Parameters
- `resultp` (uint8_t**) - Output buffer.
- `format` (const uint8_t*) - Format string.
- `...` - Arguments.

### Return Value
Returns the number of characters written, or -1 on error.
```

--------------------------------

### u32_totitle

Source: https://www.gnu.org/software/libunistring/manual/libunistring.html

Converts a string to titlecase.

```APIDOC
## u32_totitle

### Description
Converts a string to titlecase.

### Function
`u32_totitle`

### Parameters
- `s` (const uint32_t*) - Input string.
- `n` (size_t) - Length of string.
- `resultbuf` (uint32_t**) - Output buffer.
- `lengthp` (size_t*) - Output length.

### Return Value
Returns the titlecase string.
```

--------------------------------

### u32_sprintf

Source: https://www.gnu.org/software/libunistring/manual/libunistring.html

Formats a string into a buffer.

```APIDOC
## u32_sprintf

### Description
Formats a string into a buffer.

### Function
`u32_sprintf`

### Parameters
- `s` (uint32_t*) - Output buffer.
- `format` (const uint32_t*) - Format string.
- `...` - Arguments.

### Return Value
Returns the number of characters written.
```

--------------------------------

### uc_all_blocks

Source: https://www.gnu.org/software/libunistring/manual/libunistring.html

Get the list of all blocks. Stores a pointer to an array of all blocks in *blocks and the length of this array in *count.

```APIDOC
## uc_all_blocks

### Description
Get the list of all blocks. Stores a pointer to an array of all blocks in *blocks and the length of this array in *count.

### Function Signature
`void` **uc_all_blocks** `(const uc_block_t **blocks, size_t *count)`

### Parameters
- **blocks** (const uc_block_t **) - Required - Output parameter: pointer to an array of all blocks.
- **count** (size_t *) - Required - Output parameter: length of the array.

### Return Value
- **void** - No return value.

```

--------------------------------

### u32_u32_sprintf

Source: https://www.gnu.org/software/libunistring/manual/libunistring.html

Formats a string into a buffer.

```APIDOC
## u32_u32_sprintf

### Description
Formats a string into a buffer.

### Function
`u32_u32_sprintf`

### Parameters
- `s` (uint32_t*) - Output buffer.
- `format` (const uint32_t*) - Format string.
- `...` - Arguments.

### Return Value
Returns the number of characters written.
```

--------------------------------

### u32_grapheme_next

Source: https://www.gnu.org/software/libunistring/manual/libunistring.html

Returns the start of the next grapheme cluster following s, or end if no grapheme cluster break is encountered before it. Returns NULL if and only if s == end.

```APIDOC
## u32_grapheme_next

### Description
Returns the start of the next grapheme cluster following s, or end if no grapheme cluster break is encountered before it. Returns NULL if and only if s == end.

### Function Signature
const uint32_t *u32_grapheme_next(const uint32_t *s, const uint32_t *end)

### Parameters
- **s** (const uint32_t *) - Required - Pointer to the start of the string.
- **end** (const uint32_t *) - Required - Pointer to the end of the string.

### Return Value
- (const uint32_t *) - Pointer to the start of the next grapheme cluster, or end if no break is found, or NULL if s == end.

### Notes
- Does not handle cases where characters outside the range between s and end are needed to determine the boundary (e.g., Indic syllables or emojis). Use u32_grapheme_breaks for such cases.
```

--------------------------------

### Elementary Unicode string functions <unistr.h>

Source: https://www.gnu.org/software/libunistring/manual/libunistring.html

Provides functions for basic operations on Unicode strings, including checks, conversions, copying, comparing, searching, and counting characters.

```APIDOC
## Elementary Unicode string functions <unistr.h>

### Description
Provides functions for basic operations on Unicode strings, including checks, conversions, copying, comparing, searching, and counting characters.

### Functions
- **u8_check** - Check for invalid UTF-8 sequences.
- **u16_check** - Check for invalid UTF-16 sequences.
- **u32_check** - Check for invalid UTF-32 sequences.
- **u8_conv_from_encoding** - Convert from a given encoding to UTF-8.
- **u16_conv_from_encoding** - Convert from a given encoding to UTF-16.
- **u32_conv_from_encoding** - Convert from a given encoding to UTF-32.
- **u8_conv_to_encoding** - Convert from UTF-8 to a given encoding.
- **u16_conv_to_encoding** - Convert from UTF-16 to a given encoding.
- **u32_conv_to_encoding** - Convert from UTF-32 to a given encoding.
- **u8_next** - Iterate over a UTF-8 string.
- **u16_next** - Iterate over a UTF-16 string.
- **u32_next** - Iterate over a UTF-32 string.
- **u8_mbsnlen** - Count characters in a UTF-8 string.
- **u16_mbsnlen** - Count characters in a UTF-16 string.
- **u32_mbsnlen** - Count characters in a UTF-32 string.
- **u8_cpy** - Copy a UTF-8 string.
- **u16_cpy** - Copy a UTF-16 string.
- **u32_cpy** - Copy a UTF-32 string.
- **u8_cmp** - Compare two UTF-8 strings.
- **u16_cmp** - Compare two UTF-16 strings.
- **u32_cmp** - Compare two UTF-32 strings.
- **u8_strchr** - Search for a character in a UTF-8 string.
- **u16_strchr** - Search for a character in a UTF-16 string.
- **u32_strchr** - Search for a character in a UTF-32 string.
- **u8_strlen** - Get length of a NUL-terminated UTF-8 string.
- **u16_strlen** - Get length of a NUL-terminated UTF-16 string.
- **u32_strlen** - Get length of a NUL-terminated UTF-32 string.
- **u8_strcpy** - Copy a NUL-terminated UTF-8 string.
- **u16_strcpy** - Copy a NUL-terminated UTF-16 string.
- **u32_strcpy** - Copy a NUL-terminated UTF-32 string.
- **u8_strcmp** - Compare two NUL-terminated UTF-8 strings.
- **u16_strcmp** - Compare two NUL-terminated UTF-16 strings.
- **u32_strcmp** - Compare two NUL-terminated UTF-32 strings.
- **u8_strdup** - Duplicate a NUL-terminated UTF-8 string.
- **u16_strdup** - Duplicate a NUL-terminated UTF-16 string.
- **u32_strdup** - Duplicate a NUL-terminated UTF-32 string.
- **u8_strstr** - Search for a substring in a NUL-terminated UTF-8 string.
- **u16_strstr** - Search for a substring in a NUL-terminated UTF-16 string.
- **u32_strstr** - Search for a substring in a NUL-terminated UTF-32 string.
- **u8_strtok** - Tokenize a NUL-terminated UTF-8 string.
- **u16_strtok** - Tokenize a NUL-terminated UTF-16 string.
- **u32_strtok** - Tokenize a NUL-terminated UTF-32 string.
```

--------------------------------

### u8_cpy_alloc, u16_cpy_alloc, u32_cpy_alloc

Source: https://www.gnu.org/software/libunistring/manual/libunistring.html

Makes a freshly allocated copy of a Unicode string of length n.

```APIDOC
## u8_cpy_alloc, u16_cpy_alloc, u32_cpy_alloc

### Description
Makes a freshly allocated copy of the Unicode string `s`, of length `n`.

### Function Signatures
- `uint8_t *u8_cpy_alloc(const uint8_t *s, size_t n)`
- `uint16_t *u16_cpy_alloc(const uint16_t *s, size_t n)`
- `uint32_t *u32_cpy_alloc(const uint32_t *s, size_t n)`

### Parameters
- `s` (const uint8_t*/uint16_t*/uint32_t*) - Required - Pointer to the source Unicode string.
- `n` (size_t) - Required - Length of the string to copy.

### Return Value
Returns a freshly allocated copy of `s` of length `n`.
```

--------------------------------

### u16_grapheme_next

Source: https://www.gnu.org/software/libunistring/manual/libunistring.html

Returns the start of the next grapheme cluster following s, or end if no grapheme cluster break is encountered before it. Returns NULL if and only if s == end.

```APIDOC
## u16_grapheme_next

### Description
Returns the start of the next grapheme cluster following s, or end if no grapheme cluster break is encountered before it. Returns NULL if and only if s == end.

### Function Signature
const uint16_t *u16_grapheme_next(const uint16_t *s, const uint16_t *end)

### Parameters
- **s** (const uint16_t *) - Required - Pointer to the start of the string.
- **end** (const uint16_t *) - Required - Pointer to the end of the string.

### Return Value
- (const uint16_t *) - Pointer to the start of the next grapheme cluster, or end if no break is found, or NULL if s == end.

### Notes
- Does not handle cases where characters outside the range between s and end are needed to determine the boundary (e.g., Indic syllables or emojis). Use u16_grapheme_breaks for such cases.
```

--------------------------------

### uc_all_scripts

Source: https://www.gnu.org/software/libunistring/manual/libunistring.html

Returns a list of all Unicode scripts.

```APIDOC
## uc_all_scripts

### Description
Returns a list of all Unicode scripts.

### Function Signature
`const char *const *uc_all_scripts (void);`

### Parameters
None.

### Return Value
Pointer to an array of script names, terminated by NULL.
```

--------------------------------

### u8_grapheme_next

Source: https://www.gnu.org/software/libunistring/manual/libunistring.html

Returns the start of the next grapheme cluster following s, or end if no grapheme cluster break is encountered before it. Returns NULL if and only if s == end.

```APIDOC
## u8_grapheme_next

### Description
Returns the start of the next grapheme cluster following s, or end if no grapheme cluster break is encountered before it. Returns NULL if and only if s == end.

### Function Signature
const uint8_t *u8_grapheme_next(const uint8_t *s, const uint8_t *end)

### Parameters
- **s** (const uint8_t *) - Required - Pointer to the start of the string.
- **end** (const uint8_t *) - Required - Pointer to the end of the string.

### Return Value
- (const uint8_t *) - Pointer to the start of the next grapheme cluster, or end if no break is found, or NULL if s == end.

### Notes
- Does not handle cases where characters outside the range between s and end are needed to determine the boundary (e.g., Indic syllables or emojis). Use u8_grapheme_breaks for such cases.
```

--------------------------------

### Conversions between Unicode and encodings <uniconv.h>

Source: https://www.gnu.org/software/libunistring/manual/libunistring.html

Provides functions to convert between Unicode strings and various character encodings.

```APIDOC
## Conversions between Unicode and encodings <uniconv.h>

### Description
Provides functions to convert between Unicode strings and various character encodings.

### Functions
- **u8_conv_from_encoding** - Convert from a given encoding to UTF-8.
- **u16_conv_from_encoding** - Convert from a given encoding to UTF-16.
- **u32_conv_from_encoding** - Convert from a given encoding to UTF-32.
- **u8_conv_to_encoding** - Convert from UTF-8 to a given encoding.
- **u16_conv_to_encoding** - Convert from UTF-16 to a given encoding.
- **u32_conv_to_encoding** - Convert from UTF-32 to a given encoding.
```

--------------------------------

### u32_toupper

Source: https://www.gnu.org/software/libunistring/manual/libunistring.html

Converts a string to uppercase.

```APIDOC
## u32_toupper

### Description
Converts a string to uppercase.

### Function
`u32_toupper`

### Parameters
- `s` (const uint32_t*) - Input string.
- `n` (size_t) - Length of string.
- `resultbuf` (uint32_t**) - Output buffer.
- `lengthp` (size_t*) - Output length.

### Return Value
Returns the uppercase string.
```

--------------------------------

### u8_casing_prefixes_context

Source: https://www.gnu.org/software/libunistring/manual/libunistring.html

Returns the casing prefixes context of a string.

```APIDOC
## u8_casing_prefixes_context

### Description
Returns the casing prefixes context of a string.

### Function
`u8_casing_prefixes_context`

### Parameters
- `s` (const uint8_t*) - Input string.
- `n` (size_t) - Length of string.

### Return Value
Returns the prefixes context.
```

--------------------------------

### u8_totitle

Source: https://www.gnu.org/software/libunistring/manual/libunistring.html

Converts a UTF-8 string to titlecase.

```APIDOC
## u8_totitle

### Description
Converts a UTF-8 string to titlecase.

### Function Signature
`uint8_t *u8_totitle (const uint8_t *s, size_t n, const char *iso639_language, size_t *result_lengthp);`

### Parameters
- `s` (const uint8_t *) - Input UTF-8 string.
- `n` (size_t) - Number of bytes in `s`.
- `iso639_language` (const char *) - ISO 639 language code (optional).
- `result_lengthp` (size_t *) - Output length of the result.

### Return Value
Pointer to the titlecase string, or NULL on error.
```

--------------------------------

### u16_sprintf

Source: https://www.gnu.org/software/libunistring/manual/libunistring.html

Formats a string into a buffer. This function is part of the unistdio.h interface.

```APIDOC
## u16_sprintf

### Description
Formats a string into a buffer.

### Header
unistdio.h

### Parameters
- **s** (uint16_t *) - Required - Output buffer
- **format** (const uint16_t *) - Required - Format string
- **...** - Required - Arguments for format specifiers

### Return Value
Returns the number of characters written, or -1 on error.

```

--------------------------------

### u32_cpy_alloc

Source: https://www.gnu.org/software/libunistring/manual/libunistring.html

Copies a Unicode string with memory allocation.

```APIDOC
## u32_cpy_alloc

### Description
Copies a Unicode string with memory allocation.

### Function
`u32_cpy_alloc`

### Parameters
- `s` (const uint32_t*) - Source string.
- `n` (size_t) - Number of characters to copy.

### Return Value
Returns a newly allocated copy of the string, or NULL on memory allocation failure.
```

--------------------------------

### u32_u32_vsnprintf

Source: https://www.gnu.org/software/libunistring/manual/libunistring.html

Formats a string into a buffer with a size limit using a va_list.

```APIDOC
## u32_u32_vsnprintf

### Description
Formats a string into a buffer with a size limit using a va_list.

### Function
`u32_u32_vsnprintf`

### Parameters
- `s` (uint32_t*) - Output buffer.
- `maxlen` (size_t) - Maximum length of output.
- `format` (const uint32_t*) - Format string.
- `args` (va_list) - Arguments.

### Return Value
Returns the number of characters written, or a negative value on error.
```

--------------------------------

### Normalization forms (composition and decomposition) <uninorm.h>

Source: https://www.gnu.org/software/libunistring/manual/libunistring.html

Provides functions for Unicode normalization, including decomposition, composition, and normalization of strings.

```APIDOC
## Normalization forms (composition and decomposition) <uninorm.h>

### Description
Provides functions for Unicode normalization, including decomposition, composition, and normalization of strings.

### Functions
- **uc_decomposition** - Get the decomposition of a character.
- **uc_composition** - Get the composition of two characters.
- **u8_normalize** - Normalize a UTF-8 string.
- **u16_normalize** - Normalize a UTF-16 string.
- **u32_normalize** - Normalize a UTF-32 string.
- **u8_normcmp** - Compare two UTF-8 strings using normalization.
- **u16_normcmp** - Compare two UTF-16 strings using normalization.
- **u32_normcmp** - Compare two UTF-32 strings using normalization.
- **u8_normalize_stream** - Normalize a stream of UTF-8 characters.
- **u16_normalize_stream** - Normalize a stream of UTF-16 characters.
- **u32_normalize_stream** - Normalize a stream of UTF-32 characters.
```

--------------------------------

### Shaping and Rendering Properties

Source: https://www.gnu.org/software/libunistring/manual/libunistring.html

Functions to test properties that influence shaping and rendering.

```APIDOC
## bool uc_is_property_join_control(ucs4_t uc)

### Description
Tests whether the Unicode character uc has the join_control property.

### Parameters
- **uc** (ucs4_t) - Required - The Unicode character to test.

### Returns
- **bool** - True if the character has the property, false otherwise.

## bool uc_is_property_grapheme_base(ucs4_t uc)

### Description
Tests whether the Unicode character uc has the grapheme_base property.

### Parameters
- **uc** (ucs4_t) - Required - The Unicode character to test.

### Returns
- **bool** - True if the character has the property, false otherwise.

## bool uc_is_property_grapheme_extend(ucs4_t uc)

### Description
Tests whether the Unicode character uc has the grapheme_extend property.

### Parameters
- **uc** (ucs4_t) - Required - The Unicode character to test.

### Returns
- **bool** - True if the character has the property, false otherwise.

## bool uc_is_property_other_grapheme_extend(ucs4_t uc)

### Description
Tests whether the Unicode character uc has the other_grapheme_extend property.

### Parameters
- **uc** (ucs4_t) - Required - The Unicode character to test.

### Returns
- **bool** - True if the character has the property, false otherwise.

## bool uc_is_property_grapheme_link(ucs4_t uc)

### Description
Tests whether the Unicode character uc has the grapheme_link property.

### Parameters
- **uc** (ucs4_t) - Required - The Unicode character to test.

### Returns
- **bool** - True if the character has the property, false otherwise.

## bool uc_is_property_modifier_combining_mark(ucs4_t uc)

### Description
Tests whether the Unicode character uc has the modifier_combining_mark property.

### Parameters
- **uc** (ucs4_t) - Required - The Unicode character to test.

### Returns
- **bool** - True if the character has the property, false otherwise.
```

--------------------------------

### uc_all_blocks

Source: https://www.gnu.org/software/libunistring/manual/libunistring.html

Returns a list of all Unicode blocks.

```APIDOC
## uc_all_blocks

### Description
Returns a list of all Unicode blocks.

### Function Signature
`const uc_block_t *uc_all_blocks (void);`

### Parameters
None.

### Return Value
Pointer to an array of `uc_block_t` structures, terminated by a null block.
```

--------------------------------

### u16_u16_sprintf

Source: https://www.gnu.org/software/libunistring/manual/libunistring.html

Formats a string into a buffer. This function is part of the unistdio.h interface.

```APIDOC
## u16_u16_sprintf

### Description
Formats a string into a buffer.

### Header
unistdio.h

### Parameters
- **s** (uint16_t *) - Required - Output buffer
- **format** (const uint16_t *) - Required - Format string
- **...** - Required - Arguments for format specifiers

### Return Value
Returns the number of characters written, or -1 on error.

```

--------------------------------

### u8_asnprintf

Source: https://www.gnu.org/software/libunistring/manual/libunistring.html

Formats a string with allocation and size limit.

```APIDOC
## u8_asnprintf

### Description
Formats a string with allocation and size limit.

### Function
`u8_asnprintf`

### Parameters
- `resultbuf` (uint8_t**) - Output buffer.
- `lengthp` (size_t*) - Output length.
- `format` (const uint8_t*) - Format string.
- `...` - Arguments.

### Return Value
Returns the formatted string, or NULL on error.
```

--------------------------------

### u32_u32_asnprintf

Source: https://www.gnu.org/software/libunistring/manual/libunistring.html

Formats a string with allocation and size limit.

```APIDOC
## u32_u32_asnprintf

### Description
Formats a string with allocation and size limit.

### Function
`u32_u32_asnprintf`

### Parameters
- `resultbuf` (uint32_t**) - Output buffer.
- `lengthp` (size_t*) - Output length.
- `format` (const uint32_t*) - Format string.
- `...` - Arguments.

### Return Value
Returns the formatted string, or NULL on error.
```

--------------------------------

### uninorm_is_compat_decomposing

Source: https://www.gnu.org/software/libunistring/manual/libunistring.html

Tests whether the normalization form nf does compatibility decomposition.

```APIDOC
## uninorm_is_compat_decomposing

### Description
Tests whether the normalization form nf does compatibility decomposition.

### Function Signature
`bool uninorm_is_compat_decomposing (uninorm_t nf)`

### Parameters
- **nf** (uninorm_t) - Required - The normalization form to test.

### Return Value
Returns `true` if the normalization form does compatibility decomposition, `false` otherwise.

```

--------------------------------

### u8_prev, u16_prev, u32_prev

Source: https://www.gnu.org/software/libunistring/manual/libunistring.html

Backward iteration step: advances the pointer to the previous character in a NUL terminated Unicode string.

```APIDOC
## u8_prev, u16_prev, u32_prev

### Description
Backward iteration step. Advances the pointer to point to the previous character (the one that ends at `s`), or returns NULL if the beginning of the string (specified by `start`) had been reached. Puts the character's `ucs4_t` representation in `*puc`. Note that this function works only on well-formed Unicode strings.

### Function Signatures
- `const uint8_t *u8_prev(ucs4_t *puc, const uint8_t *s, const uint8_t *start)`
- `const uint16_t *u16_prev(ucs4_t *puc, const uint16_t *s, const uint16_t *start)`
- `const uint32_t *u32_prev(ucs4_t *puc, const uint32_t *s, const uint32_t *start)`

### Parameters
- `puc` (ucs4_t*) - Required - Pointer to a variable that will receive the `ucs4_t` representation of the previous character.
- `s` (const uint8_t*/uint16_t*/uint32_t*) - Required - Pointer to the current position in the NUL terminated Unicode string.
- `start` (const uint8_t*/uint16_t*/uint32_t*) - Required - Pointer to the beginning of the string.

### Return Value
Returns a pointer to the previous character, or NULL if the beginning of the string has been reached.
```

--------------------------------

### u8_casing_prefixes_context, u16_casing_prefixes_context

Source: https://www.gnu.org/software/libunistring/manual/libunistring.html

Returns the case-mapping context of a given prefix string combined with an existing context. These functions are used for case mapping of substrings.

```APIDOC
## u8_casing_prefixes_context, u16_casing_prefixes_context

### Description
Returns the case-mapping context of a given prefix string combined with an existing context. These functions are used for case mapping of substrings.

### Function Signatures
- `casing_prefix_context_t u8_casing_prefixes_context (const uint8_t *s, size_t n, casing_prefix_context_t a_context)`
- `casing_prefix_context_t u16_casing_prefixes_context (const uint16_t *s, size_t n, casing_prefix_context_t a_context)`

### Parameters
- `s` (pointer to prefix string) - The prefix string.
- `n` (size_t) - Length of the prefix string.
- `a_context` (casing_prefix_context_t) - An existing case-mapping context.

### Return Value
- `casing_prefix_context_t` - The combined case-mapping context.
```

--------------------------------

### u8_casefold

Source: https://www.gnu.org/software/libunistring/manual/libunistring.html

Casefolds a string.

```APIDOC
## u8_casefold

### Description
Casefolds a string.

### Function
`u8_casefold`

### Parameters
- `s` (const uint8_t*) - Input string.
- `n` (size_t) - Length of string.
- `iso639_language` (const char*) - Language code.
- `resultbuf` (uint8_t**) - Output buffer.
- `lengthp` (size_t*) - Output length.

### Return Value
Returns the casefolded string.
```

--------------------------------

### u32_cmp

Source: https://www.gnu.org/software/libunistring/manual/libunistring.html

Compares two Unicode strings.

```APIDOC
## u32_cmp

### Description
Compares two Unicode strings.

### Function
`u32_cmp`

### Parameters
- `s1` (const uint32_t*) - First string.
- `s2` (const uint32_t*) - Second string.
- `n` (size_t) - Number of characters to compare.

### Return Value
Returns an integer less than, equal to, or greater than zero if `s1` is found, respectively, to be less than, to match, or be greater than `s2`.
```

--------------------------------

### u8_casing_prefix_context

Source: https://www.gnu.org/software/libunistring/manual/libunistring.html

Returns the casing prefix context of a string.

```APIDOC
## u8_casing_prefix_context

### Description
Returns the casing prefix context of a string.

### Function
`u8_casing_prefix_context`

### Parameters
- `s` (const uint8_t*) - Input string.
- `n` (size_t) - Length of string.

### Return Value
Returns the prefix context.
```

--------------------------------

### u8_vsnprintf

Source: https://www.gnu.org/software/libunistring/manual/libunistring.html

Formats a string into a UTF-8 buffer with a size limit using a va_list.

```APIDOC
## u8_vsnprintf

### Description
Formats a string into a UTF-8 buffer with a size limit using a va_list.

### Function Signature
`int u8_vsnprintf (uint8_t *buf, size_t bufsize, const char *format, va_list args);`

### Parameters
- `buf` (uint8_t *) - Output buffer.
- `bufsize` (size_t) - Size of the buffer.
- `format` (const char *) - Format string.
- `args` (va_list) - Variable arguments.

### Return Value
Number of characters written, or negative on error.
```

--------------------------------

### u32_next

Source: https://www.gnu.org/software/libunistring/manual/libunistring.html

Iterates over a NUL terminated Unicode string.

```APIDOC
## u32_next

### Description
Iterates over a NUL terminated Unicode string.

### Function
`u32_next`

### Parameters
- `s` (const uint32_t**) - Pointer to the current position.

### Return Value
Returns the next character, or 0 at the end.
```

--------------------------------

### u32_vasnprintf

Source: https://www.gnu.org/software/libunistring/manual/libunistring.html

Formats a string with allocation and size limit using a va_list.

```APIDOC
## u32_vasnprintf

### Description
Formats a string with allocation and size limit using a va_list.

### Function
`u32_vasnprintf`

### Parameters
- `resultbuf` (uint32_t**) - Output buffer.
- `lengthp` (size_t*) - Output length.
- `format` (const uint32_t*) - Format string.
- `args` (va_list) - Arguments.

### Return Value
Returns the formatted string, or NULL on error.
```

--------------------------------

### u8_cpy_alloc

Source: https://www.gnu.org/software/libunistring/manual/libunistring.html

Copies a UTF-8 string with memory allocation.

```APIDOC
## u8_cpy_alloc

### Description
Copies a UTF-8 string with memory allocation.

### Function
`u8_cpy_alloc`

### Parameters
- `s` (const uint8_t*) - Source string.
- `n` (size_t) - Number of bytes to copy.

### Return Value
Returns a newly allocated copy, or NULL on memory allocation failure.
```

--------------------------------

### u8_next, u16_next, u32_next

Source: https://www.gnu.org/software/libunistring/manual/libunistring.html

Forward iteration step: advances the pointer past the next character in a NUL terminated Unicode string.

```APIDOC
## u8_next, u16_next, u32_next

### Description
Forward iteration step. Advances the pointer past the next character in the NUL terminated Unicode string `s`, or returns NULL if the end of the string has been reached. Puts the character's `ucs4_t` representation in `*puc`.

### Function Signatures
- `const uint8_t *u8_next(ucs4_t *puc, const uint8_t *s)`
- `const uint16_t *u16_next(ucs4_t *puc, const uint16_t *s)`
- `const uint32_t *u32_next(ucs4_t *puc, const uint32_t *s)`

### Parameters
- `puc` (ucs4_t*) - Required - Pointer to a variable that will receive the `ucs4_t` representation of the next character.
- `s` (const uint8_t*/uint16_t*/uint32_t*) - Required - Pointer to the current position in the NUL terminated Unicode string.

### Return Value
Returns a pointer to the character after the next character, or NULL if the end of the string has been reached.
```

--------------------------------

### u32_asnprintf

Source: https://www.gnu.org/software/libunistring/manual/libunistring.html

Formats a string with a maximum size and stores the result in a newly allocated buffer. This function is part of the unistdio.h interface.

```APIDOC
## u32_asnprintf

### Description
Formats a string with a maximum size and stores the result in a newly allocated buffer.

### Header
unistdio.h

### Parameters
- **result** (uint32_t **) - Required - Output buffer
- **lengthp** (size_t *) - Required - Pointer to store output length
- **format** (const uint32_t *) - Required - Format string
- **...** - Required - Arguments for format specifiers

### Return Value
Returns the number of characters written, or -1 on error.

```

--------------------------------

### u8_normcmp, u16_normcmp, u32_normcmp

Source: https://www.gnu.org/software/libunistring/manual/libunistring.html

Compares s1 and s2, ignoring differences in normalization. nf must be either UNINORM_NFD or UNINORM_NFKD. If successful, sets *resultp to -1 if s1 < s2, 0 if s1 = s2, 1 if s1 > s2, and returns 0. Upon failure, returns -1 with errno set.

```APIDOC
## u8_normcmp, u16_normcmp, u32_normcmp

### Description
Compares s1 and s2, ignoring differences in normalization. nf must be either UNINORM_NFD or UNINORM_NFKD. If successful, sets *resultp to -1 if s1 < s2, 0 if s1 = s2, 1 if s1 > s2, and returns 0. Upon failure, returns -1 with errno set.

### Function Signatures
- `int u8_normcmp (const uint8_t *s1, size_t n1, const uint8_t *s2, size_t n2, uninorm_t nf, int *resultp)`
- `int u16_normcmp (const uint16_t *s1, size_t n1, const uint16_t *s2, size_t n2, uninorm_t nf, int *resultp)`
- `int u32_normcmp (const uint32_t *s1, size_t n1, const uint32_t *s2, size_t n2, uninorm_t nf, int *resultp)`

### Parameters
- **s1** (const uint8_t/uint16_t/uint32_t *) - Required - First string to compare.
- **n1** (size_t) - Required - Length of s1.
- **s2** (const uint8_t/uint16_t/uint32_t *) - Required - Second string to compare.
- **n2** (size_t) - Required - Length of s2.
- **nf** (uninorm_t) - Required - Normalization form; must be UNINORM_NFD or UNINORM_NFKD.
- **resultp** (int *) - Required - Pointer to store the comparison result.

### Return Value
Returns 0 on success, -1 on failure with errno set.

```
Tokens:
Raw