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> локали, которой наделён поток.
Диаграмма наследования
Специализации
Стандартная библиотека гарантированно предоставляет следующие специализации (они должны быть реализованы любым объектом локали):
Определены в заголовочном файле <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 (открытая функция-член) |
|
вызывает do_out (открытая функция-член) |
|
вызывает do_in (открытая функция-член) |
|
вызывает do_unshift (открытая функция-член) |
|
вызывает do_encoding (открытая функция-член) |
|
вызывает do_always_noconv (открытая функция-член) |
|
вызывает do_length (открытая функция-член) |
|
вызывает do_max_length (открытая функция-член) |
Защищённые функции-члены
уничтожает фасет codecvt (защищённая функция-член) |
|
|
[виртуальная] | преобразует строку из InternT в ExternT, например при записи в файл (виртуальная защищённая функция-член) |
|
[виртуальная] | преобразует строку из ExternT в InternT, например при чтении из файла (виртуальная защищённая функция-член) |
|
[виртуальная] | формирует завершающую последовательность символов ExternT для незавершённого преобразования (виртуальная защищённая функция-член) |
|
[виртуальная] | возвращает количество символов ExternT, необходимое для получения одного символа InternT, если оно постоянно (виртуальная защищённая функция-член) |
|
[виртуальная] | проверяет, выполняет ли фасет тождественное преобразование для всех допустимых значений аргументов (виртуальная защищённая функция-член) |
|
[виртуальная] | вычисляет длину строки ExternT, которая будет использована при преобразовании в заданный буфер InternT (виртуальная защищённая функция-член) |
|
[виртуальная] | возвращает максимальное количество символов 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) |
| Не применимо |
| 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> |
| определяет ошибки преобразования символов (класс) |
|
представляет предоставленный системой std::codecvt для локали с заданным именем (шаблон класса) |
|
|
(C++11)(устарел в C++17)(удалён в C++26) | преобразует UTF-8 в UCS-2/UCS-4 и обратно (шаблон класса) |
|
(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