1 <!DOCTYPE HTML PUBLIC
"-//W3C//DTD HTML 4.01 Transitional//EN">
4 <TITLE>Class Template code_converter
</TITLE>
5 <LINK REL=
"stylesheet" HREF=
"../../../../boost.css">
6 <LINK REL=
"stylesheet" HREF=
"../theme/iostreams.css">
12 <H1 CLASS=
"title">Class Template
<CODE>code_converter
</CODE></H1>
17 <DL class=
"page-index">
18 <DT><A href=
"#description">Description
</A></DT>
19 <DT><A href=
"#headers">Headers
</A></DT>
20 <DT><A href=
"#reference">Reference
</A></DT>
25 <A NAME=
"description"></A>
29 The class templates
<CODE>code_converter
</CODE> is a
<SPAN CLASS=
"term">Device adapter
</SPAN> which takes a Device with a narrow
<A HREF=
"../guide/traits.html#char_type">character type
</A> \97 typically
<CODE>char
</CODE> \97 and produces a Device with wide character type
\97 typically
<CODE>wchar_t
</CODE> \97 by introducing a layer of
<A HREF=
"../guide/code_conversion.html">code conversion
</A>. The code conversion is performed using a
<CODE>std::codecvt
</CODE> facet which can either be specified as a template parameter or be fetched from a
<CODE>std::locale
</CODE> provided at runtime.
32 For example, we can define a wide-character Device for reading from a memory-mapped file as follows:
33 <PRE CLASS=
"broken_ie"> <SPAN CLASS=
"preprocessor">#include
</SPAN> <A CLASS=
"header" HREF=
"../../../../boost/iostreams/device/mapped_file.hpp"><SPAN CLASS=
"literal"><boost/iostreams/maped_file.hpp
></SPAN></A>
35 <SPAN CLASS=
"keyword">typedef
</SPAN> code_converter
<mapped_file_source
> my_source;
</PRE>
37 Similarly, we can define a wide-character Device which writes multibyte characters to an in-memory character sequence as follows:
39 <PRE CLASS=
"broken_ie"> <SPAN CLASS=
"preprocessor">#include
</SPAN> <A CLASS=
"header" HREF=
"../../../../boost/iostreams/device/array.hpp"><SPAN CLASS=
"literal"><boost/iostreams/device/array.hpp
></SPAN></A>
41 <SPAN CLASS=
"keyword">typedef
</SPAN> code_converter
<array_sink
> my_sink;
</PRE>
44 The
<A HREF=
"../guide/modes.html">mode
</A> of a specialization of
<CODE>code_converter
</CODE> is determined as follows. If a narrow character Device is read-only, the resulting specialization of
<CODE>code_converter
</CODE> has mode
<A HREF=
"../guide/modes.html#input">input
</A>. If a narrow character Device is write-only, the resulting specialization of
<CODE>code_converter
</CODE> has mode
<A HREF=
"../guide/modes.html#output">output
</A>. If a narrow character Device performs input and output using two distinct sequences (
<I>see
</I> <A HREF=
"../guide/modes.html">Modes
</A>), the resulting specialization of
<CODE>code_converter
</CODE> has mode
<A HREF=
"../guide/modes.html#bidirectional">bidirectional
</A>. Otherwise, attempting to spcialize
<CODE>code_converter
</CODE> results in a compile-time error.
47 <A NAME=
"headers"></A>
50 <DL class=
"page-index">
51 <DT><A CLASS=
"header" HREF=
"../../../../boost/iostreams/code_converter.hpp"><CODE><boost/iostreams/code_converter.hpp
></CODE></A></DT>
54 <A NAME=
"reference"></A>
59 <PRE CLASS=
"broken_ie"><SPAN CLASS=
"keyword">namespace
</SPAN> boost {
<SPAN CLASS=
"keyword">namespace
</SPAN> iostreams {
61 <SPAN CLASS=
"keyword">template
</SPAN>< <SPAN CLASS=
"keyword">typename
</SPAN> <A CLASS=
"documented" HREF=
"#template_params">Device
</A>,
62 <SPAN CLASS=
"keyword">typename
</SPAN> <A CLASS=
"documented" HREF=
"#template_params">Codecvt
</A> =
<SPAN CLASS='omitted'
>default_value
</SPAN>
63 <SPAN CLASS=
"keyword">typename
</SPAN> <A CLASS=
"documented" HREF=
"#template_params">Alloc
</A> = std::allocator
<<CODE>char
</CODE>> >
64 <SPAN CLASS=
"keyword">class
</SPAN> <A CLASS=
"documented" HREF=
"#template_params">code_converter
</A> {
65 <SPAN CLASS=
"keyword">public
</SPAN>:
66 <SPAN CLASS=
"keyword">typedef
</SPAN> <SPAN CLASS=
"keyword">typename
</SPAN> Codecvt::intern_type char_type;
67 <SPAN CLASS=
"keyword">typedef
</SPAN> <SPAN CLASS=
"omitted">implementation-defined
</SPAN> category;
68 <A CLASS=
"documented" HREF=
"#constructors">code_converter
</A>();
69 <A CLASS=
"documented" HREF=
"#constructors">code_converter
</A>(
<SPAN CLASS=
"keyword">const
</SPAN> Device
& dev,
70 int buffer_size =
<SPAN CLASS=
"omitted">default_value
</SPAN> );
71 <A CLASS=
"documented" HREF=
"code_converter.html#constructors">code_converter
</A>(
<SPAN CLASS=
"omitted">device-constructor-args...
</SPAN>,
72 int buffer_size =
<SPAN CLASS=
"omitted">default_value
</SPAN> );
73 <SPAN CLASS=
"keyword">void
</SPAN> <A CLASS=
"documented" HREF=
"code_converter.html#open">open
</A>(
<SPAN CLASS=
"keyword">const
</SPAN> Device
& dev,
74 int buffer_size =
<SPAN CLASS=
"omitted">default_value
</SPAN> );
75 <SPAN CLASS=
"keyword">void
</SPAN> <A CLASS=
"documented" HREF=
"code_converter.html#open">open
</A>(
<SPAN CLASS=
"omitted">device-constructor-args...
</SPAN>,
76 int buffer_size =
<SPAN CLASS=
"omitted">default_value
</SPAN> );
77 <SPAN CLASS=
"keyword">bool
</SPAN> <A CLASS=
"documented" HREF=
"#is_open">is_open
</A>()
<SPAN CLASS=
"keyword">const
</SPAN>;
78 <SPAN CLASS=
"keyword">void
</SPAN> <A CLASS=
"documented" HREF=
"#close">close
</A>();
79 std::locale
<A CLASS=
"documented" HREF=
"#imbue">imbue
</A>(
<SPAN CLASS=
"keyword">const
</SPAN> std::locale
& loc);
80 Device
& <A CLASS=
"documented" HREF=
"#operator_star">operator*
</A>();
81 Device*
<A CLASS=
"documented" HREF=
"#operator_arrow">operator-
></A>();
84 } }
<SPAN CLASS=
"comment">// End namespace boost::io
</SPAN></PRE>
86 <A NAME=
"template_params"></A>
87 <H4>Template parameters
</H4>
89 <TABLE STYLE=
"margin-left:2em" BORDER=
0 CELLPADDING=
2>
92 <TD VALIGN=
"top"><I>Device
</I></TD><TD WIDTH=
"2em" VALIGN=
"top">-
</TD>
93 <TD>A model of one of the
<A HREF=
"../guide/concepts.html#device_concepts">Device
</A> concepts; typically has
<A HREF=
"../guide/traits.html#char_type">character type
</A> <CODE>char
</CODE>.
</TD>
96 <TD VALIGN=
"top"><I>Codecvt
</I></TD><TD WIDTH=
"2em" VALIGN=
"top">-
</TD>
98 A standard library codecvt facet, which must be default constructible. If this parameter is not specified,
99 an instance of
<CODE>std::codecvt
<wchar_t, char, std::mbstate_t
></CODE> will be fetched from the global
100 local when a
<CODE>code_converter
</CODE> is constructed or opened.
104 <TD VALIGN=
"top"><I>Alloc
</I></TD><TD WIDTH=
"2em" VALIGN=
"top">-
</TD>
105 <TD>A standard library allocator type (
<A CLASS=
"bib_ref" HREF=
"../bibliography.html#iso">[ISO]
</A>,
20.1.5), used to allocate character buffers
</TD>
109 <A NAME=
"constructors"></A>
110 <H4><CODE>code_converter::code_converter
</CODE></H4>
112 <PRE CLASS=
"broken_ie"> code_converter();
113 code_converter(
<SPAN CLASS=
"keyword">const
</SPAN> Device
& dev,
115 code_converter(
<SPAN CLASS=
"omitted">device-constructor-args...
</SPAN>,
116 int buffer_size );
</PRE>
119 The first member constructs a
<CODE>code_converter
</CODE> with no associated instance of the Device type
<CODE>Device
</CODE>. Before the instance can be used for i/o, the member function
<CODE>open()
</CODE> must be invoked.
123 The second member constructs a
<CODE>code_converter
</CODE> based on the given instance of
<CODE>Device
</CODE>. The second parameter determines the size of the buffers or buffers used for code conversion. If a
<CODE>std::codecvt
</CODE> was specified as a template parameter, an instance of it will be default constructed. Otherwise, a copy of the global
<CODE>locale
</CODE> will be made, and an instance of
<CODE>std::codecvt
<wchar_t, char, std::mbstate_t
></CODE> will be fetched from it.
127 The third member constructs a
<CODE>code_converter
</CODE> based on the given instance of
<CODE>Device
</CODE> constructed with the forwarded arguments. Take care as the
<CODE>buffer_size
</CODE> can be confused for a constructor argument if it isn't an
<CODE>int
</CODE>.
<br>
131 <H4><CODE>code_converter::imbue
</CODE></H4>
133 <PRE CLASS=
"broken_ie"> std::locale imbue(
<SPAN CLASS=
"keyword">const
</SPAN> std::locale
& loc);
</PRE>
136 Used to specify a locale from which a
<CODE>std::codecvt
</CODE> facet will be fetched to perform code conversion. The effect of invoking imbue while code conversion is in progress is undefined.
140 This function is a no-op if a
<CODE>std::codecvt
</CODE> facet was specified as a template parameter.
144 <H4><CODE>code_converter::open
</CODE></H4>
146 <PRE CLASS=
"broken_ie"> <SPAN CLASS=
"keyword">void
</SPAN> open(
<SPAN CLASS=
"keyword">const
</SPAN> Device
& dev,
147 std::streamsize buffer_size =
<SPAN CLASS=
"omitted">default_value
</SPAN> );
148 <SPAN CLASS=
"keyword">void
</SPAN> open(
<SPAN CLASS=
"omitted">device-constructor-args
</SPAN>,
149 std::streamsize buffer_size =
<SPAN CLASS=
"omitted">default_value
</SPAN> );
<br></PRE>
152 Associates the given instance of
<CODE>Device
</CODE> with
<CODE>this
</CODE> instance of
<CODE>code_converter
</CODE>, if there is no such instance currently associated; otherwise, throws
<CODE>std::ios_base::failure
</CODE>. The second parameter determines the size of the buffer or buffers used for code conversion. If a
<CODE>std::codecvt
</CODE> was specified as a template parameter, an instance of it will be default constructed. Otherwise, a copy of the global
<CODE>locale
</CODE> will be made, and an instance of
<CODE>std::codecvt
<wchar_t, char, std::mbstate_t
></CODE> will be fetched from it.
155 The second member constructs a
<CODE>Device
</CODE> with the forwarded arguments. Take care as the
<CODE>buffer_size
</CODE> can be confused for a constructor argument if it isn't an
<CODE>int
</CODE>.
158 <A NAME=
"is_open"></A>
159 <H4><CODE>code_converter::is_open
</CODE></H4>
161 <PRE CLASS=
"broken_ie"> <SPAN CLASS=
"keyword">bool
</SPAN> is_open()
<SPAN CLASS=
"keyword">const
</SPAN>;
</PRE>
163 <P>Returns true if there is an instance of the Device type
<CODE>Device
</CODE> associated with
<CODE>this
</CODE> instance of
<CODE>code_converter
</CODE>.
</P>
166 <H4><CODE>code_converter::close
</CODE></H4>
168 <PRE CLASS=
"broken_ie"> <SPAN CLASS=
"keyword">void
</SPAN> close();
</PRE>
171 Disassociates from
<CODE>this
</CODE> instance of
<CODE>code_converter
</CODE> any instance of the Device type
<CODE>Device
</CODE> currently associated with it, calling cleanup functions as appropriate and destroying the associated instance of
<CODE>Device
</CODE>.
174 <A NAME=
"operator_star"></A>
175 <H4><CODE>code_converter::operator*
</CODE></H4>
177 <PRE CLASS=
"broken_ie"> Device
& operator*();
</PRE>
180 Returns a reference to the instance of Device associated with this instance of
<CODE>code_converter
</CODE>, which must be
<A HREF=
"#is_open">open
</A>.
183 <A NAME=
"operator_arrow"></A>
184 <H4><CODE>code_converter::operator-
></CODE></H4>
186 <PRE CLASS=
"broken_ie"> Device* operator-
>();
</PRE>
189 Returns a pointer to the instance of Device associated with this instance of
<CODE>code_converter
</CODE>, which must be
<A HREF=
"#is_open">open
</A>.
192 <!-- Begin Footer -->
196 <P CLASS=
"copyright">© Copyright
2008 <a href=
"http://www.coderage.com/" target=
"_top">CodeRage, LLC
</a><br/>© Copyright
2004-
2007 <a href=
"http://www.coderage.com/turkanis/" target=
"_top">Jonathan Turkanis
</a></P>
197 <P CLASS=
"copyright">
198 Distributed under the Boost Software License, Version
1.0. (See accompanying file LICENSE_1_0.txt or copy at
<A HREF=
"http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt
</A>)