wstring_convert Class

The class template 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 class template 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 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<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 class template 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

Byte
The single-element byte sequence to be converted.

ptr
The C-style, null-terminated sequence of characters to be converted.

Bstr
The byte_string to be converted.

first
The first character in a range of characters to be converted.

last
The last character in a range of characters to be converted.

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

Char
The wide character to be converted.

Wptr
The C-style, null-terminated sequence, beginning at wptr, to be converted.

Wstr
The wide_string to be converted.

first
The first element in a range of elements to be converted.

last
The last element in a range of elements to be converted.

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

*Pcvt
The object of type Codecvt to perform the conversion.

_State
The object of type state_type representing the conversion state.

_Berr
The byte_string to display on errors.

Werr
The wide_string to display on errors.

Remarks

The first constructor stores Pcvt_arg in the conversion object