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. 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 the Device. The category is a tag structure which the Iostreams library relies on to determine which operations the Device supports. Its function is similar to the iterator_category member of std::iterator_traits.[1]

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.

ConceptDefinition
Source Refinement of Device with mode convertible to input
Sink Refinement of Device with mode convertible to output
BidirectionalDevice Refinement of Device with mode convertible to bidirectional
SeekableDevice Refinement of Device with mode convertible to seekable
SeekableSource Refinement of Device with mode convertible to input_seekable
SeekableSink Refinement of Device with mode convertible to output_seekable
BidirectionalSeekableDevice Refinement of Device with mode convertible to bidirectional_seekable
DualSeekableDevice Refinement of Device with mode convertible to dual_seekable

Note

To be usable with the streams and stream buffers provided by the Boost Iostreams library, Devices must model Blocking.

Standard Streams and Stream Buffers

Standard streams and stream buffers are models of Device. It is not possible to tell the exact mode of an arbitrary stream or stream buffer, so the Iostreams library must make an educated guess. (See Class Template mode_of.) Since this guess may not accurately reflect the behavior of a particular stream or stream buffer, the user is allowed some flexibility when adding a stream or stream buffer to a filter chain. In such cases, it is up to the user to ensure that the behavior of the stream or stream buffer is consistent with the mode of the chain.

Refinement of

Associated Types

Character typeThe 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 stream_offset
way- Object of type std::ios_base::seekdir
which- Object of type std::ios_base::openmode
io- Alias for namespace boost::iostreams

Valid Expressions — Typenames

ExpressionExpression Type
typename char_type_of<D>::type typename of the character type
typename category_of<D>::type typename of the category

Valid Expressions / Semantics — Input

ExpressionExpression TypeCategory PreconditionSemantics
io::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, or -1 to indicate 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

ExpressionExpression TypeCategory PreconditionSemantics
io::write(dev, s2, n)
std::streamsize Convertible to output but not to direct_tag Writes up to n characters from the sequence beginning at s2 to the sequence controlled by dev, returning the number of characters written
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

ExpressionExpression TypeCategory PreconditionSemantics
io::seek(dev, off, way)
std::streampos 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
io::seek(dev, off, way, which)
std::streampos Convertible to dual_seekable or bidirectional_seekable but not to direct_tag

Advances 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][ISO], 24.3.1. See Tag Dispatching for a discussion.