std::codecvt_utf8

 

C++

编译器支持

独立和宿主

语言

标准库

标准库头文件

命名需求

功能测试宏 (C++20)

语言支持库

概念库 (C++20)

元编程库 (C++11)

诊断库

通用工具库

字符串库

容器库

迭代器库

范围库 (C++20)

算法库

数值库

本地化库

输入/输出库

文件系统库 (C++17)

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

并发支持库 (C++11)

执行支持库 (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
数值方面
num_get num_put	numpunct numpunct_byname
整理方面
collate	collate_byname
时间方面
time_get time_put	time_get_byname time_put_byname
货币方面
money_get money_put	moneypunct moneypunct_byname
消息方面
messages	messages_byname

字符分类和转换
字符分类
isspace isblank (C++11) iscntrl	isupper islower isalpha	ispunct isdigit isxdigit	isalnum isprint isgraph

字符转换

toupper

tolower

字符串和流转换

wstring_convert (C++11/17/26*)

wbuffer_convert (C++11/17/26*)

文本编码标识

text_encoding (C++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_utf8     : public std::codecvt<Elem, char, std::mbstate_t>;		(自 C++11 起) (在 C++17 中已弃用) (在 C++26 中已删除)

std::codecvt_utf8 是一个 std::codecvt 方面，它封装了 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	-	此方面将在不发生错误的情况下读取或写入的 Elem 的最大值
Mode	-	类型为 std::codecvt_mode 的常量

成员函数

(构造函数)	构造一个新的 codecvt_utf8 方面 (公共成员函数)
(析构函数)	销毁一个 codecvt_utf8 方面 (公共成员函数)

std::codecvt_utf8::codecvt_utf8

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

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

参数

refs

-

链接到方面的引用数

std::codecvt_utf8::~codecvt_utf8

~codecvt_utf8();

销毁方面。与区域设置管理的方面不同，此方面的析构函数是公开的。

从 std::codecvt 继承

成员类型

成员名称	定义
intern_type	internT
extern_type	externT
state_type	stateT

成员对象

成员名称	类型
id (静态)	std::locale::id

成员函数

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 [虚函数]	将字符串从 InternT 转换为 ExternT，例如在写入文件时 (std::codecvt<InternT,ExternT,StateT> 的虚函数受保护的成员函数)
do_in [虚函数]	将字符串从 ExternT 转换为 InternT，例如在从文件读取时 (std::codecvt<InternT,ExternT,StateT> 的虚函数受保护的成员函数)
do_unshift [虚函数]	为不完整转换生成 ExternT 字符的终止字符序列 (std::codecvt<InternT,ExternT,StateT> 的虚函数受保护的成员函数)
do_encoding [虚函数]	如果为常量，则返回生成一个 InternT 字符所需的 ExternT 字符数 (std::codecvt<InternT,ExternT,StateT> 的虚函数受保护的成员函数)
do_always_noconv [虚函数]	测试方面是否为所有有效参数值编码身份转换 (std::codecvt<InternT,ExternT,StateT> 的虚函数受保护的成员函数)
do_length [虚函数]	计算将被转换为给定 InternT 缓冲区的 ExternT 字符串的长度 (std::codecvt<InternT,ExternT,StateT> 的虚函数受保护的成员函数)
do_max_length [虚函数]	返回可以转换为单个 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 中删除。

示例

以下示例演示了 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

另请参阅

字符 转换	区域设置定义的多字节 (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)(C++17 中已弃用)(C++26 中删除)	标签用于更改标准 codecvt 方面的行为 (枚举)
codecvt_utf16 (C++11)(C++17 中已弃用)(C++26 中删除)	在 UTF-16 和 UCS-2/UCS-4 之间转换 (类模板)
codecvt_utf8_utf16 (C++11)(C++17 中已弃用)(C++26 中删除)	在 UTF-8 和 UTF-16 之间转换 (类模板)