code_cvt (3C++std) - Tru64 UNIX
Standard C++ LibraryCopyright 1996, Rogue Wave Software, Inc.
NAME
code_cvt - Code conversion facet.
SYNOPSIS
#include <locale>
class codecvt_base;
template <class internT, class externT, class stateT>
class codecvt;
DESCRIPTION
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).
INTERFACE
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();
};
TYPES
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.
CONSTRUCTORS AND DESTRUCTORS
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
FACET ID
static locale::id id;
Unique identifier for this type of facet.
PUBLIC MEMBER FUNCTIONS
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 delagated 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.
PROTECTED MEMBER FUNCTIONS
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.
EXAMPLE
//
// 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(" );
string ins2(ins.size(),'.');
string outs(ins.size(),'.');
// Print initial contents of buffers
cout << "Before:0 << 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 converst 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:0 << 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:0 << ins << endl;
cout << ins2 << endl;
cout << outs << endl;
return 0;
}
SEE ALSO
locale, facets, codecvt_byname
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
privacy and legal statement
