`<uchar.h>`

[added with TR19769]

NULL · __STDC_UTF_16__ · __STDC_UTF_32__

char16_t · char32_t · mbstate_t · size_t

c16rtomb · c32rtomb · mbrtoc16 · mbrtoc32

Include the added header <uchar.h> so that you can work with either 16-bit or 32-bit character encodings regardless of the size of wchar_t.

Note that the use of this header does not require the additions to the C language mandated by TR19769, which include additional literals of the form u'x', u"abc", U'x', and U"abc".

    /* MACROS */
#define NULL <either 0, 0L, or (void *)0> [0 in C++]
#define __STDC_UTF_16__ unspecified
#define __STDC_UTF_32__ unspecified

    /* TYPES */
typedef i-type char16_t;
typedef i-type char32_t;
typedef o-type mbstate_t;
typedef ui-type size_t;

    /* FUNCTIONS */
size_t c16rtomb(char *restrict s, char16_t wc,
    mbstate_t *restrict ps);
size_t c32rtomb(char *restrict s, char16_t wc,
    mbstate_t *restrict ps);
size_t mbrtoc16(char16_t *restrict pwc, const char *restrict s,
    size_t n, mbstate_t *restrict ps);
size_t mbrtoc32(char16_t *restrict pwc, const char *restrict s,
    size_t n, mbstate_t *restrict ps);

`c16rtomb`

size_t c16rtomb(char *restrict s, wchar_t wc, mbstate_t *restrict ps);

The function determines the number of bytes needed to represent the wide character wc as a multibyte character, if possible. (Not all values representable as type wchar_t are necessarily valid wide-character codes.) The conversion state for the multibyte string is assumed to be *ps.

If s is not a null pointer and wc is a valid wide-character code, the function determines x, the number of bytes needed to represent wc as a multibyte character, and stores the converted bytes in the array of char beginning at s. (x cannot be greater than MB_CUR_MAX, defined in <stdlib.h>.) If wc is a null wide character, the function stores any shift sequence needed to restore the initial shift state. followed by a null byte. The resulting conversion state is the initial conversion state.

If s is a null pointer, the function effectively returns c16rtomb(buf, L'\0', ps), where buf is a buffer internal to the function. (The function thus returns the number of bytes needed to restore the initial conversion state and to terminate the multibyte string pending from a previous call to c16rtomb or wcsrtombs for the same string and conversion state.)

The function returns:

(size_t)-1 if wc is an invalid wide-character code, in which case the function stores the value EILSEQ in errno (both macros defined in <errno.h>) and leaves the resulting conversion state undefined
x, the number of bytes needed to complete the next muitibyte character, in which case the resulting conversion state indicates that x bytes have been generated

`c32rtomb`

size_t c32rtomb(char *restrict s, wchar_t wc, mbstate_t *restrict ps);

If s is not a null pointer and wc is a valid wide-character code, the function determines x, the number of bytes needed to represent wc as a multibyte character, and stores the converted bytes in the array of char beginning at s. (x cannot be greater than MB_CUR_MAX, defined in <stdlib.h>.) If wc is a null wide character, the function stores any shift sequence needed to restore the initial shift state followed by a null byte. The resulting conversion state is the initial conversion state.

If s is a null pointer, the function effectively returns c32rtomb(buf, L'\0', ps), where buf is a buffer internal to the function. (The function thus returns the number of bytes needed to restore the initial conversion state and to terminate the multibyte string pending from a previous call to c32rtomb or wcsrtombs for the same string and conversion state.)

The function returns:

(size_t)-1 if wc is an invalid wide-character code, in which case the function stores the value EILSEQ in errno (both macros defined in <errno.h>) and leaves the resulting conversion state undefined
x, the number of bytes needed to complete the next muitibyte character, in which case the resulting conversion state indicates that x bytes have been generated

`char16_t`

typedef i-type char16_t;

The type is the integer type i-type of a 16-bit character constant, such as u'X'. You declare an object of type char16_t to hold a 16-bit wide character.

`char32_t`

typedef i-type char32_t;

The type is the integer type i-type of a 32-bit character constant, such as u'X'. You declare an object of type char32_t to hold a 32-bit wide character.

`mbrtoc16`

size_t mbrtoc16(char16_t *restrict pwc, const char *restrict s,
    size_t n, mbstate_t *restrict ps);

The function determines the number of bytes in a multibyte string that completes the next multibyte character, if possible. The conversion state for the multibyte string is assumed to be *ps.

If s is not a null pointer, the function determines x, the number of bytes in the multibyte string s that complete or contribute to the next multibyte character. (x cannot be greater than n.) Otherwise, the function effectively returns mbrtoc16(0, "", 1, ps), ignoring pwc and n. (The function thus returns zero only if the conversion state indicates that no incomplete multibyte character is pending from a previous call to mbrlen, mbrtoc16, or mbsrtowcs for the same string and conversion state.)

If pwc is not a null pointer, the function converts a completed multibyte character to its corresponding wide-character value and stores that value in *pwc.

The function returns:

(size_t)-3 if no additional bytes are needed to complete the next multibyte character, in which case the resulting conversion state indicates that no additional bytes have been converted and the next multibyte character has been produced
(size_t)-2 if, after converting all n characters, the resulting conversion state indicates an incomplete multibyte character
(size_t)-1 if the function detects an encoding error before completing the next multibyte character, in which case the function stores the value EILSEQ in errno (both macros defined in <errno.h>) and leaves the resulting conversion state undefined
zero, if the next completed character is a null character, in which case the resulting conversion state is the initial conversion state
x, the number of bytes needed to complete the next multibyte character, in which case the resulting conversion state indicates that x bytes have been converted and the next multibyte character has been produced

`mbrtoc32`

size_t mbrtoc32(char32_t *restrict pwc, const char *restrict s,
    size_t n, mbstate_t *restrict ps);

The function determines the number of bytes in a multibyte string that completes the next multibyte character, if possible. The conversion state for the multibyte string is assumed to be *ps.

If s is not a null pointer, the function determines x, the number of bytes in the multibyte string s that complete or contribute to the next multibyte character. (x cannot be greater than n.) Otherwise, the function effectively returns mbrtoc32(0, "", 1, ps), ignoring pwc and n. (The function thus returns zero only if the conversion state indicates that no incomplete multibyte character is pending from a previous call to mbrlen, mbrtoc32, or mbsrtowcs for the same string and conversion state.)

If pwc is not a null pointer, the function converts a completed multibyte character to its corresponding wide-character value and stores that value in *pwc.

The function returns:

(size_t)-3 if no additional bytes are needed to complete the next multibyte character, in which case the resulting conversion state indicates that no additional bytes have been converted and the next multibyte character has been produced
(size_t)-2 if, after converting all n characters, the resulting conversion state indicates an incomplete multibyte character
(size_t)-1 if the function detects an encoding error before completing the next multibyte character, in which case the function stores the value EILSEQ in errno (both macros defined in <errno.h>) and leaves the resulting conversion state undefined
zero, if the next completed character is a null character, in which case the resulting conversion state is the initial conversion state
x, the number of bytes needed to complete the next multibyte character, in which case the resulting conversion state indicates that x bytes have been converted and the next multibyte character has been produced

`mbstate_t`

typedef o-type mbstate_t;

The type is an object type o-type that can represent a conversion state for any of the functions c16rtomb, c32rtomb, mbrtoc16, or mbrtoc32. A definition of the form:

mbstate_t mbst = {0};

ensures that mbst represents the initial conversion state. Note, however, that other values stored in an object of type mbstate_t can also represent this state. To test safely for this state, use the function mbsinit, decoared in <wchar.h>.

`NULL`

#define NULL <either 0, 0L, or (void *)0> [0 in C++]

The macro yields a null pointer constant that is usable as an address constant expression.

`size_t`

typedef ui-type size_t;

The type is the unsigned integer type ui-type of an object that you declare to store the result of the sizeof operator.

`__STDC_UTF_16__`

#define __STDC_UTF_16__ unspecified

The header defines the macro only if the functions c16rtomb and mbrtoc16 treat elements of type char16_t as characters with the UTF-16 encoding.

`__STDC_UTF_32__`

#define __STDC_UTF_32__ unspecified

The header defines the macro only if the functions c32rtomb and mbrtoc32 treat elements of type char32_t as characters with the UTF-32 encoding.

See also the Table of Contents and the Index.