1 <!DOCTYPE HTML PUBLIC
"-//W3C//DTD HTML 4.01 Transitional//EN">
4 <TITLE>Pipelines
</TITLE>
5 <LINK REL=
"stylesheet" HREF=
"../../../../boost.css">
6 <LINK REL=
"stylesheet" HREF=
"../theme/iostreams.css">
12 <H1 CLASS=
"title">User's Guide
</H1>
20 <A HREF='lifetimes.html'
><IMG BORDER=
0 WIDTH=
19 HEIGHT=
19 SRC='../../../../doc/src/images/prev.png'
></A>
21 <A HREF='guide.html'
><IMG BORDER=
0 WIDTH=
19 HEIGHT=
19 SRC='../../../../doc/src/images/up.png'
></A>
22 <A HREF='views.html'
><IMG BORDER=
0 WIDTH=
19 HEIGHT=
19 SRC='../../../../doc/src/images/next.png'
></A>
27 <H2>3.8 Pipelines
</H2>
29 <DL class=
"page-index">
30 <DT><A href=
"#overview">Overview
</A></DT>
31 <DT><A href=
"#examples">Examples
</A></DT>
32 <DT><A href=
"#headers">Headers
</A></DT>
33 <DT><A href=
"#reference">Reference
</A></DT>
36 <HR STYLE=
"margin-top:1em">
38 <A NAME=
"overview"></A>
42 A pipeline is an expression of the form
44 <PRE CLASS=
"broken_ie">filter
<SUB>1</SUB> | ... | filter
<SUB>n
</SUB> | filter-or-device
</PRE>
46 consiting of one or more filters and an optional device, joined using
<CODE>operator|
</CODE>. Pipelines are a convenient way to pass chains of Filters and Devices to the constructor or
<CODE>push
</CODE> function of a
<A HREF=
"../classes/filtering_stream.html"><CODE>filtering_stream
</CODE></A> or
<A HREF=
"../classes/filtering_streambuf.html"><CODE>filtering_streambuf
</CODE></A>.
50 In order for instances of a model of Filter to appear in a pipeline, it must be declared
<A HREF=
"../concepts/pipable.html">Pipable
</A> using the macro
<A HREF=
"#boost_iostreams_pipable"><CODE>BOOST_IOSTREAMS_PIPABLE
</CODE></A>.
54 Pipelines for C++ filtering were introduced by Jan Christiaan van Winkel and John van Krieken.
<I>See
</I> <A CLASS=
"bib_ref" HREF=
"../bibliography.html#van_winkel">[van Winkel].
</A>
57 <A NAME=
"examples"></A>
60 <P>The following example defines a
<A HREF=
"../concepts/pipable.html">Pipable
</A> InputFilter.
</P>
62 <PRE CLASS=
"broken_ie"><SPAN CLASS='preprocessor'
>#include
</SPAN> <A CLASS='header' HREF='../../../../boost/iostreams/concepts.hpp'
><SPAN CLASS='literal'
><boost/iostreams/concepts.hpp
></SPAN></A>
63 <SPAN CLASS='preprocessor'
>#include
</SPAN> <A CLASS='header' HREF='../../../../boost/iostreams/pipeline.hpp'
><SPAN CLASS='literal'
><boost/iostreams/pipeline.hpp
></SPAN></A>
65 <SPAN CLASS=
"keyword">namespace
</SPAN> io = boost::iostreams;
67 <SPAN CLASS=
"keyword">class
</SPAN> my_filter :
<SPAN CLASS=
"keyword">public
</SPAN> io::input_filter {
68 <SPAN CLASS=
"keyword">public:
</SPAN>
69 <SPAN CLASS='omitted'
>...
</SPAN>
70 <SPAN CLASS=
"keyword">template
</SPAN><<SPAN CLASS=
"keyword">typename
</SPAN> Source
>
71 <SPAN CLASS=
"keyword">int
</SPAN> get(Source
& src)
73 <SPAN CLASS='omitted'
> ...
</SPAN>
76 BOOST_IOSTREAMS_PIPABLE(my_filter,
0)
79 <P>No semicolon is required (or allowed) following the macro invocation. The following example shows a
<A HREF=
"../classes/filtering_stream.html"><CODE>filtering_stream
</CODE></A> constructed from a pipeline
</CODE>.
</P>
81 <PRE CLASS=
"broken_ie"><SPAN CLASS='preprocessor'
>#include
</SPAN> <A CLASS='header' HREF='../../../../boost/iostreams/filtering_stream.hpp'
><SPAN CLASS='literal'
><boost/iostreams/filtering_stream.hpp
></SPAN></A>
82 <SPAN CLASS='preprocessor'
>#include
</SPAN> <A CLASS='header' HREF='../../../../boost/iostreams/device/file.hpp'
><SPAN CLASS='literal'
><boost/iostreams/device/file.hpp
></SPAN></A>
83 <SPAN CLASS='preprocessor'
>#include
</SPAN> <A CLASS='header' HREF='../../../../boost/iostreams/filter/counter.hpp'
><SPAN CLASS='literal'
><boost/iostreams/filter/counter.hpp
></SPAN></A>
85 <SPAN CLASS=
"keyword">namespace
</SPAN> io = boost::iostreams;
87 <SPAN CLASS=
"keyword">int
</SPAN> main()
89 <SPAN CLASS='comment'
>// Write to the file
"hello," counting
</SPAN>
90 <SPAN CLASS='comment'
>// the number of lines and characters
</SPAN>
91 io::filtering_ostream out(io::counter() | io::file(
"hello"));
92 <SPAN CLASS='omitted'
>...
</SPAN>
95 <A NAME=
"headers"></A>
98 <DL class=
"page-index">
99 <DT><A CLASS=
"header" HREF=
"../../../../boost/iostreams/pipeline.hpp"><CODE><boost/iostreams/pipeline.hpp
></CODE></A></DT>
102 <A NAME=
"boost_iostreams_pipable"></A>
103 <A NAME=
"reference"></A>
106 <PRE CLASS=
"broken_ie">
108 <SPAN CLASS='preprocessor'
>#define
</SPAN> BOOST_IOSTREAMS_PIPABLE(filter, arity)
<SPAN CLASS='omitted'
>...
</SPAN>
114 <P>Defines the overloads of
<CODE>operator|
</CODE> necessary for a
<A HREF=
"../concepts/filter.html">Filter
</A> to appear in pipelines.
</P>
116 <A NAME=
"macro_params"></A>
117 <H4>Macro parameters
</H4>
119 <TABLE STYLE=
"margin-left:2em" BORDER=
0 CELLPADDING=
2>
122 <TD VALIGN=
"top"><I>filter
</I></TD><TD WIDTH=
"2em" VALIGN=
"top">-
</TD>
123 <TD>The name of the
<A HREF=
"../concepts/filter.html">Filter
</A> to be declared
<A HREF=
"../concepts/pipable.html">Pipable
</A></TD>
126 <TD VALIGN=
"top"><I>arity
</I></TD><TD WIDTH=
"2em" VALIGN=
"top">-
</TD>
127 <TD>The
<A HREF=
"../concepts/filter.html">Filter
</A>'s template arity,
<I>i.e.
</I>, the number or its template parameters; a value of
<CODE>0</CODE> indicates that it is not a class template
</TD>
131 <!-- Begin Footer -->
133 <HR STYLE=
"margin-top:1em">
135 <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>
136 <P CLASS=
"copyright">
137 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>)