mbrtoc16, mbrtoc32

Article
12/18/2017

The latest version of this topic can be found at mbrtoc16, mbrtoc323.

Translates the first multibyte character in a narrow string into the equivalent UTF-16 or UTF-32 character.

Syntax

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   
);

Parameters

destination
Pointer to the char16_t or char32_t equivalent of the multibyte character to convert. If null, the function does not store a value.

source
Pointer to the multibyte character string to convert.

max_bytes
The maximum number of bytes in source to examine for a character to convert. This should be a value between one and the number of bytes, including any null terminator, remaining in source.

state
Pointer to a mbstate_t conversion state object used to interpret the multibyte string to one or more output characters.

Return Value

On success, returns the value of the first of these conditions that applies, given the current state value:

Value	Condition
0	The next `max_bytes` or fewer characters converted from `source` correspond to the null wide character, which is the value stored if `destination` is not null. `state` contains the initial shift state.
Between 1 and `max_bytes`, inclusive	The value returned is the number of bytes of `source` that complete a valid multibyte character. The converted wide character is stored if `destination` is not null.
-3	The next wide character resulting from a previous call to the function has been stored in `destination` if `destination` is not null. No bytes from `source` are consumed by this call to the function. When `source` points to a multibyte character that requires more than one wide character to represent (for example, a surrogate pair), then the `state` value is updated so that the next function call writes out the additional character.
-2	The next `max_bytes` bytes represent an incomplete, but potentially valid, multibyte character. No value is stored in `destination`. This result can occur if `max_bytes` is zero.
-1	An encoding error has occurred. The next `max_bytes` or fewer bytes do not contribute to a complete and valid multibyte character. No value is stored in `destination`. `EILSEQ` is stored in `errno` and the conversion state `state` is unspecified.

Remarks

The mbrtoc16 function reads up to max_bytes bytes from source to find the first complete, valid multibyte character, and then stores the equivalent UTF-16 character in destination. The source bytes are interpreted according to the current thread multibyte locale. If the multibyte 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 mbrtoc16. The mbrtoc32 function is identical, but output is stored as a UTF-32 character.

If source is null, these functions return the equivalent of a call made using arguments of NULL for destination, "" for source, and 1 for max_bytes. The passed values of destination and max_bytes are ignored.

If source is not 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 multibyte character, including any shift sequences. If the examined bytes contain a valid and complete multibyte character, the function converts the character into the equivalent 16-bit or 32-bit wide character or characters. If destination is not null, the function stores the first (and possibly only) result character in destination. If additional output characters are required, a value is set in state, so that subsequent calls to the function output the additional characters and return the value -3. If no more output characters are required, then state is set to the initial shift state.

Requirements

Function	C header	C++ header
`mbrtoc16`, `mbrtoc32`	<uchar.h>	<cuchar>

For additional compatibility information, see Compatibility.

Share via