Namespaces
Variants

mbstowcs, mbstowcs_s

From cppreference.net
C
Strings library
Null-terminated multibyte strings
헤더 파일에 정의됨 <stdlib.h>
(1)
size_t mbstowcs ( wchar_t * dst, const char * src, size_t len )
(C99 이전)
size_t mbstowcs ( wchar_t * restrict dst, const char * restrict src, size_t len )
(C99부터)
errno_t mbstowcs_s ( size_t * restrict retval, wchar_t * restrict dst,
rsize_t dstsz, const char * restrict src, rsize_t len ) ;
(2) (C11부터)
1) src 가 가리키는 첫 번째 요소부터 시작하는 배열에서 멀티바이트 문자 문자열을 와이드 문자 표현으로 변환합니다. 변환된 문자들은 dst 가 가리키는 배열의 연속된 요소들에 저장됩니다. 목적지 배열에는 최대 len 개의 와이드 문자만 기록됩니다.
각 문자는 mbtowc 호출처럼 변환되지만, mbtowc 변환 상태는 영향을 받지 않습니다. 다음의 경우 변환이 중단됩니다:
* 멀티바이트 널 문자가 변환되어 저장되었습니다.
* 현재 C 로캘에서 유효하지 않은 멀티바이트 문자가 발견되었습니다.
* 저장될 다음 와이드 문자가 len 을 초과할 경우
만약 src 와 dst 가 겹칠 경우, 동작은 정의되지 않음
2) (1) 과 동일하지만, 다음 사항이 다릅니다:
* 변환은 mbrtowc 에 의한 것처럼 수행되며, mbtowc 가 아닙니다
* 함수는 결과를 out-parameter로 반환합니다 retval
* null 문자가 len 개의 와이드 문자를 기록한 후 dst 에 기록되지 않았다면, L ' \0 ' 가 dst[len] 에 저장되며, 이는 총 len+1개의 와이드 문자가 기록됨을 의미합니다
* 만약 dst 가 널 포인터인 경우, 생성될 와이드 문자 수가 * retval 에 저장됨
* 해당 함수는 종료 널 문자부터 dstsz 까지 대상 배열을 파괴합니다
* 만약 src 와 dst 가 겹치는 경우, 동작은 명시되어 있지 않습니다.
* 다음 오류들은 런타임에 감지되며 현재 설치된 constraint handler 함수를 호출합니다:
  • retval 또는 src 가 null 포인터인 경우
  • dstsz 또는 len 이 RSIZE_MAX/sizeof(wchar_t) 보다 큰 경우 (단, dst 가 null이 아닐 때)
  • dstsz 가 0이 아닌 경우 (단, dst 가 null이 아닐 때)
  • src 배열의 첫 dstsz 개의 멀티바이트 문자들 중에 null 문자가 없고 len 이 dstsz 보다 큰 경우 (단, dst 가 null이 아닐 때)
모든 경계 검사 함수들과 마찬가지로, mbstowcs_s 는 구현체가 __STDC_LIB_EXT1__ 를 정의하고 사용자가 <stdlib.h> 를 포함하기 전에 __STDC_WANT_LIB_EXT1__ 를 정수 상수 1 로 정의한 경우에만 사용 가능함이 보장됩니다.

목차

참고 사항

대부분의 구현에서, mbstowcs 는 문자열을 처리하면서 mbstate_t 타입의 전역 정적 객체를 갱신하므로, 두 스레드에서 동시에 호출할 수 없습니다. 이러한 경우에는 mbsrtowcs 를 사용해야 합니다.

POSIX는 공통 확장을 명시합니다: dst 가 널 포인터인 경우, 이 함수는 변환되었을 때 dst 에 기록될 와이드 문자 수를 반환합니다. 유사한 동작이 mbstowcs_s 와 mbsrtowcs 에서 표준입니다.

매개변수

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

반환값

1) 성공 시, 대상 배열에 기록된 널 종료 문자 L ' \0 ' 를 제외한 와이드 문자 수를 반환합니다. 변환 오류 발생 시(유효하지 않은 멀티바이트 문자를 만난 경우), ( size_t ) - 1 를 반환합니다.
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 <stdlib.h>
#include <wchar.h>
int main(void)
{
    setlocale(LC_ALL, "en_US.utf8");
    const char* mbstr = u8"z\u00df\u6c34\U0001F34C"; // or u8"zß水🍌"
    wchar_t wstr[5];
    mbstowcs(wstr, mbstr, 5);
    wprintf(L"MB string: %s\n", mbstr);
    wprintf(L"Wide string: %ls\n", wstr);
}

출력: 

MB string: zß水🍌
Wide string: zß水🍌

참고문헌

  • C11 표준 (ISO/IEC 9899:2011):
  • 7.22.8.1 mbstowcs 함수 (p: 359)
  • K.3.6.5.1 mbstowcs_s 함수 (p: 611-612)
  • C99 표준 (ISO/IEC 9899:1999):
  • 7.20.8.1 mbstowcs 함수 (p: 323)
  • C89/C90 표준 (ISO/IEC 9899:1990):
  • 4.10.8.1 mbstowcs 함수

참조 항목

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