Namespaces
Variants

wcrtomb, wcrtomb_s

From cppreference.net
C
Strings library
Null-terminated multibyte strings
ヘッダーで定義 <wchar.h>
(1)
size_t wcrtomb ( char * s, wchar_t wc, mbstate_t * ps ) ;
(C95以降)
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 がnullポインタでない場合、この関数は wc のマルチバイト文字表現（シフトシーケンスを含み、現在のマルチバイト変換状態 * ps を考慮に入れて）を格納するために必要なバイト数を決定し、 s が指す先頭要素の文字配列にマルチバイト文字表現を格納し、必要に応じて * ps を更新する。この関数によって書き込まれるバイト数は最大で MB_CUR_MAX である。
sがヌルポインタの場合、この呼び出しは内部バッファ buf に対する wcrtomb ( buf, L ' \0 ' , ps ) の呼び出しと等価です。
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 で返されます
以下のエラーが実行時に検出され、現在インストールされている constraint handler 関数が呼び出されます：
  • retval または ps がnullポインタである場合
  • ssz がゼロまたは RSIZE_MAX より大きい場合（ s がnullでない限り）
  • ssz が書き込まれるバイト数より少ない場合（ s がnullでない限り）
  • s がnullポインタだが ssz がゼロでない場合
すべての境界チェック付き関数と同様に、 wcrtomb_s は、実装によって __STDC_LIB_EXT1__ が定義され、かつユーザーが <wchar.h> をインクルードする前に __STDC_WANT_LIB_EXT1__ を整数定数 1 に定義した場合にのみ利用可能であることが保証されます。

目次

パラメータ

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

戻り値

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

例

このコードを実行 
#include <stdio.h>
#include <locale.h>
#include <string.h>
#include <wchar.h>
#include <stdlib.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 ]

参考文献

  • 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++ドキュメント for wcrtomb