Source

Definition

A Source is a Device whose i/o mode refines input.

Description

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

by defining a member function read, invoked indirectly by the Iostreams Library through the function boost::iostreams::read;
by overloading or specializing boost::iostreams::read; or
by defining a member function input_sequence returning a pair of pointers delimiting the sequence in its entirety.

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

Example

A model of Source can be defined as follows:

struct Source {
    typedef char        char_type;
    typedef source_tag  io_category;
    std::streamsize read(char* s, std::streamsize n) 
        {
            // Reads up to n characters from the controlled 
            // sequence into the buffer s, returning the number 
            // of characters read. Returning a value less than n 
            // indicates 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`

Valid Expressions / Semantics

Expression	Expression Type	Category Precondition	Semantics
`typename io_char<S>::type`	`typename` of the character type	-	-
`typename io_category<S>::type`	`typename` of the category	-	-
`boost::iostreams::read(src, s, n)`	`std::streamsize`	Not convertible to `direct_tag`	Reads up to `n` characters from the sequence controlled by `src` into `s`, returning the number of characters read; returning a value less than n indicates 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, basic_file_source, file_descriptor_source, mapped_file_source.

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)