std::codecvt

定义于头文件 `<locale>`
template< class InternT, class ExternT, class StateT > class codecvt;

类模板 std::codecvt 封装了字符字符串（包括宽字符和多字节字符）从一种编码到另一种编码的转换。所有通过 std::basic_fstream<CharT> 执行的文件 I/O 操作都使用在流中注入的区域设置的 std::codecvt<CharT, char, std::mbstate_t> facet。

继承关系图

定义于头文件 `<locale>`
std::codecvt<char, char, std::mbstate_t>	恒等转换
std::codecvt<char16_t, char, std::mbstate_t> (自 C++11 起)(在 C++20 中已弃用)	UTF-16 和 UTF-8 之间的转换
std::codecvt<char16_t, char8_t, std::mbstate_t> (自 C++20 起)(已弃用)	UTF-16 和 UTF-8 之间的转换
std::codecvt<char32_t, char, std::mbstate_t> (自 C++11 起)(在 C++20 中已弃用)	UTF-32 和 UTF-8 之间的转换
std::codecvt<char32_t, char8_t, std::mbstate_t> (自 C++20 起)(已弃用)	UTF-32 和 UTF-8 之间的转换
std::codecvt<wchar_t, char, std::mbstate_t>	系统原生宽字符集和单字节窄字符集之间的转换

[编辑] 嵌套类型

类型	定义
`intern_type`	`InternT`
`extern_type`	`ExternT`
`state_type`	`StateT`

[编辑] 数据成员

成员	描述
std::locale::id `id` [静态]	facet 的标识符

[编辑] 成员函数

(构造函数)	构造一个新的 `codecvt` facet (公共成员函数)
out	调用 `do_out` (公共成员函数) [编辑]
in	调用 `do_in` (公共成员函数) [编辑]
unshift	调用 `do_unshift` (公共成员函数) [编辑]
encoding	调用 `do_encoding` (公共成员函数) [编辑]
always_noconv	调用 `do_always_noconv` (公共成员函数) [编辑]
length	调用 `do_length` (公共成员函数) [编辑]
max_length	调用 `do_max_length` (公共成员函数) [编辑]

[编辑] 受保护成员函数

(析构函数)	析构一个 `codecvt` facet (受保护成员函数)
do_out [虚函数]	将字符串从 `InternT` 转换为 `ExternT`，例如在写入文件时 (虚函数受保护成员函数) [编辑]
do_in [虚函数]	将字符串从 `ExternT` 转换为 `InternT`，例如在从文件读取时 (虚函数受保护成员函数) [编辑]
do_unshift [虚函数]	为不完整的转换生成 `ExternT` 字符的终止字符序列 (虚函数受保护成员函数) [编辑]
do_encoding [虚函数]	如果恒定，则返回生成一个 `InternT` 字符所需的 `ExternT` 字符数 (虚函数受保护成员函数) [编辑]
do_always_noconv [虚函数]	测试 facet 是否为所有有效参数值编码恒等转换 (虚函数受保护成员函数) [编辑]
do_length [虚函数]	计算将转换为给定 `InternT` 缓冲区所消耗的 `ExternT` 字符串的长度 (虚函数受保护成员函数) [编辑]
do_max_length [虚函数]	返回可以转换为单个 `InternT` 字符的最大 `ExternT` 字符数 (虚函数受保护成员函数) [编辑]

继承自 std::codecvt_base

嵌套类型	定义
enum result { ok, partial, error, noconv };	无作用域枚举类型

枚举常量	定义
`ok`	转换已完成，没有错误
`partial`	并非所有源字符都被转换
`error`	遇到无效字符
`noconv`	无需转换，输入和输出类型相同

[编辑] 示例

以下示例使用在 codecvt<wchar_t, char, std::mbstate_t> 中实现 UTF-8 转换的区域设置读取 UTF-8 文件，并使用 std::codecvt 的标准特化之一将 UTF-8 字符串转换为 UTF-16。

运行此代码

#include <codecvt>
#include <cstdint>
#include <fstream>
#include <iomanip>
#include <iostream>
#include <locale>
#include <string>
 
// utility wrapper to adapt locale-bound facets for wstring/wbuffer convert
template<class Facet>
struct deletable_facet : Facet
{
    template<class... Args>
    deletable_facet(Args&&... args) : Facet(std::forward<Args>(args)...) {}
    ~deletable_facet() {}
};
 
int main()
{
    // UTF-8 narrow multibyte encoding
    std::string data = reinterpret_cast<const char*>(+u8"z\u00df\u6c34\U0001f34c");
                       // or reinterpret_cast<const char*>(+u8"zß水🍌")
                       // or "\x7a\xc3\x9f\xe6\xb0\xb4\xf0\x9f\x8d\x8c"
 
    std::ofstream("text.txt") << data;
 
    // using system-supplied locale's codecvt facet
    std::wifstream fin("text.txt");
    // reading from wifstream will use codecvt<wchar_t, char, std::mbstate_t>
    // this locale's codecvt converts UTF-8 to UCS4 (on systems such as Linux)
    fin.imbue(std::locale("en_US.UTF-8"));
    std::cout << "The UTF-8 file contains the following UCS4 code units:\n" << std::hex;
    for (wchar_t c; fin >> c;)
        std::cout << "U+" << std::setw(4) << std::setfill('0')
                  << static_cast<uint32_t>(c) << ' ';
 
    // using standard (locale-independent) codecvt facet
    std::wstring_convert<
        deletable_facet<std::codecvt<char16_t, char, std::mbstate_t>>, char16_t> conv16;
    std::u16string str16 = conv16.from_bytes(data);
 
    std::cout << "\n\nThe UTF-8 file contains the following UTF-16 code units:\n"
              << std::hex;
    for (char16_t c : str16)
        std::cout << "U+" << std::setw(4) << std::setfill('0')
                  << static_cast<uint16_t>(c) << ' ';
    std::cout << '\n';
}

输出

The UTF-8 file contains the following UCS4 code units:
U+007a U+00df U+6c34 U+1f34c 
 
The UTF-8 file contains the following UTF-16 code units:
U+007a U+00df U+6c34 U+d83c U+df4c

[编辑] 缺陷报告

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

DR	应用于	已发布行为	正确行为
LWG 3767	C++20	std::codecvt<char16_t, char8_t, std::mbstate_t> 和 std::codecvt<char32_t, char8_t, std::mbstate_t> 是独立于区域设置的	已弃用它们

[编辑] 参见

字符转换	区域设置定义的多字节 (UTF-8, GB18030)	UTF-8	UTF-16
UTF-16	`mbrtoc16` / `c16rtomb` (使用 C11 的 DR488)	`codecvt`<char16_t,char,mbstate_t> `codecvt_utf8_utf16`<char16_t> `codecvt_utf8_utf16`<char32_t> `codecvt_utf8_utf16`<wchar_t>	N/A
UCS-2	`c16rtomb` (不使用 C11 的 DR488)	`codecvt_utf8`<char16_t>	`codecvt_utf16`<char16_t>
UTF-32	`mbrtoc32` / `c32rtomb`	`codecvt`<char32_t,char,mbstate_t> `codecvt_utf8`<char32_t>	`codecvt_utf16`<char32_t>
系统 wchar_t UTF-32 (非 Windows) UCS-2 (Windows)	`mbsrtowcs` / `wcsrtombs` `use_facet`<`codecvt` <wchar_t,char,mbstate_t>>(`locale`)	`codecvt_utf8`<wchar_t>	`codecvt_utf16`<wchar_t>

codecvt_base	定义字符转换错误 (类) [编辑]
codecvt_byname	表示命名区域设置的系统提供的 std::codecvt (类模板) [编辑]
codecvt_utf8 (C++11)(在 C++17 中已弃用)(在 C++26 中移除)	在 UTF-8 和 UCS-2/UCS-4 之间转换 (类模板) [编辑]
codecvt_utf16 (C++11)(在 C++17 中已弃用)(在 C++26 中移除)	在 UTF-16 和 UCS-2/UCS-4 之间转换 (类模板) [编辑]
codecvt_utf8_utf16 (C++11)(在 C++17 中已弃用)(在 C++26 中移除)	在 UTF-8 和 UTF-16 之间转换 (类模板) [编辑]

编译器支持
独立和宿主式
语言
标准库
标准库头文件
具名要求
特性测试宏 (C++20)
语言支持库
概念库 (C++20)
诊断库
内存管理库
元编程库 (C++11)
通用工具库
容器库
迭代器库
范围库 (C++20)
算法库
字符串库
文本处理库
数值库
日期和时间库
输入/输出库
文件系统库 (C++17)
并发支持库 (C++11)
执行控制库 (C++26)
技术规范
符号索引
外部库

成员函数
codecvt::codecvt
codecvt::~codecvt
codecvt::outcodecvt::do_out
codecvt::incodecvt::do_in
codecvt::unshiftcodecvt::do_unshift
codecvt::encodingcodecvt::do_encoding
codecvt::always_noconvcodecvt::do_always_noconv
codecvt::lengthcodecvt::do_length
codecvt::max_lengthcodecvt::do_max_length

cppreference.cn

命名空间

变体

视图

操作