1 <!DOCTYPE HTML PUBLIC
"-//W3C//DTD HTML 4.01 Transitional//EN">
4 <TITLE>Function Template flush
</TITLE>
5 <LINK REL=
"stylesheet" HREF=
"../../../../boost.css">
6 <LINK REL=
"stylesheet" HREF=
"../theme/iostreams.css">
12 <H1 CLASS=
"title">Function Template
<CODE>flush
</CODE></H1>
17 <DL class=
"page-index">
18 <DT><A href=
"#overview">Overview
</A></DT>
19 <DT><A href=
"#headers">Headers
</A></DT>
20 <DT><A href=
"#reference">Reference
</A></DT>
23 <A NAME=
"overview"></A></A>
27 The function template
<CODE>flush
</CODE> attemps to flush all buffered characters downstream. It is provided to facilite modifiying a filter chain in the middle of a sequence of output operations; specifically, it is used to implement the function
<CODE>strict_sync
</CODE> (
<I>see
</I>,
<I>e.g.
</I>,
<A HREF='../classes/filtering_stream.html#strict_sync'
><CODE>filtering_stream::strict_sync
</CODE></A>). If
<CODE>strict_sync
</CODE> succeeds, the auto-close feature of a filter chain can be safely disabled using
<CODE>set_auto_close(false)
</CODE> (
<I>see
</I>,
<I>e.g.
</I>,
<A HREF='../classes/filtering_stream.html#set_auto_close'
><CODE>filtering_stream::set_auto_close
</CODE></A>). Filters can then be added to or removed from the chain with the knowledge that no characters remain buffered.
30 For non-
<A HREF='../concepts/flushable.html'
>Flushable
</A> devices,
<CODE>flush
</CODE> returns
<CODE>true
</CODE>, indicating that no error has occurred.
<A CLASS='footnote_ref' NAME='note_1_ref'
HREF=
"#note_1"><SUP>[
1]
</SUP></A> For non-
<A HREF='../concepts/flushable.html'
>Flushable
</A> filters, however,
<CODE>flush
</CODE> returns
<CODE>false
</CODE>, indicating that some characters may remain buffered.
33 When working with Devices,
<CODE>flush
</CODE> may be used as a generic version of
<CODE>std::basic_ostream::flush()
</CODE>.
36 <A NAME=
"headers"></A>
40 <DT><A CLASS=
"header" HREF=
"../../../../boost/iostreams/flush.hpp"><CODE><boost/iostreams/flush.hpp
></CODE></A></DT>
41 <DT><A CLASS=
"header" HREF=
"../../../../boost/iostreams/operations.hpp"><CODE><boost/iostreams/operations.hpp
></CODE></A></DT>
44 <A NAME=
"reference"></A>
47 <A NAME=
"description"></A>
50 <P>Attempts to flush all buffered characters downstream. For
<A HREF='../concepts/device.html'
>Devices
</A>, returns
<CODE>true
</CODE> unless an error occurs.
<A CLASS='footnote_ref' NAME='note_1_ref2' HREF='#note_1'
><SUP>[
1]
</SUP></A>. For
<A HREF='../concepts/filter.html'
>Filters
</A>, returns
<CODE>true
</CODE> only if all buffered characters were successfully written to
<CODE>snk
</CODE>.
</P>
52 <A NAME=
"synopsis"></A>
55 <PRE CLASS=
"broken_ie"><SPAN CLASS=
"keyword">namespace
</SPAN> boost {
<SPAN CLASS=
"keyword">namespace
</SPAN> iostreams {
57 <SPAN CLASS=
"keyword">template
</SPAN><<SPAN CLASS=
"keyword">typename
</SPAN> <A CLASS=
"documented" HREF=
"#template_params">T
</A>>
58 <SPAN CLASS='keyword'
>bool
</SPAN> <A CLASS=
"documented" HREF=
"#flush_device">flush
</A>(T
& t);
60 <SPAN CLASS=
"keyword">template
</SPAN><<SPAN CLASS=
"keyword">typename
</SPAN> <A CLASS=
"documented" HREF=
"#template_params">T
</A>,
<SPAN CLASS=
"keyword">typename
</SPAN> <A CLASS=
"documented" HREF=
"#template_params">Sink
</A>>
61 <SPAN CLASS='keyword'
>bool
</SPAN> <A CLASS=
"documented" HREF=
"#flush_filter">flush
</A>(T
& t, Sink
& snk);
63 } }
<SPAN CLASS=
"comment">// End namespace boost::io
</SPAN></PRE>
65 <A NAME=
"template_params"></A>
66 <H4>Template Parameters
</H4>
68 <TABLE STYLE=
"margin-left:2em" BORDER=
0 CELLPADDING=
2>
71 <TD VALIGN=
"top"><I>T
</I></TD><TD WIDTH=
"2em" VALIGN=
"top">-
</TD>
72 <TD>For the first overload, a model of
<A HREF=
"../concepts/device.html">Device
</A>; for the second overload, a model of
<A HREF=
"../concepts/filter.html">Filter
</A>.
75 <TD VALIGN=
"top"><I>Sink
</I></TD><TD WIDTH=
"2em" VALIGN=
"top">-
</TD>
76 <TD>A model of
<A HREF=
"../concepts/sink.html">Sink
</A> with the same
<A HREF=
"../guide/traits.html#char_type">character type
</A> as
<CODE>T
</CODE>.
80 <A NAME=
"flush_device"></A>
81 <H4>Semantics
— Device Types
</H4>
83 <PRE CLASS=
"broken_ie"><SPAN CLASS=
"keyword">template
</SPAN><<SPAN CLASS=
"keyword">typename
</SPAN> T
>
84 <SPAN CLASS='keyword'
>bool
</SPAN> flush(T
& t);
</PRE>
86 <P>The semantics of
<CODE>flush
</CODE> depends on the
<A HREF=
"../guide/traits.html#category">category
</A> of
<CODE>T
</CODE> as follows:
</P>
88 <TABLE STYLE=
"margin-left:2em" BORDER=
1 CELLPADDING=
4>
89 <TR><TH><CODE>category_of
<T
>::type
</CODE></TH><TH>semantics
</TH></TR>
91 <TD VALIGN=
"top">convertible to
<A HREF=
"../guide/traits.html#category_tags"><CODE>ostream_tag
</CODE></A></TD>
92 <TD>Invokes
<CODE>t.rdbuf()-
>pubsync()
</CODE> and returns
<CODE>true
</CODE> if the operation succeeds.
</TD>
95 <TD VALIGN=
"top">convertible to
<A HREF=
"../guide/traits.html#category_tags"><CODE>streambuf_tag
</CODE></A> but not to
<A HREF=
"../guide/traits.html#category_tags"><CODE>istream_tag
</CODE></A></TD>
96 <TD>Invokes
<CODE>t.pubsync()
</CODE> and returns
<CODE>true
</CODE> if the operation succeeds.
</CODE></TD>
99 <TD VALIGN=
"top"><I>not
</I> convertible to
<A HREF=
"../guide/traits.html#category_tags"><CODE>flushable_tag
</CODE></A></TD>
100 <TD>returns
<CODE>t.flush()
</CODE></TD>
103 <TD VALIGN=
"top">otherwise
</TD>
104 <TD>returns
<CODE>true
</CODE></TD>
108 <A NAME=
"flush_filter"></A>
109 <H4>Semantics
— Filter Types
</H4>
111 <PRE CLASS=
"broken_ie"><SPAN CLASS=
"keyword">template
</SPAN><<SPAN CLASS=
"keyword">typename
</SPAN> T,
<SPAN CLASS=
"keyword">typename
</SPAN> Sink
>
112 <SPAN CLASS='keyword'
>bool
</SPAN> flush(T
& t, Sink
& snk);
</PRE>
114 <P>The semantics of
<CODE>flush
</CODE> depends on the
<A HREF=
"../guide/traits.html#category">category
</A> of
<CODE>T
</CODE> as follows:
</P>
116 <TABLE STYLE=
"margin-bottom:2em;margin-left:2em" BORDER=
1 CELLPADDING=
4>
117 <TR><TH><CODE>category_of
<T
>::type
</CODE></TH><TH>semantics
</TH></TR>
119 <TD VALIGN=
"top">convertible to
<A HREF=
"../guide/traits.html#category_tags"><CODE>flushable_tag
</CODE></A></TD>
120 <TD>returns
<CODE>t.flush(snk)
</CODE></TD>
123 <TD VALIGN=
"top">otherwise
</TD>
124 <TD>returns
<CODE>false
</CODE></TD>
128 <!-- Begin Footnotes -->
133 <A CLASS='footnote_ref' NAME='note_1' HREF='#note_1_ref'
><SUP>[
1]
</SUP></A>It was noticed late in developement that to be consistent with the policy of reporting errors using exceptions (
<I>see
</I> <A HREF='../guide/exceptions.html'
>Exceptions
</A>),
<CODE>flush
</CODE> should have been specified to return
<CODE>void
</CODE> when invoked on a Device. Until the specification is changed, Devices should always return
<CODE>true
</CODE> when flushed.
136 <!-- Begin Footer -->
140 <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>
141 <P CLASS=
"copyright">
142 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>)