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

| | Output |

| | Bidirectional |

| | Input-seekable |

| | **``` 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](../rationale.html).

## Mode Hierarchy Diagrams

The following diagrams display the refinement hierarchies among modes.

| 

**Figure 1.** The four most important modes

 ![](../graphics/important_modes.gif) | | 

| ![](../graphics/key_important.gif) | Most important |
| ![](../graphics/key_input_seq.gif) | Input sequence |
| ![](../graphics/key_output_seq.gif) | Output sequence |
| ![](../graphics/key_bidirectional_seq.gif) | Combined input-output sequence |
| ![](../graphics/key_read_head.gif) | Repositionable file-pointer for reading |
| ![](../graphics/key_write_head.gif) | Repositionable file-pointer for writing |
| ![](../graphics/key_read_write_head.gif) | Combined file-pointer for reading and writing |

 |
| 

**Figure 2.** The complete hierarchy of modes

 ![](../graphics/modes.gif) |

## Mode Tags

Each mode is represented by a mode tag, defined in the header [`<boost/iostreams/traits.hpp>`](../../../../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]](#note_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](../concepts/dual_use_filter.html) — 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](../classes/regex_filter.html), [Newline Filters](../classes/newline_filter.html) 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`](../classes/mode.html).

* * *

[[1]](#note_1_ref)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](http://www.coderage.com/)  
© Copyright 2004-2007 [Jonathan Turkanis](https://www.boost.org/users/people/jonathan_turkanis.html)

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](http://www.boost.org/LICENSE_1_0.txt))