Annex D (normative) Compatibility features [depr]

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

D.23.1 General [depr.conversions.general]

The header <locale> has the following additions: namespace std { template<class Codecvt, class Elem = wchar_t, class WideAlloc = allocator<Elem>, class ByteAlloc = allocator<char>> class wstring_convert; template<class Codecvt, class Elem = wchar_t, class Tr = char_traits<Elem>> class wbuffer_convert; }

D.23.2 Class template wstring_convert [depr.conversions.string]

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 1: 
If you want to use a code conversion facet, codecvt_for_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: std::wstring_convert<codecvt_for_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 WideAlloc = allocator<Elem>, class ByteAlloc = allocator<char>> class wstring_convert { public: using byte_string = basic_string<char, char_traits<char>, ByteAlloc>; using wide_string = basic_string<Elem, char_traits<Elem>, WideAlloc>; using state_type = typename Codecvt::state_type; using int_type = typename wide_string::traits_type::int_type; wstring_convert() : wstring_convert(new Codecvt) {} explicit wstring_convert(Codecvt* pcvt); 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 }; }
The class template describes an object that controls conversions between wide string objects of class basic_string<Elem, char_traits<Elem>, WideAlloc> and byte string objects of class basic_string<char, char_traits<char>, ByteAlloc>.
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>.
An object of this class template stores:
  • byte_err_string — a byte string to display on errors
  • wide_err_string — a wide string to display on errors
  • cvtptr — a pointer to the allocated conversion object (which is freed when the wstring_convert object is destroyed)
  • cvtstate — a conversion state object
  • cvtcount — a conversion count
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: The first member function converts the single-element sequence byte to a wide string.
The second member function converts the null-terminated sequence beginning at ptr to a wide string.
The third member function converts the sequence stored in str to a wide string.
The fourth member function converts the sequence defined by the range [first, last) to a wide string.
In all cases:
  • If the cvtstate object was not constructed with an explicit value, it is set to its default value (the initial conversion state) before the conversion begins.
    Otherwise it is left unchanged.
  • The number of input elements successfully converted is stored in cvtcount.
Returns: If no conversion error occurs, the member function returns the converted wide string.
Otherwise, if the object was constructed with a wide-error string, the member function returns the wide-error string.
Otherwise, the member function throws an object of class range_error.
state_type state() const;
Returns: cvtstate.
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: The first member function converts the single-element sequence wchar to a byte string.
The second member function converts the null-terminated sequence beginning at wptr to a byte string.
The third member function converts the sequence stored in wstr to a byte string.
The fourth member function converts the sequence defined by the range [first, last) to a byte string.
In all cases:
  • If the cvtstate object was not constructed with an explicit value, it is set to its default value (the initial conversion state) before the conversion begins.
    Otherwise it is left unchanged.
  • The number of input elements successfully converted is stored in cvtcount.
Returns: If no conversion error occurs, the member function returns the converted byte string.
Otherwise, if the object was constructed with a byte-error string, the member function returns the byte-error string.
Otherwise, the member function throws an object of class range_error.
explicit wstring_convert(Codecvt* pcvt); wstring_convert(Codecvt* pcvt, state_type state); explicit wstring_convert(const byte_string& byte_err, const wide_string& wide_err = wide_string());
Preconditions: For the first and second constructors, pcvt is not null.
Effects: The first constructor stores pcvt in cvtptr and default values in cvtstate, byte_err_string, and wide_err_string.
The second constructor stores pcvt in cvtptr, state in cvtstate, and default values in byte_err_string and wide_err_string; moreover the stored state is retained between calls to from_bytes and to_bytes.
The third constructor stores new Codecvt in cvtptr, state_type() in cvtstate, byte_err in byte_err_string, and wide_err in wide_err_string.
~wstring_convert();
Effects: delete cvtptr.

D.23.3 Class template wbuffer_convert [depr.conversions.buffer]

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; wbuffer_convert() : wbuffer_convert(nullptr) {} explicit wbuffer_convert(streambuf* bytebuf, 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 }; }
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>.
An object of this class template stores:
  • bufptr — a pointer to its underlying byte stream buffer
  • cvtptr — a pointer to the allocated conversion object (which is freed when the wbuffer_convert object is destroyed)
  • cvtstate — a conversion state object
state_type state() const;
Returns: cvtstate.
streambuf* rdbuf() const;
Returns: bufptr.
streambuf* rdbuf(streambuf* bytebuf);
Effects: Stores bytebuf in bufptr.
Returns: The previous value of bufptr.
explicit wbuffer_convert( streambuf* bytebuf, Codecvt* pcvt = new Codecvt, state_type state = state_type());
Preconditions: pcvt is not null.
Effects: The constructor constructs a stream buffer object, initializes bufptr to bytebuf, initializes cvtptr to pcvt, and initializes cvtstate to state.
~wbuffer_convert();
Effects: delete cvtptr.