名前空間
変種

    wcsrtombs, wcsrtombs_s

    提供: cppreference.com
     
    C
     
    文字列ライブラリ
     
    ヌル終端マルチバイト文字列
    マルチバイト文字列とワイド文字列の変換
    (C95)
    型
    (C95)
     
    <tbody> </tbody> <tbody class="t-dcl-rev t-dcl-rev-num "> </tbody><tbody> </tbody>
    ヘッダ <wchar.h> で定義
    (1)
    size_t wcsrtombs( char *dst, const wchar_t **src, size_t len, mbstate_t* ps );
    		 (C95以上)
    size_t wcsrtombs( char *restrict dst, const wchar_t **restrict src, size_t len, mbstate_t *restrict ps);
    		 (C99以上)
    errno_t wcsrtombs_s( size_t *restrict retval, char *restrict dst, rsize_t dstsz, const wchar_t **restrict src, rsize_t len, mbstate_t *restrict ps);
    		 (2) (C11以上)
    1) ワイド文字シーケンスを *src によって最初の要素が指されている配列から *ps の表す変換状態で始まるナローマルチバイト表現に変換します。 dst がヌルでなければ、変換された文字が dst の指す文字配列の連続する要素に格納されます。 最大 len バイトが dst 配列に書き込まれます。
    各文字は wcrtomb を呼んだかのように変換されます。 変換は以下の場合に停止します。
    * ヌル文字 L'\0' が変換され格納された。 この場合、格納されるバイト列はシフト解除シーケンス (必要であれば) に続く '\0' となり、 src は NULL に設定され、 *ps は初期シフト状態を表すように設定されます。
    * 現在の C のロケールにおいて有効な文字に対応しない wchar_t が見つかった。 src は変換されなかった最初のワイド文字を指すように設定されます。
    * 格納される次のマルチバイト文字が len を超える。 src は変換されなかった最初のワイド文字を指すように設定されます。 この条件は dst==NULL の場合はチェックされません。
    2) (1) と同じですが、以下の点が異なります。
    * 結果は出力引数 retval として返されます。
    * 変換がヌル文字を書き込まずに停止した場合は、 '\0' を dst の次のバイト (dst[len] または dst[dstsz] のいずれか先に来る方) に書き込みます (つまり最大で合計 len+1 または dstsz+1 バイトが書き込まれる可能性があります)。 この場合、終端のヌルの前にシフト解除シーケンスが書き込まれないことがあります。
    * dst 配列を終端のヌルから dstsz まで上書きします。
    * src と dst がオーバーラップしている場合、動作は未規定です。
    * 以下のエラーが実行時に検出され、現在設定されている制約ハンドラ関数を呼びます。
    • retval、 ps、 src または *src がヌルポインタ。
    • dstsz または len RSIZE_MAX より大きい (dst がヌルでなければ)。
    • dstsz がゼロでない (dst がヌルでなければ)。
    • len が dstsz より大きく、変換が dstsz に到達するまでに src 配列内にヌルまたは変換エラーに遭遇しない (dst がヌルでなければ)。
    すべての境界チェック付き関数と同様に、 wcsrtombs_s は __STDC_LIB_EXT1__ が処理系によって定義されていて、 <wchar.h> をインクルードする前にユーザが __STDC_WANT_LIB_EXT1__ を整数定数 1 に定義した場合にのみ、利用可能であることが保証されます。

    引数

    dst - マルチバイト文字が格納されるナロー文字配列を指すポインタ
    src - ヌル終端ワイド文字列の最初の要素を指すポインタへのポインタ
    len - dst の指す配列内の利用可能なバイト数
    ps - 変換状態オブジェクトを指すポインタ
    dstsz - 書き込まれる最大バイト数 (dst 配列のサイズ)
    retval - 結果が格納される size_t オブジェクトを指すポインタ

    戻り値

    1) 成功した場合は、最初の要素が dst によって指されている文字配列に書き込まれたバイト数 (あらゆるシフトシーケンスを含み、終端の '\0' を含まない) を返します。 dst==NULL の場合は、書き込まれたであろうバイト数 (終端のヌル文字 '\0' を含まない) を返します。 変換エラーが発生した場合 (無効なワイド文字に遭遇した場合) は、 (size_t)-1 を返し、 EILSEQ を errno に格納し、 *ps を未規定の状態にします。
    2) 成功した場合はゼロを返し、 dst に書き込まれたまたは書き込まれるであろう終端のゼロを除くバイト数が *retval に格納されます。 エラーが発生した場合は非ゼロを返します。 実行時制約違反の場合は、 (size_t)-1 を *retval に格納し (retval がヌルでなければ)、 dst[0] を '\0' に格納します (dst がヌルでなく、 dstmax がヌルでなく RSIZE_MAX より大きくなければ)。

    例

    Run this code
    #include <stdio.h>
#include <locale.h>
#include <string.h>
#include <wchar.h>

void print_wide(const wchar_t* wstr)
{
    mbstate_t state;
    memset(&state, 0, sizeof state);
    size_t len = 1 + wcsrtombs(NULL, &wstr, 0, &state);
    char mbstr[len];
    wcsrtombs(mbstr, &wstr, len, &state);
    printf("Multibyte string: %s\n", mbstr);
    printf("Length, including '\\0': %zu\n", len);
}

int main(void)
{
    setlocale(LC_ALL, "en_US.utf8");
    print_wide(L"z\u00df\u6c34\U0001f34c"); // or L"zß水🍌"
}

    出力: 

    Multibyte string: zß水🍌
Length, including '\0': 11

    参考文献

    • C11 standard (ISO/IEC 9899:2011):
    • 7.29.6.4.2 The wcsrtombs function (p: 446)
    • K.3.9.3.2.2 The wcsrtombs_s function (p: 649-651)
    • C99 standard (ISO/IEC 9899:1999):
    • 7.24.6.4.2 The wcsrtombs function (p: 392)

    関連項目

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