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:

struct Sink {
    typedef char      char_type;
    typedef sink_tag  category;
    std::streamsize 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:

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

ExpressionExpression TypeCategory PreconditionSemantics
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