# User's Guide

## 3.8 Pipelines

Overview
Examples
Headers
Reference

## Overview

A pipeline is an expression of the form

    filter1 | ... | filtern | filter-or-device

consiting of one or more filters and an optional device, joined using `operator|`. Pipelines are a convenient way to pass chains of Filters and Devices to the constructor or `push` function of a `filtering_stream` or `filtering_streambuf`.

In order for instances of a model of Filter to appear in a pipeline, it must be declared Pipable using the macro `BOOST_IOSTREAMS_PIPABLE`.

Pipelines for C++ filtering were introduced by Jan Christiaan van Winkel and John van Krieken. See [van Winkel].

## Examples

The following example defines a Pipable InputFilter.

    #include <boost/iostreams/concepts.hpp>
    #include <boost/iostreams/pipeline.hpp>

    namespace io = boost::iostreams;

    class my_filter : public io::input_filter {
    public:
        ...
        template<typename Source>
        int get(Source& src)
        {
            ...
        }
    };
    BOOST_IOSTREAMS_PIPABLE(my_filter, 0)

No semicolon is required (or allowed) following the macro invocation. The following example shows a `filtering_stream` constructed from a pipeline.

    #include <boost/iostreams/filtering_stream.hpp>
    #include <boost/iostreams/device/file.hpp>
    #include <boost/iostreams/filter/counter.hpp>

    namespace io = boost::iostreams;

    int main()
    {
        // Write to the file "hello," counting
        // the number of lines and characters
        io::filtering_ostream out(io::counter() | io::file("hello"));
        ...
    }

## Headers

`<boost/iostreams/pipeline.hpp>`

## Reference

    #define BOOST_IOSTREAMS_PIPABLE(filter, arity) ...

#### Description

Defines the overloads of `operator|` necessary for a Filter to appear in pipelines.

#### Macro parameters

filter | - | The name of the Filter to be declared Pipable
arity | - | The Filter's template arity, i.e., the number or its template parameters; a value of `0` indicates that it is not a class template

Revised 20 May, 2004

© Copyright Jonathan Turkanis, 2004

Distributed under the Boost Software License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)