wcrtomb

[アーティクル]
09/17/2008

更新 : 2007 年 11 月

ワイド文字をマルチバイト文字の表現に変換します。この関数のセキュリティが強化されたバージョンについては、「wcrtomb_s」を参照してください。

size_t wcrtomb(
   char *mbchar,
   wchar_t wchar,
   mbstate_t *mbstate
);
template <size_t size>
size_t wcrtomb(
   char (&mbchar)[size],
   wchar_t wchar,
   mbstate_t *mbstate
); // C++ only

パラメータ

[出力] mbchar
結果としてマルチバイトに変換された文字。
[入力] wchar
変換するワイド文字。
[入力] mbstate
mbstate_t オブジェクトへのポインタ。

戻り値

変換されたマルチバイト文字を表すのに必要なバイト数を返します。エラーが発生した場合は -1 を返します。

解説

wcrtomb 関数は、wchar に格納されている値のワイド文字を変換し mbchar で表すアドレスに格納します。このとき、変換は mbstate に含まれる指定された変換状態から始められます。戻り値は、対応するマルチバイト文字を表すのに必要なバイト数ですが、MB_CUR_MAX を超えるバイト数は返しません。

mbstate が null の場合は、mbchar の変換状態を含む mbstate_t 内部オブジェクトが使用されます。wchar 文字シーケンスを対応するマルチバイト文字で表現できない場合は、-1 が返され、errno が EILSEQ に設定されます。

wcrtomb 関数は、再起動できるかどうかに関して、wctomb、_wctomb_l と異なります。変換状態は、同じまたは他の再起動可能な関数を後で呼び出すために mbstate に格納されます。再起動可能な関数と再起動不可能な関数を混在させた場合は、予測できない結果になる可能性があります。たとえば、後で wcstombs ではなく wcsrtombs を呼び出す場合、アプリケーションは wcsnlen ではなく wcsrlen を使用します。

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

例外

wcrtomb 関数は、この関数の実行中および mbstate が null の場合に setlocale を呼び出す関数が現在のスレッドにない限り、マルチスレッドセーフです。

使用例

// crt_wcrtomb.c
// compile with: /W3
// This program converts a wide character
// to its corresponding multibyte character.

#include <string.h>
#include <stdio.h>
#include <wchar.h>

int main( void )
{
    size_t      sizeOfCovertion = 0;
    mbstate_t   mbstate;
    char        mbStr = 0;
    wchar_t*    wcStr = L"Q";

    // Reset to initial conversion state
    memset(&mbstate, 0, sizeof(mbstate));

    sizeOfCovertion = wcrtomb(&mbStr, *wcStr, &mbstate); // C4996
    // Note: wcrtomb is deprecated; consider using wcrtomb_s instead
    if (sizeOfCovertion > 0)
    {
        printf("The corresponding wide character \"");
        wprintf(L"%s\"", wcStr);
        printf(" was converted to the \"%c\" ", mbStr);
        printf("multibyte character.\n");
    }
    else
    {
        printf("No corresponding multibyte character "
               "was found.\n");
    }
}

The corresponding wide character "Q" was converted to the "Q" multibyte character.