The Boost Iostreams Library

Note

Overview

The Iostreams library serves two main purposes:

The library focuses on freeing users from writing boiler plate code and allowing them instead to create highly reusable components.

In addition to providing an abstract framework the library provides a number of concrete filters, sources and sinks which serve as example applications of the library but are also useful in their own right. These include components for accessing memory-mapped files, for file access via operating system file descriptors, for code conversion, for text filtering with regular expressions, for line-ending conversion and for compression and decompression in the zlib, gzip and bzip2 formats.

Concepts

The fundamental building blocks of the library are the concepts of a Source, which provides read access to a sequence of characters, a Sink, which provides write access to a sequence of characters, an InputFilter, which filters input read from a Source, and an OutputFilter, which filters output written to a Sink. Sources, Sinks and their refinements are called Devices. InputFilters, OutputFilters and their refinements are called Filters.

Policy-Based Streams and Stream Buffers

The class templates streambuf_facade and stream_facade implement standard stream buffers and streams which perform i/o by delegating to a contained Filter or Device. The Filter or Device is accessed using member functions open, is_open and close, providing an interface similar to the standard file-based streams and stream buffers.

Filtering Streams and Stream Buffers

For filtering data the Iostreams library provides the templates filtering_streambuf and filtering_stream. Instances of filtering_streambuf or filtering_stream contains chains of Filters and Devices accessed with an interface similar to that of std::stack.

Conventions

Acknowledgments

The original idea for the library came from Angelika Langer and Klaus Kreft ([Langer], pp. 228-43). Robert Ramey suggested extending the library to handle filtering.

[1]This is an instance of a limitation of C++ known as the forwarding problem (see [Dimov]).

[2]Technically, boost::iostreams::get and boost::iostreams::read require that a Source be indirect.

[3]Technically, boost::iostreams::put requires that a Sink be indirect.