Next: , Previous: Introduction, Up: Top


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.

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.