mbsrtowcs, mbsrtowcs_s

 

C

言語

ヘッダ

型サポート

プログラムユーティリティ

可変長引数サポート

エラー処理

動的メモリ管理

日付と時間のユーティリティ

文字列ライブラリ

アルゴリズム

数値演算

入出力サポート

ローカライゼーションサポート

アトミック操作(C11)

スレッドサポート(C11)

技術仕様書

 

文字列ライブラリ

バイト文字列

マルチバイト文字列

ワイド文字列

 

ヌル終端マルチバイト文字列

マルチバイト文字列とワイド文字列の変換
mbsinit (C95)
mbtowc mbstowcsmbstowcs_s (C11) btowc (C95) mbrtowc (C95) mbsrtowcsmbsrtowcs_s (C95)(C11) mbrtoc16 (C11) c16rtomb (C11) c32rtomb (C11) mbrtoc32 (C11)	mblen wctombwctomb_s (C11) wcstombswcstombs_s (C11) wctob (C95) wcrtombwcrtomb_s (C95)(C11) wcsrtombswcsrtombs_s (C95)(C11) mbrlen (C95)
型
mbstate_t (C95)

 

ヘッダ <wchar.h> で定義
	(1)
size_t mbsrtowcs(wchar_t* dst, constchar** src, size_t len, mbstate_t* ps );			(C95以上)
size_t mbsrtowcs(wchar_t*restrict dst, constchar**restrict src, size_t len,                   mbstate_t*restrict ps);			(C99以上)
errno_t mbsrtowcs_s(size_t*restrict retval,                      wchar_t*restrict dst, rsize_t dstsz,                      constchar**restrict src, rsize_t len,                      mbstate_t*restrict ps);		(2)	(C11以上)

1)*src によって最初の要素が指されている配列内の *ps の表す変換状態で始まるヌル終端マルチバイト文字シーケンスをワイド文字表現に変換します。 dst がヌルでなければ、変換された文字が dst の指す wchar_t 配列の連続する要素に格納されます。 最大 len 個のワイド文字が dst 配列に書き込まれます。 各マルチバイト文字は mbrtowc を呼び出したかのように変換されます。 変換は以下の場合に停止します。

* マルチバイトヌル文字が変換され格納された。 *src は NULL に設定され、 *ps は初期変換状態を表すように設定されます。

* 無効なマルチバイトシーケンス (現在の C のロケールに従った) に遭遇した。 *src は変換されなかった最初のマルチバイト文字の先頭を指すように設定されます。

* 格納される次のワイド文字が len を超える。 *src は変換されなかった最初のマルチバイト文字の先頭を指すように設定されます。 この条件は dst==NULL の場合はチェックされません。

2)(1) と同じですが、以下の点が異なります。

* 結果は出力引数 retval として返されます。

* len 個のワイド文字が書き込まれた後、ヌル文字が dst に書き込まれていなければ、 L'\0' が dst[len] に格納されます。 つまり、合計 len+1 個のワイド文字が書き込まれることを意味します。

* dst 配列を終端のヌルから dstsz まで上書きします。

* src と dst がオーバーラップしている場合、動作は未規定です。

* 以下のエラーが実行時に検出され、現在設定されている制約ハンドラ関数を呼びます。

• retval、 ps、 src または *src がヌルポインタ。
• dstsz または len が RSIZE_MAX/sizeof(wchar_t) より大きい (dst がヌルでなければ)。
• dstsz がゼロでない (dst がヌルでなければ)。
• *src 配列の最初の dstsz 個のマルチバイト文字内にヌル文字がなく、 len が dstsz より大きい (dst がヌルでなければ)。

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

引数

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

戻り値

1) 成功した場合は、文字配列に書き込まれた終端の L'\0' を除くワイド文字数を返します。 dst==NULL の場合は、長さが無制限であったならば書き込まれたであろうワイド文字数を返します。 変換エラーが発生した場合 (無効なマルチバイト文字に遭遇した場合) は、 (size_t)-1 を返し、 EILSEQ を errno に格納し、 *ps を未規定の状態にします。

2) 成功した場合はゼロを返し、 dst 書き込まれたまたは書き込まれるであろう終端のゼロを除くワイド文字数が *retval に格納されます。 エラーが発生した場合は非ゼロを返します。 実行時制約違反の場合は (size_t)-1 を *retval に格納し (retval がヌルでなければ)、 dst[0] を L'\0' に設定します (dst がヌルでなく、 dstmax がゼロでなく RSIZE_MAX より大きくなければ)。

例

Run this code

#include <stdio.h>#include <locale.h>#include <wchar.h>#include <string.h>   void print_as_wide(constchar* mbstr){mbstate_t state;memset(&state, 0, sizeof state);size_t len =1+ mbsrtowcs(NULL, &mbstr, 0, &state);wchar_t wstr[len]; mbsrtowcs(&wstr[0], &mbstr, len, &state);wprintf(L"Wide string: %ls \n", wstr);wprintf(L"The length, including L'\\0': %zu\n", len);}   int main(void){setlocale(LC_ALL, "en_US.utf8"); print_as_wide(u8"z\u00df\u6c34\U0001f34c");// u8"zß水🍌"}

出力:

Wide string: zß水🍌 The length, including L'\0': 5

参考文献

• C11 standard (ISO/IEC 9899:2011):

• 7.29.6.4.1 The mbsrtowcs function (p: 445)

• K.3.9.3.2.1 The mbsrtowcs_s function (p: 648-649)

• C99 standard (ISO/IEC 9899:1999):

• 7.24.6.4.1 The mbsrtowcs function (p: 391)

関連項目

mbstowcsmbstowcs_s (C11)	マルチバイト文字列をワイド文字列に変換します (関数)
mbrtowc (C95)	指定された状態を使用して次のマルチバイト文字をワイド文字に変換します (関数)
wcsrtombswcsrtombs_s (C95)(C11)	指定された状態を使用してワイド文字列をマルチバイト文字列に変換します (関数)
mbsrtowcs の C++リファレンス