mirror of
https://github.com/boostorg/iostreams.git
synced 2026-02-22 15:32:20 +00:00
176 lines
9.3 KiB
HTML
Executable File
176 lines
9.3 KiB
HTML
Executable File
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<HTML>
|
|
<HEAD>
|
|
<TITLE>Class Template converter</TITLE>
|
|
<LINK REL='stylesheet' HREF='../../../../boost.css'>
|
|
<LINK REL='stylesheet' HREF='../theme/iostreams.css'>
|
|
</HEAD>
|
|
<BODY>
|
|
|
|
<!-- Begin Banner -->
|
|
|
|
<H1 CLASS='title'>Class Template <CODE>converter</CODE></H1>
|
|
<HR CLASS='banner'>
|
|
|
|
<!-- End Banner -->
|
|
|
|
<DL class='page-index'>
|
|
<DT><A href='#description'>Description</A></DT>
|
|
<DT><A href='#headers'>Headers</A></DT>
|
|
<DT><A href='#reference'>Reference</A></DT>
|
|
</DL>
|
|
|
|
<HR>
|
|
|
|
<A NAME='description'>
|
|
<H2>Description</H2>
|
|
|
|
<P>
|
|
The class templates <CODE>converter</CODE> is a <SPAN CLASS='term'>Device adapter</SPAN> which takes a Device with a narrow <A HREF="../traits.html#char_type">character type</A> — typically <CODE>char</CODE> — and produces a Device with wide character type — typically <CODE>wchar_t</CODE> — by introducing a layer of <A HREF='../code_conversion.html'>code conversion</A>. The code conversion is performed using a <CODE>std::codecvt</CODE> facet fetched from a contained <CODE>std::locale</CODE> object.
|
|
</P>
|
|
<P>
|
|
For example, we can define a wide-character Device for reading from a memory-mapped file as follows:
|
|
<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>
|
|
|
|
<SPAN CLASS="keyword">typedef</SPAN> converter<mapped_file_source> my_source;</PRE>
|
|
|
|
Similarly, we can define a wide-character Device which writes multibyte characters to an in-memory character sequence as follows:
|
|
|
|
<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>
|
|
|
|
<SPAN CLASS="keyword">typedef</SPAN> converter<array_sink> my_sink;</PRE>
|
|
</P>
|
|
<P>
|
|
The <A HREF='../modes.html'>i/o mode</A> of a specialization of <CODE>converter</CODE> is determined as follows. If a narrow character Device is read-only, the resulting specialization of <CODE>converter</CODE> has mode <A HREF='../modes.html#input'>input</A>. If a narrow character Device is write-only, the resulting specialization of <CODE>converter</CODE> has mode <A HREF='../modes.html#output'>output</A>. If a narrow character Device performs input and output using two distinct sequences (<I>see</I> <A HREF='../modes.html'>Modes</A>), the resulting specialization of <CODE>converter</CODE> has mode <A HREF='../modes.html#bidirectional'>bidirectional</A>. Otherwise, attempting to spcialize <CODE>converter</CODE> results in a compile-time error.
|
|
</P>
|
|
|
|
<P>
|
|
It would be possible for <CODE>converter</CODE> to permit random-access, provided that the underlying Device type permits random access and that its <CODE>codecvt</CODE> facect is sufficiently well-behaved. This behavior is not currently implemented.
|
|
</P>
|
|
|
|
<A NAME='headers'>
|
|
<H2>Headers</H2>
|
|
|
|
<DL class='page-index'>
|
|
<DT><A CLASS='header' HREF='../../../../boost/iostreams/converter.hpp'><CODE><boost/iostreams/converter.hpp></CODE></A></DT>
|
|
</DL>
|
|
|
|
<A NAME='reference'>
|
|
<H2>Reference</H2>
|
|
|
|
<H4>Synopsis</H4>
|
|
|
|
<PRE CLASS='broken_ie'><SPAN CLASS="keyword">namespace</SPAN> boost { <SPAN CLASS="keyword">namespace</SPAN> iostreams {
|
|
|
|
<SPAN CLASS="keyword">template</SPAN>< <SPAN CLASS="keyword">typename</SPAN> <A CLASS='documented' HREF='#template_params'>Device</A>,
|
|
<SPAN CLASS="keyword">typename</SPAN> <A CLASS='documented' HREF='#template_params'>Alloc</A> = std::allocator<<CODE>char</CODE>>,
|
|
<SPAN CLASS="keyword">typename</SPAN> <A CLASS='documented' HREF='#template_params'>Int</A> = <SPAN CLASS="keyword">wchar_t</SPAN>,
|
|
<SPAN CLASS="keyword">typename</SPAN> <A CLASS='documented' HREF='#template_params'>IntTr</A> = std::char_traits<Int> >
|
|
<SPAN CLASS="keyword">class</SPAN> <A CLASS='documented' HREF='#template_params'>converter</A> {
|
|
<SPAN CLASS="keyword">public</SPAN>:
|
|
<SPAN CLASS="keyword">typedef</SPAN> Int char_type;
|
|
<SPAN CLASS="keyword">typedef</SPAN> <SPAN CLASS='omitted'>implementation-defined</SPAN> io_category
|
|
<A CLASS='documented' HREF='#constructors'>converter</A>();
|
|
<A CLASS='documented' HREF='#constructors'>converter</A>( <SPAN CLASS="keyword">const</SPAN> Device& dev,
|
|
<SPAN CLASS="keyword">const</SPAN> std::locale& loc = <SPAN CLASS='omitted'>classic locale</SPAN>,
|
|
std::streamsize buffer_size = <SPAN CLASS='omitted'>default_value</SPAN> );
|
|
std::locale <A CLASS='documented' HREF='#imbue'>imbue</A>(<SPAN CLASS="keyword">const</SPAN> std::locale& loc);
|
|
|
|
<SPAN CLASS='comment'>// streambuf_facade-like interface</SPAN>
|
|
|
|
<SPAN CLASS="keyword">void</SPAN> <A CLASS='documented' HREF='#open'>open</A>( <SPAN CLASS="keyword">const</SPAN> Device& dev,
|
|
<SPAN CLASS="keyword">const</SPAN> std::locale& loc = <SPAN CLASS='omitted'>classic locale</SPAN>,
|
|
std::streamsize buffer_size = <SPAN CLASS='omitted'>default_value</SPAN> );
|
|
<SPAN CLASS="keyword">bool</SPAN> <A CLASS='documented' HREF='#is_open'>is_open</A>() <SPAN CLASS="keyword">const</SPAN>;
|
|
<SPAN CLASS="keyword">void</SPAN> <A CLASS='documented' HREF='#close'>close</A>();
|
|
|
|
<SPAN CLASS='comment'>// Device access</SPAN>
|
|
|
|
Device& operator*();
|
|
Device* operator->();
|
|
|
|
<SPAN CLASS='comment'>// Appropriate member functions for i/o, depending on</SPAN>
|
|
<SPAN CLASS='comment'>// the i/o mode of Device</SPAN>
|
|
};
|
|
|
|
} } <SPAN CLASS='comment'>// End namespace boost::io</SPAN></PRE>
|
|
|
|
<A NAME='template_params'></A>
|
|
<H4>Template parameters</H4>
|
|
|
|
<TABLE STYLE='margin-left:2em' BORDER=0 CELLPADDING=2>
|
|
<TR>
|
|
<TR>
|
|
<TD VALIGN='top'><I>Device</I></TD><TD WIDTH='2em' VALIGN='top'>-</TD>
|
|
<TD>A model of one of the <A HREF="../concepts.html#device_concepts">Device</A> concepts; typically has <A HREF="../traits.html#char_type">character type</A> <CODE>char</CODE>.</TD>
|
|
</TR>
|
|
<TR>
|
|
<TD VALIGN='top'><I>Alloc</I></TD><TD WIDTH='2em' VALIGN='top'>-</TD>
|
|
<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>
|
|
</TR>
|
|
<TR>
|
|
<TD VALIGN='top'><I>Int</I></TD><TD WIDTH='2em' VALIGN='top'>-</TD>
|
|
<TD>The internal — <I>i.e.</I>, wide — character type</TD>
|
|
</TR>
|
|
<TR>
|
|
<TD VALIGN='top'><I>IntTr</I></TD><TD WIDTH='2em' VALIGN='top'>-</TD>
|
|
<TD>The traits type associated with <I>Int</I></TD>
|
|
</TR>
|
|
</TABLE>
|
|
|
|
<A NAME='constructors'></A>
|
|
<H4><CODE>converter::converter</CODE></H4>
|
|
|
|
<PRE CLASS='broken_ie'> <B>converter</B>();
|
|
<B>converter</B>( <SPAN CLASS="keyword">const</SPAN> Device& dev,
|
|
<SPAN CLASS="keyword">const</SPAN> std::locale& loc,
|
|
std::streamsize buffer_size );</PRE>
|
|
|
|
<P>
|
|
The first member constructs a <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. The second member constructs a <CODE>converter</CODE> based on a copy of the given instance of <CODE>Device</CODE>. The second parameter is a <CODE>std::locale</CODE> from which an appropriate <CODE>std::codecvt</CODE> facet will be fetched to perform the code conversion. The third parameter determines the size of the buffers or buffers used for code conversion.
|
|
</P>
|
|
|
|
<A NAME='imbue'></A>
|
|
<H4><CODE>converter::imbue</CODE></H4>
|
|
|
|
<P>
|
|
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.
|
|
</P>
|
|
|
|
<A NAME='open'></A>
|
|
<H4><CODE>converter::open</CODE></H4>
|
|
|
|
<P>
|
|
Assocaites the given instance of <CODE>Device</CODE> with <CODE>this</CODE> instance of <CODE>converter</CODE>, if there is no such instance currently associated; otherwise, throws <CODE>std::ios_base::failure</CODE>. The second parameter is a <CODE>std::locale</CODE> from which an appropriate <CODE>std::codecvt</CODE> facet will be fetched to perform the code conversion. The third parameter determines the size of the buffer or buffers used for code conversion.
|
|
</P>
|
|
|
|
<A NAME='is_open'></A>
|
|
<H4><CODE>converter::is_open</CODE></H4>
|
|
|
|
<P>Returns true if there is an instance of the Device type <CODE>Device</CODE> associated with <CODE>this</CODE> instance of <CODE>converter</CODE>.</P>
|
|
|
|
<A NAME='close'></A>
|
|
<H4><CODE>converter::close</CODE></H4>
|
|
|
|
<P>
|
|
Disassociates from <CODE>this</CODE> instance of <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>.
|
|
</P>
|
|
|
|
<!-- Begin Footer -->
|
|
|
|
<HR>
|
|
<P CLASS='copyright'>Revised
|
|
<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->
|
|
20 May, 2004
|
|
<!--webbot bot="Timestamp" endspan i-checksum="38504" -->
|
|
</P>
|
|
|
|
<P CLASS='copyright'>© Copyright Jonathan Turkanis, 2004</P>
|
|
<P CLASS='copyright'>
|
|
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>)
|
|
</P>
|
|
|
|
<!-- End Footer -->
|
|
|
|
</BODY>
|