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> (начиная с C++11)(устарела в C++20)	преобразование между UTF-16 и UTF-8
std::codecvt_byname<char16_t,char8_t,std::mbstate_t> (начиная с C++20)	преобразование между UTF-16 и UTF-8
std::codecvt_byname<char32_t,char,std::mbstate_t> (начиная с C++11)(устарела в C++20)	преобразование между UTF-32 и UTF-8
std::codecvt_byname<char32_t,char8_t,std::mbstate_t> (начиная с C++20)	преобразование между UTF-32 и UTF-8
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`

Данные-члены

Член	Описание
`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 [виртуальная]	преобразует строку из `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

Вложенный тип	Определение
enumresult{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/cpp/locale/codecvt_byname