Namespaces
Variants

mbsrtowcs, mbsrtowcs_s

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

wchar_t * restrict dst, rsize_t dstsz,
const char ** restrict src, rsize_t len,

mbstate_t * restrict ps ) ;
(2) (C11부터)
1) *ps 로 기술된 변환 상태에서 시작하여, * src 가 가리키는 첫 번째 요소부터 시작하는 배열의 널 종료 멀티바이트 문자 시퀀스를 와이드 문자 표현으로 변환합니다. dst 가 null이 아닌 경우, 변환된 문자들은 dst 가 가리키는 wchar_t 배열의 연속된 요소들에 저장됩니다. 최대 len 개의 와이드 문자만 목적 배열에 기록됩니다. 각 멀티바이트 문자는 mbrtowc 를 호출하는 것처럼 변환됩니다. 변환은 다음 경우에 중단됩니다:
  • 멀티바이트 널 문자가 변환되어 저장된 경우. * src 는 null 포인터 값으로 설정되고 *ps 는 초기 시프트 상태를 나타냅니다.
  • (현재 C 로케일에 따라) 유효하지 않은 멀티바이트 문자를 만난 경우. * src 는 변환되지 않은 첫 번째 멀티바이트 문자의 시작을 가리키도록 설정됩니다.
  • 저장될 다음 와이드 문자가 len 을 초과할 경우. * src 는 변환되지 않은 첫 번째 멀티바이트 문자의 시작을 가리키도록 설정됩니다. 이 조건은 dst 가 null 포인터인 경우 검사되지 않습니다.
2) (1) 과 동일하지만, 다음 사항이 다릅니다:
  • 함수가 결과를 출력 매개변수 retval 로 반환합니다
  • len 개의 와이드 문자를 기록한 후 dst 에 널 문자가 기록되지 않은 경우, L ' \0 ' 가 dst[len] 에 저장됩니다. 즉 총 len+1개의 와이드 문자가 기록됨을 의미합니다
  • 함수는 종료 널 문자부터 dstsz 까지 대상 배열을 덮어씁니다
  • src 와 dst 가 겹치는 경우 동작은 명시되지 않습니다
  • 다음 오류들이 런타임에 감지되어 현재 설치된 제약 처리기 함수를 호출합니다:
  • retval , ps , src , 또는 * src 가 널 포인터인 경우
  • dstsz 또는 len 이 RSIZE_MAX/sizeof(wchar_t) 보다 큰 경우 ( dst 가 null이 아닌 경우)
  • dstsz 가 0이 아닌 경우 ( dst 가 null이 아닌 경우)
  • dstsz 개의 멀티바이트 문자 내에 널 문자가 없고 len 이 dstsz 보다 큰 경우 ( dst 가 null이 아닌 경우)
모든 경계 검사 함수와 마찬가지로, mbsrtowcs_s 는 구현에서 __STDC_LIB_EXT1__ 가 정의되고 사용자가 <wchar.h> 를 포함하기 전에 __STDC_WANT_LIB_EXT1__ 를 정수 상수 1 로 정의한 경우에만 사용 가능함이 보장됩니다

목차

매개변수

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

반환값

1) 성공 시, 널 종료 문자 L ' \0 ' 를 제외하고 문자 배열에 기록된 와이드 문자 수를 반환합니다. dst 가 널 포인터인 경우, 무제한 길이가 주어졌을 때 기록되었을 와이드 문자 수를 반환합니다. 변환 오류 시(유효하지 않은 멀티바이트 문자를 만난 경우), ( size_t ) - 1 를 반환하고, EILSEQ 을 errno 에 저장하며, * ps 를 지정되지 않은 상태로 둡니다.
2) 성공 시 0을 반환하며 (이 경우, 널 종료 문자를 제외하고 dst 에 기록되었거나 기록될 와이드 문자의 개수가 * retval 에 저장됨), 오류 발생 시 0이 아닌 값을 반환합니다. 런타임 제약 조건 위반 시, ( size_t ) - 1 를 * retval 에 저장하며 ( retval 가 null이 아닌 경우), dst [ 0 ] 를 L ' \0 ' 로 설정합니다 ( dst 가 null이 아니고, dstmax 가 0이 아니며 RSIZE_MAX 보다 크지 않은 경우).

예제

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

출력: 

Wide string: zß水🍌
The length, including L'\0': 5

참조문헌

  • C11 표준 (ISO/IEC 9899:2011):
  • 7.29.6.4.1 mbsrtowcs 함수 (p: 445)
  • K.3.9.3.2.1 mbsrtowcs_s 함수 (p: 648-649)
  • C99 표준 (ISO/IEC 9899:1999):
  • 7.24.6.4.1 mbsrtowcs 함수 (p: 391)

참고 항목

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