1 <!DOCTYPE HTML PUBLIC
"-//W3C//DTD HTML 4.01 Transitional//EN">
4 <TITLE>OutputFilter
</TITLE>
5 <LINK REL=
"stylesheet" HREF=
"../../../../boost.css">
6 <LINK REL=
"stylesheet" HREF=
"../theme/iostreams.css">
12 <H1 CLASS=
"title">OutputFilter
</H1>
17 <DL CLASS=
"page-index" STYLE=
"margin-top:0">
18 <DT><A HREF=
"#definition">Definition
</A>
19 <DT><A HREF=
"#description">Description
</A>
20 <DT><A HREF=
"#examples">Examples
</A>
21 <DT><A HREF=
"#detailed_specification">Detailed Specification
</A>
24 <A NAME=
"definition"></A>
28 An OutputFilter is a
<A HREF=
"filter.html">Filter
</A> whose
<A HREF=
"../guide/modes.html">mode
</A> refines
<A HREF=
"../guide/modes.html#output">output
</A>.
31 <A NAME=
"description"></A>
35 An OutputFilter operates on the character sequence controlled by a
<A HREF=
"sink.html">Sink
</A>, providing access to a filtered sequence having the same character type. It may expose the filtered sequence in two ways:
37 <LI STYLE=
"list-style-type:lower-roman">
38 by defining a member function
<CODE>put
</CODE>
40 <LI STYLE=
"list-style-type:lower-roman">
41 by defining a member function
<CODE>write
</CODE>
43 The second alternative is provided for enhanced performance. OutputFilters implementing this alternative are referred to as as
<I>Multi-Character
</I>. (
<I>See
</I> <A HREF=
"multi_character.html">Multi-Character Filter
</A>.)
46 <A NAME=
"examples"></A>
49 <H4>I. Ordinary OutputFilter
</H4>
52 The following example shows an OutputFilter which converts each character in a sequence to uppercase.
55 <PRE CLASS=
"broken_ie"> <SPAN CLASS=
"preprocessor">#include
</SPAN> <SPAN CLASS=
"literal"><ctype.h
></SPAN> <SPAN CLASS=
"comment">// toupper
</SPAN>
56 <SPAN CLASS=
"preprocessor">#include
</SPAN> <A CLASS=
"header" HREF=
"../../../../boost/iostreams/categories.hpp"><SPAN CLASS=
"literal"><boost/iostreams/categories.hpp
></SPAN></A> <SPAN CLASS=
"comment">// output_filter_tag
</SPAN>
57 <SPAN CLASS=
"preprocessor">#include
</SPAN> <A CLASS=
"header" HREF=
"../../../../boost/iostreams/operations.hpp"><SPAN CLASS=
"literal"><boost/iostreams/operations.hpp
></SPAN></A> <SPAN CLASS=
"comment">// put
</SPAN>
59 <SPAN CLASS=
"keyword">using
</SPAN> <SPAN CLASS=
"keyword">namespace
</SPAN> std;
60 <SPAN CLASS=
"keyword">namespace
</SPAN> io = boost::iostreams;
62 <SPAN CLASS=
"keyword">struct
</SPAN> toupper_output_filter {
63 <SPAN CLASS=
"keyword">typedef
</SPAN> <SPAN CLASS=
"keyword">char
</SPAN> char_type;
64 <SPAN CLASS=
"keyword">typedef
</SPAN> io::output_filter_tag category;
66 <SPAN CLASS=
"keyword">template
</SPAN><<SPAN CLASS=
"keyword">typename
</SPAN> Sink
>
67 <SPAN CLASS=
"keyword">bool
</SPAN> put(Sink
& snk,
<SPAN CLASS=
"keyword">char
</SPAN> c)
69 <SPAN CLASS=
"keyword">return
</SPAN> io::put(snk, toupper((
<SPAN CLASS=
"keyword">unsigned
</SPAN> <SPAN CLASS=
"keyword">char
</SPAN>) c));
74 Here
<CODE>char_type
</CODE> is the
<A HREF=
"../guide/traits.html#char_type">character type
</A> of the Filter,
<CODE>output_filter_tag
</CODE> is a
<A HREF=
"../guide/traits.html#category">category tag
</A> identifying the Filter as a model of OutputFilter, and the function
<A HREF=
"../functions/put.html"><CODE>io::put
</CODE></A> writes a character to an arbitrary Sink.
<A CLASS=
"footnote_ref" NAME=
"note_1_ref" HREF=
"#note_1"><SUP>[
1]
</SUP></A>
78 The Iostreams library defines two convenience classes,
<A HREF=
"../classes/filter.html#synopsis"><CODE>output_filter
</CODE></A> and
<A HREF=
"../classes/filter.html#synopsis"><CODE>output_wfilter
</CODE></A>, which provide member
<CODE>typedef
</CODE>s
<CODE>char_type
</CODE> and
<CODE>category
</CODE> as well as default implementations of several member functions. When defining a new model of OutputFilter, it is often sufficient to derive from
<CODE>output_filter
</CODE> or
<CODE>output_wfilter
</CODE> and to define a member function
<CODE>put
</CODE>.
81 <H4>II. Multi-Character OutputFilter
</H4>
84 The following example shows a Multi-Character OutputFilter which performs the same filtering operation as the Filter in Example I.
87 <PRE CLASS=
"broken_ie"> <SPAN CLASS=
"preprocessor">#include
</SPAN> <SPAN CLASS=
"literal"><ctype.h
></SPAN> <SPAN CLASS=
"comment">// toupper
</SPAN>
88 <SPAN CLASS=
"preprocessor">#include
</SPAN> <A CLASS=
"header" HREF=
"../../../../boost/iostreams/categories.hpp"><SPAN CLASS=
"literal"><boost/iostreams/categories.hpp
></SPAN></A> <SPAN CLASS=
"comment">// output_filter_tag
</SPAN>
89 <SPAN CLASS=
"preprocessor">#include
</SPAN> <A CLASS=
"header" HREF=
"../../../../boost/iostreams/operations.hpp"><SPAN CLASS=
"literal"><boost/iostreams/operations.hpp
></SPAN></A> <SPAN CLASS=
"comment">// put
</SPAN>
91 <SPAN CLASS=
"keyword">using
</SPAN> <SPAN CLASS=
"keyword">namespace
</SPAN> std;
92 <SPAN CLASS=
"keyword">namespace
</SPAN> io = boost::iostreams;
94 <SPAN CLASS=
"keyword">struct
</SPAN> toupper_filter {
95 <SPAN CLASS=
"keyword">typedef
</SPAN> <SPAN CLASS=
"keyword">char
</SPAN> char_type;
96 <SPAN CLASS=
"keyword">typedef
</SPAN> io::multichar_output_filter_tag category;
98 <SPAN CLASS=
"keyword">template
</SPAN><<SPAN CLASS=
"keyword">typename
</SPAN> Sink
>
99 <SPAN CLASS=
"keyword">std::streamsize
</SPAN> write(Sink
& snk,
<SPAN CLASS=
"keyword">const
</SPAN> <SPAN CLASS=
"keyword">char
</SPAN>* s, streamsize n)
101 std::streamsize rest = n;
102 <SPAN CLASS=
"keyword">while
</SPAN> (rest !=
0 && io::put(snk, toupper((
<SPAN CLASS=
"keyword">unsigned
</SPAN> <SPAN CLASS=
"keyword">char
</SPAN>) *s++))
104 <SPAN CLASS=
"keyword">return
</SPAN> n - rest;
109 Here
<CODE>multichar_output_filter_tag
</CODE> is a
<A HREF=
"../guide/traits.html#category">category tag
</A> identifying the Filter as a multichar OutputFilter.
112 The Iostreams library defines two convenience classes,
<A HREF=
"../classes/filter.html#synopsis"><CODE>multichar_output_filter
</CODE></A> and
<A HREF=
"../classes/filter.html#synopsis"><CODE>multichar_output_wfilter
</CODE></A>, which provide the member
<CODE>typedef
</CODE>s
<CODE>char_type
</CODE> and
<CODE>category
</CODE> as well as default implementations of several member functions. When defining a new multichar OutputFilter, it is often sufficient to derive from
<CODE>multichar_output_filter
</CODE> or
<CODE>multichar_output_wfilter
</CODE> and to define a member function
<CODE>write
</CODE>.
115 <A NAME=
"detailed_specification"></A>
116 <H2>Refinement of
</H2>
118 <P><A HREF=
"filter.html">Filter
</A>.
</P>
120 <H2>Associated Types
</H2>
122 <TABLE CELLPADDING=
"5" BORDER=
"1">
123 <TR><TD>Character type
</TD><TD>The type of the characters in the filtered sequences
</TD></TR>
127 A type convertible to
<A HREF=
"../guide/traits.html#category_tags"><CODE>filter_tag
</CODE></A> and to
<A HREF=
"../guide/modes.html#output"><CODE>output
</CODE></A>
133 The unique
<I>most-derived
</I> <A HREF=
"../guide/modes.html#mode_tags">mode tag
</A> to which Category is convertible
140 <TABLE CELLPADDING=
"2">
141 <TR><TD><CODE>F
</CODE></TD><TD>- A type which is a model of OutputFilter
</TD></TR>
142 <TR><TD><CODE>D
</CODE></TD><TD>- A type which is a model of
<A HREF=
"device.html">Device
</A>, with the same character type as
<CODE>F
</CODE> and with mode refining the mode of
<CODE>F
</CODE></TD></TR>
143 <TR><TD><CODE>Ch
</CODE></TD><TD>- The character type of
<CODE>F
</CODE></TD></TR>
144 <TR><TD><CODE>Tr
</CODE></A></TD><TD>-
<A HREF=
"../classes/char_traits.html"><CODE>boost::iostreams::char_traits
<Ch
></CODE></A></TD></TR>
145 <TR><TD><CODE>f
</CODE></TD><TD>- Object of type
<CODE>F
</CODE></TD></TR>
146 <TR><TD><CODE>d
</CODE></TD><TD>- Object of type
<CODE>D
</CODE></TD></TR>
147 <TR><TD><CODE>c
</CODE></TD><TD>- Object of type
<CODE>Ch
</CODE></TD></TR>
148 <TR><TD><CODE>s
</CODE></TD><TD>- Object of type
<CODE>const Ch*
</CODE></TD></TR>
149 <TR><TD><CODE>n
</CODE></TD><TD>- Object of type
<CODE>std::streamsize
</CODE></TD></TR>
150 <TR><TD><CODE>io
</CODE></TD><TD>- Alias for namespace
<CODE>boost::iostreams
</CODE></TD></TR>
153 <A NAME=
"semantics"></A>
154 <H2>Valid Expressions / Semantics
</H2>
156 <TABLE CELLPADDING=
"5" BORDER=
"1">
157 <TR><TH>Expression
</TH><TH>Expression Type
</TH><TH>Category Precondition
</TH><TH>Semantics
</TH></TR>
160 <PRE CLASS=
"plain_code"><CODE>typename
<A HREF=
"../guide/traits.html#char_type_of_ref">char_type_of
</A><F
>::type
</CODE></PRE>
162 <TD><CODE>typename
</CODE> of the character type
</TD>
163 <TD ALIGN=
"center">-
</TD><TD ALIGN=
"center">-
</TD>
167 <PRE CLASS=
"plain_code"><CODE>typename
<A HREF=
"../guide/traits.html#category_ref">category_of
</A><F
>::type
</CODE></PRE>
169 <TD><CODE>typename
</CODE> of the category
</TD>
170 <TD ALIGN=
"center">-
</TD><TD ALIGN=
"center">-
</TD>
173 <TD><PRE CLASS=
"plain_code"><CODE>f.put(d, c)
</CODE></PRE></TD>
174 <TD><CODE>bool
</CODE></TD>
176 Convertible to
<A HREF=
"../guide/modes.html#mode_tags"><CODE>output
</CODE></A> but not to
<A HREF=
"../guide/traits.html#category_tags"><CODE>multichar_tag
</CODE></A>
179 Attempts to writes the character
<CODE>c
</CODE> to the output sequence controlled by
<CODE>f
</CODE>, returning
<CODE>false
</CODE> if
<CODE>c
</CODE> cannot be consumed because a call to
<CODE>d
</CODE> has consumed fewer characters than requested. The output sequence controlled by
<CODE>d
</CODE> may be accessed using
<A HREF=
"../functions/put.html"><CODE>io::put
</CODE></A> and
<A HREF=
"../functions/write.html"><CODE>io::write
</CODE></A>.
183 <TD><PRE CLASS=
"plain_code"><CODE>f.write(d, s, n)
</CODE></PRE></TD>
184 <TD><PRE CLASS=
"plain_code"><CODE>std::streamsize
</CODE></PRE></TD>
186 Convertible to
<A HREF=
"../guide/modes.html#mode_tags"><CODE>output
</CODE></A> and to
<A HREF=
"../guide/traits.html#category_tags"><CODE>multichar_tag
</CODE></A>
189 Writes up to
<CODE>n
</CODE> characters from the buffer
<CODE>s
</CODE> to the output sequence controlled by
<CODE>d
</CODE>, returning the number of characters written. A value less than
<CODE>n
</CODE> may be returned only if a call to
<CODE>d
</CODE> has consumed fewer characters than requested. The output sequence controlled by
<CODE>d
</CODE> may be accessed using
<A HREF=
"../functions/put.html"><CODE>io::put
</CODE></A> and
<A HREF=
"../functions/write.html"><CODE>io::write
</CODE></A>.
197 Errors which occur during the execution of
<CODE>put
</CODE> or
<CODE>write
</CODE> are indicated by throwing exceptions. Attempting to write past the end of the sequence is always an error.
201 After an exception is thrown, an OutputFilter must be in a consistent state; further i/o operations may throw exceptions but must have well-defined behaviour.Furthermore, unless it is
<A HREF=
"closable.html">Closable
</A>, it must be ready to begin processing a new character sequence.
206 <H2>Acknowledgments
</H2>
209 The concept OutputFilter was inspired by the
<I>inserters
</I> of
<A CLASS=
"footnote_ref" HREF=
"../bibliography.html#kanze">[Kanze]
</A>.
212 <!-- Begin Footnotes -->
217 <A CLASS=
"footnote_ref" NAME=
"note_1" HREF=
"#note_1_ref"><SUP>[
1]
</SUP></A>Technically,
<CODE>boost::iostreams::put
</CODE> requires that a Sink be
<A HREF=
"../concepts/direct.html"><I>indirect
</I></A>.
220 <!-- End Footnotes -->
221 <!-- Begin Footer -->
225 <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>
226 <P CLASS=
"copyright">
227 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>)