Namespaces
Variants

mbsrtowcs, mbsrtowcs_s

From cppreference.net
C
Strings library
Null-terminated multibyte strings
定義済みヘッダー <wchar.h>
(1)
size_t mbsrtowcs ( wchar_t * dst, const char ** src, size_t len, mbstate_t * ps ) ;
(C95以降)
(C99まで)
size_t mbsrtowcs ( wchar_t * restrict dst, const char ** 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,
const char ** restrict src, rsize_t len,

mbstate_t * restrict ps ) ;
(2) (C11以降)
1) 変換状態 *ps で記述される状態から開始して、 * src が指す要素から始まる配列から、ヌル終端マルチバイト文字シーケンスをワイド文字表現に変換する。 dst がnullでない場合、変換された文字は dst が指すwchar_t配列の連続する要素に格納される。宛先配列には最大で len 個のワイド文字が書き込まれる。各マルチバイト文字は mbrtowc の呼び出しによって変換されるかのように変換される。変換は以下の場合に停止する:
  • マルチバイトのヌル文字が変換され格納された。 * src はヌルポインタ値に設定され、 *ps は初期シフト状態を表す。
  • （現在のCロケールにおいて）無効なマルチバイト文字に遭遇した。 * src は変換されていない最初のマルチバイト文字の先頭を指すように設定される。
  • 次に格納されるワイド文字が len を超える場合。 * src は変換されていない最初のマルチバイト文字の先頭を指すように設定される。この条件は dst がヌルポインタの場合にはチェックされない。
2) (1) と同様ですが、以下の点が異なります：
  • 関数は結果を出力パラメータ retval として返す
  • len 個のワイド文字が書き込まれた後、 dst にnull文字が書き込まれていない場合、 L ' \0 ' が dst[len] に格納される（つまり合計len+1個のワイド文字が書き込まれる）
  • 関数は終端nullから dstsz までの宛先配列を上書きする
  • src と dst が重複している場合、動作は未定義
  • 以下のエラーが実行時に検出され、現在設定されている 制約ハンドラ 関数が呼び出される：
  • retval 、 ps 、 src または * src がnullポインタ
  • dstsz または len が RSIZE_MAX/sizeof(wchar_t) より大きい（ dst がnullでない場合）
  • dstsz がゼロでない（ dst がnullでない場合）
  • dstsz 個のマルチバイト文字以内にnull文字が存在せず、かつ len が dstsz より大きい（ dst がnullでない場合）
すべての境界チェック付き関数と同様に、 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 がnullでない場合）、 dst [ 0 ] を L ' \0 ' に設定する（ dst がnullでない、かつ dstmax がゼロでなく RSIZE_MAX より大きくない場合）

例

このコードを実行 
#include <stdio.h>
#include <locale.h>
#include <wchar.h>
#include <string.h>
void print_as_wide(const char* 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規格 (ISO/IEC 9899:2011):
  • 7.29.6.4.1 mbsrtowcs関数 (p: 445)
  • K.3.9.3.2.1 mbsrtowcs_s関数 (p: 648-649)
  • C99規格 (ISO/IEC 9899:1999):
  • 7.24.6.4.1 mbsrtowcs関数 (p: 391)

関連項目

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