...codecvt_base codecvt... ...
Code conversion facet.
| Data Types | |
| extern_type id intern_type state_type |
| Member Functions | |
| always_noconv() do_always_noconv() do_encoding() do_in() do_length() do_max_length() do_out() encoding() in() length() |
max_length() out() |
#include <locale> class codecvt_base; template <class internT, class externT, class stateT> class codecvt;
The codecvt<internT,externT,stateT> template provides code conversion facilities. Default implementations of codecvt<char,wchar_t,mbstate_t> and codecvt<wchar_t,char,mbstate_t> use ctype<wchar_t>::widen and ctype<wchar_t>::narrow respectively. The default implementation of codecvt<wchar_t,wchar_t,mbstate_t> simply uses memcpy (no particular conversion applied).
class codecvt_base {
public:
enum result { ok, partial, error, noconv };
};
template <class internT, class externT, class 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 = 0)
result out(stateT&, const internT*,
const internT*, const internT*&,
externT*, externT*, externT*&) const;
result in(stateT&, const externT*,
const externT*, const externT*&,
internT*, internT*, internT*&) const;
bool always_noconv() const throw();
int length(const stateT&, const internT*, const internT*,
size_t) const;
int max_length() const throw();
int encoding() const throw();
static locale::id id;
protected:
~codecvt(); // virtual
virtual result do_out(stateT&,
const internT*,
const internT*,
const internT*&,
externT*, externT*,
externT*&) const;
virtual result do_in(stateT&,
const externT*,
const externT*,
const externT*&,
internT*, internT*,
internT*&) const;
virtual bool do_always_noconv() const throw();
virtual int do_length(const stateT&, const internT*,
const internT*,
size_t) const;
virtual int do_max_length() const throw();
virtual int do_encoding() const throw();
};
intern_type
Type of character to convert from.
extern_type
Type of character to convert to.
state_type
Type to keep track of state and determine the direction of the conversion.
explicit codecvt(size_t refs = 0)
Construct a codecvt facet. If the refs argument is 0 then destruction of the object is delegated to the locale, or locales, containing it. This allows the user to ignore lifetime management issues. On the other had, if refs is 1 then the object must be explicitly deleted; the locale will not do so. In this case, the object can be maintained across the lifetime of multiple locales.
~codecvt(); // virtual and protected
Destroy the facet
static locale::id id;
Unique identifier for this type of facet.
The public members of the codecvt facet provide an interface to protected members. Each public member xxx has a corresponding virtual protected member do_xxx. All work is delegated to these protected members. For instance, the long version of the public length function simply calls its protected cousin do_length.
bool
always_noconv() const
throw();
int
encoding() const
throw();
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
length(const stateT&, const internT* from,
const internT* end,
size_t max) const;
int
max_length() const
throw();
result
out(stateT& state, const internT* from,
const internT* from_end, const internT*& from_next,
externT* to, externT* to_limit, externT*& to_next) const;
Each of these public member functions xxx simply calls the corresponding protected do_xxx function.
virtual bool do_always_noconv() const throw();
Returns true if no conversion is required. This is the case if do_in and do_out return noconv for all valid arguments. The instantiation codecvt<char,char,mbstate_t> returns true, while all other default instantiations return false.
virtual int do_encoding() const throw();
Returns one of the following
-1 if the encoding on the external character sequence is dependent on state.
A constant number representing the number of external characters in a fixed width encoding.
0 if the encoding is uses a variable width.
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_out(stateT& state,
const internT* from,
const internT* from_end,
const internT*& from_next,
externT* to, externT* to_limit,
externT*& to_next) const;
Both functions take characters in the range of [from,from_end), apply an appropriate conversion, and place the resulting characters in the buffer starting at to. Each function converts at most from_end-from internT characters, and stores no more than to_limit-to externT characters. Both do_out and do_in will stop if they find a character they cannot convert. In any case, from_next and to_next are always left pointing to the next character beyond the last one successfully converted.
do_out and do_in must be called under the following pre-conditions:
from <= from_end
to <= to_end
state either initialized for the beginning of a sequence or equal to the result of the previous conversion on the sequence.
In the case where no conversion is required, from_next will be set to from and to_next set to to.
do_out and do_in return one the following:
|
Return Value |
Meaning |
|
ok |
completed the conversion |
|
partial |
not all source characters converted |
|
error |
encountered a from_type character it could not convert |
|
noconv |
no conversion was needed |
If either function returns partial and (from == from_end) then one of two conditions prevail:
The destination sequence has not accepted all the converted characters, or
Additional internT characters are needed before another externT character can be assembled.
virtual int
do_length(const stateT&, const internT* from,
const internT* end,
size_t max) const;
Returns the largest number < max of internT characters available in the range [from,end).
do_length must be called under the following pre-conditions:
from <= from_end
state either initialized for the beginning of a sequence or equal to the result of the previous conversion on the sequence.
virtual int do_max_length() const throw();
Returns the maximum value that do_length can return for any valid set of arguments.
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;
See do_in above.
//
// codecvt.cpp
//
#include <sstream>
#include "codecvte.h"
int main ()
{
using namespace std;
mbstate_t state;
// A string of ISO characters and buffers to hold
// conversions
string ins("\xfc \xcc \xcd \x61 \xe1 \xd9 \xc6 \xf5");
string ins2(ins.size(),'.');
string outs(ins.size(),'.');
// Print initial contents of buffers
cout << "Before:\n" << ins << endl;
cout << ins2 << endl;
cout << outs << endl << endl;
// Initialize buffers
string::iterator in_it = ins.begin();
string::iterator out_it = outs.begin();
// Create a user defined codecvt fact
// This facet converts from ISO Latin
// Alphabet No. 1 (ISO 8859-1) to
// U.S. ASCII code page 437
// This facet replaces the default for
// codecvt<char,char,mbstate_t>
locale loc(locale(),new ex_codecvt);
// Now get the facet from the locale
const codecvt<char,char,mbstate_t>& cdcvt =
#ifndef _RWSTD_NO_TEMPLATE_ON_RETURN_TYPE
use_facet<codecvt<char,char,mbstate_t> >(loc);
#else
use_facet(loc,(codecvt<char,char,mbstate_t>*)0);
#endif
// convert the buffer
cdcvt.in(state,ins.begin(),ins.end(),in_it,
outs.begin(),outs.end(),out_it);
cout << "After in:\n" << ins << endl;
cout << ins2 << endl;
cout << outs << endl << endl;
// Lastly, convert back to the original codeset
in_it = ins.begin();
out_it = outs.begin();
cdcvt.out(state, outs.begin(),outs.end(),out_it,
ins2.begin(),ins2.end(),in_it);
cout << "After out:\n" << ins << endl;
cout << ins2 << endl;
cout << outs << endl;
return 0;
}
locale, facets, codecvt_byname
©Copyright 1996, Rogue Wave Software, Inc.