名前空間
変種

    mbstowcs, mbstowcs_s

    提供: cppreference.com
     
    C
     
    文字列ライブラリ
     
    ヌル終端マルチバイト文字列
    マルチバイト文字列とワイド文字列の変換
    (C95)
    型
    (C95)
     
    <tbody> </tbody> <tbody class="t-dcl-rev t-dcl-rev-num "> </tbody><tbody> </tbody>
    ヘッダ <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 の変換状態が影響を受けないことを除いて std::mbtowc を呼んだかのように変換されます。 変換は以下の場合に停止します。
    * マルチバイトヌル文字が変換され格納された。
    * (現在の C のロケールにおいて) 無効なマルチバイト文字に遭遇した。
    * 格納する次のワイド文字が len を超える。
    src と dst がオーバーラップする場合、動作は未定義です。
    2) (1) と同じですが、以下の点が異なります。
    * 変換は、 mbtowc ではなく、 mbrtowc によって行われたかのように行われます。
    * 関数は結果を出力引数 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 マルチバイト文字内にヌル文字がなく、 len が dstsz より大きい (dst がヌルでなければ)。
    すべての境界チェック付き関数と同様に、 mbstowcs_s は __STDC_LIB_EXT1__ が処理系によって定義されていて、 <stdlib.h> をインクルードする前にユーザが __STDC_WANT_LIB_EXT1__ を整数定数 1 に定義した場合にのみ、利用可能であることが保証されます。

    ノート

    ほとんどの処理系では、この関数は文字列を処理するにあたって mbstate_t 型のグローバルな静的オブジェクトを更新し、複数のスレッドから同時に呼ぶことができません。 そのような場合は 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 より大きくなければ)。

    例

    Run this code
    #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 standard (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 standard (ISO/IEC 9899:1999):
    • 7.20.8.1 The mbstowcs function (p: 323)
    • C89/C90 standard (ISO/IEC 9899:1990):
    • 4.10.8.1 The mbstowcs function

    関連項目

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