Source

Definition

A Source is a Device whose mode refines input.

Description

A Source provides read-access to a sequence of characters of a given type. In general, a Source may expose this sequence in two ways:

  1. by defining a member function read; or
  2. by defining a member function input_sequence returning a pair of pointers delimiting the sequence in its entirety.

As a special case, Boost.Iostreams treats standard input streams as Sources. (For details, see read.)

The mode of a Source is input or one of its refinements.

Note

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

Example

A model of Source can be defined as follows:

struct Source {
    typedef char        char_type;
    typedef source_tag  category;
    std::streamsize read(char* s, std::streamsize n) 
    {
        // Read up to n characters from the input 
        // sequence into the buffer s, returning   
        // the number of characters read, or -1 
        // to indicate end-of-sequence.
    }
};

Here source_tag is a category tag identifying the type as a model of Source. Typically a Source can be defined by deriving from the helper classes source or wsource and defining a member function read.

Refinement of

Device.

Associated Types

Same as Device, with the following additional requirements:

CategoryA type convertible to device_tag and to input

Notation

S- A type which is a model of Source
Ch- The character type
src- Object of type S
s- Object of type Ch*
n- Object of type std::streamsize
io- Alias for namespace boost::iostreams

Valid Expressions / Semantics

ExpressionExpression TypeCategory PreconditionSemantics
typename char_type_of<S>::type
typename of the character type --
typename category_of<S>::type
typename of the category --
io::read(src, s, n)
std::streamsize Not convertible to direct_tag Reads up to n characters from the input sequence controlled by dev into s, returning the number of characters read, or -1 to indicate end-of-sequence
src.input_sequence()
std::pair<Ch*,Ch*>
Convertible to direct_tag Returns a pair of pointers delimiting the sequence controlled by src

Exceptions

Errors which occur during the execution of member functions read or input_sequence are indicated by throwing exceptions. Reaching the end of the sequence is not an error.

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

Models