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.

For a list of all members of this type, see codecvt Members.

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.

Requirements

Header: <locale>

Namespace: std

See Also

Reference

Thread Safety in the Standard C++ Library

Other Resources

codecvt Members

<locale> Members