Modes

# 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:

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

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

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)