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 facet 定義了轉換，則將源範圍 [from, from_end) 中的內部字元翻譯為外部字元，將結果放置在從 to 開始的後續位置。最多轉換 from_end - from 個內部字元，最多寫入 to_end - to 個外部字元。讓 from_next 和 to_next 指向成功轉換的最後一個元素之後的位置。若此 codecvt facet 未定義轉換，則不轉換任何字元。to_next 設定為等於 to，state 保持不變，並返回 std::codecvt_base::noconv。
do_out(state, from, from + 1, from_next, to, to_end, to_next) 必須返回 ok，若
- 此
codecvtfacet 為 basic_filebuf 所用，且 - do_out(state, from, from_end, from_next, to, to_end, to_next) 將返回
ok，其中 from != from_end。
目錄 |
[編輯] 返回值
一個 std::codecvt_base::result 型別的值，指示成功狀態，如下所示
ok
|
轉換完成 |
部分
|
輸出緩衝區中空間不足，或源緩衝區意外結束 |
error
|
遇到無法轉換的字元 |
noconv
|
此 facet 不執行轉換，未寫入輸出 |
非轉換特化 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，其中可能需要兩個內部字元來決定輸出哪些外部字元），但 std::basic_filebuf 只能使用定義 1:N 轉換的 codecvt facet，即在寫入檔案時，它必須能夠一次處理一個內部字元。
執行 N:M 轉換時，此函式可能在消耗所有源字元（from_next == from_end）後返回 std::codecvt_base::partial。這意味著需要另一個內部字元來完成轉換（例如，當將 UTF-16 轉換為 UTF-8 時，如果源緩衝區中的最後一個字元是高代理項）。
對 state 的影響是故意未指定的。在標準 facet 中，它用於維護移位狀態，如同呼叫 std::wcsrtombs 時，因此會更新以反映最後成功轉換的字元後的移位狀態，但使用者定義的 facet 可以自由使用它來維護任何其他狀態，例如計算遇到的特殊字元的數量。
[編輯] 示例
#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++ 標準。
| 缺陷報告 | 應用於 | 釋出時的行為 | 正確的行為 |
|---|---|---|---|
| LWG 76 | C++98 | 不清楚轉換是否要求 支援一次處理一個內部字元 |
僅在被 basic_filebuf 使用時要求 |
[編輯] 參閱
| [virtual] |
從放置區向關聯檔案寫入字元 （ std::basic_filebuf<CharT,Traits> 的虛保護成員函式） |
| 將寬字串轉換為位元組字串 （ std::wstring_convert<Codecvt,Elem,Wide_alloc,Byte_alloc> 的公有成員函式） | |
| 將寬字串轉換為窄多位元組字元字串，給定狀態 （函式） | |
| [virtual] |
將字串從 ExternT 轉換為 InternT，例如從檔案讀取時（虛保護成員函式） |
