Spec-Zone.ru › C++

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] идентификатор фасета

Функции-члены

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

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/cpp/locale/codecvt_utf8

Spec-Zone.ru

Настройки Оффлайн Что нового Помощь О нас
Spec-Zone .ru
спецификации, руководства, описания, API