CKTIS / C
mbrtoc16 — C23 Unicode-conversion function
`mbrtoc16(pc16, s, n, ps)` from `<uchar.h>` examines at most `n` bytes of the next execution multibyte character and stores the corresponding UTF-16 `char16_t` code unit. The `mbstate_t` object designated by `ps` preserves conversion state between calls; `pc16 == NULL` suppresses only the output store.
Version: C23
Syntax
size_t mbrtoc16(char16_t * restrict pc16, const char * restrict s, size_t n, mbstate_t * restrict ps);mbrtoc16(pc16, s, n, ps) from <uchar.h> examines at most n bytes of the next execution multibyte character and stores the corresponding UTF-16 char16_t code unit. The mbstate_t object designated by ps preserves conversion state between calls; pc16 == NULL suppresses only the output store.
The example uses an explicitly zero-initialized state and converts the single-byte string "A". The function consumes one byte, stores U+0041, and the program prints 1 U+0041; it therefore checks both the real return value and the UTF-16 unit.
A result of 0 denotes the null character and initial state, -2 an incomplete but potentially valid character, and -1 an encoding error with errno == EILSEQ and unspecified state. A character outside the BMP yields a surrogate pair: the first call consumes bytes, while a later call can return -3 and store the next unit without consuming input, so do not advance s then. When s == NULL, the call is exactly equivalent to mbrtoc16(NULL, "", 1, ps); pc16 and n are ignored. This is the specified empty-string call in the current conversion state, not a promise of an unconditional reset. With non-null s, pc16 == NULL suppresses only the store; explicit ps avoids internal state that is not required to be race-free.
Examples
#include <stdio.h>
#include <uchar.h>
int main(void){mbstate_t state={0};char16_t unit=0;size_t count=mbrtoc16(&unit,"A",1,&state);printf("%zu U+%04X\n",count,(unsigned)unit);return 0;}
Result
1 U+0041
The example uses an explicitly zero-initialized state and converts the single-byte string `"A"`. The function consumes one byte, stores `U+0041`, and the program prints `1 U+0041`; it therefore checks both the real return value and the UTF-16 unit.