wcsrtombs

  • [アーティクル]

ワイド文字の文字列をマルチバイト文字の文字列表現に変換します。 この関数のセキュリティが強化されたバージョンについては、「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 バイトがあっても含まれません)。それ以外の場合は、エラーが発生した場合に -1 を返します。

解説

wcsrtombs 関数は、mbstate に含まれる指定された変換の状態で始まるワイド文字の文字列を、wcstr で間接的に指されている値から mbstr のアドレスに変換します。 null で終了するワイド文字が発生した後、または対応しない文字が発生するか、次の文字が count に含まれる制限を超えるまで、各文字の変換が継続されます。 wcsrtombs は、count の発生前または発生時にワイド文字の null 文字 (L'\0') を検出すると、それを 8 ビットの 0 に変換して停止します。

このため、mbstr のマルチバイト文字の文字列が null 終了になるのは、wcsrtombs が変換中にワイド文字の null 文字を検出した場合だけです。 wcstr および mbstr が指すシーケンスが重なり合う場合、wcsrtombs の動作は未定義です。 wcsrtombs は、現在のロケールの LC_TYPE カテゴリの影響を受けます。

wcsrtombs関数は、再起動可能性によって_wcstombs_lwcstombsとは異なります。 同じ関数または再開可能な他の関数の後続の呼び出しのために、変換状態が mbstate に格納されます。 再開可能な関数と再開不可能な関数を混用した場合、結果は未定義です。 たとえば、アプリケーションは wcsrlen を使用し、wcsnlen は使用しないことがあります。これは、後続の呼び出しで wcsrtombs を使用しており、wcstombs は使用しない場合です。

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

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

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

例外

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

例

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

要件

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

関連項目

データ変換
ロケール
マルチバイト文字のシーケンスの解釈
wcrtomb
wcrtomb_s
wctomb, _wctomb_l
wcstombs, _wcstombs_l
mbsinit