.\" ident @(#)codecvt.3
.\" Standard Template Library
.\" $$RW_INSERT_HEADER "slyrs.man"
.TH codecvt 3C++ "02 Apr 1998" "Rogue Wave Software" "-"
.ce2
Standard C++ Library   
Copyright 1998, Rogue Wave Software, Inc.   

.SH NAME

\f2codecvt\fP

\ - A code conversion facet.



.SH  SYNOPSIS


.RE
.RS 0
#include <locale>
.br
class codecvt_base;
.br
template <class internT, class externT, class stateT>
.br
class codecvt;



.SH  DESCRIPTION


The codecvt<internT,externT,stateT>_template has code conversion facilities. Default implementations of codecvt<char,wchar_t,mbstate_t> and codecvt<wchar_t,char,mbstate_t> use_\f2ctype<wchar_t>::widen \fPand \f2ctype<wchar_t>::narrow\fP respectively. The default implementation of codecvt<wchar_t,wchar_t,mbstate_t> simply uses \f2memcpy\fP (no particular conversion applied).



.SH  INTERFACE



.br
class codecvt_base {
.br
public:
.RE
.RS 1
enum result { ok, partial, error, noconv };
.RE
.RS 0
};
.br

.br
template <class internT, class externT, class stateT>
.br
class codecvt : public locale::facet, public codecvt_base {
.br
public:
.RE
.RS 1
typedef internT  intern_type;
.br
typedef externT  extern_type;
.br
typedef stateT   state_type;
.RE
.RS 0

.RE
.RS 1
explicit codecvt(size_t = 0)
.br
result out(stateT&, const internT*, 
.RE
.RS 12
const internT*, const internT*&,
.br
externT*, externT*, externT*&) const;
.RE
.RS 1
result unshift(stateT&, externT*, externT*, extern*&)
.RE
.RS 16
const;
.RE
.RS 1
result in(stateT&, const externT*, 
.RE
.RS 11
const externT*, const externT*&,
.br
internT*, internT*, internT*&) const;
.RE
.RS 0

.RE
.RS 1
int encoding() const throw();
.br
bool always_noconv() const throw();
.RE
.RS 0

.RE
.RS 1
int length(const stateT&, const externT*, const externT*,
.RE
.RS 12
size_t) const;
.RE
.RS 0

.RE
.RS 1
int max_length() const throw();
.br
static locale::id id;
.RE
.RS 0

.br
protected:
.RE
.RS 2
~codecvt();  // virtual
.RE
.RS 1
virtual result do_out(stateT&,
.RE
.RS 23
const internT*, 
.br
const internT*, 
.br
const internT*&,
.br
externT*, externT*,
.br
externT*&) const;
.RE
.RS 1
virtual result do_in(stateT&,
.RE
.RS 22
const externT*, 
.br
const externT*, 
.br
const externT*&,
.br
internT*, internT*,
.br
internT*&) const;
.RE
.RS 1
virtual result do_unshift(stateT&,
.RE
.RS 27
externT*, externT*,
.br
externT*&) const;
.RE
.RS 0

.RE
.RS 1
virtual int do_encoding() const throw();
.br
virtual bool do_always_noconv() const throw();
.br
virtual int do_length(const stateT&, const internT*, 
.RE
.RS 23
const internT*,
.br
size_t) const;
.RE
.RS 0

.RE
.RS 1
virtual int do_max_length() const throw();
.RE
.RS 0
};



.SH  TYPES



.br
intern_type
.RE
.RS 3


Type of character to convert from.

.RE


.br
extern_type
.RE
.RS 3


Type of character to convert to.

.RE


.br
state_type
.RE
.RS 3


Type to keep track of state and determine the codeset(s) to be converted.

.RE



.SH  CONSTRUCTORS 



.br
explicit codecvt(size_t refs = 0) 
.RE
.RS 3


Construct a codecvt facet. If the \f2refs\fP argument is \f20\fP (default), 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 hand, if \f2refs\fP is \f21\fP, then the object must be explicitly deleted; the locale does not do so.

.RE



.SH  DESTRUCTORS



.br
~codecvt();  // virtual and protected
.RE
.RS 3


Destroy the facet.

.RE



.SH  FACET ID



.br
static locale::id id; 
.RE
.RS 3


Unique identifier for this type of facet.

.RE



.SH  PUBLIC MEMBER FUNCTIONS


The public members of the codecvt facet include an interface to protected members. Each public member \f2xxx\fP has a corresponding virtual protected member \f2do_xxx\fP. All work is delegated to these protected members.   For instance, the public \f2length\fP function simply calls its protected cousin \f2do_length\fP.


.br
bool 
.br
always_noconv() const 
.RE
.RS 1
throw();
.RE
.RS 0
int
.br
encoding() const
.RE
.RS 1
throw();
.RE
.RS 0
result 
.br
in(stateT& state, const externT* from, 
.RE
.RS 2
const externT* from_end, const externT*& from_next,
.br
internT* to, internT* to_limit, internT*& to_next) const; 
.RE
.RS 0
int 
.br
length(const stateT& state, const internT* from, 
.RE
.RS 6
const internT* end,
.br
size_t max) const; 
.RE
.RS 0
int 
.br
max_length() const 
.RE
.RS 1
throw();
.RE
.RS 0
result 
.br
out(stateT& state, const internT* from, 
.RE
.RS 3
const internT* from_end, const internT*& from_next,
.br
externT* to, externT* to_limit, externT*& to_next)
.br
const; 
.RE
.RS 0
result 
.br
unshift(stateT& state, externT* to, externT* to_limit, 
.RE
.RS 7
externT*& to) const;
.RE
.RS 3


Each of these public member functions \f2xxx\fP simply calls the corresponding protected \f2do_xxx\fP function.

.RE



.SH  PROTECTED MEMBER FUNCTIONS



.RE
.RS 0
virtual bool 
.br
do_always_noconv() const 
.RE
.RS 1
throw();
.RE
.RS 3


Returns \f2true\fP if no conversion is required. This is the case if\f2 do_in\fP and \f2do_out\fP return \f2noconv\fP for all valid arguments. The instantiation \f2codecvt<char,char,mbstate_t>\fP returns \f2true\fP, while all other default instantiations return \f2false\fP.

.RE


.RE
.RS 0
virtual int 
.br
do_encoding() const 
.RE
.RS 1
throw();
.RE
.RS 3


Returns one of the following

.RS .5i


.HP .5i
-	\f2-1\fP if the encoding on the external character sequence is dependent on state. 
.HP .5i
-	A constant number representing the number of external characters per internal character in a fixed width encoding.
.HP .5i
-	\f20\fP if the encoding is uses a variable width.

.RE

.RE

.RS 0
virtual result 
.br
do_in(stateT& state,
.RE
.RS 5
const externT* from, 
.br
const externT* from_end, 
.br
const externT*& from_next,
.br
internT* to, internT* to_limit,
.br
internT*& to_next) const; 
.RE
.RS 0
virtual result 
.br
do_out(stateT& state,
.RE
.RS 6
const internT* from, 
.br
const internT* from_end, 
.br
const internT*& from_next,
.br
externT* to, externT* to_limit,
.br
externT*& to_next) const; 
.RE
.RS 3


Both functions take characters in the range of \f2[from,from_end)\fP, apply an appropriate conversion, and place the resulting characters in the buffer starting at \f2to\fP. Each function converts at most \f2from_end-from internT\fP characters, and stores no more than\f2 to_limit-to externT\fP characters. Both \f2do_out\fP and \f2do_in\fP stop if they find a character they cannot convert. In any case, \f2from_next\fP and \f2to_next\fP are always left pointing to the next character beyond the last one successfully converted.

\f2do_out\fP and \f2do_in\fP must be called under the following pre-conditions:

.RS .5i


.HP .5i
-	\f2from <= from_end\fP
.HP .5i
-	\f2to <= to_end\fP
.HP .5i
-	\f2state\fP is either initialized to the beginning of a sequence or equal to the result of the previous conversion on the sequence.

.RE

In the case where no conversion is required, \f2from_next\fP is set to \f2from\fP and \f2to_next\fP set to \f2to\fP.

\f2do_out\fP and\f2 do_in\fP return one the following:

RETURN VALUE		MEANING
  
\f2ok\fP				\f2completed the conversion\fP

\f2partial\fP			\f2not all source characters converted\fP

\f2error\fP			\f2encountered a source character 
				it could not convert\fP

\f2noconv\fP			\f2no conversion was needed\fP


If either function returns \f2partial\fP and\f2 (from == from_end)\fP, then one of two conditions prevail:

.RS .5i


.HP .5i
-	The destination sequence has not accepted all the converted characters, or
.HP .5i
-	Additional source characters are needed before another destination element can be assembled..RE

.RE


.RE
.RS 0
virtual int 
.br
do_length(const stateT&, const externT* from, 
.RE
.RS 9
const externT* end,
.br
size_t max) const; 
.RE
.RS 3


Determines the largest number \f2<= max\fP of \f2internT\fP characters that can be produced from the sequence \f2[from,end)\fP, and returns the number of \f2externT\fP characters that would be consumed from \f2[from,end)\fP in order to produce this number of \f2internT\fP characters.

\f2do_length\fP must be called under the following pre-conditions:

.RS .5i


.HP .5i
-	\f2from <= from_end\fP
.HP .5i
-	\f2state\fP is either initialized to the beginning of a sequence or equal to the result of the previous conversion on the sequence.

.RE

.RE

.RS 0
virtual int 
.br
do_max_length() const throw();
.RE
.RS 3


Returns the maximum value that \f2do_length\fP can return for any valid combination of its first three arguments, with the fourth argument (\f2max\fP) set to \f21\fP.

.RE


.br
virtual result 
.br
do_out(stateT& state,
.RE
.RS 6
const internT* from, 
.br
const internT* from_end, 
.br
const internT*& from_next,
.br
externT* to, externT* to_limit,
.br
externT*& to_next) const; 
.RE
.RS 3


See \f2do_in\fP above.

.RE


.RE
.RS 0
virtual result
.br
\f2do_unshift\fP(stateT& state, externT* to, externT* to_limit,
.RE
.RS 10
externT*& to_next) const;
.RE
.RS 3


Determines the sequence of \f2externT\fP characters that should be appended to a sequence whose state is given by \f2state\fP, in order to terminate the sequence (that is, to return it to the default or initial or unshifted state). Stores the terminating sequence starting at \f2to\fP, proceeding no farther than \f2to_limit\fP. Sets \f2to_end\fP to point past the last \f2externT\fP character stored.

\f2do_unshift\fP must be called under the following pre-conditions:

.RS .5i


.HP .5i
-	\f2from <= from_end\fP
.HP .5i
-	\f2state\fP is either initialized to the beginning of a sequence or equal to the result of the previous conversion on the sequence.

.RE

The return value from \f2do_unshift\fP is as follows:

RETURN VALUE		MEANING
  

\f2ok\fP				\f2terminating sequence was
				stored successfully\fP

\f2partial\fP			\f2only part of the sequence 
				was stored\fP

\f2error\fP			\f2the state is invalid\fP

\f2noconv\fP			\f2no terminating sequence is 
				needed for this state\fP

.RE

.SH  EXAMPLE

.RE
.RS 0
//
.br
// codecvt.cpp
.br
//
.br
#include <sstream>
.br
#include "codecvte.h"
.br

.br
int main ()
.br
{
.RE
.RS 1
using namespace std;
.RE
.RS 0

.RE
.RS 1
mbstate_t state;
.RE
.RS 0

.RE
.RS 2
// A string of ISO characters and buffers to hold 
.br
// conversions
.RE
.RS 1
string ins("\\xfc \\xcc \\xcd \\x61 \\xe1 \\xd9 \\xc6 \\xf5");
.br
string ins2(ins.size(),'.');
.br
string outs(ins.size(),'.');
.RE
.RS 0

.RE
.RS 2
// Print initial contents of buffers
.RE
.RS 1
cout << "Before:\\n" << ins << endl;
.br
cout << ins2 << endl;
.br
cout << outs << endl << endl;
.RE
.RS 0

.RE
.RS 2
// Initialize buffers
.RE
.RS 1
string::iterator in_it = ins.begin();
.br
string::iterator out_it = outs.begin();
.RE
.RS 0

.RE
.RS 2
// Create a user defined codecvt fact
.br
// This facet converts from ISO Latin 
.br
// Alphabet No. 1 (ISO 8859-1) to 
.br
// U.S. ASCII code page 437
.br
// This facet replaces the default for
.br
// codecvt<char,char,mbstate_t>
.RE
.RS 1
locale loc(locale(),new ex_codecvt);
.RE
.RS 0

.RE
.RS 2
// Now get the facet from the locale 
.RE
.RS 1
const codecvt<char,char,mbstate_t>& cdcvt = 
.RE
.RS 0
#ifndef _RWSTD_NO_TEMPLATE_ON_RETURN_TYPE
.RE
.RS 3
use_facet<codecvt<char,char,mbstate_t> >(loc);
.RE
.RS 0
#else
.RE
.RS 3
use_facet(loc,(codecvt<char,char,mbstate_t>*)0);
.RE
.RS 0
#endif
.br

.RE
.RS 2
// convert the buffer
.RE
.RS 1
cdcvt.in(state,ins.begin(),ins.end(),in_it,
.RE
.RS 10
outs.begin(),outs.end(),out_it);
.RE
.RS 3

.RE
.RS 1
cout << "After in:\\n" << ins << endl;
.br
cout << ins2 << endl;
.br
cout << outs << endl << endl;
.RE
.RS 0

.RE
.RS 2
// Lastly, convert back to the original codeset
.RE
.RS 1
in_it = ins.begin();
.br
out_it = outs.begin();
.br
cdcvt.out(state, outs.begin(),outs.end(),out_it,
.RE
.RS 11
ins2.begin(),ins2.end(),in_it);
.RE
.RS 3

.RE
.RS 1
cout << "After out:\\n" << ins << endl;
.br
cout << ins2 << endl;
.br
cout << outs << endl;
.RE
.RS 0

.RE
.RS 1
return 0;
.RE
.RS 0
}



.SH  SEE ALSO


locale, facets, codecvt_byname