std::codecvt<InternT,ExternT,StateT>::out, do_out
| ヘッダー <locale> で定義 |
||
| public: result out( StateT& state, |
(1) | |
| protected: virtual result do_out( StateT& state, |
(2) | |
do_outを呼び出します。codecvtファセットが変換を定義している場合、ソース範囲 [from, from_end) の内部文字を外部文字に変換し、結果を to から始まる後続の場所に格納します。from_end - from 個以下の内部文字を変換し、to_end - to 個以下の外部文字を書き込みます。from_next と to_next は、正常に変換された最後の要素の次の位置を指すようにします。このcodecvtファセットが変換を定義していない場合、文字は変換されません。to_next は to と等しく設定され、state は変更されず、std::codecvt_base::noconv が返されます。
do_out(state, from, from + 1, from_next, to, to_end, to_next) は、次の場合にokを返さなければなりません。
- この
codecvtファセットが basic_filebuf によって使用される場合、そして - do_out(state, from, from_end, from_next, to, to_end, to_next) が、from != from_end の場合に
okを返す場合。
目次 |
[編集] 戻り値
std::codecvt_base::result 型の値。成功ステータスを示す。
ok
|
変換が完了した |
部分的
|
出力バッファのスペースが不足しているか、ソースバッファの予期しない終端 |
error
|
変換できない文字が見つかった |
noconv
|
このファセットは非変換であり、出力は書き込まれなかった |
非変換特殊化 std::codecvt<char, char, std::mbstate_t> は常に std::codecvt_base::noconv を返します。
[編集] 注記
from <= from_end && to <= to_end であり、state が初期シフト状態を表しているか、またはシーケンスの先行する文字を変換することによって取得された状態であることを要求します。
codecvtはN:M変換（例：UTF-16からUTF-8へ、2つの内部文字が必要な場合がある）をサポートしますが、std::basic_filebufは1:N変換を定義するcodecvtファセットのみを使用できます。つまり、ファイルへの書き込み時に1度に1つの内部文字を処理できる必要があります。
N:M変換を実行する場合、この関数はソース文字をすべて消費した後（from_next == from_end）、std::codecvt_base::partialを返すことがあります。これは、変換を完了するために別の内部文字が必要であることを意味します（例：UTF-16からUTF-8への変換で、ソースバッファの最後の文字が高位サロゲートの場合）。
state への影響は意図的に未定義です。標準ファセットでは、std::wcsrtombs を呼び出す際のシフト状態を維持するために使用され、したがって最後に正常に変換された文字の後のシフト状態を反映するように更新されますが、ユーザー定義ファセットはそれを任意の他の状態（例：特殊文字の数を数える）を維持するために自由に再利用できます。
[編集] 例
#include <iostream> #include <locale> #include <string> int main() { std::locale::global(std::locale("en_US.utf8")); auto& f = std::use_facet<std::codecvt<wchar_t, char, std::mbstate_t>>(std::locale()); std::wstring internal = L"z\u00df\u6c34\U0001f34c"; // L"zß水🍌" // note that the following can be done with wstring_convert std::mbstate_t mb{}; // initial shift state std::string external(internal.size() * f.max_length(), '\0'); const wchar_t* from_next; char* to_next; f.out(mb, &internal[0], &internal[internal.size()], from_next, &external[0], &external[external.size()], to_next); // error checking skipped for brevity external.resize(to_next - &external[0]); std::cout << "The string in narrow multibyte encoding: " << external << '\n'; }
出力
The string in narrow multibyte encoding: zß水🍌
[編集] 不具合報告
以下の動作変更を伴う欠陥報告が、以前に公開されたC++標準に遡って適用されました。
| DR | 適用対象 | 公開された動作 | 正しい動作 |
|---|---|---|---|
| LWG 76 | C++98 | 変換が必要かどうか不明確だった 一度に1つの内部文字を受け入れることをサポートするために |
使用する場合のみ必要 by basic_filebuf |
[編集] 関連項目
| [virtual] |
ファイルバッファの格納領域から、関連付けられたファイルへ文字を書き込みます。 ( std::basic_filebuf<CharT,Traits> の保護仮想メンバ関数) |
| ワイド文字列をバイト文字列に変換する ( std::wstring_convert<Codecvt,Elem,Wide_alloc,Byte_alloc> の公開メンバ関数) | |
| 与えられた状態で、ワイド文字列をナローマルチバイト文字列に変換する (関数) | |
| [virtual] |
ファイルからの読み込み時など、ExternT から InternT への文字列を変換します。(仮想保護メンバ関数) |
