Namespaces
Variants

mbstowcs, mbstowcs_s

From cppreference.net
C
Strings library
Null-terminated multibyte strings
ヘッダーで定義 <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) 配列の先頭要素が src によって指されるマルチバイト文字列を、そのワイド文字表現に変換する。変換された文字は、 dst によって指される配列の連続する要素に格納される。最大で len 個のワイド文字が変換先配列に書き込まれる。
各文字は、 mbtowc の呼び出しによって変換されるかのように処理されます。ただし、mbtowcの変換状態は影響を受けません。以下の場合に変換は停止します：
* マルチバイトのヌル文字が変換され格納されました。
* 現在のCロケールにおいて無効なマルチバイト文字が検出されました。
* 格納される次のワイド文字が len を超える場合。
src と dst が重なっている場合、動作は未定義です
2) (1) と同様ですが、以下の点が異なります。
* 変換は mbrtowc によるかのようであり、 mbtowc ではない
* 関数は結果をout-parameterとして返します retval
* null文字が len 個のワイド文字が書き込まれた後に dst に書き込まれなかった場合、 L ' \0 ' が dst[len] に格納され、これは合計len+1個のワイド文字が書き込まれたことを意味します
* dst がnullポインタの場合、生成されるワイド文字の数が * retval に格納される
* この関数は終端ナル文字から dstsz まで、宛先配列を上書きします
* src と dst が重なる場合、動作は未定義です。
* 以下のエラーは実行時に検出され、現在インストールされている constraint handler 関数を呼び出します：
  • retval または src がnullポインタである場合
  • dstsz または len が RSIZE_MAX/sizeof(wchar_t) より大きい場合（ dst がnullでない限り）
  • dstsz がゼロでない場合（ dst がnullでない限り）
  • src 配列の最初の dstsz マルチバイト文字内にnull文字が存在せず、かつ len が dstsz より大きい場合（ dst がnullでない限り）
すべての境界チェック付き関数と同様に、 mbstowcs_s は、実装によって __STDC_LIB_EXT1__ が定義されており、かつユーザーが <stdlib.h> をインクルードする前に __STDC_WANT_LIB_EXT1__ を整数定数 1 に定義している場合にのみ利用可能であることが保証されます。

目次

変更点: - 「Contents」を「目次」に翻訳 - その他のテキスト（Notes, Parameters, Return value, Example, References, See also）はC++関連の専門用語として原文のまま保持 - HTMLタグ、属性、構造は完全に保持 - 番号部分は変更なし

注記

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

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

パラメータ

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

戻り値

1) 成功時は、終端文字 L ' \0 ' を除き、変換先配列に書き込まれたワイド文字の数を返す。変換エラー時（無効なマルチバイト文字が検出された場合）は ( size_t ) - 1 を返す。
2) 成功時はゼロ（この場合、終端ナル文字を除くワイド文字数が dst に書き込まれた、または書き込まれるはずだった値が * retval に格納される）、エラー時は非ゼロを返す。実行時制約違反の場合、 ( size_t ) - 1 を * retval に格納し（ retval がnullでない場合）、 dst [ 0 ] を L ' \0 ' に設定する（ dst がnullでない、かつ 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 mbstowcs関数 (p: 359)
  • K.3.6.5.1 mbstowcs_s関数 (p: 611-612)
  • C99標準 (ISO/IEC 9899:1999):
  • 7.20.8.1 mbstowcs関数 (p: 323)
  • C89/C90標準 (ISO/IEC 9899:1990):
  • 4.10.8.1 mbstowcs関数

関連項目

(C95) (C11)
状態を指定してナローマルチバイト文字列をワイド文字列に変換する
(関数)
(C11)
ワイド文字列をナローマルチバイト文字列に変換する
(関数)
C++ドキュメント for mbstowcs