名前空間
変種
操作

wcrtomb, wcrtomb_s

提供: cppreference.com
< c‎ | string‎ | multibyte
 
C
 
文字列ライブラリ
 
ヌル終端マルチバイト文字列
マルチバイト文字列とワイド文字列の変換
(C95)
(C11)
(C11)
(C95)
wcrtombwcrtomb_s
(C95)(C11)
(C95)(C11)
(C95)
型
(C95)
 
ヘッダ <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 を返し、 EILSEQ を errno に格納し、 *ps を未規定な状態にします。
2) 成功した場合はゼロ、失敗した場合は非ゼロを返します。 失敗した場合は、 s[0] が '\0' に設定され (s がヌルでなく、 ssz がゼロでなく RSIZE_MAX より大きくなければ)、 *retval が (size_t)-1 に設定されます (retval がヌルでなければ)。

[編集] 例

Run this code
#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 standard (ISO/IEC 9899:2011):
  • 7.29.6.3.3 The wcrtomb function (p: 444)
  • K.3.9.3.1.1 The wcrtomb_s function (p: 647-648)
  • C99 standard (ISO/IEC 9899:1999):
  • 7.24.6.3.3 The wcrtomb function (p: 390)

[編集] 関連項目

(C11)
 ワイド文字をマルチバイト表現に変換します
(関数) [edit]
(C95)
 指定された状態を使用して次のマルチバイト文字をワイド文字に変換します
(関数) [edit]
wcrtomb の C++リファレンス
「https://ja.cppreference.com/mwiki/index.php?title=c/string/multibyte/wcrtomb&oldid=37959」から取得