mbstowcs, _mbstowcs_l

멀티바이트 문자 시퀀스를 해당 와이드 문자 시퀀스로 변환합니다. 이러한 함수의 더 안전한 버전을 사용할 수 있습니다. mbstowcs_s, _mbstowcs_s_l(을)를 참조하세요.

구문

size_t mbstowcs(
   wchar_t *wcstr,
   const char *mbstr,
   size_t count
);
size_t _mbstowcs_l(
   wchar_t *wcstr,
   const char *mbstr,
   size_t count,
   _locale_t locale
);
template <size_t size>
size_t mbstowcs(
   wchar_t (&wcstr)[size],
   const char *mbstr,
   size_t count
); // C++ only
template <size_t size>
size_t _mbstowcs_l(
   wchar_t (&wcstr)[size],
   const char *mbstr,
   size_t count,
   _locale_t locale
); // C++ only

매개 변수

wcstr
와이드 문자 시퀀스의 주소입니다.

mbstr
null로 끝나는 멀티바이트 문자 시퀀스의 주소입니다.

count
변환할 멀티바이트 문자의 최대 수입니다.

locale
사용할 로캘입니다.

반환 값

mbstowcs가 소스 문자열을 성공적으로 변환하는 경우 변환된 멀티바이트 문자 수를 반환합니다. wcstr 인수가 NULL인 경우 이 함수는 대상 문자열에 필요한 크기(와이드 문자)를 반환합니다. 잘못된 멀티바이트 문자가 발견되면 mbstowcs -1을 반환합니다. 반환 값이 count면 와이드 문자열이 null로 종료되지 않습니다.

Important

wcstr 및 mbstr이 겹치지 않고 count가 변환할 멀티바이트 문자 수를 정확하게 반영하도록 합니다.

설명

mbstowcs 함수는 mbstr이 가리키는 count 멀티바이트 문자의 최대 수를 현재 로캘에 따라 결정된 해당 와이드 문자의 문자열로 변환합니다. 결과 와이드 문자열을 나타내는 주소에 저장합니다 wcstr. 결과는 일련의 mbtowc 호출과 유사합니다. 단일 바이트 null 문자('\0')가 발생할 경우 mbstowcs count null 문자를 와이드 문자 null 문자(L'\0')로 변환하고 중지합니다. 따라서 wcstr의 와이드 문자열은 변환 중에 null 문자가 발견되는 경우에만 null로 끝납니다. wcstr 및 mbstr이 가리키는 시퀀스가 겹치는 경우 동작이 정의되지 않습니다.

wcstr 인수가 NULL이면 mbstowcs는 변환되는 와이드 문자 수를 반환하며 null 종결자를 포함하지 않습니다. 올바른 값을 반환하려면 소스 문자열이 null로 끝나야 합니다. 결과 와이드 문자열이 null로 끝나야 하는 경우 반환된 값에 추가하세요.

인수가 mbstr NULL있는 경우 또는 이 인수인 >INT_MAX경우 count 매개 변수 유효성 검사에 설명된 대로 잘못된 매개 변수 처리기가 호출됩니다. 계속해서 실행하도록 허용된 경우 errno 는 EINVAL 로 설정되고 함수는 -1을 반환합니다.

mbstowcs는 로캘 종속 동작에 현재 로캘을 사용하고 _mbstowcs_l은 전달된 로캘을 대신 사용한다는 점을 제외하고는 동일합니다. 자세한 내용은 Locale을 참조하세요.

C++에서 이러한 함수는 보다 최신의 보안 대응 함수를 호출하는 템플릿 오버로드를 갖고 있습니다. 자세한 내용은 안전한 템플릿 오버로드를 참조하세요.

기본적으로 이 함수의 전역 상태는 애플리케이션으로 범위가 지정됩니다. 이 동작을 변경하려면 CRT 전역 상태를 참조하세요.

요구 사항

루틴에서 반환된 값	필수 헤더
mbstowcs	<stdlib.h>
_mbstowcs_l	<stdlib.h>

호환성에 대한 자세한 내용은 호환성을 참조하세요.

예시

// crt_mbstowcs.c
// compile with: /W3
// illustrates the behavior of the mbstowcs function

#include <stdlib.h>
#include <stdio.h>
#include <locale.h>

int main( void )
{
    size_t size;
    int nChar = 2; // number of characters to convert
    int requiredSize;

    unsigned char    *pmbnull  = NULL;
    unsigned char    *pmbhello = NULL;
    char* localeInfo;

    wchar_t *pwchello = L"\x3042\x3043"; // 2 Hiragana characters
    wchar_t *pwc;

    /* Enable the Japanese locale and codepage */
    localeInfo = setlocale(LC_ALL, "Japanese_Japan.932");
    printf("Locale information set to %s\n", localeInfo);

    printf( "Convert to multibyte string:\n" );

    requiredSize = wcstombs( NULL, pwchello, 0); // C4996
    // Note: wcstombs is deprecated; consider using wcstombs_s
    printf("   Required Size: %d\n", requiredSize);

    /* Add one to leave room for the null terminator. */
    pmbhello = (unsigned char *)malloc( requiredSize + 1);
    if (! pmbhello)
    {
        printf("Memory allocation failure.\n");
        return 1;
    }
    size = wcstombs( pmbhello, pwchello, requiredSize + 1); // C4996
    // Note: wcstombs is deprecated; consider using wcstombs_s
    if (size == (size_t) (-1))
    {
        printf("Couldn't convert string. Code page 932 may"
                " not be available.\n");
        return 1;
    }
    printf( "   Number of bytes written to multibyte string: %u\n",
            (unsigned int) size );
    printf( "   Hex values of the" );
    printf( " multibyte characters: %#.2x %#.2x %#.2x %#.2x\n",
            pmbhello[0], pmbhello[1], pmbhello[2], pmbhello[3] );
    printf( "   Codepage 932 uses 0x81 to 0x9f as lead bytes.\n\n");

    printf( "Convert back to wide-character string:\n" );

    /* Assume we don't know the length of the multibyte string.
     Get the required size in characters, and allocate enough space. */

    requiredSize = mbstowcs(NULL, pmbhello, 0); // C4996
    /* Add one to leave room for the null terminator */
    pwc = (wchar_t *)malloc( (requiredSize + 1) * sizeof( wchar_t ));
    if (! pwc)
    {
        printf("Memory allocation failure.\n");
        return 1;
    }
    size = mbstowcs( pwc, pmbhello, requiredSize + 1); // C4996
    if (size == (size_t) (-1))
    {
       printf("Couldn't convert string--invalid multibyte character.\n");
    }
    printf( "   Characters converted: %u\n", (unsigned int)size );
    printf( "   Hex value of first 2" );
    printf( " wide characters: %#.4x %#.4x\n\n", pwc[0], pwc[1] );
    free(pwc);
    free(pmbhello);
}

Locale information set to Japanese_Japan.932
Convert to multibyte string:
   Required Size: 4
   Number of bytes written to multibyte string: 4
   Hex values of the  multibyte characters: 0x82 0xa0 0x82 0xa1
   Codepage 932 uses 0x81 to 0x9f as lead bytes.

Convert back to wide-character string:
   Characters converted: 2
   Hex value of first 2 wide characters: 0x3042 0x3043

참고 항목

데이터 변환
Locale
멀티바이트 문자 시퀀스 해석
_mbclen, , mblen_mblen_l
mbtowc, _mbtowc_l
wcstombs, _wcstombs_l
wctomb, _wctomb_l
MultiByteToWideChar