std::codecvt_utf16
Определён в заголовке <codecvt> | ||
|---|---|---|
template<
class Elem,
unsigned long Maxcode = 0x10ffff,
std::codecvt_mode Mode = (std::codecvt_mode)0 >
class codecvt_utf16
: public std::codecvt<Elem, char, std::mbstate_t>;
| (начиная с C++11) (устарело в C++17) (удалено в C++26) |
std::codecvt_utf16 — это фасет std::codecvt, инкапсулирующий преобразование между байтовой строкой в кодировке UTF-16 и символьной строкой в кодировке UCS-2 или UTF-32 (в зависимости от типа Elem). Этот фасет std::codecvt можно использовать для чтения и записи файлов UTF-16 в двоичном режиме.
UCS-2 — устаревшая кодировка, являющаяся подмножеством UTF-16; она кодирует только скалярные значения в диапазоне U+0000–U+FFFF (базовая многоязычная плоскость).
Параметры шаблона
| Elem | - | либо char16_t, либо char32_t, либо wchar_t |
| Maxcode | - | наибольшее значение Elem, которое этот фасет будет читать или записывать без ошибок |
| Mode | - | константа типа std::codecvt_mode |
Функции-члены
создаёт новый фасет codecvt_utf16 (открытая функция-член) |
|
уничтожает фасет codecvt_utf16 (открытая функция-член) |
std::codecvt_utf16::codecvt_utf16
explicit codecvt_utf16( std::size_t refs = 0 ); |
Создаёт новый фасет std::codecvt_utf16, передавая базовому классу начальное значение счётчика ссылок refs.
Параметры
| refs | - | количество ссылок, указывающих на фасет |
std::codecvt_utf16::~codecvt_utf16
~codecvt_utf16(); |
Уничтожает фасет. В отличие от фасетов, управляемых локалью, деструктор этого фасета является открытым.
Унаследовано от 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
| Вложенный тип | Определение |
|---|---|
| enumresult{ok,partial,error,noconv}; | Неперечисляемый тип перечисления |
| Элемент перечисления | Определение |
|---|---|
ok | преобразование выполнено без ошибок |
partial | не все исходные символы были преобразованы |
error | обнаружен недопустимый символ |
noconv | преобразование не требуется, типы входных и выходных данных совпадают |
Примечания
Хотя стандарт требует, чтобы эта грань работала с UCS-2, когда размер Elem составляет 16 бит, некоторые реализации вместо этого используют UTF-16, что делает такую локаль неконвертирующей. Термин «UCS-2» был объявлен устаревшим и исключён из ISO 10646.
Пример
В следующем примере показано декодирование файла UTF-16le в системе с 32-битным wchar_t. В системе с 16-битным wchar_t декодирование третьего символа завершится ошибкой, поскольку std::codecvt_utf16<char16_t> выдаёт UCS-2, а не UTF-16.
#include <codecvt>
#include <cwchar>
#include <fstream>
#include <iostream>
#include <locale>
#include <string>
void prepare_file()
{
// UTF-16le data (if host system is little-endian)
char16_t utf16le[4] = {0x007a, // latin small letter 'z' U+007a
0x6c34, // CJK ideograph "water" U+6c34
0xd834, 0xdd0b}; // musical sign segno U+1d10b
// store in a file
std::ofstream fout("text.txt");
fout.write(reinterpret_cast<char*>(utf16le), sizeof utf16le);
}
int main()
{
prepare_file();
// open as a byte stream
std::wifstream fin("text.txt", std::ios::binary);
// apply facet
fin.imbue(std::locale(fin.getloc(),
new std::codecvt_utf16<wchar_t, 0x10ffff, std::little_endian>));
wchar_t c = 0;
for (std::cout << std::showbase << std::hex; fin.get(c);
std::cout << static_cast<std::wint_t>(c) << '\n');
}
Вывод:
0x7a 0x6c34 0x1d10b
Отчёты об ошибках
Следующие отчёты об ошибках, изменяющие поведение, были ретроактивно применены к ранее опубликованным стандартам C++.
| DR | Применён к | Опубликованное поведение | Правильное поведение |
|---|---|---|---|
| LWG 2229 | C++98 | конструктор и деструктор не были специфицированы | специфицирует их |
См. также
| Преобразования символов | многобайтовые кодировки, определяемые локалью (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> |
| преобразует кодировки символов, включая UTF-8, UTF-16 и UTF-32 (шаблон класса) |
|
|
(C++11)(устарел в C++17)(удалён в C++26) | теги для изменения поведения стандартных граней codecvt (перечисление) |
|
(C++11)(устарел в C++17)(удалён в C++26) | преобразует UTF-8 в 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_utf16