# std::codecvt_byname

< cpp‎ | locale

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

`std::codecvt_byname` 是 std::codecvt 平面，封装于构造时指定的 locale 的多字节/宽字符转换规则。

标准库提供以下独立特化：

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

### 成员函数

(构造函数) | 构造新的 `codecvt_byname` 平面 (公开成员函数)
(析构函数) | 析构 `codecvt_byname` 平面 (受保护成员函数)

## 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` 平面。

`refs` 用于资源管理：在销毁最后一个保有平面的 std::locale 对象时，若 refs == 0 ，则实现销毁平面对象。否则，不销毁对象。

### 参数

name | - | 本地环境的名称
refs | - | 链接到该平面的引用数

## std::codecvt_byname::~codecvt_byname

protected: ~codecvt_byname(); |  |

销毁平面。

## 继承自 std::codecvt

### 成员类型

成员类型 | 定义
`intern_type` | `internT`
`extern_type` | `externT`
`state_type` | `stateT`

### 成员对象

成员名 | 类型
`id` [静态] | std::locale::id

### 成员函数

out | 调用 `do_out` (`std::codecvt<InternT,ExternT,State>` 的公开成员函数)
in | 调用 `do_in` (`std::codecvt<InternT,ExternT,State>` 的公开成员函数)
unshift | 调用 `do_unshift` (`std::codecvt<InternT,ExternT,State>` 的公开成员函数)
encoding | 调用 `do_encoding` (`std::codecvt<InternT,ExternT,State>` 的公开成员函数)
always_noconv | 调用 `do_always_noconv` (`std::codecvt<InternT,ExternT,State>` 的公开成员函数)
length | 调用 `do_length` (`std::codecvt<InternT,ExternT,State>` 的公开成员函数)
max_length | 调用 `do_max_length` (`std::codecvt<InternT,ExternT,State>` 的公开成员函数)

### 受保护成员函数

do_out [虚] | 从 internT 转换字符串为 externT 转换字符串，如在写入文件时 (`std::codecvt<InternT,ExternT,State>` 的虚受保护成员函数)
do_in [虚] | 从 externT 转换字符串为 internT ，如在从文件读取时 (`std::codecvt<InternT,ExternT,State>` 的虚受保护成员函数)
do_unshift [虚] | 为不完整转换生成 externT 字符的终止字符序列 (`std::codecvt<InternT,ExternT,State>` 的虚受保护成员函数)
do_encoding [虚] | 返回产生一个 internT 字符所需的 externT 字符数，若此值为常数 (`std::codecvt<InternT,ExternT,State>` 的虚受保护成员函数)
do_always_noconv [虚] | 测试平面编码是否对所有合法值为恒等转换 (`std::codecvt<InternT,ExternT,State>` 的虚受保护成员函数)
do_length [虚] | 计算转换成给定的 internT 缓冲区会消耗的 externT 字符串长度 (`std::codecvt<InternT,ExternT,State>` 的虚受保护成员函数)
do_max_length [虚] | 返回能转换成单个 internT 字符的最大 externT 字符数 (`std::codecvt<InternT,ExternT,State>` 的虚受保护成员函数)

## 继承自 std::codecvt_base

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

枚举常量 | 定义
`ok` | 完成转换而无错误
`partial` | 未转换所有源字符
`error` | 遇到非法字符
`noconv` | 不要求转换，输入与输出类型相同

### 示例

此示例演示用来自具备 GB18030 的 locale 的本地环境读取 GB18030 编码的文件

    #include <iostream>
    #include <fstream>
    #include <string>
    #include <locale>

    int main()
    {
        // GB18030 窄多字节编码
        std::ofstream("text.txt") << "\x7a"              // 字母 'z' ， U+007a
                                     "\x81\x30\x89\x38"  // 字母 'ß' ， U+00df
                                     "\xcb\xae"          // CJK 表意字符 '水' ， 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 << c << '\n';
    }

输出：

    0x7a
    0xdf
    0x6c34
    0x1d10b

### 参阅

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