Translates the first UTF-8 multibyte character in a string into the equivalent UTF-16 or UTF-32 character.
size_t mbrtoc16( char16_t* destination, const char* source, size_t max_bytes, mbstate_t* state ); size_t mbrtoc32( char32_t* destination, const char* source, size_t max_bytes, mbstate_t* state );
Pointer to the
char32_t equivalent of the UTF-8 multibyte character to convert. If null, the function doesn't store a value.
Pointer to the UTF-8 multibyte character string to convert.
The maximum number of bytes in
source to examine for a character to convert. This argument should be a value between one and the number of bytes, including any null terminator, remaining in
Pointer to a
mbstate_t conversion state object used to interpret the UTF-8 multibyte string to one or more output characters.
On success, returns the value of the first of these conditions that applies, given the current
|Between 1 and
||The value returned is the number of bytes of
|-3||The next wide character resulting from a previous call to the function has been stored in
|-1||An encoding error has occurred. The next
mbrtoc16 function reads up to
max_bytes bytes from
source to find the first complete, valid UTF-8 multibyte character, and then stores the equivalent UTF-16 character in
destination. If the character requires more than one UTF-16 output character, such as a surrogate pair, then the
state value is set to store the next UTF-16 character in
destination on the next call to
mbrtoc32 function is identical, but output is stored as a UTF-32 character.
source is null, these functions return the equivalent of a call made using arguments of
"" (an empty, null-terminated string) for
source, and 1 for
max_bytes. The passed values of
max_bytes are ignored.
source isn't null, the function starts at the beginning of the string and inspects up to
max_bytes bytes to determine the number of bytes required to complete the next UTF-8 multibyte character, including any shift sequences. If the examined bytes contain a valid and complete UTF-8 multibyte character, the function converts the character into the equivalent 16-bit or 32-bit wide character or characters. If
destination isn't null, the function stores the first (and possibly only) result character in destination. If extra output characters are required, a value is set in
state, so that subsequent calls to the function output the extra characters and return the value -3. If no more output characters are required, then
state is set to the initial shift state.
By default, this function's global state is scoped to the application. To change this behavior, see Global state in the CRT.
|Function||C header||C++ header|
For more compatibility information, see Compatibility.