wctomb, wctomb_s

 

C

コンパイラサポート

言語

ヘッダー

型サポート

プログラムユーティリティ

可変長引数関数のサポート

エラーハンドリング

動的メモリ管理

文字列ライブラリ

アルゴリズム

数値

日付と時刻のユーティリティ

入出力サポート

ローカライゼーションサポート

並行処理サポート (C11)

技術仕様

シンボルインデックス

 

文字列ライブラリ

ヌル終端バイト文字列

ヌル終端マルチバイト文字列

ヌル終端ワイド文字列

 

ヌル終端マルチバイト文字列

関数
ワイド文字/マルチバイト文字変換
mbsinit (C95)
mbstowcsmbstowcs_s (C11) btowc (C95) mbrtowc (C95) mbsrtowcsmbsrtowcs_s (C95)(C11)   mbrtoc8 (C23) c8rtomb (C23) mbrtoc16 (C11) c16rtomb (C11) c32rtomb (C11) mbrtoc32 (C11)	mblen mbtowc wctombwctomb_s (C11) wcstombswcstombs_s (C11) wctob (C95) wcrtombwcrtomb_s (C95)(C11) wcsrtombswcsrtombs_s (C95)(C11) mbrlen (C95)
型
mbstate_t (C95) char8_t (C23)	char16_t (C11) char32_t (C11)
マクロ
MB_LEN_MAX	MB_CUR_MAX

 

ヘッダー <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) と同じですが、結果はoutパラメータ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	-	結果（マルチバイトシーケンスの長さまたはシフトシーケンスの状態）が格納されるoutパラメータへのポインタ

戻り値

1) sがヌルポインタでない場合、wcのマルチバイト表現に含まれるバイト数を返します。wcが無効な文字の場合は-1を返します。

sがヌルポインタの場合、内部変換状態を初期シフト状態を表すようにリセットし、現在のマルチバイトエンコーディングが状態依存でない（シフトシーケンスを使用しない）場合は​0​を返します。状態依存（シフトシーケンスを使用する）場合はゼロ以外の値を返します。

2) 成功した場合はゼロ。この場合、wcのマルチバイト表現がsに格納され、その長さが*statusに格納されます（sがヌルの場合は、シフトシーケンスの状態が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 The wctomb function (p: 261)

• K.3.6.4.1 The wctomb_s function (p: 443)

• C11標準 (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標準 (ISO/IEC 9899:1999)

• 7.20.7.3 The wctomb function (p: 322-323)

• C89/C90標準 (ISO/IEC 9899:1990)

• 4.10.7.3 The wctomb function

関連項目

mbtowc	次のマルチバイト文字をワイド文字に変換する (関数)
wcrtombwcrtomb_s (C95)(C11)	与えられた状態で、ワイド文字をそのマルチバイト表現に変換する (関数)
C++ ドキュメント (wctomb)