codecvt Class

A template class that describes an object that can serve as a locale facet. It is able to control conversions between a sequence of values used to encode characters within the program and a sequence of values used to encode characters outside the program.

template<class CharType, class Byte, class StateType>
    class codecvt
        : public locale::facet, codecvt_base {
public:
    typedef CharType intern_type;
    typedef Byte extern_type;
    typedef StateType state_type;

    explicit codecvt (size_t _Refs = 0);

    result in (
        StateType& _State,
        const Byte *_First1, 
        const Byte *_Last1,
        const Byte *_Next1,
        CharType *_First2, 
        CharType *_Last2, 
        CharType *_Next2
    );
    result out (
        StateType& _State,
        const Elem *_First1, 
        const Elem *_Last1,
        const Elem *_Next1,
        Byte *_First2, 
        Byte *_Last2, 
        Byte *_Next2
    );
    result unshift (
        StateType& _State,
        Byte *_First2, 
        Byte *_Last2, 
        Byte *_Next2
    );

    bool always_noconv () const throw();
    int max_length () const throw();
    int length (
        const StateType& _State,
        const Byte *_First1, 
        const Byte *_Last1,
        size_t _N2
    ) const throw();
    int encoding () const throw();

    static locale::id id;

protected:
    ~codecvt();

    virtual result do_in (
        StateType& _State,
        const Byte *_First1, 
        const Byte *_Last1,
        const Byte *_Next1,
        CharType *_First2, 
        CharType *_Last2, 
        CharType *_Next2
    );
    virtual result do_out (
        StateType& _State,
        const CharType *_First1, 
        const CharType *_Last1,
        const CharType *_Next1,
        Byte *_First2, 
        Byte *_Last2, 
        Byte *_Next2
    );
    virtual result do_unshift (
        StateType& _State,
        Byte *_First2, 
        Byte *_Last2, 
        Byte *_Next2
    );

    virtual bool do_always_noconv () const throw();
    virtual int do_max_length () const throw();
    virtual int do_encoding () const throw();
    virtual int do_length (
        const StateType& _State,
        const Byte *_First1, 
        const Byte *_Last1,
        size_t _Len2
    ) const throw();
};

Parameters

  • CharType
    The type used within a program to encode characters.

  • Byte
    A type used to encode characters outside a program.

  • StateType
    A type that can be used to represent intermediate states of a conversion between internal and external types of character representations.

Remarks

The template class describes an object that can serve as a locale facet, to control conversions between a sequence of values of type CharType and a sequence of values of type Byte. The class StateType characterizes the transformation -- and an object of class StateType stores any necessary state information during a conversion.

The internal encoding uses a representation with a fixed number of bytes per character, usually either type char or type wchar_t.

As with any locale facet, the static object id has an initial stored value of zero. The first attempt to access its stored value stores a unique positive value inid.

The template versions of do_in and do_out always return codecvt_base::noconv.

The Standard C++ Library defines several explicit specializations:

template<>

codecvt<wchar_t, char, mbstate_t>

converts between wchar_t and char sequences.

template<>

codecvt<char16_t, char, mbstate_t>

converts between char16_t sequences encoded as UTF-16 and char sequences encoded as UTF-8.

template<>

codecvt<char32_t, char, mbstate_t>

converts between char32_t sequences encoded as UTF-32 (UCS-4) and char sequences encoded as UTF-8.

Constructors

codecvt

The constructor for objects of class codecvt that serves as a locale facet to handle conversions.

Typedefs

extern_type

A character type that is used for external representations.

intern_type

A character type that is used for internal representations.

state_type

A character type that is used to represent intermediate states during conversions between internal and external representations.

Member Functions

always_noconv

Tests whether no conversions need be done.

do_always_noconv

A virtual function called to test whether no conversions need be done.

do_encoding

A virtual function that tests if the encoding of the Byte stream is state dependent, whether the ratio between the Bytes used and the CharTypes produced is constant, and, if so, determines the value of that ratio.

do_in

A virtual function called to convert a sequence of internal Bytes to a sequence of external CharTypes.

do_length

A virtual function that determines how many Bytes from a given sequence of external Bytes produce not more than a given number of internal CharTypes and returns that number of Bytes.

do_max_length

A virtual function that returns the maximum number of external Bytes necessary to produce one internal CharType.

do_out

A virtual function called to convert a sequence of internal CharTypes to a sequence of external Bytes.

do_unshift

A virtual function called to provide the Bytes needed in a state-dependent conversion to complete the last character in a sequence of Bytes.

encoding

Tests if the encoding of the Byte stream is state dependent, whether the ratio between the Bytes used and the CharTypes produced is constant, and, if so, determines the value of that ratio.

in

Converts an external representation of a sequence of Bytes to an internal representation of a sequence of CharTypes.

length

Determines how many Bytes from a given sequence of external Bytes produce not more than a given number of internal CharTypes and returns that number of Bytes.

max_length

Returns the maximum number of external Bytes necessary to produce one internal CharType.

out

Converts a sequence of internal CharTypes to a sequence of external Bytes.

unshift

Provides the external Bytes needed in a state-dependent conversion to complete the last character in the sequence of Bytes.

Requirements

Header: <locale>

Namespace: std

See Also

Reference

Thread Safety in the Standard C++ Library

Other Resources

<locale> Members