Namespaces
Variants

wctomb, wctomb_s

From cppreference.net
C
Strings library
Null-terminated multibyte strings
定義先ヘッダ <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 が指す先頭要素のchar配列に格納します。 MB_CUR_MAX 文字を超える文字は格納されません。変換は現在のロケールのLC_CTYPEカテゴリの影響を受けます。
wc がナル文字の場合、初期シフト状態を復元するために必要なシフトシーケンスに続けて、ナルバイトが s に書き込まれる。
s がヌルポインタの場合、この関数はグローバル変換状態をリセットし、シフトシーケンスが使用されるかどうかを判定します。
2) (1) と同様ですが、結果は出力パラメータ status で返され、以下のエラーが実行時に検出され、現在設定されている constraint handler 関数を呼び出します：
  • ssz が書き込まれるバイト数より小さい場合（ s がnullでない限り）
  • ssz が RSIZE_MAX より大きい場合（ s がnullでない限り）
  • s がnullポインタだが ssz がゼロでない場合
すべての境界チェック付き関数と同様に、 wctomb_s は、実装によって __STDC_LIB_EXT1__ が定義されており、かつユーザーが <stdlib.h> をインクルードする前に __STDC_WANT_LIB_EXT1__ を整数定数 1 に定義している場合にのみ利用可能であることが保証されます。

目次

翻訳のポイント： - 「Contents」を「目次」に翻訳 - HTMLタグ、属性、 、 
、タグ内のテキストは翻訳せず保持
- C++関連の専門用語（Notes, Parameters, Return value, Example, References, See also）は原文のまま保持
- 数値、構造、フォーマットは完全に維持

注記

wctomb への各呼び出しは、内部のグローバル変換状態（この関数のみが認識する mbstate_t 型の静的オブジェクト）を更新します。マルチバイトエンコーディングがシフト状態を使用する場合、この関数はリエントラントではありません。いずれの場合も、複数のスレッドが同期なしに wctomb を呼び出すべきではありません：代わりに wcrtomb または wctomb_s を使用できます。

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

パラメータ

s - 出力用文字配列へのポインタ
wc - 変換するワイド文字
ssz - s に書き込む最大バイト数（配列 s のサイズ）
status - 結果（マルチバイトシーケンスの長さまたはシフトシーケンスステータス）が格納される出力パラメータへのポインタ

戻り値

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

例

このコードを実行 
#include <stdio.h>
#include <stdlib.h>
#include <locale.h>
void demo(wchar_t wc)
{
    const char* dep = wctomb(NULL, wc) ? "Yes" : "No";
    printf("State-dependent encoding? %s.\n", dep);
    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("%s%#2x", idx ? " " : "", (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? No.
wide char 'A' -> multibyte char [0x41]
State-dependent encoding? No.
wide char 'ß' -> multibyte char [0xc3 0x9f]
State-dependent encoding? No.
wide char '𝄋' -> multibyte char [0xf0 0x9d 0x84 0x8b]

参考文献

  • C17規格 (ISO/IEC 9899:2018):
  • 7.22.7.3 wctomb関数 (p: 261)
  • K.3.6.4.1 wctomb_s関数 (p: 443)
  • C11標準 (ISO/IEC 9899:2011):
  • 7.22.7.3 wctomb関数 (p: 358-359)
  • K.3.6.4.1 wctomb_s関数 (p: 610-611)
  • C99規格 (ISO/IEC 9899:1999):
  • 7.20.7.3 wctomb関数 (p: 322-323)
  • C89/C90標準 (ISO/IEC 9899:1990):
  • 4.10.7.3 wctomb関数

関連項目

次のマルチバイト文字をワイド文字に変換する
(関数)
(C95) (C11)
ワイド文字をそのマルチバイト表現に変換する（状態を指定）
(関数)
C++ documentation for wctomb