c16rtomb

가변 길이 16비트 와이드 문자 표현(일반적으로 UTF-16)에서 단일 코드 포인트를 좁은 멀티바이트 문자 표현으로 변환합니다.

만약 s 가 null 포인터가 아니고 c16 가 유효한 가변 길이 인코딩에서 코드 포인트의 마지막 16비트 코드 유닛인 경우, 이 함수는 해당 코드 포인트의 멀티바이트 문자 표현을 저장하는 데 필요한 바이트 수를 결정하고(시프트 시퀀스를 포함하며 현재 멀티바이트 변환 상태 * ps 를 고려함), 멀티바이트 문자 표현을 s 가 가리키는 첫 번째 요소를 갖는 문자 배열에 저장하며 필요에 따라 * ps 를 업데이트합니다. 이 함수로 최대 MB_CUR_MAX 바이트까지 기록할 수 있습니다.

만약 s 가 null 포인터인 경우, 이 호출은 내부 버퍼 buf 에 대해 c16rtomb ( buf, u ' \0 ' , ps ) 와 동일합니다.

만약 c16 이 null 와이드 문자 u ' \0 ' 인 경우, null 바이트가 저장되며, 초기 shift state를 복원하는 데 필요한 shift sequence가 앞에 추가되고 변환 상태 매개변수 * ps 는 초기 shift state를 나타내도록 업데이트됩니다.

만약 c16 이 와이드 문자(wchar)의 16비트 표현에서 최종 코드 유닛이 아니라면, s 가 가리키는 배열에는 쓰여지지 않고, 오직 * ps 만 업데이트됩니다.

매크로 __STDC_UTF_16__ 가 정의된 경우, 이 함수가 사용하는 16비트 인코딩은 UTF-16입니다. 그렇지 않으면 구현에 따라 정의됩니다. 이 매크로는 항상 정의되며 인코딩은 항상 UTF-16입니다. (C23 이후) 어떤 경우든, 이 함수가 사용하는 멀티바이트 문자 인코딩은 현재 활성화된 C 로캘에 의해 지정됩니다.

매개변수

반환값

성공 시, s 가 가리키는 첫 번째 요소를 시작으로 하는 문자 배열에 기록된 바이트 수(시프트 시퀀스를 포함)를 반환합니다. 이 값은 ​ 0 ​ 일 수 있으며, 예를 들어 다중 char16_t 유닛 시퀀스에서 선행 char16_t 유닛을 처리할 때(UTF-16 서로게이트 쌍에서 선행 서로게이트를 처리하는 경우) 발생합니다.

실패 시( c16 이 유효한 16비트 코드 유닛이 아닌 경우), - 1 을 반환하고, EILSEQ 을 errno 에 저장하며, * ps 를 지정되지 않은 상태로 둡니다.

참고 사항

C11로 출판된 당시에는, mbrtoc16 이 가변 너비 멀티바이트(예: UTF-8)를 가변 너비 16비트(예: UTF-16) 인코딩으로 변환하는 것과 달리, 이 함수는 단일 유닛 16비트 인코딩만 변환할 수 있습니다. 즉, 이 함수의 원래 의도에도 불구하고 UTF-16을 UTF-8로 변환할 수 없었습니다. 이 문제는 C11 이후 결함 보고서 DR488 에 의해 수정되었습니다.

예제

#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"
    const size_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 ? " " : "", +(unsigned char)out[x]);
    puts("]");
    free(out);
}

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]

참고문헌

참고 항목