std::codecvt

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

类模板 std::codecvt 封装了字符字符串（包括宽字符和多字节字符）从一种编码到另一种编码的转换。所有通过 std::basic_fstream<CharT> 执行的文件 I/O 操作都使用流中注入的 locale 的 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`	转换完成，无错误
`部分`	并非所有源字符都已转换
`error`	遇到无效字符
`noconv`	无需转换，输入和输出类型相同

[编辑] 示例

以下示例使用在 codecvt<wchar_t, char, std::mbstate_t> 中实现 UTF-8 转换的 locale 读取 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++ 标准。

缺陷报告	应用于	发布时的行为	正确的行为
LWG 3767	C++20	std::codecvt<char16_t, char8_t, std::mbstate_t> 和 std::codecvt<char32_t, char8_t, std::mbstate_t> 是与 locale 无关的	弃用它们

[编辑] 参阅

字符转换	由区域设置定义的多字节 (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	表示指定 locale 的系统提供的 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 之间转换 (类模板) [编辑]

编译器支持
自由（freestanding）与宿主（hosted）
语言
标准库
标准库头文件
具名要求
特性测试宏 (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

命名空间

变体

视图

操作