Namespaces
Variants

wcrtomb, wcrtomb_s

From cppreference.net
C
Strings library
Null-terminated multibyte strings
헤더 파일에 정의됨 <wchar.h>
(1)
size_t wcrtomb ( char * s, wchar_t wc, mbstate_t * ps ) ;
(C95부터)
size_t wcrtomb ( char * restrict s, wchar_t wc, mbstate_t * restrict ps ) ;
(C99부터)
errno_t wcrtomb_s ( size_t * restrict retval, char * restrict s, rsize_t ssz,
wchar_t wc, mbstate_t * restrict ps ) ;
(2) (C11부터)

와이드 문자를 좁은 멀티바이트 표현으로 변환합니다.

1) 만약 s 가 null 포인터가 아니라면, 이 함수는 wc 의 멀티바이트 문자 표현을 저장하는 데 필요한 바이트 수(현재 멀티바이트 변환 상태 * ps 를 고려하여 시퀀스 전환을 포함)를 결정하고, 멀티바이트 문자 표현을 s 가 가리키는 첫 번째 요소를 갖는 문자 배열에 저장하며, 필요에 따라 * ps 를 갱신합니다. 이 함수에 의해 최대 MB_CUR_MAX 바이트까지 기록될 수 있습니다.
만약 s 가 널 포인터인 경우, 이 호출은 내부 버퍼 buf 에 대해 wcrtomb ( buf, L ' \0 ' , ps ) 와 동일합니다.
만약 wc가 널 와이드 문자 L ' \0 ' 인 경우, 초기 변환 상태로 복원하는 데 필요한 시퀀스 변환을 앞에 두고 널 바이트가 저장되며, 변환 상태 매개변수 * ps 는 초기 변환 상태를 나타내도록 갱신됩니다.
환경 매크로 __STDC_ISO_10646__ 가 정의된 경우, wchar_t 타입의 값들은 유니코드 필수 문자 집합의 짧은 식별자(일반적으로 UTF-32 인코딩)와 동일합니다; 그렇지 않으면 구현에 따라 정의됩니다. 어떤 경우든, 이 함수가 사용하는 멀티바이트 문자 인코딩은 현재 활성화된 C 로캘에 의해 지정됩니다.
2) (1) 과 동일하지만, 다음 사항이 다릅니다:
만약 s 가 null 포인터인 경우, 이 호출은 내부 변수 retval 과 buf (그 크기가 MB_CUR_MAX 보다 큰)를 사용한 wcrtomb_s ( & retval, buf, sizeof buf, L ' \0 ' , ps ) 와 동등합니다
결과는 출력 매개변수 retval 에 반환됩니다
다음 오류들은 런타임에 감지되며 현재 설치된 constraint handler 함수를 호출합니다:
  • retval 또는 ps 가 null 포인터인 경우.
  • ssz 가 0이거나 RSIZE_MAX 보다 큰 경우 (단, s 가 null이 아닐 때)
  • ssz 가 기록될 바이트 수보다 작은 경우 (단, s 가 null이 아닐 때)
  • s 가 null 포인터이지만 ssz 가 0이 아닌 경우
모든 bounds-checked 함수들과 마찬가지로, wcrtomb_s 는 구현에 의해 __STDC_LIB_EXT1__ 가 정의되고 사용자가 <wchar.h> 를 포함하기 전에 __STDC_WANT_LIB_EXT1__ 를 정수 상수 1 로 정의한 경우에만 사용 가능함이 보장됩니다.

목차

매개변수

s - 멀티바이트 문자가 저장될 narrow 문자 배열에 대한 포인터
wc - 변환할 와이드 문자
ps - 멀티바이트 문자열을 해석할 때 사용되는 변환 상태 객체에 대한 포인터
ssz - 최대 기록 바이트 수 ( s 버퍼의 크기)
retval - 결과(시퀀스 전환 문자를 포함한 멀티바이트 문자열의 바이트 수)가 저장될 출력 매개변수에 대한 포인터

반환값

1) 성공 시, s 가 가리키는 첫 번째 요소를 시작으로 하는 문자 배열에 기록된 바이트 수(시프트 시퀀스를 포함)를 반환합니다.
실패 시( wc 가 유효한 와이드 문자가 아닌 경우), ( size_t ) - 1 를 반환하고, EILSEQ 를 errno 에 저장하며, * ps 를 지정되지 않은 상태로 둡니다.
2) 성공 시 0을 반환하고 실패 시 0이 아닌 값을 반환하며, 이 경우 s [ 0 ] 가 ' \0 ' 로 설정됨 ( s 가 null이거나 ssz 가 0이거나 RSIZE_MAX 보다 큰 경우는 제외) 그리고 * retval 가 ( size_t ) - 1 로 설정됨 ( retval 가 null인 경우는 제외)

예제

이 코드 실행 
#include <stdio.h>
#include <locale.h>
#include <string.h>
#include <wchar.h>
#include <stdlib.h>
int main(void)
{
    setlocale(LC_ALL, "en_US.utf8");
    mbstate_t state;
    memset(&state, 0, sizeof state);
    wchar_t in[] = L"zß水🍌"; // or "z\u00df\u6c34\U0001F34C"
    size_t in_sz = sizeof in / sizeof *in;
    printf("Processing %zu wchar_t units: [ ", in_sz);
    for(size_t n = 0; n < in_sz; ++n) printf("%#x ", (unsigned int)in[n]);
    puts("]");
    char out[MB_CUR_MAX * in_sz];
    char *p = out;
    for(size_t n = 0; n < in_sz; ++n) {
        int rc = wcrtomb(p, in[n], &state); 
        if(rc == -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("%#x ", +(unsigned char)out[x]);
    puts("]");
}

출력: 

Processing 5 wchar_t units: [ 0x7a 0xdf 0x6c34 0x1f34c 0 ]
into 11 UTF-8 code units: [ 0x7a 0xc3 0x9f 0xe6 0xb0 0xb4 0xf0 0x9f 0x8d 0x8c 0 ]

참고문헌

  • C11 표준 (ISO/IEC 9899:2011):
  • 7.29.6.3.3 wcrtomb 함수 (p: 444)
  • K.3.9.3.1.1 wcrtomb_s 함수 (p: 647-648)
  • C99 표준 (ISO/IEC 9899:1999):
  • 7.24.6.3.3 wcrtomb 함수 (p: 390)

참고 항목

(C11)
와이드 문자를 멀티바이트 표현으로 변환
(함수)
(C95)
주어진 상태에서 다음 멀티바이트 문자를 와이드 문자로 변환
(함수)
C++ 문서 for wcrtomb