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.

This document was generated by Daiki Ueno on August, 12 2014 using texi2html 1.78a.