Namespaces
Variants

std:: codecvt_byname

From cppreference.net
C++
Text processing library
Localization library
定义于头文件 <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 > 宽字符串与窄字符集间的本地化特定转换

成员函数

(constructor)
构造新的 codecvt_byname facet
(公开成员函数)
(destructor)
销毁 codecvt_byname facet
(受保护成员函数)

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 ) ;
(since C++11)

为具有 name 的区域设置构造新的 std::codecvt_byname 平面。

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

参数

name - 区域设置的名称
refs - 链接到该平面的引用数量

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 的标识符

成员函数

调用 do_out
( std::codecvt<InternT,ExternT,StateT> 的公开成员函数)
调用 do_in
( std::codecvt<InternT,ExternT,StateT> 的公开成员函数)
调用 do_unshift
( std::codecvt<InternT,ExternT,StateT> 的公开成员函数)
调用 do_encoding
( std::codecvt<InternT,ExternT,StateT> 的公开成员函数)
调用 do_always_noconv
( std::codecvt<InternT,ExternT,StateT> 的公开成员函数)
调用 do_length
( std::codecvt<InternT,ExternT,StateT> 的公开成员函数)
调用 do_max_length
( std::codecvt<InternT,ExternT,StateT> 的公开成员函数)

受保护成员函数

[virtual]
将字符串从 InternT 转换为 ExternT ，例如写入文件时
( std::codecvt<InternT,ExternT,StateT> 的虚受保护成员函数)
[virtual]
将字符串从 ExternT 转换为 InternT ，例如从文件读取时
( std::codecvt<InternT,ExternT,StateT> 的虚受保护成员函数)
[virtual]
为不完整转换生成 ExternT 字符的终止字符序列
( std::codecvt<InternT,ExternT,StateT> 的虚受保护成员函数)
[virtual]
返回生成一个 InternT 字符所需的 ExternT 字符数（若为常量）
( std::codecvt<InternT,ExternT,StateT> 的虚受保护成员函数)
[virtual]
测试该 facet 是否对所有有效参数值执行恒等转换
( std::codecvt<InternT,ExternT,StateT> 的虚受保护成员函数)
[virtual]
计算转换为给定 InternT 缓冲区时将消耗的 ExternT 字符串长度
( std::codecvt<InternT,ExternT,StateT> 的虚受保护成员函数)
[virtual]
返回可转换为单个 InternT 字符的最大 ExternT 字符数
( std::codecvt<InternT,ExternT,StateT> 的虚受保护成员函数)

继承自 std:: codecvt_base

嵌套类型 定义
enum result { ok, partial, error, noconv } ; 非限定作用域枚举类型
枚举常量 定义
ok 转换成功完成且无错误
partial 未转换全部源字符
error 遇到无效字符
noconv 无需转换，输入输出类型相同

示例

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

运行此代码 
#include <fstream>
#include <iostream>
#include <locale>
#include <string>
int main()
{
    // GB18030窄字符多字节编码
    std::ofstream("text.txt") << "\x7a"              // 字母'z', U+007a
                                 "\x81\x30\x89\x38"  // 字母'ß', U+00df
                                 "\xcb\xae"          // 汉字'水', U+6c34
                                 "\x94\x32\xbc\x35"; // 音乐符号'𝄋' (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++标准。

DR 适用范围 发布时的行为 正确行为
LWG 21 C++98 标准库无需提供
任何 std::codecvt_byname 特化 		需要提供两个特化

参见

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