Tutorial

2.1.1. Overview: Devices, stream_buffer and stream

Writing a new stream or stream buffer class using the Boost Iostreams library is easy: you simply write a class modeling the Device concept, then use that class as the template argument to stream or stream_buffer:

#include <boost/iostreams/stream.hpp>
#include <boost/iostreams/stream_buffer.hpp>

namespace io = boost::iostreams;

class my_device { /* */ };

typedef io::stream<my_device>         my_stream;
typedef io::stream_buffer<my_device>  my_streambuf;

Here io::stream_buffer<my_device> is a derived class of std::basic_streambuf, and io::stream<my_device> is a derived class of std::basic_istream, std::basic_ostream or std::basic_iostream depending on the mode of my_device, i.e., depending on which of the fundamental i/o operations read, write and seek it supports.

The template io::stream is provided as a convenience. It's always possible to avoid io::stream and simply use io::stream_buffer together with one of the standard library stream templates. E.g.,

#include <ostream>
#include <boost/iostreams/device/file.hpp>
#include <boost/iostreams/stream.hpp>

namespace io = boost::iostreams;

int main()
{
    io::stream_buffer<io::file_sink> buf("log.txt");
    std::ostream                     out(&buf);
    // out writes to log.txt
}

In this example, the ostream out uses the stream_buffer buf as its underlying data sink, so that data written to out goes to the file log.txt. The same effect could be achieved by default constructing out and telling it to use stream buffer buf by invoking out.rdbuf(&buf).

Another way to define a new stream or stream buffer class using the Boost Iostreams library is to derive from filtering_stream or filtering_streambuf.

The next three items will demonstrate how to write Devices for accessing STL-compatible containers. The source code for the examples can be found in the header <libs/iostreams/example/container_device.hpp>

© Copyright 2008 CodeRage, LLC
© Copyright 2004-2007 Jonathan Turkanis

Use, modification, and distribution are subject to the Boost Software License, Version 2.0. (See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)