wstring"`

Include the header "Dinkum/codecvt/wstring" to define template class wstring_convert, for performing conversions between a wide string and a byte string.

`wstring_convert`

namespace Dinkum {
    namespace codecvt {
template<class Codecvt,
    class Elem = wchar_t>
    class wstring_convert
    {
    typedef std::basic_string<char> byte_string;
    typedef std::basic_string<Elem> wide_string;
    typedef typename Codecvt::state_type state_type;
    typedef typename wide_string::traits_type::int_type int_type;

    wstring_convert(Codecvt *pcvt = new Codecvt);
    wstring_convert(Codecvt *pcvt, state_type state);
    wstring_convert(const byte_string& byte_err,
        const wide_string& wide_err = wide_string());

    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;
    state_type state() const;

    // exposition only
private:
    byte_string byte_err_string;
    wide_string wide_err_string;
    Codecvt *cvtptr;
    state_type cvtstate;
    size_t cvtcount;
    };
        }  // namespace codecvt
    }  // namespace Dinkum

The template class describes an object that controls conversions between wide string objects of class std::basic_string<Elem> and byte string objects of class std::basic_string<char> (also known as std::string). The template class 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<Elem, char, std::mbstate_t>, which meets the requirements of the standard code-conversion facet std::codecvt<Elem, char, std::mbstate_t>.

An object of this template class 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 wbuffer_convert object is destroyed)
cvtstate -- a conversion state object
cvtcount -- a conversion count

`wstring_convert::byte_string`

typedef std::basic_string<char> byte_string;

The type is a synonym for std::basic_string<char>.

`wstring_convert::converted`

size_t converted() const;

The member function returns cvtcount.

`wstring_convert::from_bytes`

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

The first member function converts the single-element sequence byte to a wide string. The second member function converts the nul-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.
If no conversion error occurs, the member function returns the converted wide string.
Otherwise, if the object was constructed with an initializer for wide_err_string, the member function returns wide_err_string.
Otherwise, the member function throws an object of class std::range_error.

`wstring_convert::int_type`

typedef typename wide_string::traits_type::int_type int_type;

The type is a synonym for wide_string::traits_type::int_type.

`wstring_convert::state`

state_type state() const;

The member function returns cvtstate.

`wstring_convert::state_type`

typedef typename Codecvt::state_type state_type;

The type is a synonym for Codecvt::state_type.

`wstring_convert::to_bytes`

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

The first member function converts the single-element sequence wchar to a byte string. The second member function converts the nul-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.
If no conversion error occurs, the member function returns the converted byte string.
Otherwise, if the object was constructed with an initializer for byte_err_string, the member function returns byte_err_string.
Otherwise, the member function throws an object of class std::range_error.

`wstring_convert::wide_string`

typedef std::basic_string<Elem> wide_string;

The type is a synonym for std::basic_string<Elem>.

`wstring_convert::wstring_convert`

wstring_convert(Codecvt *pcvt = new Codecvt);
wstring_convert(Codecvt *pcvt, state_type state);
wstring_convert(const byte_string& byte_err,
    const wide_string& wide_err = wide_string());

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.

See also the Table of Contents and the Index.