std::codecvt<InternT,ExternT,StateT>:: out, do_out

如果此 codecvt facet 未定义转换，则不会转换任何字符。 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 的值，用于指示成功状态如下：

非转换特化 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转换时，此函数可能在消耗完所有源字符后返回 std::codecvt_base::partial （ from_next == from_end ）。这意味着需要另一个内部字符才能完成转换（例如，当从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ß水🍌"
    // 注意以下操作也可通过 wstring_convert 实现
    std::mbstate_t mb{}; // 初始移位状态
    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);
    // 为简洁起见省略了错误检查
    external.resize(to_next - &external[0]);
    std::cout << "The string in narrow multibyte encoding: " << external << '\n';
}

The string in narrow multibyte encoding: zß水🍌

缺陷报告

以下行为变更缺陷报告被追溯应用于先前发布的 C++ 标准。

参见