std::codecvt_utf8
Определён в заголовочном файле <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 |
Поля данных
| Элемент | Описание |
|---|---|
std::locale::id id [static] | идентификатор фасета |
Функции-члены
вызывает 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] | возвращает количество символов ExternT, необходимых для представления одного символа InternT, если оно постоянно (виртуальная защищённая функция-член std::codecvt<InternT,ExternT,StateT>) |
|
[virtual] | проверяет, выполняет ли фасет тождественное преобразование для всех допустимых значений аргументов (виртуальная защищённая функция-член std::codecvt<InternT,ExternT,StateT>) |
|
[virtual] | вычисляет длину строки ExternT, которая будет использована при преобразовании в заданный буфер InternT (виртуальная защищённая функция-член std::codecvt<InternT,ExternT,StateT>) |
|
[virtual] | возвращает максимальное количество символов ExternT, которые могут быть преобразованы в один символ InternT (виртуальная защищённая функция-член std::codecvt<InternT,ExternT,StateT>) |
Унаследовано от std::codecvt_base
| Вложенный тип | Определение |
|---|---|
| enumresult{ok,partial,error,noconv}; | Неперечисляемый тип перечисления |
| Элемент перечисления | Определение |
|---|---|
ok | преобразование выполнено без ошибок |
partial | не все исходные символы были преобразованы |
error | обнаружен недопустимый символ |
noconv | преобразование не требуется, типы входных и выходных данных совпадают |
Примечания
Хотя стандарт требует, чтобы этот фасет работал с UCS-2, когда размер Elem составляет 16 бит, некоторые реализации вместо этого используют 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++.
| DR | Применено к | Опубликованное поведение | Корректное поведение |
|---|---|---|---|
| LWG 2229 | C++98 | конструктор и деструктор не были специфицированы | специфицирует их |
См. также
| Преобразования символов | многобайтовая кодировка, определяемая локалью (UTF-8, GB18030) | UTF-8 | UTF-16 |
|---|---|---|---|
| UTF-16 |
mbrtoc16 / c16rtomb (с DR488 для C11) |
| Н/Д |
| UCS-2 |
c16rtomb (без DR488 для C11) |
codecvt_utf8<char16_t> |
codecvt_utf16<char16_t> |
| UTF-32 |
|
|
|
| системный wchar_t: UTF-32 (не Windows) |
|
codecvt_utf8<wchar_t> |
codecvt_utf16<wchar_t> |
| преобразует между кодировками символов, включая UTF-8, UTF-16, UTF-32 (шаблон класса) |
|
|
(C++11)(устарел в C++17)(удалён в C++26) | теги для изменения поведения стандартных фасетов codecvt (перечисление) |
|
(C++11)(устарел в C++17)(удалён в C++26) | преобразует между UTF-16 и UCS-2/UCS-4 (шаблон класса) |
|
(C++11)(устарел в C++17)(удалён в C++26) | преобразует между UTF-8 и UTF-16 (шаблон класса) |
© cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
https://en.cppreference.com/cpp/locale/codecvt_utf8