名前空間
変種

    wctomb, wctomb_s

    提供: cppreference.com
     
    C
     
    文字列ライブラリ
     
    ヌル終端マルチバイト文字列
    マルチバイト文字列とワイド文字列の変換
    (C95)
    型
    (C95)
     
    <tbody> </tbody>
    ヘッダ <stdlib.h> で定義
    int wctomb( char *s, wchar_t wc );
    		 (1)
    errno_t wctomb_s(int *restrict status, char *restrict s, rsize_t ssz, wchar_t wc);
    		 (2) (C11以上)
    1) ワイド文字 wc をマルチバイトエンコーディングに変換し、それを (シフトシーケンスを含めて) s によって最初の要素が指されている文字配列に格納します。 最大 MB_CUR_MAX 文字が格納されます。
    wc がヌル文字の場合は、初期シフト状態を復元するために必要なシフトシーケンスを前に置いたヌルバイトが s に書き込まれます。
    s がヌルポインタの場合は、グローバルな変換状態をリセットし、シフトシーケンスが使用されるかどうかを調べます。
    2) (1) と同じですが、結果は出力引数 status に返され、以下のエラーが実行時に検出され、現在設定されている制約ハンドラ関数を呼びます。
    • ssz が書き込まれるバイト数より小さい (s がヌルでなければ)
    • ssz が RSIZE_MAX より大きい (s がヌルでなければ)
    • s がヌルポインタだけれども ssz がゼロでない
    すべての境界チェック付き関数と同様に、 wctomb_s は __STDC_LIB_EXT1__ が処理系によって定義されていて、 <stdlib.h> をインクルードする前にユーザが __STDC_WANT_LIB_EXT1__ を整数定数 1 に定義した場合にのみ、利用可能であることが保証されます。

    ノート

    wctomb を呼ぶたびに、内部のグローバルな変換状態 (この関数のみが使用する mbstate_t 型の静的オブジェクト) を更新します。 マルチバイトエンコーディングがシフト状態を使用する場合、バックトラッキングや複数回のスキャンを避けるように注意しなければなりません。 いずれの場合でも、複数のスレッドが同期せずに wctomb を呼ぶべきではありません。 代わりに wcrtomb または wctomb_s を使用することができます。

    ほとんどの境界チェック関数と異なり、 wctomb_s は文字列を文字ごとに処理するループで使用するよう設計されているため、出力をヌル終端しません。

    引数

    s - 出力用の文字配列を指すポインタ
    wc - 変換するワイド文字
    ssz - s に書き込む最大バイト数 (配列 s のサイズ)
    status - 結果 (マルチバイトシーケンスの長さまたはシフトシーケンスの状態) を格納する出力引数を指すポインタ

    戻り値

    1) s がヌルポインタでなければ、 wc のマルチバイト表現に含まれるバイト数を返します。 wc が有効な文字でない場合は -1 を返します。
    s がヌルポインタであれば、内部の変換状態を初期シフト状態を表すようにリセットし、現在のマルチバイトエンコーディングが状態依存でない (シフトシーケンスを使用しない) 場合は 0、現在のマルチバイトエンコーディングが状態依存 (シフトシーケンスを使用する) の場合は非ゼロの値を返します。
    2) 成功した場合はゼロを返し、 wc のマルチバイト表現が s に格納され、その長さが *status に格納されます。 s がヌルの場合は、シフトシーケンスの状態が status) に格納されます。 エンコーディングエラーまたは実行時制約違反の場合は非ゼロの値を返し、 (size_t)-1 が *status に格納されます。 *status に格納される値が MB_CUR_MAX を超えることはありません。

    例

    Run this code
    #include <stdio.h>
#include <stdlib.h>
#include <locale.h>

void demo(wchar_t wc)
{
    printf("State-dependent encoding?   %d\n", wctomb(NULL, wc));

    char mb[MB_CUR_MAX];
    int len = wctomb(mb,wc);
    printf("wide char '%lc' -> multibyte char '", wc);
    for (int idx = 0; idx < len; ++idx)
        printf("%#2x ", (unsigned char)mb[idx]);
    printf("'\n");
}

int main(void)
{
    setlocale(LC_ALL, "en_US.utf8");
    printf("MB_CUR_MAX = %zu\n", MB_CUR_MAX);
    demo(L'A');
    demo(L'\u00df');
    demo(L'\U0001d10b');
}

    出力例: 

    MB_CUR_MAX = 6
State-dependent encoding?   0
wide char 'A' -> multibyte char '0x41 '
State-dependent encoding?   0
wide char 'ß' -> multibyte char '0xc3 0x9f '
State-dependent encoding?   0
wide char '𝄋' -> multibyte char '0xf0 0x9d 0x84 0x8b '

    参考文献

    • C11 standard (ISO/IEC 9899:2011):
    • 7.22.7.3 The wctomb function (p: 358-359)
    • K.3.6.4.1 The wctomb_s function (p: 610-611)
    • C99 standard (ISO/IEC 9899:1999):
    • 7.20.7.3 The wctomb function (p: 322-323)
    • C89/C90 standard (ISO/IEC 9899:1990):
    • 4.10.7.3 The wctomb function

    関連項目

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