Device

Description

A Device provides access to one or two character sequences. It may provide access to an input sequence, for reading, an output sequence, for writing, or both. The relationship between the two sequences, as well as the operations that may be performed on them, depends on the Device type.

Typically, Devices are class types which define one or more member functions read, write and seek having interfaces resembling the member functions sgetn, sputn and pubseekoff of std::basic_streambuf.^[1] The concept Device is defined a bit more broadly, however, so that pre-existing types, such as standard streams and stream buffers, can be treated as models of Device, and so that Devices managing in-memory sequences can be optimized.

Each Device type has an associated character type and category. The character type is the type of the characters in the sequence or sequences controlled by instances of D. The category is a tag structure which the Iostreams Library relies on to determine which operations D supports. Its function is similar to the iterator_category member of std::iterator_traits.^[2]

There is one refinement of Device for each of the eight modes, and for each such refinement there is a corresponding refinement of Filter. In order to express this corresponce cleanly, it is helpful to include the requirements of the various refinements of Device in the definition of Device itself, qualified by category. The various refinements of Device can then be characterized exactly by the following definitions. For convenience, the requirements of the four most common Device refinements are also documented individually.

Concept	Definition
Source	Refinement of Device with io_mode convertible to `input`
Sink	Refinement of Device with io_mode convertible to `output`
BidirectionalDevice	Refinement of Device with io_mode convertible to `bidirectional`
SeekableDevice	Refinement of Device with io_mode convertible to `seekable`
SeekableSource	Refinement of Device with io_mode convertible to `input_seekable`
SeekableSink	Refinement of Device with io_mode convertible to `output_seekable`
BidirectionalSeekableDevice	Refinement of Device with io_mode convertible to `bidirectional_seekable`
DualSeekableDevice	Refinement of Device with io_mode convertible to `dual_seekable`

Standard Streams and Stream Buffers

Standard streams and stream buffer types are model of Device. It is not possible to tell the exact i/o mode of an arbitrary stream or stream buffer, so the Iostreams Library has to guess. (See Class Template io_mode.) If the i/o mode selected by default does not accurately reflect a particular implementation, the function template adapt may be used.

Refinement of

Associated Types

Character type	The type of the characters in the controlled sequences
Category	A type convertible to device_tag and to a unique most-derived mode tag
Mode	The unique most-derived mode tag to which Category is convertible

Notation

`D`	- A type which is a model of Device
`Ch`	- The character type of `D`
`dev`	- Object of type `D`
`s1`	- Object of type `Ch*`
`s2`	- Object of type `const Ch*`
`n`	- Object of type `std::streamsize`
`off`	- Object of type `std::streamoff`
`way`	- Object of type `std::ios_base::seekdir`
`which`	- Object of type `std::ios_base::openmode`

Valid Expressions — Typenames

Expression	Expression Type
`typename io_char<D>::type`	`typename` of the character type
`typename io_category<D>::type`	`typename` of the category

Valid Expressions / Semantics — Input

Expression	Expression Type	Category Precondition	Semantics
`boost::iostreams::read(dev, s1, n)`	`std::streamsize`	Convertible to `input` but not to `direct_tag`	Reads up to `n` characters from the sequence controlled by `dev` into `s1`, returning the number of characters read; returning a value less than n indicates end-of-sequence
`dev.input_sequence()`	`std::pair<Ch,Ch>`	Convertible to `input` and to `direct_tag`	Returns a pair of pointers delimiting the sequence controlled by `dev`

Valid Expressions / Semantics — Output

Expression	Expression Type	Category Precondition	Semantics
`boost::iostreams::write(dev, s2, n)`	`void`	Convertible to `output` but not to `direct_tag`	Writes `n` characters from the sequence beginning at `s2` to the sequence controlled by `dev`
`dev.output_sequence()`	`std::pair<Ch,Ch>`	Convertible to `output` and to `direct_tag`	Returns a pair of pointers delimiting the sequence controlled by `dev`

Valid Expressions / Semantics — Random-Access

Expression Expression Type Category Precondition Semantics

Expression	Expression Type	Category Precondition	Semantics
`boost::iostreams::seek(dev, off, way)`	`std::streamoff`	Convertible to `seekable` but not to `direct_tag`	Advances the read/write head by `off` characters, returning the new position, where the offset is calculated from: the start of the sequence if `way` is `ios_base::beg` the current position if `way` is `ios_base::cur` the end of the sequence if `way` is `ios_base::end`
`boost::iostreams::seek(dev, off, way, which)`	`std::streamoff`	Convertible to `dual_seekable` or `bidirectional_seekable` but not to `direct_tag`	Repositions the read head (if `which` is `std::ios_base::in`), the write head (if `which` is `std::ios_base::out`) or both heads (if `which` is `std::ios_base::in \| std::ios_base::out`) by `off` characters, returning the new position, where the offset is calculated from the start of the sequence if `way` is `ios_base::beg` the current position if `way` is `ios_base::cur` the end of the sequence if `way` is `ios_base::end` The result is undefined if `way` is `ios_base::cur` and `which` is `(std::ios_base::in \| std::ios_base::out)`.

boost::iostreams::seek(dev, off, way)

std::streamoff

Convertible to seekable but not to direct_tag

Advances the read/write head by off characters, returning the new position, where the offset is calculated from:

the start of the sequence if way is ios_base::beg
the current position if way is ios_base::cur
the end of the sequence if way is ios_base::end

boost::iostreams::seek(dev, off, way, which)

std::streamoff

Convertible to dual_seekable or bidirectional_seekable but not to direct_tag

Repositions the read head (if which is std::ios_base::in), the write head (if which is std::ios_base::out) or both heads (if which is std::ios_base::in | std::ios_base::out) by off characters, returning the new position, where the offset is calculated from

the start of the sequence if way is ios_base::beg
the current position if way is ios_base::cur
the end of the sequence if way is ios_base::end

The result is undefined if way is ios_base::cur and which is (std::ios_base::in | std::ios_base::out).

Exceptions

Errors which occur during the execution of read, write, seek, input_sequence or output_sequence are indicated by throwing exceptions. Reaching the end of the input sequence is not an error, but attempting to write past the end of the output sequence is.

After an exception is thrown, a Device must be in a consistent state; further i/o operations may throw exceptions but must have well-defined behaviour.

Models

See Source, Sink, BidirectionalDevice and SeekableDevice.

^[1]Familiarity with these std::basic_streambuf members is not required.

^[2][ISO], 24.3.1. See Tag Dispatching for a discussion.

Revised 20 May, 2004

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)