wcsrtombs, wcsrtombs_s

ヘッダー `<wchar.h>` で定義
	(1)
size_t wcsrtombs( char dst, const wchar_t src, size_t len, mbstate_t ps );			(C95 以降) (C99まで)
size_t wcsrtombs( char restrict dst, const wchar_t restrict src, size_t len, mbstate_t restrict ps );			(C99以降)
errno_t wcsrtombs_s( size_t restrict retval, char restrict dst, rsize_t dstsz, const wchar_t *restrict src, rsize_t len, mbstate_t restrict ps );		(2)	(C11 以降)

1) *src が指す配列から、*ps で記述された変換状態から始まる、ワイド文字のシーケンスを、そのマルチバイト文字列表現に変換します。dst が NULL でない場合、変換された文字は dst が指す char 配列の連続する要素に格納されます。宛先配列には最大 len バイトまで書き込まれます。各文字は、wcrtomb の呼び出しのように変換されます。変換は以下の場合に停止します。

ヌル文字 L'\0' が変換され、格納された場合。この場合、格納されるバイトは、シフトシーケンス（必要であれば）に続いて '\0' であり、*src は NULL ポインタ値に設定され、*ps は初期シフト状態を表します。
現在の C ロケールで有効な文字に対応しない wchar_t が見つかった場合。*src は、変換されなかった最初のワイド文字を指すように設定されます。
格納される次のマルチバイト文字が len を超える場合。*src は、変換されなかった最初のワイド文字を指すように設定されます。dst が NULL ポインタの場合は、この条件はチェックされません。

2) 以下を除いて (1) と同じです。

関数は、結果を出力パラメータ retval として返します。
変換がヌル文字を書き込まずに停止した場合、関数は dst の次のバイトに '\0' を格納します。これは dst[len] または dst[dstsz] のいずれか早い方になる可能性があります（つまり、最大 len+1 または dstsz+1 バイトが書き込まれる可能性があります）。この場合、終端ヌル文字の前にシフトシーケンスが書き込まれないことがあります。
関数は、終端ヌル文字から dstsz までの宛先配列を上書きします。
src と dst が重複する場合、動作は未定義です。
すべての境界チェック関数と同様に、以下のエラーは実行時に検出され、現在インストールされている制約ハンドラ関数が呼び出されます。

retval、ps、src、または *src が NULL ポインタである。
dstsz または len が RSIZE_MAX より大きい（dst が NULL でない場合）。
dstsz がゼロでない（dst がヌルでない場合）。
len が dstsz より大きい場合、かつ dstsz に到達するまでに src 配列でヌルまたはエンコーディングエラーが発生しない場合（dst が NULL でない場合）。

すべての境界チェック関数と同様に、wcsrtombs_s が利用可能であると保証されるのは、実装によって __STDC_LIB_EXT1__ が定義されており、ユーザーが <wchar.h> をインクルードする前に __STDC_WANT_LIB_EXT1__ を整数定数 1 として定義した場合のみです。

dst	-	マルチバイト文字が格納されるワイド文字配列へのポインタ。
src	-	NULL で終端されるワイド文字列の最初の要素へのポインタへのポインタ。
len	-	`dst` が指す配列で利用可能なバイト数。
ps	-	変換状態オブジェクトへのポインタ。
dstsz	-	書き込まれる最大バイト数（`dst` 配列のサイズ）。
retval	-	結果が格納される size_t オブジェクトへのポインタ。

[編集] 戻り値

1) 成功した場合、dst が指す文字配列に書き込まれたバイト数（シフトシーケンスを含むが、終端の '\0' は除く）を返します。dst が NULL ポインタの場合、書き込まれたであろうバイト数を返します。変換エラー（無効なワイド文字が見つかった場合）の場合、(size_t)-1 を返し、EILSEQ を errno に格納し、*ps を未定義の状態のままにします。

2) 成功した場合、ゼロを返します（この場合、書き込まれた、または書き込まれたであろう終端ゼロを除くバイト数が *retval に格納されます）。エラーの場合、ゼロ以外を返します。実行時制約違反の場合、(size_t)-1 を *retval に格納します（retval が NULL でない場合）。また、dst[0] を '\0' に設定します（dst が NULL でない場合、または dstmax がゼロまたは RSIZE_MAX より大きい場合）。

[編集] 例

このコードを実行

#include <stdio.h>
#include <locale.h>
#include <string.h>
#include <wchar.h>
 
void print_wide(const wchar_t* wstr)
{
    mbstate_t state;
    memset(&state, 0, sizeof state);
    size_t len = 1 + wcsrtombs(NULL, &wstr, 0, &state);
    char mbstr[len];
    wcsrtombs(mbstr, &wstr, len, &state);
    printf("Multibyte string: %s\n", mbstr);
    printf("Length, including '\\0': %zu\n", len);
}
 
int main(void)
{
    setlocale(LC_ALL, "en_US.utf8");
    print_wide(L"z\u00df\u6c34\U0001f34c"); // or L"zß水🍌"
}

出力

Multibyte string: zß水🍌
Length, including '\0': 11

[編集] 参考文献

C17標準 (ISO/IEC 9899:2018)

7.29.6.4.2 The wcsrtombs function (p: 324-325)

K.3.9.3.2.2 The wcsrtombs_s function (p: 471-472)

C11標準 (ISO/IEC 9899:2011)

7.29.6.4.2 The wcsrtombs function (p: 446)

K.3.9.3.2.2 The wcsrtombs_s function (p: 649-651)

C99標準 (ISO/IEC 9899:1999)

7.24.6.4.2 The wcsrtombs function (p: 392)

[編集] 関連項目

wcstombswcstombs_s (C11)	ワイド文字列をナローマルチバイト文字列に変換する (関数) [編集]
wcrtombwcrtomb_s (C95)(C11)	与えられた状態で、ワイド文字をそのマルチバイト表現に変換する (関数) [編集]
mbsrtowcsmbsrtowcs_s (C95)(C11)	与えられた状態で、ナローマルチバイト文字列をワイド文字列に変換する (関数) [編集]
C++ ドキュメント（wcsrtombs）

コンパイラサポート
言語
ヘッダー
型サポート
プログラムユーティリティ
可変長引数関数のサポート
エラーハンドリング
動的メモリ管理
文字列ライブラリ
アルゴリズム
数値
日付と時刻のユーティリティ
入出力サポート
ローカライゼーションサポート
並行処理サポート (C11)
技術仕様
シンボルインデックス

cppreference.com

名前空間

変種

表示

操作

wcsrtombs, wcsrtombs_s

目次

[編集] パラメータ

[編集] 戻り値

[編集] 例

[編集] 参考文献

[編集] 関連項目

ナビゲーション

ツールボックス