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:

structSource {typedefcharchar_type;typedefsource_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

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.

© 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)