Шаблон класса wstring_convert выполняет преобразования между широкой строкой и байтовой строкой. Он позволяет указать фасет преобразования кода (например, шаблон класса codecvt) для выполнения преобразований, не затрагивая какие-либо потоки или языковые стандарты. [ Example: Если вы хотите использовать фасет преобразования кода codecvt_utf8 для вывода в cout многобайтовую последовательность UTF-8, соответствующую широкой строке, но вы не хотите изменять языковой стандарт cout, вы можете написать что-то вроде:
wstring_convert<std::codecvt_utf8<wchar_t>> myconv; std::string mbstring = myconv.to_bytes(L"Hello\n"); std::cout << mbstring;
— end example ]
namespace std { template <class Codecvt, class Elem = wchar_t, class Wide_alloc = allocator<Elem>, class Byte_alloc = allocator<char>> class wstring_convert { public: using byte_string = basic_string<char, char_traits<char>, Byte_alloc>; using wide_string = basic_string<Elem, char_traits<Elem>, Wide_alloc>; using state_type = typename Codecvt::state_type; using int_type = typename wide_string::traits_type::int_type; explicit wstring_convert(Codecvt* pcvt = new Codecvt); wstring_convert(Codecvt* pcvt, state_type state); explicit wstring_convert(const byte_string& byte_err, const wide_string& wide_err = wide_string()); ~wstring_convert(); wstring_convert(const wstring_convert&) = delete; wstring_convert& operator=(const wstring_convert&) = delete; wide_string from_bytes(char byte); wide_string from_bytes(const char* ptr); wide_string from_bytes(const byte_string& str); wide_string from_bytes(const char* first, const char* last); byte_string to_bytes(Elem wchar); byte_string to_bytes(const Elem* wptr); byte_string to_bytes(const wide_string& wstr); byte_string to_bytes(const Elem* first, const Elem* last); size_t converted() const noexcept; state_type state() const; private: byte_string byte_err_string; // exposition only wide_string wide_err_string; // exposition only Codecvt* cvtptr; // exposition only state_type cvtstate; // exposition only size_t cvtcount; // exposition only }; }
Шаблон класса описывает объект, который управляет преобразованиями между объектами широких строк класса basic_string<Elem, char_traits<Elem>, Wide_alloc> и объектами байтовых строк класса basic_string<char, char_traits<char>, Byte_alloc>. Шаблон класса определяет типы wide_string и byte_string как синонимы для этих двух типов. Преобразование между последовательностью Elem значений (хранящейся в wide_string объекте) и многобайтовыми последовательностями (хранящейся в byte_string объекте) выполняется объектом класса Codecvt, который соответствует требованиям стандартного аспекта преобразования кода codecvt<Elem, char, mbstate_t>.
В объекте этого шаблона класса хранятся:
byte_err_string - строка байтов для отображения при ошибках
wide_err_string - широкая строка для отображения при ошибках
cvtptr - указатель на выделенный объект преобразования (который освобождается при wstring_convert уничтожении объекта)
cvtstate - объект состояния преобразования
cvtcount - счетчик конверсий
using byte_string = basic_string<char, char_traits<char>, Byte_alloc>;
size_t converted() const noexcept;
wide_string from_bytes(char byte);
wide_string from_bytes(const char* ptr);
wide_string from_bytes(const byte_string& str);
wide_string from_bytes(const char* first, const char* last);
Effects: Первая функция-член должна преобразовывать одноэлементную последовательность byte в широкую строку. Вторая функция-член должна преобразовать последовательность с завершающим нулем, начинающуюся ptr с, в широкую строку. Третья функция-член должна преобразовать сохраненную последовательность в str широкую строку. Четвертая функция-член должна преобразовывать последовательность, определенную диапазоном, [first, last) в широкую строку.
В любом случае:
Если cvtstate объект не был создан с явным значением, ему должно быть присвоено значение по умолчанию (начальное состояние преобразования) до начала преобразования. В противном случае оставить без изменений.
Количество успешно преобразованных входных элементов должно быть сохранено в cvtcount.
Returns: Если ошибки преобразования не возникает, функция-член должна возвращать преобразованную широкую строку. В противном случае, если объект был построен с использованием строки с расширенной ошибкой, функция-член должна возвращать строку с расширенной ошибкой. В противном случае функция-член создает объект класса range_error.
using int_type = typename wide_string::traits_type::int_type;
state_type state() const;
using state_type = typename Codecvt::state_type;
byte_string to_bytes(Elem wchar);
byte_string to_bytes(const Elem* wptr);
byte_string to_bytes(const wide_string& wstr);
byte_string to_bytes(const Elem* first, const Elem* last);
Effects: Первая функция-член должна преобразовывать одноэлементную последовательность wchar в байтовую строку. Вторая функция-член должна преобразовать последовательность с завершающим нулем, начинающуюся wptr с, в байтовую строку. Третья функция-член должна преобразовать сохраненную последовательность в wstr байтовую строку. Четвертая функция-член должна преобразовывать последовательность, определенную диапазоном, [first, last) в байтовую строку.
В любом случае:
Если cvtstate объект не был создан с явным значением, ему должно быть присвоено значение по умолчанию (начальное состояние преобразования) до начала преобразования. В противном случае оставить без изменений.
Количество успешно преобразованных входных элементов должно быть сохранено в cvtcount.
Returns: Если ошибки преобразования не возникает, функция-член должна возвращать преобразованную байтовую строку. В противном случае, если объект был построен со строкой байтовой ошибки, функция-член должна вернуть строку байтовой ошибки. В противном случае функция-член должна генерировать объект класса range_error.
using wide_string = basic_string<Elem, char_traits<Elem>, Wide_alloc>;
explicit wstring_convert(Codecvt* pcvt = new Codecvt);
wstring_convert(Codecvt* pcvt, state_type state);
explicit wstring_convert(const byte_string& byte_err,
const wide_string& wide_err = wide_string());
Effects: Первый конструктор должен хранить pcvt в cvtptr и значения по умолчанию в cvtstate, byte_err_stringи wide_err_string. Второй конструктор должен сохранять pcvt в cvtptr, state в cvtstateи значения по умолчанию в byte_err_string и wide_err_string; кроме того, сохраненное состояние должно сохраняться между вызовами from_bytes и to_bytes. Третий конструктор должен сохранять new Codecvt in cvtptr, state_type() in cvtstate, byte_err in byte_err_stringи wide_err in wide_err_string.
~wstring_convert();