Annex D (normative) Compatibility features [depr]

D.16 Deprecated convenience conversion interfaces [depr.conversions]

D.16.1 Class template wstring_­convert [depr.conversions.string]

Шаблон класса 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>;

Тип должен быть синонимом для basic_­string<char, char_­traits<char>, Byte_­alloc>.

size_t converted() const noexcept;

Returns: cvtcount.

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;

Тип должен быть синонимом для wide_­string​::​traits_­type​::​int_­type.

state_type state() const;

возвращается cvtstate.

using state_type = typename Codecvt::state_type;

Тип должен быть синонимом для 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>;

Тип должен быть синонимом для 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());

Requires: Для первого и второго конструкторов pcvt != nullptr.

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();

Effects: Деструктор должен удалить cvtptr.