std::codecvt_utf16

 

C++

编译器支持

独立和宿主式

语言

标准库

标准库头文件

命名要求

特性测试宏 (C++20)

语言支持库

概念库 (C++20)

诊断库

内存管理库

元编程库 (C++11)

通用工具库

容器库

迭代器库

范围库 (C++20)

算法库

字符串库

文本处理库

数值库

日期和时间库

输入/输出库

文件系统库 (C++17)

并发支持库 (C++11)

执行控制库 (C++26)

技术规范

符号索引

外部库

 

文本处理库

本地化库

正则表达式库 (C++11)

格式化库 (C++20)

空字符结尾序列工具

字节字符串

多字节字符串

宽字符串

原始数值转换

to_chars (C++17) to_chars_result (C++17) from_chars (C++17) from_chars_result (C++17) chars_format (C++17)

文本编码标识

text_encoding (C++26)

 

本地化库

本地环境和侧面   本地环境 has_facet use_facet locale 侧面类别 基类 ctype_base codecvt_base messages_base time_base money_base ctype 侧面 ctype ctype<char> ctype_byname codecvt codecvt_byname numeric 侧面 num_get num_put numpunct numpunct_byname collate 侧面 collate collate_byname time 侧面 time_get time_put time_get_byname time_put_byname

monetary 侧面 money_get money_put moneypunct moneypunct_byname messages 侧面 messages messages_byname 字符分类和转换 字符分类 isspace    iscntrl isupper islower    isalpha ispunct isdigit    isxdigit isalnum isblank (C++11) isprint isgraph 字符转换 toupper    tolower 字符串和流转换 wstring_convert (C++11/17/26*) wbuffer_convert (C++11/17/26*) Unicode 转换侧面 codecvt_utf8 (C++11/17/26*) codecvt_utf16 (C++11/17/26*) codecvt_utf8_utf16 (C++11/17/26*) codecvt_mode (C++11/17/26*) C 库本地环境 LC_ALLLC_COLLATELC_CTYPELC_MONETARYLC_NUMERICLC_TIME    setlocale localeconv lconv

 

定义于头文件 <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>;		(since C++11) (deprecated in C++17) (removed in C++26)

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

UCS-2 是一种过时的编码，它是 UTF-16 的子集，仅编码 U+0000-U+FFFF 范围内的标量值（基本多文种平面）。

模板参数

Elem	-	char16_t、char32_t 或 wchar_t 之一
Maxcode	-	此侧面在没有错误的情况下读取或写入的 Elem 的最大值
Mode	-	std::codecvt_mode 类型的常量

成员函数

（构造函数）	构造一个新的 codecvt_utf16 侧面 （公共成员函数）
（析构函数）	销毁一个 codecvt_utf16 侧面 （公共成员函数）

std::codecvt_utf16::codecvt_utf16

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

构造一个新的 std::codecvt_utf16 侧面，并将初始引用计数器 refs 传递给基类。

参数

refs

-

链接到此侧面的引用数

std::codecvt_utf16::~codecvt_utf16

~codecvt_utf16();

销毁此侧面。与本地环境管理的侧面不同，此侧面的析构函数是公共的。

继承自 std::codecvt

嵌套类型

类型	定义
intern_type	internT
extern_type	externT
state_type	stateT

数据成员

成员	描述
std::locale::id id [static]	侧面的标识符

成员函数

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]	测试此侧面是否为所有有效参数值编码恒等转换 （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	转换已完成，没有错误
partial	并非所有源字符都被转换
error	遇到无效字符
noconv	无需转换，输入和输出类型相同

注释

尽管标准要求当 Elem 的大小为 16 位时，此侧面应与 UCS-2 一起使用，但某些实现改为使用 UTF-16，使其成为非转换的本地环境。“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 data (if host system is little-endian)
    char16_t utf16le[4] = {0x007a,          // latin small letter 'z' U+007a
                           0x6c34,          // CJK ideograph "water"  U+6c34
                           0xd834, 0xdd0b}; // musical sign segno U+1d10b    
 
    // store in a file
    std::ofstream fout("text.txt");
    fout.write(reinterpret_cast<char*>(utf16le), sizeof utf16le);
}
 
int main()
{
    prepare_file();
    // open as a byte stream
    std::wifstream fin("text.txt", std::ios::binary);
    // apply 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++ 标准。

DR	应用于	已发布行为	正确行为
LWG 2229	C++98	构造函数和析构函数未指定	指定它们

参见

字符 转换	本地环境定义的多字节 （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	在字符编码之间转换，包括 UTF-8、UTF-16、UTF-32 （类模板）
codecvt_mode (C++11)(deprecated in C++17)(removed in C++26)	用于更改标准 codecvt 侧面行为的标签 （枚举）
codecvt_utf8 (C++11)(deprecated in C++17)(removed in C++26)	在 UTF-8 和 UCS-2/UCS-4 之间转换 （类模板）
codecvt_utf8_utf16 (C++11)(deprecated in C++17)(removed in C++26)	在 UTF-8 和 UTF-16 之间转换 （类模板）