wcsrtombs

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

更新 : 2007 年 11 月

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

size_t wcsrtombs(
   char *mbstr,
   const wchar_t **wcstr,
   sizeof count,
   mbstate_t *mbstate
);
template <size_t size>
size_t wcsrtombs(
   char (&mbstr)[size],
   const wchar_t **wcstr,
   sizeof count,
   mbstate_t *mbstate
); // C++ only

パラメータ

[出力] mbstr
変換された結果のマルチバイト文字列のアドレス。
[入力] wcstr
変換されるワイド文字列の場所を間接的に示します。
[入力] count
変換される文字数。
[入力] mbstate
mbstate_t 変換状態オブジェクトへのポインタ。

戻り値

正常に変換されたバイト数を返します。ただし、null で終わる null バイトがある場合、その null バイトはバイト数に含まれません。エラーが発生した場合は -1 を返します。

解説

wcsrtombs 関数は、ワイド文字の文字列を wcstr に間接的に指した値から変換し mbstr のアドレスに格納します。このとき、変換は mbstate に含まれる指定された変換状態から始められます。変換は、文字ごとに継続して行われます。変換が終了するのは、null で終わるワイド文字が検出されたとき、対応する文字が検出されなくなったとき、または次の文字が count に指定されている制限を超えたときです。count に指定した値以内で wcsrtombs 関数がワイド文字の null 文字 (L'\0') を検出すると、8 ビットの 0 に変換して停止します。

したがって、mbstr のマルチバイト文字の文字列が null で終わるのは、wcsrtombs 関数が変換時にワイド文字の null 文字を検出した場合だけです。wcstr と mbstr が指すシーケンスが重複する場合、wcsrtombs の動作は未定義です。wcsrtombs は、現在のロケールの LC_TYPE カテゴリの影響を受けます。

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

mbstr 引数が NULL の場合、wcsrtombs は変換先文字列に必要なサイズをバイト数で返します。mbstate が null の場合は、内部 mbstate_t 変換状態が使用されます。wchar 文字シーケンスを対応するマルチバイト文字で表現できない場合は、-1 が返され、errno が EILSEQ に設定されます。

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

例外

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

使用例

// crt_wcsrtombs.cpp
// compile with: /W3
// This code example converts a wide
// character string into a multibyte
// character string.

#include <stdio.h>
#include <memory.h>
#include <wchar.h>
#include <errno.h>

#define MB_BUFFER_SIZE 100

int main()
{
    const wchar_t   wcString[] = 
                    {L"Every good boy does fine."};
    const wchar_t   *wcsIndirectString = wcString;
    char            mbString[MB_BUFFER_SIZE];
    size_t          countConverted;
    mbstate_t       mbstate;

    // Reset to initial shift state
    ::memset((void*)&mbstate, 0, sizeof(mbstate));

    countConverted = wcsrtombs(mbString, &wcsIndirectString,
                               MB_BUFFER_SIZE, &mbstate); // C4996
    // Note: wcsrtombs is deprecated; consider using wcsrtombs_s
    if (errno == EILSEQ)
    {
        printf( "An encoding error was detected in the string.\n" );
    }
    else 
    {
        printf( "The string was successfuly converted.\n" );
    }
}

The string was successfuly converted.