Namespaces
Variants

wcsrtombs, wcsrtombs_s

From cppreference.net
C
Strings library
Null-terminated multibyte strings
헤더 파일에 정의됨 <wchar.h>
(1)
size_t wcsrtombs ( char * dst, const wchar_t ** src, size_t len, mbstate_t * ps ) ;
(C95부터)
(C99까지)
size_t wcsrtombs ( char * restrict dst, const wchar_t ** restrict src, size_t len,
mbstate_t * restrict ps ) ;
(C99부터)
errno_t wcsrtombs_s ( size_t * restrict retval, char * restrict dst, rsize_t dstsz,

const wchar_t ** restrict src, rsize_t len,

mbstate_t * restrict ps ) ;
(2) (C11부터)
1) * src 가 가리키는 첫 번째 요소를 갖는 배열로부터 와이드 문자 시퀀스를, * ps 로 기술된 변환 상태에서 시작하는 좁은 멀티바이트 표현으로 변환합니다. dst 가 null이 아닌 경우, 변환된 문자들은 dst 가 가리키는 char 배열의 연속된 요소들에 저장됩니다. 최대 len 바이트까지 대상 배열에 기록됩니다. 각 문자는 wcrtomb 호출처럼 변환됩니다. 변환은 다음 경우에 중단됩니다:
  • null 문자 L ' \0 ' 가 변환되어 저장된 경우. 이 경우 저장되는 바이트들은 (필요한 경우) 언시프트 시퀀스와 그 뒤를 따르는 ' \0 ' 입니다. * src 는 null 포인터 값으로 설정되고 * ps 는 초기 시프트 상태를 나타냅니다.
  • 현재 C 로캘에서 유효한 문자에 해당하지 않는 wchar_t 를 발견한 경우. * src 는 변환되지 않은 첫 번째 와이드 문자를 가리키도록 설정됩니다.
  • 저장될 다음 멀티바이트 문자가 len 를 초과할 경우. * src 는 변환되지 않은 첫 번째 와이드 문자를 가리키도록 설정됩니다. 이 조건은 dst 가 null 포인터인 경우 검사되지 않습니다.
2) (1) 과 동일하지만, 다음 사항이 다릅니다:
  • 함수가 결과를 아웃-파라미터 retval 로 반환합니다
  • 변환이 널 문자를 쓰지 않고 중단되면, 함수는 ' \0 ' 를 dst 의 다음 바이트에 저장합니다(이는 dst [ len ] 또는 dst [ dstsz ] 중 먼저 도달하는 위치일 수 있음). 이 경우, 종료 널 문자 앞에 unshift 시퀀스가 작성되지 않을 수 있습니다.
  • 함수는 종료 널 문자부터 dstsz 까지 대상 배열을 덮어씁니다
  • 만약 src 와 dst 가 겹치면 동작은 명시되지 않습니다
  • 다음 오류들은 런타임에 감지되며 현재 설치된 constraint handler 함수를 호출합니다:
  • retval , ps , src , 또는 * src 가 널 포인터인 경우
  • dstsz 또는 len 이 RSIZE_MAX 보다 큰 경우(단, dst 가 null이 아닐 때)
  • dstsz 가 0이 아닌 경우(단, dst 가 null이 아닐 때)
  • len 이 dstsz 보다 크고 변환이 dstsz 에 도달할 때까지 src 배열에서 널 또는 인코딩 오류를 만나지 않는 경우(단, dst 가 null이 아닐 때)
모든 bounds-checked 함수들과 마찬가지로, wcsrtombs_s 는 구현에 의해 __STDC_LIB_EXT1__ 가 정의되고 사용자가 <wchar.h> 를 포함하기 전에 __STDC_WANT_LIB_EXT1__ 를 정수 상수 1 로 정의한 경우에만 사용 가능함이 보장됩니다.

목차

매개변수

dst - 멀티바이트 문자가 저장될 좁은 문자 배열에 대한 포인터
src - 널 종료 와이드 문자열의 첫 번째 요소에 대한 포인터의 포인터
len - dst가 가리키는 배열에서 사용 가능한 바이트 수
ps - 변환 상태 객체에 대한 포인터
dstsz - 기록될 최대 바이트 수 ( dst 배열의 크기)
retval - 결과가 저장될 size_t 객체에 대한 포인터

반환값

1) 성공 시, dst 가 가리키는 첫 번째 요소를 시작으로 하는 문자 배열에 기록된 바이트 수(시프트 시퀀스를 포함하지만 종료 ' \0 ' 는 제외)를 반환합니다. dst 가 null 포인터인 경우, 기록되었을 바이트 수를 반환합니다. 변환 오류 시(유효하지 않은 와이드 문자를 만난 경우), ( size_t ) - 1 를 반환하고, EILSEQ 를 errno 에 저장하며, * ps 를 미지정 상태로 둡니다.
2) 성공 시 0을 반환하며(이 경우, null 종결자를 제외하고 dst 에 기록되었거나 기록될 바이트 수가 * retval 에 저장됨), 오류 시 0이 아닌 값을 반환합니다. 런타임 제약 조건 위반 시, ( size_t ) - 1 을 * retval 에 저장하고( retval 이 null이 아닌 경우), dst [ 0 ] 을 ' \0 ' 으로 설정합니다( dst 가 null이거나 dstmax 가 0이거나 RSIZE_MAX 보다 큰 경우는 제외).

예제

이 코드 실행 
#include <stdio.h>
#include <locale.h>
#include <string.h>
#include <wchar.h>
void print_wide(const wchar_t* wstr)
{
    mbstate_t state;
    memset(&state, 0, sizeof state);
    size_t len = 1 + wcsrtombs(NULL, &wstr, 0, &state);
    char mbstr[len];
    wcsrtombs(mbstr, &wstr, len, &state);
    printf("Multibyte string: %s\n", mbstr);
    printf("Length, including '\\0': %zu\n", len);
}
int main(void)
{
    setlocale(LC_ALL, "en_US.utf8");
    print_wide(L"z\u00df\u6c34\U0001f34c"); // or L"zß水🍌"
}

출력: 

Multibyte string: zß水🍌
Length, including '\0': 11

참고문헌

  • C17 표준 (ISO/IEC 9899:2018):
  • 7.29.6.4.2 wcsrtombs 함수 (p: 324-325)
  • K.3.9.3.2.2 wcsrtombs_s 함수 (p: 471-472)
  • C11 표준 (ISO/IEC 9899:2011):
  • 7.29.6.4.2 wcsrtombs 함수 (p: 446)
  • K.3.9.3.2.2 wcsrtombs_s 함수 (p: 649-651)
  • C99 표준 (ISO/IEC 9899:1999):
  • 7.24.6.4.2 wcsrtombs 함수 (p: 392)

참고 항목

(C11)
와이드 문자열을 좁은 멀티바이트 문자 문자열로 변환
(함수)
(C95) (C11)
상태 정보를 사용하여 와이드 문자를 멀티바이트 표현으로 변환
(함수)
(C95) (C11)
상태 정보를 사용하여 좁은 멀티바이트 문자 문자열을 와이드 문자열로 변환
(함수)
C++ 문서 for wcsrtombs