Converts a single code point from its narrow multibyte character representation to its variable-length 16-bit wide character representation (typically, UTF-16).

Ifs is not a null pointer, inspects at mostn bytes of the multibyte character string, beginning with the byte pointed to bys to determine the number of bytes necessary to complete the next multibyte character (including any shift sequences, and taking into account the current multibyte conversion state*ps). If the function determines that the next multibyte character ins is complete and valid, converts it to the corresponding 16-bit wide character and stores it in*pc16 (ifpc16 is not null).

If the multibyte character in*s corresponds to a multi-char16_t sequence (e.g. a surrogate pair in UTF-16), then after the first call to this function,*ps is updated in such a way that the next call tombrtoc16 will write out the additionalchar16_t, without considering*s.

Ifs is a null pointer, the values ofn andpc16 are ignored and the call is equivalent tombrtoc16(NULL,"",1, ps).

If the wide character produced is the null character, the conversion state*ps represents the initial shift state.

If the macro__STDC_UTF_16__ is defined, the 16-bit encoding used by this function is UTF-16; otherwise, it is implementation-defined.The macro is always defined and the encoding is always UTF-16.(since C23) In any case, the multibyte character encoding used by this function is specified by the currently active C locale.

[edit]Parameters

[edit]Return value

The first of the following that applies:

• ​0​ if the character converted froms (and stored in*pc16 if non-null) was the null character.
• The number of bytes[1, n] of the multibyte character successfully converted froms.
• (size_t)-3 if the nextchar16_t from a multi-char16_t character (e.g. a surrogate pair) has now been written to*pc16. No bytes are processed from the input in this case.
• (size_t)-2 if the nextn bytes constitute an incomplete, but so far valid, multibyte character. Nothing is written to*pc16.
• (size_t)-1 if encoding error occurs. Nothing is written to*pc16, the valueEILSEQ is stored inerrno and the value of*ps is unspecified.

[edit]Example

#include <locale.h>#include <stdio.h>#include <uchar.h> int main(void){setlocale(LC_ALL,"en_US.utf8");constchar in[]= u8"zß水🍌";// or "z\u00df\u6c34\U0001F34C"enum{ in_sz=sizeof in/sizeof*in}; printf("Processing %d UTF-8 code units: [", in_sz);for(int n=0; n< in_sz;++n)printf("%s%02X", n?" ":"",(unsignedchar)in[n]);puts("]");     char16_t out[in_sz];constchar* p_in= in;constchar* end= in+ in_sz;    char16_t* p_out= out;mbstate_t state={0}; for(size_t rc;(rc= mbrtoc16(p_out, p_in, end- p_in,&state));){if(rc==(size_t)-1)// invalid inputbreak;elseif(rc==(size_t)-2)// truncated inputbreak;elseif(rc==(size_t)-3)// UTF-16 high surrogate            p_out+=1;else{            p_in+= rc;            p_out+=1;};} constsize_t out_sz= p_out- out+1;printf("into %zu UTF-16 code units: [", out_sz);for(size_t x=0; x< out_sz;++x)printf("%s%04X", x?" ":"", out[x]);puts("]");}

Processing 11 UTF-8 code units: [7A C3 9F E6 B0 B4 F0 9F 8D 8C 00]into 6 UTF-16 code units: [007A 00DF 6C34 D83C DF4C 0000]

[edit]References

[edit]See also

• In other languages

• العربية
• Česky
• Deutsch
• Español
• Français
• Italiano
• 日本語
• 한국어
• Polski
• Português
• Русский
• Türkçe
• 中文