wstring_convert Class

 

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

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.

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

wstring_convertConstructs an object of type wstring_convert.

Typedefs

byte_stringA type that represents a byte string.
wide_stringA type that represents a wide string.
state_typeA type that represents the conversion state.
int_typeA type that represents an integer.

Member Functions

from_bytesConverts a byte string to a wide string.
to_bytesConverts a wide string to a byte string.
convertedReturns the number of successful conversions.
stateReturns an object representing the state of the conversion.

Header: <locale>

Namespace: std

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>.

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.

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

ParameterDescription
_ByteThe single-element byte sequence to be converted.
ptrThe C-style, null-terminated sequence of characters to be converted.
_BstrThe byte_string to be converted.
firstThe first character in a range of characters to be converted.
lastThe 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.

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.

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

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.

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

ParameterDescription
_CharThe wide character to be converted.
_WptrThe C-style, null-terminated sequence, beginning at wptr, to be converted.
_WstrThe wide_string to be converted.
firstThe first element in a range of elements to be converted.
lastThe 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.

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>.

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

ParameterDescription
*_PcvtThe object of type Codecvt to perform the conversion.
_StateThe object of type state_type representing the conversion state.
_BerrThe byte_string to display on errors.
_WerrThe wide_string to display on errors.

Remarks

The first constructor stores _Pcvt_arg in the conversion object

Show: