mbstowcs, mbstowcs_s

 

C

コンパイラサポート

言語

ヘッダー

型サポート

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

可変長引数関数のサポート

エラーハンドリング

動的メモリ管理

文字列ライブラリ

アルゴリズム

数値

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

入出力サポート

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

並行処理サポート (C11)

技術仕様

シンボルインデックス

 

文字列ライブラリ

ヌル終端バイト文字列

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

ヌル終端ワイド文字列

 

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

関数
ワイド文字/マルチバイト文字変換
mbsinit (C95)
mbstowcsmbstowcs_s (C11) btowc (C95) mbrtowc (C95) mbsrtowcsmbsrtowcs_s (C95)(C11)   mbrtoc8 (C23) c8rtomb (C23) mbrtoc16 (C11) c16rtomb (C11) c32rtomb (C11) mbrtoc32 (C11)	mblen mbtowc wctombwctomb_s (C11) wcstombswcstombs_s (C11) wctob (C95) wcrtombwcrtomb_s (C95)(C11) wcsrtombswcsrtombs_s (C95)(C11) mbrlen (C95)
型
mbstate_t (C95) char8_t (C23)	char16_t (C11) char32_t (C11)
マクロ
MB_LEN_MAX	MB_CUR_MAX

 

ヘッダー <stdlib.h> で定義
	(1)
size_t mbstowcs( wchar_t          *dst, const char          *src, size_t len)			(C99まで)
size_t mbstowcs( wchar_t *restrict dst, const char *restrict src, size_t len)			(C99以降)
errno_t mbstowcs_s(size_t *restrict retval, wchar_t *restrict dst,                   rsize_t dstsz, const char *restrict src, rsize_t len);		(2)	(C11 以降)

1) multibyte 文字列を、src が指す配列の最初の要素から、そのワイド文字表現に変換します。変換された文字は、dst が指す配列の successive 要素に格納されます。宛先配列には、len 文字を超えるワイド文字は書き込まれません。

各文字は mbtowc を呼び出したかのように変換されますが、mbtowc の変換状態は影響を受けません。変換は、次のいずれかの場合に停止します。

* multibyte のヌル文字が変換され、格納された場合。

* 現在の C ロケールで無効な multibyte 文字が見つかった場合。

* 次に格納されるワイド文字が len を超える場合。

src と dst が重複する場合、動作は未定義です。

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

* 変換は mbrtowc によるもので、mbtowc によるものではありません。

* 関数は、その結果を out-parameter retval として返します。

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

* dst がヌルポインタの場合、生成されるワイド文字の数が *retval に格納されます。

* 関数は、終端ヌル文字から dstsz までの宛先配列を上書きします。

* src と dst が重複する場合、動作は未指定です。

* 次のエラーは実行時に検出され、現在インストールされている 制約ハンドラ 関数が呼び出されます。

• retval または src がヌルポインタである。
• dstsz または len が RSIZE_MAX/sizeof(wchar_t) より大きい（dst がヌルでない場合）。
• dstsz がゼロでない（dst がヌルでない場合）。
• src 配列の最初の dstsz 文字の multibyte 文字の中にヌル文字がなく、len が dstsz より大きい（dst がヌルでない場合）。

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

注記

ほとんどの実装では、mbstowcs は文字列の処理中に mbstate_t 型のグローバル静的オブジェクトを更新するため、2つのスレッドから同時に呼び出すことはできません。このような場合は、mbsrtowcs を使用する必要があります。

POSIX は一般的な拡張機能を指定しています。dst がヌルポインタの場合、この関数は変換された場合に dst に書き込まれるワイド文字の数を返します。同様の動作は、mbstowcs_s および mbsrtowcs の標準です。

パラメータ

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

戻り値

1) 成功した場合、宛先配列に書き込まれた、終端の L'\0' を除くワイド文字数を返します。変換エラー（無効な multibyte 文字が見つかった場合）の場合、(size_t)-1 を返します。

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

例

このコードを実行

#include <stdio.h>
#include <locale.h>
#include <stdlib.h>
#include <wchar.h>
 
int main(void)
{
    setlocale(LC_ALL, "en_US.utf8");
    const char* mbstr = u8"z\u00df\u6c34\U0001F34C"; // or u8"zß水🍌"
    wchar_t wstr[5];
    mbstowcs(wstr, mbstr, 5);
    wprintf(L"MB string: %s\n", mbstr);
    wprintf(L"Wide string: %ls\n", wstr);
}

出力

MB string: zß水🍌
Wide string: zß水🍌

参照

• C11標準 (ISO/IEC 9899:2011)

• 7.22.8.1 The mbstowcs function (p: 359)

• K.3.6.5.1 The mbstowcs_s function (p: 611-612)

• C99標準 (ISO/IEC 9899:1999)

• 7.20.8.1 The mbstowcs function (p: 323)

• C89/C90標準 (ISO/IEC 9899:1990)

• 4.10.8.1 The mbstowcs function

関連項目

mbsrtowcsmbsrtowcs_s (C95)(C11)	与えられた状態で、ナローマルチバイト文字列をワイド文字列に変換する (関数)
wcstombswcstombs_s (C11)	ワイド文字列をナローマルチバイト文字列に変換する (関数)
C++ ドキュメント mbstowcs