User's Guide

3.2 Modes

Overview
Definitions of the Modes
Mode Hierchy 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:

Whether input, output or both input and output can be performed.
If both input and output are possible, whether there are two separate character sequences for input and output, or a single combined sequence.
Whether the reading or writing heads are repositionable, and if so, whether there are separate heads for reading and writing or a single read/write head.

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:

Mode Definition/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 Hierchy 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.

Revised 02 Feb 2008

Distributed under the Boost Software License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)