|
Library /sys$common/syshlp/helplib.hlb CXXLSTD, locales, code_cvt *Conan The Librarian |
Standard C++ Library
Copyright 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
|
|