mbstowcs、_mbstowcs_lmbstowcs, _mbstowcs_l

マルチバイト文字のシーケンスを、対応するワイド文字のシーケンスに変換します。Converts a sequence of multibyte characters to a corresponding sequence of wide characters. これらの関数のセキュリティを強化したバージョンについては、「mbstowcs_s、_mbstowcs_s_l」を参照してください。More secure versions of these functions are available; see mbstowcs_s, _mbstowcs_s_l.

構文Syntax

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

パラメーターParameters

wcstrwcstr
ワイド文字のシーケンスのアドレス。The address of a sequence of wide characters.

mbstrmbstr
null で終了するマルチバイト文字のシーケンスのアドレス。The address of a sequence of null terminated multibyte characters.

countcount
変換するマルチバイト文字の最大数。The maximum number of multibyte characters to convert.

localelocale
使用するロケール。The locale to use.

戻り値Return Value

場合mbstowcs元の文字列を変換が正常に変換されたマルチバイト文字の数を返します。If mbstowcs successfully converts the source string, it returns the number of converted multibyte characters. 場合、 wcstr引数がNULL、コピー先の文字列のワイド文字) の「必要なサイズを返します。If the wcstr argument is NULL, the function returns the required size (in wide characters) of the destination string. 場合mbstowcs無効なマルチバイト文字が検出された-1 を返します。If mbstowcs encounters an invalid multibyte character, it returns -1. 戻り値が場合カウント、ワイド文字の文字列が null で終わっていません。If the return value is count, the wide-character string is not null-terminated.

重要

いることを確認wcstrmbstr重複しないと変換するマルチバイト文字の数を正確に反映します。Ensure that wcstr and mbstr do not overlap, and that count correctly reflects the number of multibyte characters to convert.

RemarksRemarks

Mbstowcs関数はの最大数に変換カウントがマルチバイト文字が指すmbstrは対応するワイド文字の文字列に現在のロケールによって決まります。The mbstowcs function converts up to a maximum number of count multibyte characters pointed to by mbstr to a string of corresponding wide characters that are determined by the current locale. 結果として得られるワイド文字の文字列で表されるアドレスにある格納wcstrします。It stores the resulting wide-character string at the address represented by wcstr. 結果は、一連の呼び出しに似ていますmbtowcします。The result is similar to a series of calls to mbtowc. 場合mbstowcs前に、か、1 バイトの null 文字 ('\0') が発生したカウントnull 文字をワイド文字の null 文字 (L '\0') および停止変換が発生します。If mbstowcs encounters the single-byte null character ('\0') either before or when count occurs, it converts the null character to a wide-character null character (L'\0') and stops. したがって、ワイド文字の文字列でwcstrは null 終端 null 文字が変換中に発生した場合にのみです。Thus the wide-character string at wcstr is null-terminated only if a null character is encountered during conversion. によって、シーケンスを指している場合wcstrmbstr重なっているため、の動作は未定義です。If the sequences pointed to by wcstr and mbstr overlap, the behavior is undefined.

場合、 wcstr引数がNULLmbstowcs null 終端文字を含まない、変換によって得られるワイド文字の数を返します。If the wcstr argument is NULL, mbstowcs returns the number of wide characters that would result from conversion, not including a null terminator. 正しい値を返すには、ソース文字列が null で終わっている必要があります。The source string must be null-terminated for the correct value to be returned. 結果のワイド文字列を null で終了する必要がある場合は、戻り値に 1 を追加します。If you need the resulting wide character string to be null-terminated, add one to the returned value.

場合、 mbstr引数がNULL、またはカウントは > INT_MAX 」の説明に従って、無効なパラメーターハンドラーが呼び出されますパラメーターの検証です。If the mbstr argument is NULL, or if count is > INT_MAX, the invalid parameter handler is invoked, as described in Parameter Validation . Errno に設定されて実行の継続が許可された場合EINVAL関数は-1 を返します。If execution is allowed to continue, errno is set to EINVAL and the function returns -1.

mbstowcsロケールに依存する動作に現在のロケールを使用 _mbstowcs_l代わりに渡されたロケールを使用すると同じです。mbstowcs uses the current locale for any locale-dependent behavior; _mbstowcs_l is identical except that it uses the locale passed in instead. 詳細については、「 Locale」を参照してください。For more information, see Locale.

C++ では、これらの関数にテンプレートのオーバーロードがあります。このオーバーロードは、これらの関数に対応するセキュリティで保護された新しい関数を呼び出します。In C++, these functions have template overloads that invoke the newer, secure counterparts of these functions. 詳細については、「 Secure Template Overloads」を参照してください。For more information, see Secure Template Overloads.

必要条件Requirements

ルーチンによって返される値Routine 必須ヘッダーRequired header
mbstowcsmbstowcs <stdlib.h><stdlib.h>
_mbstowcs_l_mbstowcs_l <stdlib.h><stdlib.h>

互換性の詳細については、「 互換性」を参照してください。For additional compatibility information, see Compatibility.

Example

// 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

関連項目See also

データ変換Data Conversion
ロケールLocale
マルチバイト文字のシーケンスの解釈Interpretation of Multibyte-Character Sequences
_mbclen、mblen、_mblen_l_mbclen, mblen, _mblen_l
mbtowc、_mbtowc_lmbtowc, _mbtowc_l
wcstombs、_wcstombs_lwcstombs, _wcstombs_l
wctomb、_wctomb_lwctomb, _wctomb_l
MultiByteToWideCharMultiByteToWideChar