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:

by defining a member function read; or
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:

Category A 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

Expression	Expression Type	Category Precondition	Semantics
`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

Standard input streams and stream buffers.
array_source, file_source, file_descriptor_source, mapped_file_source.

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)