次の方法で共有

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 で終わることはありません。

重要

wcstr と mbstr が重なり合わず、変換するマルチバイト文字の数が count に適切に反映されていることを確認します。

解説

mbstowcs 関数は、mbstr が指す count 数までのマルチバイト文字を、現在のロケールに基づいて対応するワイド文字の文字列に変換します。 結果のワイド文字列は、 wcstrで表されるアドレスに格納されます。 結果は、mbtowc を複数回呼び出した場合と類似しています。 count の前かその発生時に 1 バイトの null 文字 ('\0') が検出されると、mbstowcs では null 文字をワイド文字の null 文字 (L'\0') に変換して停止します。 このため、wcstr のワイド文字の文字列が null 終了になるのは、変換中にマルチバイト null 文字が検出された場合だけです。 wcstr および mbstr が指すシーケンスが重なり合う場合、動作は未定義です。

wcstr 引数が NULL の場合、mbstowcs は変換によって得られるワイド文字数を返します。終端の null は含まれません。 正しい値を返すには、ソース文字列が null で終わっている必要があります。 結果のワイド文字列を null で終了する必要がある場合は、戻り値に 1 を追加します。

mbstr引数がNULLされている場合、またはcountが>INT_MAXされている場合は、「パラメーターの検証」で説明されているように、無効なパラメーター ハンドラー呼び出されます。 実行の継続が許可された場合、 errno が EINVAL に設定され、関数から -1 が返されます。

mbstowcs は、ロケールに依存するあらゆる動作に現在のロケールを使用します。_mbstowcs_l は、渡されたロケールを代わりに使用することを除いて同じです。 詳細については、「 Locale」を参照してください。

C++ では、これらの関数にテンプレートのオーバーロードがあります。このオーバーロードは、これらの関数に対応するセキュリティで保護された新しい関数を呼び出します。 詳細については、「セキュリティ保護されたテンプレート オーバーロード」を参照してください。

既定では、この関数のグローバル状態の適用対象は、アプリケーションになります。 この動作を変更するには、「CRT でのグローバル状態」を参照してください。

要件

ルーチンによって返される値 必須ヘッダー
mbstowcs <stdlib.h>
_mbstowcs_l <stdlib.h>

互換性の詳細については、「 Compatibility」を参照してください。

例

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

関連項目

データ変換
ロケール
マルチバイト文字のシーケンスの解釈
_mbclen、 mblen、 _mblen_l
mbtowc, _mbtowc_l
wcstombs, _wcstombs_l
wctomb, _wctomb_l
MultiByteToWideChar