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