Namespaces
Variants

    mbstowcs, mbstowcs_s

    ja.cppreference.net から
     
    C
     
    文字列ライブラリ
     
    ナル終端マルチバイト文字列
     
    ヘッダ <stdlib.h> 
    size_t mbstowcs( wchar_t* dst, const char* src, size_t len)
    		で定義 (1) (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
    • ではありません。関数は結果を出力パラメータ retval
    • として返します。dst に len 個のワイド文字が書き込まれた後、まだナル文字が書き込まれていない場合、L'\0' が dst[len] に格納されます。つまり、合計で len+1 個のワイド文字が書き込まれます。
    • dst がヌルポインタの場合、生成されるであろうワイド文字の数が *retval
    • に格納されます。関数は終端ナルから dstsz
    • までの宛先配列をクリアします。src と dst が重なっている場合、動作は未規定です。
    • 以下のエラーが実行時に検出され、現在インストールされている 制約ハンドラ 関数を呼び出します:
    • retval または src がヌルポインタである
    • dstsz または len が RSIZE_MAX / sizeof(wchar_t) より大きい（dst がヌルの場合を除く）
    • dstsz がゼロでない（dst がヌルの場合を除く）
    • 配列 dstsz の最初の src マルチバイト文字にナル文字がなく、len が dstsz より大きい（dst がヌルの場合を除く）
    すべての境界チェック付き関数と同様に、mbstowcs_s は実装によって __STDC_LIB_EXT1__ が定義され、ユーザーが __STDC_WANT_LIB_EXT1__ を整数定数 1 に定義してから <stdlib.h> をインクルードする場合にのみ使用可能であることが保証されます。

    ノート

    ほとんどの実装では、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 がヌルでない限り）、dst[0] を L'\0' に設定します（dst がヌルでない、または dstmax がゼロである、または RSIZE_MAX より大きい場合を除く）

    例

    このコードを実行する
    #include <locale.h>
#include <stdio.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ß水🍌

    参考文献

    • C23 標準 (ISO/IEC 9899:2024):
    • 7.22.8.1 The mbstowcs function (p: TBD)
    • K.3.6.5.1 The mbstowcs_s function (p: TBD)
    • C17 標準 (ISO/IEC 9899:2018):
    • 7.22.8.1 The mbstowcs function (p: TBD)
    • K.3.6.5.1 The mbstowcs_s function (p: TBD)
    • 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

    関連項目

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