The Boost Iostreams Library

Purpose

The Iostreams library has three aims:

In addition to providing an abstract framework, the library provides a number of concrete Filters, Sources and Sinks. These include components for accessing memory-mapped files, for file access using 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.

Overview

At the heart of the Boost Iostreams library are a collection of concepts and set of templates which turn models of these concepts into C++ standard library streams and stream buffers.

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.

Generic Streams and Stream Buffers

The class templates stream_buffer and stream implement standard stream buffers and streams which perform i/o by delegating to a contained Device. The 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

All classes, functions and templates introduced in the documentation are in the namespace boost::io. Namespace qualification is usually omitted.

Specializations of std::basic_istream will be refered to as standard input streams, specializations of std::basic_ostream as standard output streams, specializations of std::basic_iostream as standard i/o streams, and specializations of std::basic_streambuf as standard stream buffers. Together, standard input streams, standard output streams and standard i/o streams will be refered to as standard streams. Sometimes the qualifier standard will be omitted for brevity.


[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.