c16rtomb
| ヘッダ <uchar.h> で定義
|
||
size_t c16rtomb( char * restrict s, char16_t c16, mbstate_t * restrict ps ); |
(C11以上) | |
単一のコードポイントを可変長16ビットワイド文字表現 (一般的には UTF-16) からナローマルチバイト文字表現に変換します。
s がヌルポインタでなく、 c16 があるコードポイントの有効な可変長エンコーディング内の最後の16ビットコードユニットであれば、そのコードポイントのマルチバイト文字表現 (あらゆるシフトシーケンスを含み、現在のマルチバイト変換状態 *ps を考慮に入れた) を格納するために必要なバイト数を決定し、 s によって最初の要素が指されている文字配列にそのマルチバイト表現を格納し、必要に応じて *ps を更新します。 最大 MB_CUR_MAX バイトが書き込まれます。
s がヌルポインタであれば、その呼び出しは何らかの内部バッファ buf に対する c16rtomb(buf, u'\0', ps) と同等です。
c16 がヌルワイド文字 u'\0' であれば、初期シフト状態を復元するために必要なあらゆるシフトシーケンスの後にヌルのバイトが格納され、 *ps が初期シフト状態を表すように更新されます。
c16 がワイド文字の16ビット表現の最後のコードユニットでなければ、 s の指す配列には書き込まれず、 *ps のみが更新されます。
マクロ __STDC_UTF_16__ が定義されている場合、この関数が使用する16ビットエンコーディングは UTF-16 です。 そうでなければ、処理系定義です。 いずれの場合でも、この関数が使用するマルチバイト文字エンコーディングは、現在アクティブな C のロケールによって指定されます。
引数
| s | - | マルチバイト文字が格納されるナロー文字配列を指すポインタ |
| c16 | - | 変換する16ビットワイド文字 |
| ps | - | マルチバイト文字列を解釈するときに使用される変換状態オブジェクトを指すポインタ |
戻り値
成功した場合は、 s によって最初の要素が指されている文字配列に書き込まれた (あらゆるシフトシーケンスを含む) バイト数を返します。 この値は、例えば複数の char16_t のユニットのシーケンスの先行する char16_t を処理するとき (UTF-16 のサロゲートペアの先行するサロゲートを処理するときに発生します) など、 0 になる場合があります。
失敗した場合 (c16 が有効な16ビットコードユニットでない場合) は、 -1 を返し、 EILSEQ を errno に格納し、 *ps を未規定な状態に置きます。
ノート
発行当時の C11 では、可変長のマルチバイト (UTF-8 など) を可変幅の16ビット (UTF-16 など) エンコーディングに変換する mbrtoc16 と異なり、この関数は単一ユニットの16ビットエンコーディングを変換することだけが可能でした。 つまり、元々の意図に反して UTF-16 を UTF-8 に変換することはできませんでした。 これは C11 発行後の欠陥報告 DR488 で訂正されました。
例
ノート: この例は欠陥報告 488 に対する修正が適用されていることを想定しています。
#include <stdio.h>
#include <locale.h>
#include <uchar.h>
#include <stdlib.h>
mbstate_t state;
int main(void)
{
setlocale(LC_ALL, "en_US.utf8");
char16_t in[] = u"zß水🍌"; // or "z\u00df\u6c34\U0001F34C"
size_t in_sz = sizeof in / sizeof *in;
printf("Processing %zu UTF-16 code units: [ ", in_sz);
for(size_t n = 0; n < in_sz; ++n) printf("%#x ", in[n]);
puts("]");
char out[MB_CUR_MAX * in_sz];
char *p = out;
for(size_t n = 0; n < in_sz; ++n) {
size_t rc = c16rtomb(p, in[n], &state);
if(rc == (size_t)-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 6 UTF-16 code units: [ 0x7a 0xdf 0x6c34 0xd83c 0xdf4c 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.28.1.2 The c16rtomb function (p: 399-400)
関連項目
(C11) |
マルチバイト文字列から次の16ビットワイド文字を生成します (関数) |
c16rtomb の C++リファレンス
| |