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 (основная многоязычная плоскость).

(с C++23)

Шаблонные параметры

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 [виртуальный]	возвращает количество `ExternT` символов, необходимых для получения одного `InternT` символа, если константа (виртуальная защищённая член-функция `std::codecvt<InternT,ExternT,StateT>`)
do_always_noconv [виртуальный]	проверяет, кодирует ли фасет тождественное преобразование для всех допустимых значений аргумента (виртуальная защищённая член-функция `std::codecvt<InternT,ExternT,StateT>`)
do_length [виртуальный]	вычисляет длину строки `ExternT`, которая будет потребляться преобразованием в заданный буфер `InternT` (виртуальная защищённая член-функция `std::codecvt<InternT,ExternT,StateT>`)
do_max_length [виртуальный]	возвращает максимальное количество `ExternT` символов, которые могут быть преобразованы в один `InternT` символ (виртуальная защищённая член-функция `std::codecvt<InternT,ExternT,StateT>`)

Наследуется от std::codecvt_base

Тип члена	Определение
enum result { ok, partial, error, noconv };	Тип перечисления без области видимости

Константа перечисления	Определение
`ok`	преобразование завершено без ошибок
`partial`	не все символы источника были преобразованы
`error`	обнаружен недопустимый символ
`noconv`	преобразование не требуется, типы входных и выходных данных одинаковы

Примечания

Хотя стандарт требует, чтобы этот фасет работал с UCS-2, когда размер Elem составляет 16 бит, некоторые реализации вместо этого используют UTF-16. Термин «UCS-2» устарел и удалён из ISO 10646.

С C++23 UCS-2 больше не относится к его первоначальному определению. Он становится синонимом UTF-16, но с более узким диапазоном кодирования.

Пример

Следующий пример демонстрирует разницу между преобразованиями 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` (с DR488 в C11)	`codecvt`<char16_t,char,mbstate_t> `codecvt_utf8_utf16`<char16_t> `codecvt_utf8_utf16`<char32_t> `codecvt_utf8_utf16`<wchar_t>	Н/Д
UCS-2	`c16rtomb` (без DR488 в C11)	`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 (шаблон класса)

© cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
https://en.cppreference.com/w/cpp/locale/codecvt_utf8