# 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:

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`.

Revised 02 Feb 2008

© Copyright 2008 CodeRage, LLC
© Copyright 2004-2007 Jonathan Turkanis

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)