Annex D (normative) Compatibility features [depr]

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

1
#
The header <locale> has the following additions:
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]

1
#
Class template wstring_­convert performs conversions between a wide string and a byte string.
It lets you specify a code conversion facet (like class template codecvt) to perform the conversions, without affecting any streams or locales.
[ Example
:
If you want to use the code conversion facet codecvt_­utf8 to output to cout a UTF-8 multibyte sequence corresponding to a wide string, but you don't want to alter the locale for cout, you can write something like: 
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
    };
}
2
#
The class template describes an object that controls conversions between wide string objects of class basic_­string<Elem, char_­traits<Elem>, Wide_­alloc> and byte string objects of class basic_­string<char, char_­traits<char>, Byte_­alloc>.
The class template defines the types wide_­string and byte_­string as synonyms for these two types.
Conversion between a sequence of Elem values (stored in a wide_­string object) and multibyte sequences (stored in a byte_­string object) is performed by an object of class Codecvt, which meets the requirements of the standard code-conversion facet codecvt<Elem, char, mbstate_­t>.
3
#
An object of this class template stores:
  • (3.1)
    byte_­err_­string — a byte string to display on errors
  • (3.2)
    wide_­err_­string — a wide string to display on errors
  • (3.3)
    cvtptr — a pointer to the allocated conversion object (which is freed when the wstring_­convert object is destroyed)
  • (3.4)
    cvtstate — a conversion state object
  • (3.5)
    cvtcount — a conversion count
using byte_string = basic_string<char, char_traits<char>, Byte_alloc>;
4
#
The type shall be a synonym for basic_­string<char, char_­traits<char>, Byte_­alloc>.
size_t converted() const noexcept;
5
#
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);
6
#
Effects: The first member function shall convert the single-element sequence byte to a wide string.
The second member function shall convert the null-terminated sequence beginning at ptr to a wide string.
The third member function shall convert the sequence stored in str to a wide string.
The fourth member function shall convert the sequence defined by the range [first, last) to a wide string.
7
#
In all cases:
  • (7.1)
    If the cvtstate object was not constructed with an explicit value, it shall be set to its default value (the initial conversion state) before the conversion begins.
    Otherwise it shall be left unchanged.
  • (7.2)
    The number of input elements successfully converted shall be stored in cvtcount.
8
#
Returns: If no conversion error occurs, the member function shall return the converted wide string.
Otherwise, if the object was constructed with a wide-error string, the member function shall return the wide-error string.
Otherwise, the member function throws an object of class range_­error.
using int_type = typename wide_string::traits_type::int_type;
9
#
The type shall be a synonym for wide_­string​::​traits_­type​::​int_­type.
state_type state() const;
10
#
returns cvtstate.
using state_type = typename Codecvt::state_type;
11
#
The type shall be a synonym for 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);
12
#
Effects: The first member function shall convert the single-element sequence wchar to a byte string.
The second member function shall convert the null-terminated sequence beginning at wptr to a byte string.
The third member function shall convert the sequence stored in wstr to a byte string.
The fourth member function shall convert the sequence defined by the range [first, last) to a byte string.
13
#
In all cases:
  • (13.1)
    If the cvtstate object was not constructed with an explicit value, it shall be set to its default value (the initial conversion state) before the conversion begins.
    Otherwise it shall be left unchanged.
  • (13.2)
    The number of input elements successfully converted shall be stored in cvtcount.
14
#
Returns: If no conversion error occurs, the member function shall return the converted byte string.
Otherwise, if the object was constructed with a byte-error string, the member function shall return the byte-error string.
Otherwise, the member function shall throw an object of class range_­error.
using wide_string = basic_string<Elem, char_traits<Elem>, Wide_alloc>;
15
#
The type shall be a synonym for 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());
16
#
Requires: For the first and second constructors, pcvt != nullptr.
17
#
Effects: The first constructor shall store pcvt in cvtptr and default values in cvtstate, byte_­err_­string, and wide_­err_­string.
The second constructor shall store pcvt in cvtptr, state in cvtstate, and default values in byte_­err_­string and wide_­err_­string; moreover the stored state shall be retained between calls to from_­bytes and to_­bytes.
The third constructor shall store new Codecvt in cvtptr, state_­type() in cvtstate, byte_­err in byte_­err_­string, and wide_­err in wide_­err_­string.
~wstring_convert();
18
#
Effects: The destructor shall delete cvtptr.

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

1
#
Class template wbuffer_­convert looks like a wide stream buffer, but performs all its I/O through an underlying byte stream buffer that you specify when you construct it.
Like class template wstring_­convert, it lets you specify a code conversion facet to perform the conversions, without affecting any streams or locales.
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
  };
}
2
#
The class template describes a stream buffer that controls the transmission of elements of type Elem, whose character traits are described by the class Tr, to and from a byte stream buffer of type streambuf.
Conversion between a sequence of Elem values and multibyte sequences is performed by an object of class Codecvt, which shall meet the requirements of the standard code-conversion facet codecvt<Elem, char, mbstate_­t>.
3
#
An object of this class template stores:
  • (3.1)
    bufptr — a pointer to its underlying byte stream buffer
  • (3.2)
    cvtptr — a pointer to the allocated conversion object (which is freed when the wbuffer_­convert object is destroyed)
  • (3.3)
    cvtstate — a conversion state object
state_type state() const;
4
#
Returns: cvtstate.
streambuf* rdbuf() const;
5
#
Returns: bufptr.
streambuf* rdbuf(streambuf* bytebuf);
6
#
Effects: Stores bytebuf in bufptr.
7
#
Returns: The previous value of bufptr.
using state_type = typename Codecvt::state_type;
8
#
The type shall be a synonym for Codecvt​::​state_­type.
explicit wbuffer_convert( streambuf* bytebuf = 0, Codecvt* pcvt = new Codecvt, state_type state = state_type());
9
#
Requires: pcvt != nullptr.
10
#
Effects: The constructor constructs a stream buffer object, initializes bufptr to bytebuf, initializes cvtptr to pcvt, and initializes cvtstate to state.
~wbuffer_convert();
11
#
Effects: The destructor shall delete cvtptr.