std::codecvt_byname

Определено в заголовке `<locale>`
template< class InternT, class ExternT, class State > class codecvt_byname : public std::codecvt<InternT, ExternT, State>;

std::codecvt_byname — это std::codecvt фасет, который инкапсулирует правила преобразования многобайтовых/широких символов для локали, указанной при его создании.

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

Стандартная библиотека гарантирует предоставление следующих специализаций:

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

Члены

(конструктор)	создаёт новый `codecvt_byname` фасет (публичный член-функция)
(деструктор)	уничтожает `codecvt_byname` фасет (защищённый член-функция)

std::codecvt_byname::codecvt_byname

explicit codecvt_byname( const char* name, std::size_t refs = 0 );
explicit codecvt_byname( const std::string& name, std::size_t refs = 0 );		(с C++11)

Создаёт новый std::codecvt_byname фасет для локали с name.

refs используется для управления ресурсами: если refs == 0, то реализация уничтожает фасет, когда последний объект std::locale содержащий его, уничтожается. В противном случае объект не уничтожается.

Параметры

name	-	имя локали
refs	-	количество ссылок, связанных с фасетом

std::codecvt_byname::~codecvt_byname

protected:
~codecvt_byname();

Уничтожает фасет.

Наследуется от 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`	преобразование не требуется, типы входных и выходных данных совпадают

Пример

Этот пример демонстрирует чтение файла, закодированного в GB18030, с использованием компоненты codecvt из локали, поддерживающей GB18030.

#include <fstream>
#include <iostream>
#include <locale>
#include <string>
 
int main()
{
    // GB18030 narrow multibyte encoding
    std::ofstream("text.txt") << "\x7a"              // letter 'z', U+007a
                                 "\x81\x30\x89\x38"  // letter 'ß', U+00df
                                 "\xcb\xae"          // CJK ideogram '水' (water), U+6c34
                                 "\x94\x32\xbc\x35"; // musical sign '𝄋' (segno), U+1d10b
 
    std::wifstream fin("text.txt");
    fin.imbue(std::locale(fin.getloc(),
              new std::codecvt_byname<wchar_t, char, std::mbstate_t>("zh_CN.gb18030")));
 
    for (wchar_t c; fin.get(c);)
        std::cout << std::hex << std::showbase << static_cast<unsigned>(c) << '\n';
}

Возможный вывод:

0x7a
0xdf
0x6c34
0x1d10b

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

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

DR	Применяется к	Поведение, как опубликовано	Правильное поведение
LWG 21	C++98	библиотека стандартной библиотеки не должна была предоставлять никаких `std::codecvt_byname` специализаций	требуются две специализации

См. также

codecvt

преобразует между кодировками символов, включая UTF-8, UTF-16, UTF-32
(шаблон класса)

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