wcrtomb, wcrtomb_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

 

ヘッダー <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 がヌルポインタでない場合、この関数は 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 がヌルポインタの場合、この呼び出しは内部変数 retval および buf (サイズは MB_CUR_MAX より大きい) を使用して wcrtomb_s(&retval, buf, sizeof buf, L'\0', ps) と同等です。

結果は出力パラメータ retval で返されます。

以下のエラーが実行時に検出され、現在インストールされている 制約ハンドラ 関数が呼び出されます。

• retval または ps がヌルポインタです。
• ssz がゼロであるか、RSIZE_MAX より大きい (s がヌルでない場合を除く)
• ssz が書き込まれるバイト数より少ない (s がヌルでない場合を除く)
• s がヌルポインタですが 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 を返し、errno に EILSEQ を格納し、*ps を不定の状態にします。

2) 成功した場合はゼロを返し、失敗した場合は非ゼロを返します。この場合、s[0] は '\0' に設定され (s がヌルであるか、ssz がゼロであるか、RSIZE_MAX より大きい場合を除く)、*retval は (size_t)-1 に設定されます (retval がヌルである場合を除く)。

例

このコードを実行

#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)

関連項目

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