Namespaces
Variants

std:: codecvt_utf8

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

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

std::codecvt_utf8 是一个 std::codecvt 平面（facet），用于封装 UTF-8 编码字节串与 UCS-2 或 UTF-32 字符串（取决于 Elem 类型）之间的转换。此 std::codecvt 平面可用于读写 UTF-8 文件，包括文本文件和二进制文件。

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

目录

模板参数

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

成员函数

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

std::codecvt_utf8:: codecvt_utf8

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

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

参数

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

std::codecvt_utf8:: ~codecvt_utf8

~codecvt_utf8 ( ) ;

销毁该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。术语 "UCS-2" 已被弃用并从 ISO 10646 标准中移除。

示例

以下示例演示了 UCS-2/UTF-8 与 UTF-16/UTF-8 转换之间的差异：字符串中的第三个字符不是有效的 UCS-2 字符。

运行此代码 
#include <codecvt>
#include <cstdint>
#include <iostream>
#include <locale>
#include <string>
int main()
{
    // UTF-8 data. The character U+1d10b, musical sign segno, does not fit in UCS-2
    std::string utf8 = "z\u6c34\U0001d10b";
    // the UTF-8 / UTF-16 standard conversion facet
    std::wstring_convert<std::codecvt_utf8_utf16<char16_t>, char16_t> utf16conv;
    std::u16string utf16 = utf16conv.from_bytes(utf8);
    std::cout << "UTF-16 conversion produced " << utf16.size() << " code units:\n"
              << std::showbase << std::hex;
    for (char16_t c : utf16)
        std::cout << static_cast<std::uint16_t>(c) << ' ';
    // the UTF-8 / UCS-2 standard conversion facet
    std::wstring_convert<std::codecvt_utf8<char16_t>, char16_t> ucs2conv;
    try
    {
        std::u16string ucs2 = ucs2conv.from_bytes(utf8);
    }
    catch(const std::range_error& e)
    {
        std::u16string ucs2 = ucs2conv.from_bytes(utf8.substr(0, ucs2conv.converted()));
        std::cout << "\nUCS-2 failed after producing " << std::dec << ucs2.size()
                  << " characters:\n" << std::showbase << std::hex;
        for (char16_t c : ucs2)
            std::cout << static_cast<std::uint16_t>(c) << ' ';
        std::cout << '\n';
    }
}

输出： 

UTF-16 conversion produced 4 code units:
0x7a 0x6c34 0xd834 0xdd0b
UCS-2 failed after producing 2 characters:
0x7a 0x6c34

缺陷报告

以下行为变更缺陷报告被追溯应用于先前发布的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) (C++17 中弃用) (C++26 中移除)
用于改变标准 codecvt facet 行为的标签
（枚举）
(C++11) (C++17 中弃用) (C++26 中移除)
在 UTF-16 与 UCS-2/UCS-4 之间进行转换
（类模板）
(C++11) (C++17 中弃用) (C++26 中移除)
在 UTF-8 与 UTF-16 之间进行转换
（类模板）