GNU libunistring: 2. Conventions

[ << ] | [ >> ] |  |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

# 2. Conventions

This chapter explains conventions valid throughout the libunistring library.

Variables of type `char *` denote C strings in locale encoding. See Locale encodings.

Variables of type `uint8_t *` denote UTF-8 strings. Their units are bytes.

Variables of type `uint16_t *` denote UTF-16 strings, without byte order mark. Their units are 2-byte words.

Variables of type `uint32_t *` denote UTF-32 strings, without byte order mark. Their units are 4-byte words.

Argument pairs `(s, n)` denote a string `s[0..n-1]` with exactly n units.(1)

All functions with prefix ‘`ulc_`’ operate on C strings in locale encoding.

All functions with prefix ‘`u8_`’ operate on UTF-8 strings.

All functions with prefix ‘`u16_`’ operate on UTF-16 strings.

All functions with prefix ‘`u32_`’ operate on UTF-32 strings.

For every function with prefix ‘`u8_`’, operating on UTF-8 strings, there is also a corresponding function with prefix ‘`u16_`’, operating on UTF-16 strings, and a corresponding function with prefix ‘`u32_`’, operating on UTF-32 strings. Their description is analogous; in this documentation we describe only the function that operates on UTF-8 strings, for brevity.

A declaration with a variable n denotes the three concrete declarations with n = 8, n = 16, n = 32.

All parameters starting with ‘`str`’ and the parameters of functions starting with `u8_str`/`u16_str`/`u32_str` denote a NUL terminated string.

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 an pointer, or -1 for functions that return an `int`).

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.

To invoke such a function:

- First ask yourself whether you want 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 large; pass this array as resultbuf; and initialize `*lengthp` to the number of units of this array.
- Upon return from such a function, 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.
- Finally, do memory management. You know that the result was `malloc`-allocated if it is `!= NULL` and `!= resultbuf`.

[ << ] | [ >> ] |  |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

This document was generated by Bruno Haible on February, 24 2024 using texi2html 1.78a.