| Functions | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Wide/multibyte conversions | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
(C95) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Types | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Macros | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Defined in header <uchar.h> | ||
| (since C11) | ||
Converts a single code point from its variable-length 16-bit wide character representation (typically, UTF-16) to its narrow multibyte character representation.
Ifs is not a null pointer andc16 is the last 16-bit code unit in a valid variable-length encoding of a code point, the function determines the number of bytes necessary to store the multibyte character representation of that code point (including any shift sequences, and taking into account the current multibyte conversion state*ps), and stores the multibyte character representation in the character array whose first element is pointed to bys, updating*ps as necessary. At mostMB_CUR_MAX bytes can be written by this function.
Ifs is a null pointer, the call is equivalent toc16rtomb(buf, u'\0', ps) for some internal bufferbuf.
Ifc16 is the null wide characteru'\0', a null byte is stored, preceded by any shift sequence necessary to restore the initial shift state and the conversion state parameter*ps is updated to represent the initial shift state.
Ifc16 is not the final code unit in a 16-bit representation of a wide character, it does not write to the array pointed to bys, only*ps is updated.
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.
Contents |
| s | - | pointer to narrow character array where the multibyte character will be stored |
| c16 | - | the 16-bit wide character to convert |
| ps | - | pointer to the conversion state object used when interpreting the multibyte string |
On success, returns the number of bytes (including any shift sequences) written to the character array whose first element is pointed to bys. This value may be0, e.g. when processing the leadingchar16_t units in a multi-char16_t-unit sequence (occurs when processing the leading surrogate in a surrogate pair of UTF-16).
On failure (ifc16 is not a valid 16-bit code unit), returns-1, storesEILSEQ inerrno, and leaves*ps in unspecified state.
In C11 as published, unlikembrtoc16, which converts variable-width multibyte (such as UTF-8) to variable-width 16-bit (such as UTF-16) encoding, this function can only convert single-unit 16-bit encoding, meaning it cannot convert UTF-16 to UTF-8 despite that being the original intent of this function. This was corrected by the post-C11 defect reportDR488.
Note: this example assumes the fix for the defect reportDR488 is applied.
On MSVC you may need the/utf-8 compiler flag for UTF_8 to work properly.
#include <locale.h>#include <stdio.h>#include <stdlib.h>#include <uchar.h> int main(void){setlocale(LC_ALL,"en_US.utf8");const char16_t in[]= u"zß水🍌";// or "z\u00df\u6c34\U0001F34C"constsize_t in_sz=sizeof in/sizeof*in; printf("Processing %zu UTF-16 code units: [", in_sz);for(size_t n=0; n< in_sz;++n)printf("%s%04X", n?" ":"", in[n]);puts("]"); char* out=malloc(MB_CUR_MAX* in_sz);char* p= out;mbstate_t state={0}; for(size_t n=0; n< in_sz;++n){size_t rc= c16rtomb(p, in[n],&state);if(rc==(size_t)-1)break; p+= rc;} size_t out_sz= p- out;printf("into %zu UTF-8 code units: [", out_sz);for(size_t x=0; x< out_sz;++x)printf("%s%02X", x?" ":"",+(unsignedchar)out[x]);puts("]");free(out);}
Output:
Processing 6 UTF-16 code units: [007A 00DF 6C34 D83C DF4C 0000]into 13 UTF-8 code units: [7A C3 9F E6 B0 B4 ED A0 BC ED BD 8C 00]
(C11) | converts a narrow multibyte character to UTF-16 encoding (function)[edit] |
C++ documentation forc16rtomb | |
