codecvt class template — Facet for mapping one character set to another
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).