Namespaces
Variants

std:: codecvt_utf8_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_utf8_utf16

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

std::codecvt_utf8_utf16 是一个 std::codecvt facet，它封装了 UTF-8 编码字节串与 UTF-16 编码字符串之间的转换。如果 Elem 是 32 位类型，每个输出序列的 32 位字符将存储一个 UTF-16 码元。

这是一个N:M转换facet，不能与 std::basic_filebuf 一起使用（后者仅允许在内部编码和外部编码之间进行1:N转换，例如UTF-32/UTF-8）。该facet可与 std::wstring_convert 配合使用。

目录

模板参数

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

成员函数

(constructor)
构造新的 codecvt_utf8_utf16 转换平面
(公开成员函数)
(destructor)
销毁 codecvt_utf8_utf16 转换平面
(公开成员函数)

std::codecvt_utf8_utf16:: codecvt_utf8_utf16

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

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

参数

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

std::codecvt_utf8_utf16:: ~codecvt_utf8_utf16

~codecvt_utf8_utf16 ( ) ;

销毁该facet。与由locale管理的facet不同，此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 无需转换，输入输出类型相同

示例

运行此代码 
#include <cassert>
#include <codecvt>
#include <cstdint>
#include <iostream>
#include <locale>
#include <string>
int main()
{
    std::string u8 = "z\u00df\u6c34\U0001f34c";
    std::u16string u16 = u"z\u00df\u6c34\U0001f34c";
    // UTF-8 转 UTF-16/char16_t
    std::u16string u16_conv = std::wstring_convert<
        std::codecvt_utf8_utf16<char16_t>, char16_t>{}.from_bytes(u8);
    assert(u16 == u16_conv);
    std::cout << "UTF-8 转 UTF-16 转换生成 " << u16_conv.size()
              << " 个编码单元：\n" << std::showbase << std::hex;
    for (char16_t c : u16_conv)
        std::cout << static_cast<std::uint16_t>(c) << ' ';
    // UTF-16/char16_t 转 UTF-8
    std::string u8_conv = std::wstring_convert<
        std::codecvt_utf8_utf16<char16_t>, char16_t>{}.to_bytes(u16);
    assert(u8 == u8_conv);
    std::cout << "\nUTF-16 转 UTF-8 转换生成 "
              << std::dec << u8_conv.size() << " 字节：\n" << std::hex;
    for (char c : u8_conv)
        std::cout << +static_cast<unsigned char>(c) << ' ';
    std::cout << '\n';
}

输出： 

UTF-8 转 UTF-16 转换生成 5 个编码单元：
0x7a 0xdf 0x6c34 0xd83c 0xdf4c
UTF-16 转 UTF-8 转换生成 10 字节：
0x7a 0xc3 0x9f 0xe6 0xb0 0xb4 0xf0 0x9f 0x8d 0x8c

缺陷报告

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

DR 适用范围 发布时的行为 正确行为
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) (C++17 中弃用) (C++26 中移除)
用于改变标准 codecvt facet 行为的标签
（枚举）
(C++11) (C++17 中弃用) (C++26 中移除)
在 UTF-8 和 UCS-2/UCS-4 之间进行转换
（类模板）
(C++11) (C++17 中弃用) (C++26 中移除)
在 UTF-16 和 UCS-2/UCS-4 之间进行转换
（类模板）