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:

1. by defining a member function write, invoked indirectly by the Iostreams library through the function boost::iostreams::write;
2. 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:

structSink {typedefcharchar_type;typedefsink_tag category;
    std::streamsize write(constchar* 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:

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.

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