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.

This document was generated by Bruno Haible on October, 16 2024 using texi2html 1.78a.