C++

Reference

<locale>

codecvt

class template
<locale>

std::codecvt

template <class internT, class externT, class stateT> class codecvt;
Convert codeset facet

The codecvt standard facet translates between two different character encodings: an internal character type (generally some type of wide character) and an external character type (generally representing a multibyte sequence).

The codecvt class template has a protected destructor: Programs shall only construct objects of derived classes, or use those installed in locale objects (through use_facet).

All standard locale objects support at least the following facet instantiations of the codecvt class template (as part of the ctype category):
facets in locale objectsdescription
codecvt<char,char,mbstate_t>performs no conversion
codecvt<wchar_t,char,mbstate_t>converts between native wide and narrow character sets
facets in locale objectsdescription
codecvt<char,char,mbstate_t>performs no conversion
codecvt<wchar_t,char,mbstate_t>converts between native wide and narrow character sets
codecvt<char16_t,char,mbstate_t>converts between UTF16 and UTF8 encodings
codecvt<char32_t,char,mbstate_t>converts between UTF32 and UTF8 encodings

Header <codecvt> defines additional stand-alone facet objects derived from codecvt (for more info, see header <codecvt>).

Template parameters

internT
Internal character type: Typically, this is the wide character type.
Aliased as member intern_type.
externT
External character type: Typically, this is the multi-byte type.
Aliased as member extern_type.
stateT
A state type: Typically, this is an object able to keep track of the state of the conversion, such as mbstate_t (or, more generically, char_traits<externT>::state_type).
Aliased as member state_type.

Member types

member typedefinitiondescription
intern_typeThe first template parameter (internT)Internal character type
extern_typeThe second template parameter (externT)External character type
state_typeThe third template parameter (stateT)State type
The class also inherits codecvt_base::result, which is used as the return type for members in, out and unshift.

Member constants

The following member constants are inherited from codecvt_base (as labels of enum type codecvt_base::result); They are used as return values by certain member functions.
member constanttypevaluedescription
okcodecvt_base::result0Conversion successful
partialcodecvt_base::result1Partial conversion
errorcodecvt_base::result2Conversion error
noconvcodecvt_base::result3No conversion

The class also contains a public static constant of type locale::id, that uniquely identifies facets with codecvt semantics.

Public member functions

(constructor)
codecvt constructor (public member function)

Conversion functions

in
Translate in characters (public member function)
out
Translate out characters (public member function)
unshift
Unshift translation state (public member function)

Character encoding properties

always_noconv
Return noconv characteristics (public member function)
encoding
Return encoding width (public member function)
length
Return length of translated sequence (public member function)
max_length
Return max length of one character (public member function)

Virtual protected member functions

The class defines the virtual protected members which implement the behavior by default of their respective public member functions:
do_always_noconv
Return noconv characteristics [virtual] (protected virtual member function)
do_encoding
Return encoding width [virtual] (protected virtual member function)
do_in
Translate in characters [virtual] (protected virtual member function)
do_length
Return length of translated sequence [virtual] (public member function)
do_max_length
Return max length of one character [virtual] (protected virtual member function)
do_out
Translate out characters [virtual] (protected virtual member function)
do_unshift
Unshift translation state [virtual] (protected virtual member function)

Along with the class destructor:
(destructor)
codecvt destructor (protected member function)

The class contains a public static constant of type locale::id that uniquely identifies facets with codecvt semantics.

Specializations

At least the following specializations of this template are provided in all library implementations:
specialization
codecvt<char,char,mbstate_t>
codecvt<wchar_t,char,mbstate_t>
specialization
codecvt<char,char,mbstate_t>
codecvt<wchar_t,char,mbstate_t>
codecvt<char16_t,char,mbstate_t>
codecvt<char32_t,char,mbstate_t>