Namespaces
Variants

    wcrtomb, wcrtomb_s

    ja.cppreference.net より
     
    C
     
    文字列ライブラリ
     
    ナル終端マルチバイト文字列
     
    ヘッダで定義 <wchar.h> 
    size_t wcrtomb( char* s, wchar_t wc, mbstate_t* ps);
    		(1) (C95以降)
    (C99まで)    		 
    size_t wcrtomb( char* restrict s, wchar_t wc, mbstate_t* restrict ps);
    		(C99以降) 
    errno_t wcrtomb_s(size_t* restrict retval, char* restrict s, rsize_t ssz,
                  wchar_t wc, mbstate_t* restrict ps);
    		(2) (C11以降)

    ワイド文字をそのナローマルチバイト表現に変換します。

    1) もし s がヌルポインタでない場合、関数はマルチバイト文字表現を格納するために必要なバイト数を決定し、wc (シフトシーケンスを含み、現在のマルチバイト変換状態 *ps を考慮し)、そして最初の要素が s で指されている文字配列にマルチバイト文字表現を格納し、 *ps を必要に応じて更新します。最大で MB_CUR_MAX バイトをこの関数で書き込むことができます。
    もし s がヌルポインタである場合、呼び出しは wcrtomb(buf, L'\0', ps) 何らかの内部バッファに対して buf と同等です。
    wc がヌルワイド文字である場合、L'\0' ヌルバイトが格納され、その前に初期シフト状態を復元するために必要なシフトシーケンスが付加され、変換状態パラメータ *ps が初期シフト状態を表すように更新されます。
    環境マクロ __STDC_ISO_10646__ が定義されている場合、型 wchar_t の値はUnicode必須セットの文字の短縮識別子と同じです (通常はUTF-32エンコーディング)；そうでなければ、実装定義です。いずれの場合でも、この関数で使用されるマルチバイト文字エンコーディングは、現在アクティブなCロケールによって指定されます。
    2) と同じ (1)、ただし
    もし s がヌルポインタである場合、呼び出しは wcrtomb_s(&retval, buf, sizeof buf, L'\0', ps) 内部変数 retval と buf (そのサイズは MB_CUR_MAX より大きい)
    結果は出力パラメータ retval
    で返される 次のエラーが実行時に検出され、現在インストールされている制約ハンドラ 関数:
    • retval または ps はヌルポインタです。
    • ssz がゼロであるか、RSIZE_MAX より大きい (ただし s がヌルの場合を除く)
    • ssz が書き込まれるバイト数より小さい (ただし s がヌルの場合を除く)
    • s がヌルポインタであるが ssz がゼロでない
    すべての境界チェック関数と同様に、wcrtomb_s は、__STDC_LIB_EXT1__ が実装によって定義され、ユーザーが __STDC_WANT_LIB_EXT1__ を整数定数 1 に <wchar.h> をインクルードする前に定義する場合にのみ利用可能であることが保証されます。

    引数

    s - マルチバイト文字が格納されるナロー文字配列へのポインタ
    wc - 変換するワイド文字
    ps - マルチバイト文字列の解釈に使用される変換状態オブジェクトへのポインタ
    ssz - 書き込む最大バイト数（バッファ s のサイズ）
    retval - 結果（シフトシーケンスを含むマルチバイト文字列のバイト数）が格納される出力パラメータへのポインタ

    戻り値

    1) 成功した場合、sが指す最初の要素を持つ文字配列に書き込まれたバイト数（シフトシーケンスを含む）を返す。
    失敗した場合（wcが有効なワイド文字でない場合）、(size_t)-1を返し、EILSEQをerrnoに格納し、*psを未規定の状態にする。
    2) 成功した場合は0を返し、失敗した場合は0以外を返す。その場合、s[0]は'\0'に設定される（ただし、sがヌルであるか、sszが0またはRSIZE_MAXより大きい場合は除く）。また、*retvalは(size_t)-1に設定される（retvalがヌルの場合を除く）

    例

    このコードを実行
    #include <locale.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <wchar.h>

int main(void)
{
    setlocale(LC_ALL, "en_US.utf8");
    mbstate_t state;
    memset(&state, 0, sizeof state);
    wchar_t in[] = L"zß水🍌"; // or "z\u00df\u6c34\U0001F34C"
    size_t in_sz = sizeof in / sizeof *in;
 
    printf("Processing %zu wchar_t units: [ ", in_sz);
    for (size_t n = 0; n < in_sz; ++n)
        printf("%#x ", (unsigned int)in[n]);
    puts("]");
 
    char out[MB_CUR_MAX * in_sz];
    char* p = out;
    for (size_t n = 0; n < in_sz; ++n)
    {
        int rc = wcrtomb(p, in[n], &state);
        if (rc == -1)
            break;
        p += rc;
    }
 
    size_t out_sz = p - out;
    printf("into %zu UTF-8 code units: [ ", out_sz);
    for (size_t x = 0; x < out_sz; ++x)
        printf("%#x ", +(unsigned char)out[x]);
    puts("]");
}

    出力: 

    Processing 5 wchar_t units: [ 0x7a 0xdf 0x6c34 0x1f34c 0 ]
into 11 UTF-8 code units: [ 0x7a 0xc3 0x9f 0xe6 0xb0 0xb4 0xf0 0x9f 0x8d 0x8c 0 ]

    参考文献

    • C23標準 (ISO/IEC 9899:2024):
    • 7.29.6.3.3 wcrtomb関数 (p: TBD)
    • K.3.9.3.1.1 wcrtomb_s関数 (p: TBD)
    • C17標準 (ISO/IEC 9899:2018):
    • 7.29.6.3.3 wcrtomb関数 (p: TBD)
    • K.3.9.3.1.1 wcrtomb_s関数 (p: TBD)
    • C11標準 (ISO/IEC 9899:2011):
    • 7.29.6.3.3 wcrtomb関数 (p: 444)
    • K.3.9.3.1.1 wcrtomb_s関数 (p: 647-648)
    • C99標準 (ISO/IEC 9899:1999):
    • 7.24.6.3.3 wcrtomb関数 (p: 390)

    関連項目

    (C11)
    		 ワイド文字をマルチバイト表現に変換する
    (関数)
    (C95)
    		 次のマルチバイト文字をワイド文字に変換する（状態を指定）
    (関数)
    C++ドキュメントのwcrtomb