Namespaces
Variants

    mbstowcs, mbstowcs_s

    cppreference.net에서
     
    C
     
    문자열 라이브러리
     
    널 종료 멀티바이트 문자열
     
    헤더에 정의됨 <stdlib.h> 
    size_t mbstowcs( wchar_t* dst, const char* src, size_t len)
    		(1) (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
    • 가 아닙니다. 함수는 결과를 출력 매개변수 retval
    • 로 반환합니다. dst에 널 문자가 기록되지 않은 경우 len개의 와이드 문자가 기록된 후, L'\0'이 dst[len]에 저장되며, 이는 총 len+1개의 와이드 문자가 기록됨을 의미합니다.
    • dst이 널 포인터인 경우, 생성될 와이드 문자 수가 *retval
    • 에 저장됩니다. 함수는 종료 널부터 dstsz
    • 까지 대상 배열을 덮어씁니다. src와 dst이 겹치는 경우, 동작은 명세되지 않습니다.
    • 런타임에 다음 오류가 감지되며, 현재 설치된 제약 처리기 함수를 호출합니다:
    • retval 또는 src이 널 포인터인 경우
    • dstsz 또는 len이 RSIZE_MAX / sizeof(wchar_t)보다 큰 경우 (dst이 널이 아닌 경우)
    • dstsz이 0이 아닌 경우 (dst이 널이 아닌 경우)
    • dstsz 배열의 처음 src 멀티바이트 문자에 널 문자가 없고 len이 dstsz보다 큰 경우 (dst이 널이 아닌 경우)
    모든 경계 검사 함수와 마찬가지로, mbstowcs_s은 __STDC_LIB_EXT1__이 구현에 의해 정의되고 사용자가 __STDC_WANT_LIB_EXT1__를 1을 포함하기 전에 정수 상수 <stdlib.h>로 정의한 경우에만 사용 가능합니다.

    참고

    대부분의 구현에서, 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을 반환합니다(이 경우 종료되는 0을 제외하고 dst에 기록되었거나 기록될 와이드 문자의 개수가 *retval에 저장됩니다), 오류 시 0이 아닌 값을 반환합니다. 런타임 제약 조건 위반 시, (size_t)-1을 *retval에 저장하고(retval이 null이 아닌 경우), dst[0]을 L'\0'으로 설정합니다(dst이 null이거나 dstmax이 0이거나 RSIZE_MAX보다 큰 경우 제외).

    예제

    이 코드 실행하기
    #include <locale.h>
#include <stdio.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ß水🍌

    참조

    • C23 표준 (ISO/IEC 9899:2024):
    • 7.22.8.1 mbstowcs 함수 (p: TBD)
    • K.3.6.5.1 mbstowcs_s 함수 (p: TBD)
    • C17 표준 (ISO/IEC 9899:2018):
    • 7.22.8.1 mbstowcs 함수 (p: TBD)
    • K.3.6.5.1 mbstowcs_s 함수 (p: TBD)
    • 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++ 문서를 위한 mbstowcs