Name

codecvt class template — Facet for mapping one character set to another

Synopsis

template <typename internT,typename externT,typename stateT>
class codecvt : public locale::facet, public codecvt_base
{
public:
  typedef internT intern_type;
  typedef externT extern_type;
  typedef stateT state_type;
  explicit codecvt(size_t refs = 0);
  result out(stateT& state, const internT* from, const internT* from_end,
             const internT*& from_next, externT* to, externT* to_limit, 
             externT*& to_next) const;
  result unshift(stateT& state, externT* to, externT* to_limit, 
                 externT*& to_next) const;
  result in(stateT& state, const externT* from, const externT* from_end,
            const externT*& from_next, internT* to, internT* to_limit, 
            internT*& to_next) const;
  int encoding(  ) const throw(  );
  bool always_noconv(  ) const throw(  );
  int length(stateT&, const externT* from, const externT* end, size_t max)
    const;
  int max_length(  ) const throw(  );
  static locale::id id;
protected:
  virtual ~codecvt(  );
  virtual result do_out(stateT& state, const internT* from, 
                        const internT* from_end, const internT*& from_next, 
                        externT* to, externT* to_limit, externT*& to_next)
    const;
  virtual result do_in(stateT& state, const externT* from, 
                       const externT* from_end, const externT*& from_next,
                       internT* to, internT* to_limit, internT*& to_next)
    const;
  virtual result do_unshift(stateT& state, externT* to, externT* to_limit,
                            externT*& to_next) const;
  virtual int do_encoding(  ) const throw(  );
  virtual bool do_always_noconv(  ) const throw(  );
  virtual int do_length(stateT&, const externT* from, const externT* end,
                        size_t max) const;
  virtual int do_max_length(  ) const throw(  );
};

The codecvt template converts characters from one character encoding to another. It is most often used to convert multibyte characters to and from wide characters.

The following template specializations are required by the standard:

codecvt<wchar_t, char, mbstate_t>

Converts multibyte narrow characters to wide characters (in) and wide to multibyte (out)

codecvt<char, char, mbstate_t>

A no-op, "converting" characters to themselves

As with other facets, the public members of codecvt call virtual, protected members with the same name prefaced by do_. Thus, to use the facet, call the public functions, such as in and out, which in turn call do_in and do_out. The descriptions below are for the virtual functions because they do the real work. Imagine that for each virtual function description, there is a corresponding description for a public, nonvirtual function, such as:

The following are the virtual, protected members of codecvt:

virtual bool do_always_noconv ( ) const throw( )

Returns true if the codecvt object does not actually perform any conversions, that is, in and out are no-ops. For example, for the specialization codecvt<char,char,mbstate_t>, do_always_noconv always returns true.

virtual int do_encoding ( ) const throw( )

Returns the number of externT characters needed to represent a single internT character. If this number is not a fixed constant, the return value is 0. The return value is -1 if externT character sequences are not state-dependent.

virtual result do_in (stateT& state, const externT* from, const externT* from_end, const externT*& from_next, internT* to, internT* to_limit, internT*& to_next) const

Converts externT characters to internT characters. The characters in the range [from, from_end) are converted and stored in the array starting at to. The number of characters converted is the minimum of from_end - from and to_limit - to.

The from_next parameter is set to point to the value in [from, from_end) where the conversion stopped, and to_next points to the value in [to, to_limit) where the conversion stopped. If no conversion was performed, from_next is the same as from, and to_next is equal to to.

The return value is a result, as described in Table 13-19 (under the codecvt_base class).

virtual int do_length (stateT&, const externT* from, const externT* from_end, size_t max) const

Returns the number of externT characters in the range [from, from_end) that are used to convert to internT characters. At most, max internT characters are converted.

virtual int do_max_length ( ) const throw( )

Returns the maximum number of externT characters needed to represent a single internT character, that is, the maximum value that do_length can return when max is 1.

virtual result do_out (stateT& state, const internT* from, const internT* from_end, const internT*& from_next, externT* to, externT* to_limit, externT*& to_next) const

Converts internT characters to externT characters. The characters in the range [from, from_end) are converted and stored in the array starting at to. The number of characters converted is the minimum of from_end - from and to_limit - to.

The from_next parameter is set to point to the value in [from, from_end) where the conversion stopped, and to_next points to the value in [to, to_limit) where the conversion stopped. If no conversion was performed, from_next is the same as from, and to_next is equal to to.

The return value is a result, as described in Table 13-19 (under codecvt_base class).

virtual result do_unshift (stateT& state, externT* to, externT* to_limit, externT*& to_next) const

Ends a shift state by storing characters in the array starting at to such that the characters undo the state shift given by state. Up to to_limit - to characters are written, and to_next is set to point to one past the last character written into to.

The return value is a result, as described in Table 13-19 (under codecvt_base class).