Sink

Definition

A Sink is a Device whose mode refines output.

Description

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

by defining a member function write, invoked indirectly by the Iostreams library through the function boost::iostreams::write;
by defining a member function output_sequence returning a pair of pointers delimiting the sequence in its entirety.

As a special case, Boost.Iostreams treats standard output streams as Sinks. (For details, see write.)

The mode of a Sink is output or one of its refinements.

Note

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

Example

A model of Sink can be defined as follows:

struct Sink {
    typedef char      char_type;
    typedef sink_tag  category;
    void write(const char* s, std::streamsize n) 
    {
        // Write up to n characters from the buffer
        // s to the output sequence, returning the 
        // number of characters written
    }
};

Here sink_tag is a category tag identifying the type as a model of Sink. Typically a Sink can be defined by deriving from the helper classes sink or wsink and defining a member function write.

Refinement of

Device.

Associated Types

Same as Device, with the following additional requirements:

Category A type convertible to device_tag and to output

Notation

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

Valid Expressions / Semantics

Same as Device, with the following additional requirements:

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::write(snk, s, n)`	`std::streamsize`	Not convertible to `direct_tag`	Writes up to `n` characters from the sequence beginning at `s` to the output sequence controlled by `dev`, returning the number of characters written
`snk.output_sequence()`	`std::pair<Ch,Ch>`	Convertible to `direct_tag`	Returns a pair of pointers delimiting the sequence controlled by `snk`

Exceptions

Errors which occur during the execution of member functions write or output_sequence are indicated by throwing exceptions. Attempting to write past the end of the sequence is always an error.

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

Models

Standard output streams and stream buffers.
array_sink, file_sink, file_descriptor_sink, mapped_file_sink.

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)