std::codecvt_byname

定义于头文件 `<locale>`
template< class InternT, class ExternT, class State > class codecvt_byname : public std::codecvt<InternT, ExternT, State>;

std::codecvt_byname 是一个 std::codecvt facet，它封装了在其构造时指定的区域设置的多字节/宽字符转换规则。

定义于头文件 `<locale>`
std::codecvt_byname<char, char, std::mbstate_t>	同一性转换
std::codecvt_byname<char16_t, char, std::mbstate_t> (C++11 起)(C++20 中弃用)	UTF-16 和 UTF-8 之间的转换
std::codecvt_byname<char16_t, char8_t, std::mbstate_t> (C++20 起)	UTF-16 和 UTF-8 之间的转换
std::codecvt_byname<char32_t, char, std::mbstate_t> (C++11 起)(C++20 中弃用)	UTF-32 和 UTF-8 之间的转换
std::codecvt_byname<char32_t, char8_t, std::mbstate_t> (C++20 起)	UTF-32 和 UTF-8 之间的转换
std::codecvt_byname<wchar_t, char, std::mbstate_t>	宽字符串和窄字符集之间的区域设置特定转换

[编辑] 成员函数

(构造函数)	构造一个新的 `codecvt_byname` facet (public member function) [编辑]
(析构函数)	销毁一个 `codecvt_byname` facet (protected member function) [编辑]

[编辑]

std::codecvt_byname::codecvt_byname

explicit codecvt_byname( const char* name, std::size_t refs = 0 );
explicit codecvt_byname( const std::string& name, std::size_t refs = 0 );		(C++11 起)

为具有 name 的区域设置构造一个新的 std::codecvt_byname facet。

refs 用于资源管理：如果 refs == 0，则当最后一个持有它的 std::locale 对象被销毁时，实现会销毁该 facet。否则，对象不会被销毁。

参数

name	-	区域设置的名称
refs	-	链接到 facet 的引用计数

[编辑]

std::codecvt_byname::~codecvt_byname

protected: ~codecvt_byname();

销毁 facet。

继承自 std::codecvt

嵌套类型

类型	定义
`intern_type`	`internT`
`extern_type`	`externT`
`state_type`	`stateT`

[编辑] 数据成员

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

成员函数

out	调用 `do_out` (`std::codecvt<InternT,ExternT,StateT>` 的公共成员函数) [编辑]
in	调用 `do_in` (`std::codecvt<InternT,ExternT,StateT>` 的公共成员函数) [编辑]
unshift	调用 `do_unshift` (`std::codecvt<InternT,ExternT,StateT>` 的公共成员函数) [编辑]
encoding	调用 `do_encoding` (`std::codecvt<InternT,ExternT,StateT>` 的公共成员函数) [编辑]
always_noconv	调用 `do_always_noconv` (`std::codecvt<InternT,ExternT,StateT>` 的公共成员函数) [编辑]
length	调用 `do_length` (`std::codecvt<InternT,ExternT,StateT>` 的公共成员函数) [编辑]
max_length	调用 `do_max_length` (`std::codecvt<InternT,ExternT,StateT>` 的公共成员函数) [编辑]

受保护的成员函数

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

继承自 std::codecvt_base

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

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

[编辑] 示例

此示例演示如何使用来自支持 GB18030 的区域设置的 codecvt facet 读取 GB18030 编码的文件。

运行此代码

#include <fstream>
#include <iostream>
#include <locale>
#include <string>
 
int main()
{
    // GB18030 narrow multibyte encoding
    std::ofstream("text.txt") << "\x7a"              // letter 'z', U+007a
                                 "\x81\x30\x89\x38"  // letter 'ß', U+00df
                                 "\xcb\xae"          // CJK ideogram '水' (water), U+6c34
                                 "\x94\x32\xbc\x35"; // musical sign '𝄋' (segno), U+1d10b
 
    std::wifstream fin("text.txt");
    fin.imbue(std::locale(fin.getloc(),
              new std::codecvt_byname<wchar_t, char, std::mbstate_t>("zh_CN.gb18030")));
 
    for (wchar_t c; fin.get(c);)
        std::cout << std::hex << std::showbase << static_cast<unsigned>(c) << '\n';
}

可能的输出

0x7a
0xdf
0x6c34
0x1d10b

[编辑] 缺陷报告

下列更改行为的缺陷报告追溯地应用于以前出版的 C++ 标准。

缺陷报告	应用于	发布时的行为	正确的行为
LWG 21	C++98	标准库不需要提供任何 `std::codecvt_byname` 特化	需要两个特化

[编辑] 参阅

codecvt

在字符编码之间转换，包括 UTF-8、UTF-16、UTF-32
(类模板) [编辑]

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

cppreference.cn

命名空间

变体

视图

操作