wstring_convert Class

The latest version of this topic can be found at wstring_convert Class.

The template class wstring_convert performs conversions between a wide string and a byte string.

Syntax

template <class Codecvt, class Elem = wchar_t>
class wstring_convert

Parameters

Codecvt
The locale facet that represents the conversion object.

Elem
The wide-character element type.

Remarks

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:

• A byte string to display on errors

• A wide string to display on errors

• A pointer to the allocated conversion object (which is freed when the wbuffer_convert object is destroyed)

• A conversion state object of type state_type

• A conversion count

Constructors

Typedefs

Member Functions

Requirements

Header: <locale>

Namespace: std

wstring_convert::byte_string

A type that represents a byte string.

typedef std::basic_string<char> byte_string;

Remarks

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

wstring_convert::converted

Returns the number of successful conversions.

size_t converted() const;

Return Value

The number of successful conversions.

Remarks

The number of successful conversions is stored in the conversion count object.

wstring_convert::from_bytes

Converts a byte string to a wide string.

wide_string from_bytes(char _Byte);

wide_string from_bytes(const char* ptr);

wide_string from_bytes(const byte_string& _Bstr);

wide_string from_bytes(const char* first, const char* last);

Parameters

Return Value

A wide string object resulting from the conversion.

Remarks

If the conversion state 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 the conversion count object. If no conversion error occurs, the member function returns the converted wide string. Otherwise, if the object was constructed with an initializer for the wide-string error message, the member function returns the wide-string error message object. Otherwise, the member function throws an object of class range_error.

wstring_convert::int_type

A type that represents an integer.

typedef typename wide_string::traits_type::int_type int_type;

Remarks

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

wstring_convert::state

Returns an object representing the state of the conversion.

state_type state() const;

Return Value

The conversion state object that represents the state of the conversion.

Remarks

wstring_convert::state_type

A type that represents the conversion state.

typedef typename Codecvt::state_type state_type;

Remarks

The type describes an object that can represent a conversion state. The type is a synonym for Codecvt::state_type.

wstring_convert::to_bytes

Converts a wide string to a byte string.

byte_string to_bytes(_Elem _Char);

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

Parameters

Remarks

If the conversion state 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 the conversion count object. If no conversion error occurs, the member function returns the converted byte string. Otherwise, if the object was constructed with an initializer for the byte-string error message, the member function returns the byte-string error message object. Otherwise, the member function throws an object of class range_error.

wstring_convert::wide_string

A type that represents a wide string.

typedef std::basic_string<_Elem> wide_string;

Remarks

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

wstring_convert::wstring_convert

Constructs an object of type wstring_convert.

wstring_convert(Codecvt *_Pcvt = new Codecvt);

wstring_convert(Codecvt *_Pcvt,
    state_type _State);

wstring_convert(const byte_string& _Berr,
    const wide_string& _Werr = wide_string());

Parameters

Remarks

The first constructor stores _Pcvt_arg in the conversion object