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

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

© Copyright Jonathan Turkanis, 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)