mbrtoc32 - complete and convert multi-byte string to UTF-32 character

Syntax	C11 #include <uchar.h> size_t mbrtoc32(char32_t *pc32, const char *s, size_t n, mbstate_t *ps); (End)
Description	If s is not a null pointer, mbrtoc32() determines how many bytes (starting at the position pointed to by *s) are required to complete the next multi-byte character. Any Shift sequences are also taken into account. A maximum of the next n bytes are tested. If mbrtoc32() can compete the multi-byte character, the corresponding UTF-32 character is determined and stored in *pc32 as long as pc32 is not a null pointer. If the corresponding wide character is the null character, the final state corresponds to the “initial conversion” state. If s is a null pointer, mbrtoc32() corresponds to the call mbrtoc32(NULL, "", 1, ps). In this case the parameters pc32 and n are ignored.
Return val.	Depending on the current conversion state, mbrtoc32() returns the value of the first condition of the following conditions that is met:
	0	if the next (maximum of n) bytes result in a valid multi-byte character that corresponds to the UTF-32 character “null”.
	Number of bytes required to complete the multi-byte character
		if the next (maximum of n) bytes result in a valid multi-byte character. The wide character corresponding to this multi-byte character is stored.
	(size_t)-2	if the next n bytes result in an incomplete, but potentially valid multi-byte character. No value is stored.
	(size_t)-1	if a coding error occurs, i.e. if the next (maximum of n) bytes do not result in a complete and valid multi-byte character. No value is stored an the value of the EILSEQ macro is written in errno. The conversion status is undefined.
Notes	Restriction In this version of the C runtime system, only 1-byte characters are supported as wide characters. (End)
See also	c16rtomb(), c32rtomb(), mbrtoc16().