Spec-Zone.ru › C++

std::codecvt

Определён в заголовочном файле <locale>
template< 
    class InternT, 
    class ExternT, 
    class StateT
> class codecvt;

Шаблон класса std::codecvt инкапсулирует преобразование строк символов, включая широкие и многобайтовые строки, из одной кодировки в другую. Все операции ввода-вывода файлов, выполняемые через std::basic_fstream<CharT>, используют фасет std::codecvt<CharT,char,std::mbstate_t> локали, которой наделён поток.

cpp/locale/codecvt base cpp/locale/locale/facet

Диаграмма наследования

Специализации

Стандартная библиотека гарантированно предоставляет следующие специализации (они должны быть реализованы любым объектом локали):

Определены в заголовочном файле <locale>
std::codecvt<char,char,std::mbstate_t> преобразование без изменений
std::codecvt<char16_t,char,std::mbstate_t>
(начиная с C++11)(устарело в C++20)
преобразование между UTF-16 и UTF-8
std::codecvt<char16_t,char8_t,std::mbstate_t>
(начиная с C++20)(устарело)
преобразование между UTF-16 и UTF-8
std::codecvt<char32_t,char,std::mbstate_t>
(начиная с C++11)(устарело в C++20)
преобразование между UTF-32 и UTF-8
std::codecvt<char32_t,char8_t,std::mbstate_t>
(начиная с C++20)(устарело)
преобразование между UTF-32 и UTF-8
std::codecvt<wchar_t,char,std::mbstate_t> преобразование между системными широкими символами и однобайтовыми узкими символами

Вложенные типы

Тип Определение
intern_type InternT
extern_type ExternT
state_type StateT

Члены-данные

Член Описание
std::locale::id id [static] идентификатор фасета

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

(конструктор)
создаёт новый фасет codecvt
(открытая функция-член)
out
вызывает do_out
(открытая функция-член)
in
вызывает do_in
(открытая функция-член)
unshift
вызывает do_unshift
(открытая функция-член)
encoding
вызывает do_encoding
(открытая функция-член)
always_noconv
вызывает do_always_noconv
(открытая функция-член)
length
вызывает do_length
(открытая функция-член)
max_length
вызывает do_max_length
(открытая функция-член)

Защищённые функции-члены

(деструктор)
уничтожает фасет codecvt
(защищённая функция-член)
do_out
[виртуальная]
преобразует строку из InternT в ExternT, например при записи в файл
(виртуальная защищённая функция-член)
do_in
[виртуальная]
преобразует строку из ExternT в InternT, например при чтении из файла
(виртуальная защищённая функция-член)
do_unshift
[виртуальная]
формирует завершающую последовательность символов ExternT для незавершённого преобразования
(виртуальная защищённая функция-член)
do_encoding
[виртуальная]
возвращает количество символов ExternT, необходимое для получения одного символа InternT, если оно постоянно
(виртуальная защищённая функция-член)
do_always_noconv
[виртуальная]
проверяет, выполняет ли фасет тождественное преобразование для всех допустимых значений аргументов
(виртуальная защищённая функция-член)
do_length
[виртуальная]
вычисляет длину строки ExternT, которая будет использована при преобразовании в заданный буфер InternT
(виртуальная защищённая функция-член)
do_max_length
[виртуальная]
возвращает максимальное количество символов ExternT, которое можно преобразовать в один символ InternT
(виртуальная защищённая функция-член)

Унаследовано от std::codecvt_base

Вложенный тип Определение
enumresult{ok,partial,error,noconv}; Перечисление без области видимости
Элемент перечисления Определение
ok преобразование завершено без ошибок
partial не все исходные символы были преобразованы
error обнаружен недопустимый символ
noconv преобразование не требуется, типы входных и выходных данных совпадают

Пример

В следующих примерах файл UTF-8 считывается с использованием локали, которая реализует преобразование UTF-8 в codecvt<wchar_t,char,std::mbstate_t>, а строка UTF-8 преобразуется в UTF-16 с помощью одной из стандартных специализаций std::codecvt.

#include <codecvt>
#include <cstdint>
#include <fstream>
#include <iomanip>
#include <iostream>
#include <locale>
#include <string>

// utility wrapper to adapt locale-bound facets for wstring/wbuffer convert
template<class Facet>
struct deletable_facet : Facet
{
    template<class... Args>
    deletable_facet(Args&&... args) : Facet(std::forward<Args>(args)...) {}
    ~deletable_facet() {}
};

int main()
{
    // UTF-8 narrow multibyte encoding
    std::string data = reinterpret_cast<const char*>(+u8"z\u00df\u6c34\U0001f34c");
                       // or reinterpret_cast<const char*>(+u8"zß水🍌")
                       // or "\x7a\xc3\x9f\xe6\xb0\xb4\xf0\x9f\x8d\x8c"
    
    std::ofstream("text.txt") << data;
    
    // using system-supplied locale's codecvt facet
    std::wifstream fin("text.txt");
    // reading from wifstream will use codecvt<wchar_t, char, std::mbstate_t>
    // this locale's codecvt converts UTF-8 to UCS4 (on systems such as Linux)
    fin.imbue(std::locale("en_US.UTF-8"));
    std::cout << "The UTF-8 file contains the following UCS4 code units:\n" << std::hex;
    for (wchar_t c; fin >> c;)
        std::cout << "U+" << std::setw(4) << std::setfill('0')
                  << static_cast<uint32_t>(c) << ' ';
    
    // using standard (locale-independent) codecvt facet
    std::wstring_convert<
        deletable_facet<std::codecvt<char16_t, char, std::mbstate_t>>, char16_t> conv16;
    std::u16string str16 = conv16.from_bytes(data);
    
    std::cout << "\n\nThe UTF-8 file contains the following UTF-16 code units:\n"
              << std::hex;
    for (char16_t c : str16)
        std::cout << "U+" << std::setw(4) << std::setfill('0')
                  << static_cast<uint16_t>(c) << ' ';
    std::cout << '\n';
}

Вывод:

The UTF-8 file contains the following UCS4 code units:
U+007a U+00df U+6c34 U+1f34c 

The UTF-8 file contains the following UTF-16 code units:
U+007a U+00df U+6c34 U+d83c U+df4c

Отчёты об ошибках

Следующие отчёты об ошибках, изменяющих поведение, были применены ретроактивно к ранее опубликованным стандартам C++.

DR Применяется к Поведение согласно опубликованной версии Правильное поведение
LWG 3767 C++20 std::codecvt<char16_t,char8_t,std::mbstate_t> и
std::codecvt<char32_t,char8_t,std::mbstate_t> не зависят от локали
объявить их устаревшими

См. также

Преобразования
символов
Многобайтовая кодировка, определяемая локалью
(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_base
определяет ошибки преобразования символов
(класс)
codecvt_byname
представляет предоставленный системой std::codecvt для локали с заданным именем
(шаблон класса)
codecvt_utf8
(C++11)(устарел в C++17)(удалён в C++26)
преобразует UTF-8 в UCS-2/UCS-4 и обратно
(шаблон класса)
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

Spec-Zone.ru

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