std::c16rtomb

単一のコードポイントを可変長16ビット文字表現 (一般的には UTF-16) からナローマルチバイト文字表現に変換します。

s がヌルポインタでなく、 c16 があるコードポイントの有効な可変長エンコーディング内の最後の16ビットコードユニットであれば、そのコードポイントのマルチバイト文字表現 (あらゆるシフトシーケンスを含み、現在のマルチバイト変換状態 *ps を考慮に入れた) を格納するために必要なバイト数を決定し、 s によって最初の要素が指されている文字配列にそのマルチバイト表現を格納し、必要に応じて *ps を更新します。 最大 MB_CUR_MAX バイトが書き込まれます。

s がヌルポインタであれば、その呼び出しは何らかの内部バッファ buf に対する std::c16rtomb(buf, u'\0', ps) と同等です。

c16 がワイド文字の16ビット表現の最後のコードユニットでなければ、 s の指す配列には書き込まれず、 *ps のみが更新されます。

c16 がヌルワイド文字 u'\0' であれば、初期シフト状態を復元するために必要なあらゆるシフトシーケンスの後にヌルのバイトが格納され、 *ps が初期シフト状態を表すように更新されます。

この関数が使用するマルチバイトエンコーディングは、現在アクティブな C のロケールによって指定されます。

[編集] 引数

[編集] 戻り値

成功した場合は、 s によって最初の要素が指されている文字配列に書き込まれた (あらゆるシフトシーケンスを含む) バイト数を返します。 この値は、例えばサロゲートペアの最初の char16_t を処理するときなど、 ​0​ になる場合があります。

失敗した場合 (c16 が有効な16ビット文字でない場合) は、 -1 を返し、 EILSEQ を errno に格納し、 *ps を未規定な状態に置きます。

[編集] ノート

C++ 標準はこの関数のセマンティクスについて C 標��に従っています。 発行当時の C11 では、可変長のマルチバイト (UTF-8 など) を可変幅の16ビット (UTF-16 など) エンコーディングに変換する std::mbrtoc16 と異なり、この関数は単一の16ビットエンコーディングを変換することだけが可能でした。 つまり、元々の意図に反して UTF-16 を UTF-8 に変換することはできませんでした。 これは C11 発行後の欠陥報告 DR488 で訂正されました。

[編集] 例

#include <iostream>
#include <iomanip>
#include <string_view>
#include <clocale>
#include <cuchar>
#include <climits>
 
int main()
{
    std::setlocale(LC_ALL, "en_US.utf8");
    std::u16string_view strv = u"zß水🍌"; // or z\u00df\u6c34\U0001F34C
    std::cout << "Processing " << strv.size() << " UTF-16 code units: [ ";
    for(char16_t c : strv)
        std::cout << std::showbase << std::hex << c << ' ';
    std::cout << "]\n";
 
    std::mbstate_t state{};
    char out[MB_LEN_MAX]{};
    for(char16_t c : strv)
    {   
        std::size_t rc = std::c16rtomb(out, c, &state);
        std::cout << c << " converted to [ ";
        if(rc != (std::size_t)-1)
            for(unsigned char c8 : std::string_view{out, rc})
                std::cout << +c8 << ' ';
        std::cout << "]\n";
    }
}

Processing 5 UTF-16 code units: [ 0x7a 0xdf 0x6c34 0xd83c 0xdf4c ]
0x7a converted to [ 0x7a ]
0xdf converted to [ 0xc3 0x9f ]
0x6c34 converted to [ 0xe6 0xb0 0xb4 ]
0xd83c converted to [ ]
0xdf4c converted to [ 0xf0 0x9f 0x8d 0x8c ]

[編集] 関連項目