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 , который инкапсулирует преобразование между строкой байтов в кодировке 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

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

(constructor)
создает новый codecvt_utf8 фасе́т
(публичная функция-член)
(destructor)
уничтожает 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

Вложенный тип Определение
enum result { 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 Applied to Behavior as published Correct behavior
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 >
преобразует между кодировками символов, включая 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
(шаблон класса)