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
| Constructor | Description |
|---|---|
| wstring_convert | Constructs an object of type wstring_convert. |
Typedefs
| Type name | Description |
|---|---|
| byte_string | A type that represents a byte string. |
| wide_string | A type that represents a wide string. |
| state_type | A type that represents the conversion state. |
| int_type | A type that represents an integer. |
Member functions
| Member function | Description |
|---|---|
| from_bytes | Converts a byte string to a wide string. |
| to_bytes | Converts a wide string to a byte string. |
| converted | Returns the number of successful conversions. |
| state | Returns an object representing the state of the conversion. |
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