User's Guide

3.2 Modes

Overview
Definitions of the Modes
Mode Hierarchy Diagrams
Mode Tags
The metafunction mode_of

Overview

In order for a sequence of Filters and Devices to work together they must have certain properties in common. The most basic requirement is that they have the same character type; a collection of additional properties which Filters and Devices must share to be used for a particular purpose is called a mode.

The templates stream_buffer and stream are each parameterized by a mode, represented by a mode tag.

The Iostreams library supports eight modes, described in the next section (see also Figure 2). Of these, four are most import (see Figure 1). The two modes input and output are by far the most common. Readers new to the Iostreams library should feel free to concentrate primarily on these two modes.

Definitions of the Modes

Modes can be categorized in several ways:

The concepts representing optional behavior are not related to mode, and so need not be shared in order for a collection of Filters and Devices to work together:

Modes are summarized in the following table:

ModeDefinition/Examples
Input
Definition:Involves a single sequence of characters, for input
Example:std::cin
Output
Definition:Involves a single sequence of characters, for output
Example:std::cout
Bidirectional
Definition: Involves a two separate sequences of characters, one for input and one for output
Example:A std::iostream for accessing a TCP connection
Input-seekable
Definition: Involves a single sequence of characters, for input, with a repositionable reading head
Examples:std::ifstream, std::istringstream

Output-seekable

Definition: Involves a single sequence of characters, for output, with a repositionable writing head
Examples:std::ofstream, std::ostringstream
Seekable
Definition: Involves a single sequence of characters, for input and output, with a combined repositionable read/write head
Example:std::fstream
Dual-seekable
Definition: Involves a single sequence of characters, for input and output, with separate repositionable reading and writing heads
Example:std::stringstream
Bidirectional-seekable
Definition:Involves a two separate sequences of characters, one for input and one for output, each with a repositionable head
Example:No known examples

For more on the selection of modes, see the Rationale.

Mode Hierarchy Diagrams

The following diagrams display the refinement hierarchies among modes.

Figure 1. The four most important modes

Most important
Input sequence
Output sequence
Combined input-output sequence
Repositionable file-pointer for reading
Repositionable file-pointer for writing
Combined file-pointer for reading and writing

Figure 2. The complete hierarchy of modes

Mode Tags

Each mode is represented by a mode tag, defined in the header <boost/iostreams/traits.hpp>. There are eight tags for the eight modes: input, output, bidirectional, input_seekable, output_seekable, seekable, dual_seekable and bidirectional_seekable.[1] As with standard library iterator category tags, the tag corresponding to a mode is convertible to each of the tags corresponding to modes which the first mode refines.

In addition, there is a pseudo-mode tag dual_use, which is used to define DualUseFilters — which can perform input or output, but not both simultaneously. This is useful to help reduce the number of different of Filter types. The Regular Expression Filters, Newline Filters and compression and decompression filters all have mode dual_use so that they may be used with either input or output streams.

The Metafunction mode_of

To determine the mode of a model of a Filter or Device, use the metafunction mode_of.


[1]It is traditional for tag structures to have names ending with "_tag". Since mode tags feature prominently in user code, this suffix was dropped to improve readability.