Namespaces
Variants

std:: codecvt_utf16

From cppreference.net
C++
Text processing library
Localization library
定义于头文件 <codecvt>
template <

class Elem,
unsigned long Maxcode = 0x10ffff ,
std:: codecvt_mode Mode = ( std:: codecvt_mode ) 0 >
class codecvt_utf16

: public std:: codecvt < Elem, char , std:: mbstate_t > ;
(C++11 起)
(C++17 中弃用)
(C++26 中移除)

std::codecvt_utf16 是一个 std::codecvt facet，它封装了 UTF-16 编码字节串与 UCS-2 或 UTF-32 字符串（取决于 Elem 类型）之间的转换。此 std::codecvt facet 可用于以二进制模式读写 UTF-16 文件。

UCS-2是一种过时的编码格式，属于UTF-16的子集，仅能对U+0000至U+FFFF（基本多文种平面）范围内的标量值进行编码。

目录

模板参数

Elem - 可以是 char16_t 、 char32_t 或 wchar_t 之一
Maxcode - 此 facet 能够无错误读写 Elem 类型的最大值
Mode - 类型为 std::codecvt_mode 的常量

成员函数

(constructor)
构造新的 codecvt_utf16 facet
(公开成员函数)
(destructor)
销毁 codecvt_utf16 facet
(公开成员函数)

std::codecvt_utf16:: codecvt_utf16

explicit codecvt_utf16 ( std:: size_t refs = 0 ) ;

构造新的 std::codecvt_utf16 facet，将初始引用计数器 refs 传递给基类。

参数

refs - 链接到该 facet 的引用数量

std::codecvt_utf16:: ~codecvt_utf16

~codecvt_utf16 ( ) ;

销毁该facet。与由locale管理的facet不同，此facet的析构函数是公开的。

继承自 std:: codecvt

嵌套类型

类型 定义
intern_type internT
extern_type externT
state_type stateT

数据成员

成员 描述
std::locale::id id [静态] 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> 的公开成员函数)

受保护成员函数

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

继承自 std:: codecvt_base

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

注释

尽管标准要求在 Elem 为16位时该facet应支持UCS-2编码，但某些实现会改用UTF-16编码，这使得该locale成为非转换区域。"UCS-2"这一术语现已被弃用，并从ISO 10646标准中移除。

示例

以下示例演示在具有32位 wchar_t 的系统上解码UTF-16le文件。在具有16位 wchar_t 的系统上，第三个字符的解码将失败，因为 std :: codecvt_utf16 < char16_t > 生成的是UCS-2编码，而非UTF-16。

运行此代码 
#include <codecvt>
#include <cwchar>
#include <fstream>
#include <iostream>
#include <locale>
#include <string>
void prepare_file()
{
    // UTF-16le 数据（若主机系统为小端序）
    char16_t utf16le[4] = {0x007a,          // 拉丁小写字母 'z' U+007a
                           0x6c34,          // 中日韩表意文字“水” U+6c34
                           0xd834, 0xdd0b}; // 音乐符号 segno U+1d10b    
    // 存入文件
    std::ofstream fout("text.txt");
    fout.write(reinterpret_cast<char*>(utf16le), sizeof utf16le);
}
int main()
{
    prepare_file();
    // 以字节流形式打开
    std::wifstream fin("text.txt", std::ios::binary);
    // 应用locale facet
    fin.imbue(std::locale(fin.getloc(),
        new std::codecvt_utf16<wchar_t, 0x10ffff, std::little_endian>));
    wchar_t c = 0;
    for (std::cout << std::showbase << std::hex; fin.get(c);
         std::cout << static_cast<std::wint_t>(c) << '\n');
}

输出： 

0x7a
0x6c34
0x1d10b

缺陷报告

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

缺陷报告 适用范围 发布时行为 正确行为
LWG 2229 C++98 未规定构造函数和析构函数 已规定这些函数

另请参阅

字符
转换 		区域设置定义的多字节
(UTF-8, GB18030) 		UTF-8
UTF-16
UTF-16 mbrtoc16 / c16rtomb (with C11's DR488)

codecvt < char16_t , char ,mbstate_t >
codecvt_utf8_utf16 < char16_t >
codecvt_utf8_utf16 < char32_t >
codecvt_utf8_utf16 < wchar_t >

不适用
UCS-2 c16rtomb (without C11's 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 >
在字符编码之间进行转换，包括 UTF-8、UTF-16、UTF-32
(类模板)
(C++11) (deprecated in C++17) (removed in C++26)
用于修改标准 codecvt facet 行为的标签
(枚举)
(C++11) (deprecated in C++17) (removed in C++26)
在 UTF-8 和 UCS-2/UCS-4 之间进行转换
(类模板)
(C++11) (deprecated in C++17) (removed in C++26)
在 UTF-8 和 UTF-16 之间进行转换
(类模板)