mirror of
https://github.com/boostorg/iostreams.git
synced 2026-02-23 15:52:13 +00:00
295 lines
18 KiB
HTML
Executable File
295 lines
18 KiB
HTML
Executable File
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<HTML>
|
|
<HEAD>
|
|
<TITLE>Policy-Based Streams and Stream Buffers</TITLE>
|
|
<LINK REL='stylesheet' HREF='../../../boost.css'>
|
|
<LINK REL='stylesheet' HREF='theme/iostreams.css'>
|
|
<STYLE>PRE { font-size: 80% }</STYLE>
|
|
</HEAD>
|
|
<BODY>
|
|
|
|
<!-- Begin Banner -->
|
|
|
|
<H1 CLASS='title'>Policy-Based Streams and Stream Buffers</H1>
|
|
<HR CLASS='banner'>
|
|
|
|
<!-- End Banner -->
|
|
|
|
<DL class='page-index'>
|
|
<DT><A href='#overview'>Overview</A></DT>
|
|
<DT><A href='#headers'>Headers</A></DT>
|
|
<DT><A href='#reference'>Reference</A>
|
|
<DL>
|
|
<DT><A href='#streambuf_facade'>Class template <CODE>streambuf_facade</CODE></A></DT>
|
|
<DT><A href='#stream_facade'>Class template <CODE>stream_facade</CODE></A></DT>
|
|
</DL>
|
|
</DT>
|
|
<DT><A href='#examples'>Examples</A></DT>
|
|
</DL>
|
|
|
|
<HR>
|
|
|
|
<A NAME='overview'>
|
|
<H2>Overview</H2>
|
|
|
|
<P>
|
|
The fundamental component provided by the Iostreams Library is the class template <CODE>streambuf_facade</CODE>, a derived class of <CODE>std::basic_streambuf</CODE> which performs i/o by delegating to a contained instance of a policy class. The policy class must model one of the various <A HREF='concepts.html#filter_concepts'>Filter</A> or <A HREF='concepts.html#device_concepts'>Device</A> concepts. Instances of the policy class can be associated and disassociated with an instance of <CODE>streambuf_facade</CODE> using member functions <CODE><A HREF="#streambuf_facade_open">open</A></CODE> and <CODE><A HREF="#streambuf_facade_close">close</A></CODE>. The interface is patterned after <CODE>std::basic_filebuf</CODE> and <CODE>std::basic_fstream</CODE>.
|
|
</P>
|
|
|
|
<P>
|
|
The class template <CODE>stream_facade</CODE> is a policy-based stream template which derives from one of <CODE>std::basic_istream</CODE>, <CODE>std::basic_ostream</CODE> and <CODE>std::basic_iostream</CODE> depending on the <A HREF='modes.html'>i/o mode</A> of the policy class. As with <CODE>streambuf_facade</CODE>, instances of the policy class can by associated and disassociated with an instance of <CODE>stream_facade</CODE> using its member functions <CODE><A HREF="#stream_facade_open">open</A></CODE> and <CODE><A HREF="#stream_facade_close">close</A></CODE>.
|
|
</P>
|
|
|
|
|
|
<A NAME='headers'>
|
|
<H2>Headers</H2>
|
|
|
|
<DL class='page-index'>
|
|
<DT><A CLASS='header' HREF='../../../boost/iostreams/streambuf_facade.hpp'><CODE><boost/iostreams/streambuf_facade.hpp></CODE></A></DT>
|
|
<DT><A CLASS='header' HREF='../../../boost/iostreams/stream_facade.hpp'><CODE><boost/iostreams/stream_facade.hpp></CODE></A></DT>
|
|
</DL>
|
|
|
|
<A NAME='reference'>
|
|
<H2>Reference</H2>
|
|
|
|
<A NAME='streambuf_facade'>
|
|
<H3>Class template <CODE>streambuf_facade</CODE></H3>
|
|
|
|
<H4>Description</H4>
|
|
|
|
<P>Policy-based stream buffer template with an interface similar to <CODE>std::basic_filebuf</CODE>.
|
|
|
|
<H4>Synopsis</H4>
|
|
|
|
<PRE><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="#streambuf_facade_params">T</A>,
|
|
<SPAN CLASS="keyword">typename</SPAN> <A CLASS="documented" HREF="#streambuf_facade_params">Tr</A> = std::char_traits<<SPAN CLASS="omitted">...</SPAN>>,
|
|
<SPAN CLASS="keyword">typename</SPAN> <A CLASS="documented" HREF="#streambuf_facade_params">Alloc</A> = std::allocator<<SPAN CLASS="omitted">...</SPAN>>,
|
|
<SPAN CLASS="keyword">typename</SPAN> <A CLASS="documented" HREF="#streambuf_facade_params">Mode</A> = <SPAN CLASS="omitted">...</SPAN> >
|
|
<SPAN CLASS="keyword">class</SPAN> <A CLASS="documented" HREF="#streambuf_facade_params">streambuf_facade</A> : <SPAN CLASS="keyword">public</SPAN> std::basic_streambuf<<SPAN CLASS="omitted">...</SPAN>> {
|
|
<SPAN CLASS="keyword">public</SPAN>:
|
|
<SPAN CLASS="keyword">typedef</SPAN> T policy_type;
|
|
<SPAN CLASS="keyword">typedef</SPAN> <SPAN CLASS="keyword">typename</SPAN> io_char<T>::type char_type;
|
|
<SPAN CLASS="keyword">typedef</SPAN> <SPAN CLASS="keyword">typename</SPAN> Tr traits_type;
|
|
|
|
[<SPAN CLASS="omitted">Standard stream buffer typedefs: int_type, off_type, etc.</SPAN>]
|
|
|
|
<A CLASS="documented" HREF="#streambuf_facade_default_constructor">streambuf_facade</A>();
|
|
<A CLASS="documented" HREF="#streambuf_facade_policy_constructor">streambuf_facade</A>( <SPAN CLASS="keyword">const</SPAN> T& t,
|
|
std::streamsize buffer_size = <SPAN CLASS="omitted">default_value</SPAN>,
|
|
std::streamsize pback_size = <SPAN CLASS="omitted">default_value</SPAN> );
|
|
|
|
<SPAN CLASS="comment">// Forwarding constructors</SPAN>
|
|
|
|
<SPAN CLASS="keyword">template</SPAN><<SPAN CLASS="keyword">typename</SPAN> U>
|
|
<A CLASS="documented" HREF="#streambuf_facade_forwarding_constructors">streambuf_facade</A>(<SPAN CLASS="keyword">const</SPAN> U& u);
|
|
|
|
<SPAN CLASS="keyword">template</SPAN><<SPAN CLASS="keyword">typename</SPAN> U1, <SPAN CLASS="keyword">typename</SPAN> U2>
|
|
<A CLASS="documented" HREF="#streambuf_facade_forwarding_constructors">streambuf_facade</A>(<SPAN CLASS="keyword">const</SPAN> U1& u1, <SPAN CLASS="keyword">const</SPAN> U2& u2);
|
|
|
|
<SPAN CLASS="omitted">...</SPAN>
|
|
|
|
template<<SPAN CLASS="keyword">typename</SPAN> U1, <SPAN CLASS="omitted">...</SPAN>, <SPAN CLASS="keyword">typename</SPAN> UN>
|
|
<A CLASS="documented" HREF="#streambuf_facade_forwarding_constructors">streambuf_facade</A>(<SPAN CLASS="keyword">const</SPAN> U1& u1, <SPAN CLASS="omitted">...</SPAN>, <SPAN CLASS="keyword">const</SPAN> UN& uN);
|
|
|
|
<SPAN CLASS="keyword">void</SPAN> <A CLASS="documented" HREF="#streambuf_facade_open">open</A>( <SPAN CLASS="keyword">const</SPAN> T& t,
|
|
std::streamsize buffer_size = <SPAN CLASS="omitted">default_value</SPAN>,
|
|
std::streamsize pback_size = <SPAN CLASS="omitted">default_value</SPAN> );
|
|
|
|
<SPAN CLASS="comment">// Forwarding overloads of open()</SPAN>
|
|
|
|
<SPAN CLASS="keyword">template</SPAN><<SPAN CLASS="keyword">typename</SPAN> U>
|
|
<SPAN CLASS="keyword">void</SPAN> <A CLASS="documented" HREF="#streambuf_facade_forwarding_open">open</A>(<SPAN CLASS="keyword">const</SPAN> U& u);
|
|
|
|
<SPAN CLASS="keyword">template</SPAN><<SPAN CLASS="keyword">typename</SPAN> U1, <SPAN CLASS="keyword">typename</SPAN> U2>
|
|
<SPAN CLASS="keyword">void</SPAN> <A CLASS="documented" HREF="#streambuf_facade_forwarding_open">open</A>(<SPAN CLASS="keyword">const</SPAN> U1& u1, <SPAN CLASS="keyword">const</SPAN> U2& u2);
|
|
|
|
<SPAN CLASS="omitted">...</SPAN>
|
|
|
|
<SPAN CLASS="keyword">template</SPAN><<SPAN CLASS="keyword">typename</SPAN> U1, <SPAN CLASS="omitted">...</SPAN>, <SPAN CLASS="keyword">typename</SPAN> UN>
|
|
<SPAN CLASS="keyword">void</SPAN> <A CLASS="documented" HREF="#streambuf_facade_forwarding_open">open</A>(<SPAN CLASS="keyword">const</SPAN> U1& u1, <SPAN CLASS="omitted">...</SPAN>, <SPAN CLASS="keyword">const</SPAN> UN& uN);
|
|
|
|
<SPAN CLASS="keyword">bool</SPAN> <A CLASS="documented" HREF="#streambuf_facade_is_open">is_open</A>() <SPAN CLASS="keyword">const</SPAN>;
|
|
<SPAN CLASS="keyword">void</SPAN> <A CLASS="documented" HREF="#streambuf_facade_close">close</A>();
|
|
};
|
|
|
|
} } <SPAN CLASS="comment">// namespace boost::io</SPAN></PRE>
|
|
|
|
<A NAME='streambuf_facade_params'></A>
|
|
<H4>Template parameters</H4>
|
|
|
|
<TABLE STYLE='margin-left:2em' BORDER=0 CELLPADDING=2>
|
|
<TR>
|
|
<TR>
|
|
<TD VALIGN='top'><A NAME='level'></A><I>T</I></TD><TD WIDTH='2em' VALIGN='top'>-</TD>
|
|
<TD>A model of one of the <A HREF='concepts.html#filter_concepts'>Filter</A> or <A HREF='concepts.html#device_concepts'>Device</A> concepts. Specializations of <CODE>streambuf_facade</CODE> with Filter types are used internally by the Iostreams Library to construct chains of Filters and Devices. Users of the library never need to specialize <CODE>streambuf_facade</CODE> with a Filter type.</TD>
|
|
</TR>
|
|
<TR>
|
|
<TD VALIGN='top'><A NAME='level'></A><I>Tr</I></TD><TD WIDTH='2em' VALIGN='top'>-</TD>
|
|
<TD>A C++ standard library charatcer traits type (<A CLASS='bib_ref' HREF='bibliography.html#iso'>[ISO]</A>, 21.1.1) with <CODE>char_type</CODE> equal to the <A HREF="traits.html#char_type">character type</A> <CODE>Ch</CODE> of T. Defaults to <CODE>std::char_traits<Ch></CODE>.</TD>
|
|
</TR>
|
|
<TR>
|
|
<TD VALIGN='top'><A NAME='level'></A><I>Alloc</I></TD><TD WIDTH='2em' VALIGN='top'>-</TD>
|
|
<TD>A C++ standard library allocator type (<A CLASS='bib_ref' HREF='bibliography.html#iso'>[ISO]</A>, 20.1.5), used to allocate any required character buffers. Defaults to <CODE>std::allocator<Ch></CODE>, where <CODE>Ch</CODE> is the <A HREF="traits.html#char_type">character type</A> of T.</TD>
|
|
</TR>
|
|
<TR>
|
|
<TD VALIGN='top'><A NAME='level'></A><I>Mode</I></TD><TD WIDTH='2em' VALIGN='top'>-</TD>
|
|
<TD>A mode tag <I>convertible to the <CODE>io_mode</CODE> of T</I>. This parameter is principally for internal use. Specifying a <A HREF="modes.html#mode_tags">mode tag</A> properly refined by the mode of T can prevent an unneeded buffer from being allocated in some cases. Defaults to the mode of T.</TD>
|
|
</TR>
|
|
</TABLE>
|
|
|
|
<H4><CODE>streambuf_facade::streambuf_facade</CODE></H4>
|
|
|
|
<A NAME='streambuf_facade_default_constructor'></A>
|
|
<PRE> <B>streambuf_facade</B>();</PRE>
|
|
|
|
<P>
|
|
Constructs a <CODE>streambuf_facade</CODE> with no associated instance of the policy type <CODE>T</CODE>. Before the instance can be used for i/o, one of its <CODE>open()</CODE> overloads must be invoked.
|
|
</P>
|
|
|
|
<H4><CODE>streambuf_facade::streambuf_facade</CODE></H4>
|
|
|
|
<A NAME='streambuf_facade_policy_constructor'></A>
|
|
<PRE> <B>streambuf_facade</B>( <SPAN CLASS="keyword">const</SPAN> T& t,
|
|
std::streamsize buffer_size,
|
|
std::streamsize pback_size );</PRE>
|
|
|
|
<P>
|
|
Constructs a <CODE>streambuf_facade</CODE> which is ready to perform i/o, where the parameters have the following interpretations:
|
|
|
|
<TABLE STYLE='margin-left:2em' BORDER=0 CELLPADDING=2>
|
|
<TR>
|
|
<TR>
|
|
<TD VALIGN='top'><A NAME='level'></A><I>t</I></TD><TD WIDTH='2em' VALIGN='top'>-</TD>
|
|
<TD>An instance of the policy type</TD>
|
|
</TR>
|
|
<TR>
|
|
<TD VALIGN='top'><A NAME='level'></A><I>buffer_size</I></TD><TD WIDTH='2em' VALIGN='top'>-</TD>
|
|
<TD>The size of any buffers that need to be allocated</TD>
|
|
</TR>
|
|
<TR>
|
|
<TD VALIGN='top'><A NAME='level'></A><I>pback_size</I></TD><TD WIDTH='2em' VALIGN='top'>-</TD>
|
|
<TD>The size of the putback buffer, relevant only if <CODE>Mode</CODE> is a refinement of <A HREF="modes.html#input"><CODE>input</CODE></TD>
|
|
</TR>
|
|
</TABLE>
|
|
|
|
<A NAME='streambuf_facade_forwarding_constructors'></A>
|
|
<PRE> <SPAN CLASS="keyword">template</SPAN><<SPAN CLASS="keyword">typename</SPAN> U>
|
|
<B>streambuf_facade</B>(<SPAN CLASS="keyword">const</SPAN> U& u);
|
|
|
|
<SPAN CLASS="keyword">template</SPAN><<SPAN CLASS="keyword">typename</SPAN> U1, <SPAN CLASS="keyword">typename</SPAN> U2>
|
|
<B>streambuf_facade</B>(<SPAN CLASS="keyword">const</SPAN> U1& u1, <SPAN CLASS="keyword">const</SPAN> U2& u2);
|
|
|
|
<SPAN CLASS="omitted">...</SPAN>
|
|
|
|
template<<SPAN CLASS="keyword">typename</SPAN> U1, <SPAN CLASS="omitted">...</SPAN>, <SPAN CLASS="keyword">typename</SPAN> UN>
|
|
<B>streambuf_facade</B>(<SPAN CLASS="keyword">const</SPAN> U1& u1, <SPAN CLASS="omitted">...</SPAN>, <SPAN CLASS="keyword">const</SPAN> UN& uN);</PRE>
|
|
|
|
<P>
|
|
Each of these members constructs an instance of <CODE>streambuf_facade</CODE> and associates it with an instance of the policy type <CODE>T</CODE> constructed from the given lists of arguments. The <CODE>T</CODE> constructors involved must take all arguments by value or <CODE>const</CODE> reference.
|
|
</P>
|
|
<P>
|
|
It is not possible to specify a custom buffer size or putback buffer size using these constructors.
|
|
</P>
|
|
|
|
<H4><CODE>streambuf_facade::open</CODE></H4>
|
|
|
|
<A NAME='streambuf_facade_open'></A>
|
|
<PRE> void <B>open</B>( <SPAN CLASS="keyword">const</SPAN> T& t,
|
|
std::streamsize buffer_size,
|
|
std::streamsize pback_size );</PRE>
|
|
|
|
<P>
|
|
Assocaites the given instance of <CODE>T</CODE> with <CODE>this</CODE> instance of <CODE>streambuf_facade</CODE>, if there is no such instance currently associated; otherwise, throws <CODE>std::ios_base::failure</CODE>. The second parameter determines the size of any buffers that need to be allocated; a value of zero indicates that i/o should be unbuffered. The third parameter determines the size of the putback buffer; it is relevant only if <CODE>Mode</CODE> is a refinement of <A HREF="modes.html#input"><CODE>input</CODE></A>.
|
|
</P>
|
|
|
|
<A NAME='streambuf_facade_forwarding_open'></A>
|
|
<PRE> <SPAN CLASS="keyword">template</SPAN><<SPAN CLASS="keyword">typename</SPAN> U>
|
|
<SPAN CLASS="keyword">void</SPAN> <B>open</B>(<SPAN CLASS="keyword">const</SPAN> U& u);
|
|
|
|
<SPAN CLASS="keyword">template</SPAN><<SPAN CLASS="keyword">typename</SPAN> U1, <SPAN CLASS="keyword">typename</SPAN> U2>
|
|
<SPAN CLASS="keyword">void</SPAN> <B>open</B>(<SPAN CLASS="keyword">const</SPAN> U1& u1, <SPAN CLASS="keyword">const</SPAN> U2& u2);
|
|
|
|
<SPAN CLASS="omitted">...</SPAN>
|
|
|
|
template<<SPAN CLASS="keyword">typename</SPAN> U1, <SPAN CLASS="omitted">...</SPAN>, <SPAN CLASS="keyword">typename</SPAN> UN>
|
|
<SPAN CLASS="keyword">void</SPAN> <B>open</B>(<SPAN CLASS="keyword">const</SPAN> U1& u1, <SPAN CLASS="omitted">...</SPAN>, <SPAN CLASS="keyword">const</SPAN> UN& uN);</PRE>
|
|
|
|
<P>
|
|
Each of these members associates with <CODE>this</CODE> instance of <CODE>streambuf_facade</CODE> a newly constructed instance of the policy type <CODE>T</CODE> constructed from the given lists of arguments, if there is no such instance currently associated; otherwise, they throw <CODE>std::ios_base::failure</CODE>. The <CODE>T</CODE> constructors involved must take all arguments by value or <CODE>const</CODE> reference.
|
|
</P>
|
|
<P>
|
|
It is not possible to specify a custom buffer size or putback buffer size using these members.
|
|
</P>
|
|
|
|
<A NAME='streambuf_facade_is_open'></A>
|
|
<H4><CODE>streambuf_facade::is_open</CODE></H4>
|
|
<PRE> <SPAN CLASS="keyword">bool</SPAN> <B>is_open</B>() <SPAN CLASS="keyword">const</SPAN>;</PRE>
|
|
|
|
<P>Returns true if there is an instance of the policy type <CODE>T</CODE> associated with <CODE>this</CODE> instance of <CODE>streambuf_facade</CODE>.</P>
|
|
|
|
<A NAME='streambuf_facade_close'></A>
|
|
<H4><CODE>streambuf_facade::close</CODE></H4>
|
|
<PRE> <SPAN CLASS="keyword">void</SPAN> <B>close</B>();</PRE>
|
|
|
|
<P>
|
|
Disassociates from <CODE>this</CODE> instance of <CODE>streambuf_facade</CODE> any instance of the policy type <CODE>T</CODE> currently associated with it, calling cleanup functions as appropriate and destroying the associated instance of <CODE>T</CODE>.
|
|
</P>
|
|
|
|
|
|
<A NAME='stream_facade'>
|
|
<H3>Class template <CODE>stream_facade</CODE></H3>
|
|
|
|
<P>[Copy <CODE>streambuf_facade</CODE> after all errors are corrected]</P>
|
|
|
|
<A NAME='examples'>
|
|
<H2>Examples</H2>
|
|
|
|
<H4>Defining a simple <CODE>ofstream</CODE></H4>
|
|
|
|
<P>The following example uses a <A HREF='file_based_devices.html'>File-Based Device</A> to define a class similar to a <CODE>std::ofstream</CODE>.
|
|
|
|
<PRE> <SPAN CLASS='preprocessor'>#include</SPAN> <A STYLE='text-decoration:none' HREF='../../../boost/iostreams/device/file.hpp'><SPAN CLASS='literal'><boost/iostreams/device/file.hpp></SPAN></A>
|
|
<SPAN CLASS='preprocessor'>#include</SPAN> <A STYLE='text-decoration:none' HREF='../../../boost/iostreams/stream_facade.hpp'><SPAN CLASS='literal'><boost/iostreams/stream_facade.hpp></SPAN></A>
|
|
|
|
<SPAN CLASS="keyword">typedef</SPAN> stream_facade<file_sink> ofstream;
|
|
|
|
ofstream out(<SPAN CLASS='literal'>"HeavyArtillery.txt"</SPAN>); <SPAN CLASS='comment'>// Wilfred Owen</SPAN>
|
|
out << <SPAN CLASS='literal'>"Reach at that Arrogance which needs thy harm,\n"</SPAN>
|
|
<SPAN CLASS='literal'>"And beat it down before its sins grow worse.\n"</SPAN>;
|
|
out.close();</PRE>
|
|
|
|
<H4>Reading from an array</H4>
|
|
|
|
<P>The following example uses an <A HREF='classes/array.html#array_source'><CODE>array_source</CODE></A> to construct an input stream from a C-style string.
|
|
|
|
<PRE> <SPAN CLASS='preprocessor'>#include</SPAN> <SPAN CLASS='literal'><cstring></SPAN>
|
|
<SPAN CLASS='preprocessor'>#include</SPAN> <SPAN CLASS='literal'><iostream></SPAN>
|
|
<SPAN CLASS='preprocessor'>#include</SPAN> <SPAN CLASS='literal'><string></SPAN>
|
|
<SPAN CLASS='preprocessor'>#include</SPAN> <A STYLE='text-decoration:none' HREF='../../../boost/iostreams/device/array.hpp'><SPAN CLASS='literal'><boost/iostreams/device/array.hpp></SPAN></A>
|
|
<SPAN CLASS='preprocessor'>#include</SPAN> <A STYLE='text-decoration:none' HREF='../../../boost/iostreams/stream_facade.hpp'><SPAN CLASS='literal'><boost/iostreams/stream_facade.hpp></SPAN></A>
|
|
|
|
const char* h = <SPAN CLASS='literal'>"Hello World!"</SPAN>;
|
|
stream_facade<array_source> in(h, std::strlen(h));
|
|
std::string hello;
|
|
std::getline(in, hello);
|
|
std::cout << hello << "\n"; // <SPAN CLASS='comment'>Prints "Hello World!"</SPAN></PRE>
|
|
|
|
<!-- 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> |