Annex D (normative) Compatibility features [depr]

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

В шапку<locale> внесены следующие дополнения:

namespace std {
  template <class Codecvt, class Elem = wchar_t,
            class Wide_alloc = allocator<Elem>,
            class Byte_alloc = allocator<char>>
    class wstring_convert;

  template <class Codecvt, class Elem = wchar_t,
            class Tr = char_traits<Elem>>
    class wbuffer_convert;
}

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 incvtptr, state_­type() incvtstate,byte_­err inbyte_­err_­stringиwide_­err in wide_­err_­string.

~wstring_convert();

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

D.16.2 Class template wbuffer_­convert [depr.conversions.buffer]

Шаблон классаwbuffer_­convert выглядит как широкий буфер потока, но все операции ввода-вывода выполняются через нижележащий буфер потока байтов, который вы указываете при его создании. Как и шаблон классаwstring_­convert, он позволяет указать фасет преобразования кода для выполнения преобразований, не затрагивая никакие потоки или языковые стандарты.

namespace std {
  template <class Codecvt, class Elem = wchar_t, class Tr = char_traits<Elem>>
    class wbuffer_convert : public basic_streambuf<Elem, Tr> {
    public:
      using state_type = typename Codecvt::state_type;

      explicit wbuffer_convert(streambuf* bytebuf = 0,
                               Codecvt* pcvt = new Codecvt,
                               state_type state = state_type());

      ~wbuffer_convert();

      wbuffer_convert(const wbuffer_convert&) = delete;
      wbuffer_convert& operator=(const wbuffer_convert&) = delete;

      streambuf* rdbuf() const;
      streambuf* rdbuf(streambuf* bytebuf);

      state_type state() const;

    private:
      streambuf* bufptr;            // exposition only
      Codecvt* cvtptr;              // exposition only
      state_type cvtstate;          // exposition only
  };
}

Шаблон класса описывает буфер потока, который управляет передачей элементов типаElem, характеристики символов которых описываются классомTr, в буфер потока байтов типа и из него streambuf. Преобразование между последовательностьюElem значений и многобайтовыми последовательностями выполняется объектом класса Codecvt, который должен удовлетворять требованиям стандартного аспекта преобразования кодаcodecvt<Elem, char, mbstate_­t>.

В объекте этого шаблона класса хранятся:

  • bufptr - указатель на его нижележащий буфер потока байтов

  • cvtptr - указатель на выделенный объект преобразования (который освобождается приwbuffer_­convert уничтожении объекта)

  • cvtstate - объект состояния преобразования

state_type state() const;

Returns:cvtstate.

streambuf* rdbuf() const;

Returns:bufptr.

streambuf* rdbuf(streambuf* bytebuf);

Effects: Магазиныbytebuf вbufptr.

Returns: Предыдущее значениеbufptr.

using state_type = typename Codecvt::state_type;

Тип должен быть синонимом дляCodecvt​::​state_­type.

explicit wbuffer_convert( streambuf* bytebuf = 0, Codecvt* pcvt = new Codecvt, state_type state = state_type());

Requires: pcvt != nullptr.

Effects: Конструктор строит объект буфера потока, инициализирует bufptr кbytebuf, инициализируетcvtptr кpcvtи инициализируетcvtstate кstate.

~wbuffer_convert();

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