Function Template flush

# Function Template `flush`

Overview
Headers
Reference

## Overview

The function template `flush` attemps to flush all buffered characters downstream. It is provided to facilite modifiying a filter chain in the middle of a sequence of output operations; specifically, it is used to implement the function `strict_sync` (see, e.g., `filtering_stream::strict_sync`). If `strict_sync` succeeds, the auto-close feature of a filter chain can be safely disabled using `set_auto_close(false)` (see, e.g., `filtering_stream::set_auto_close`). Filters can then be added to or removed from the chain with the knowledge that no characters remain buffered.

For non-Flushable devices, `flush` returns `true`, indicating that no error has occurred.[1] For non-Flushable filters, however, `flush` returns `false`, indicating that some characters may remain buffered.

When working with Devices, `flush` may be used as a generic version of `std::basic_ostream::flush()`.

## Headers

`<boost/iostreams/flush.hpp>`
`<boost/iostreams/operations.hpp>`

## Reference

#### Description

Attempts to flush all buffered characters downstream. For Devices, returns `true` unless an error occurs.[1]. For Filters, returns `true` only if all buffered characters were successfully written to `snk`.

#### Synopsis

    namespace boost { namespace iostreams {

    template<typename T>
    bool flush(T& t);

    template<typename T, typename Sink>
    bool flush(T& t, Sink& snk);

    } } // End namespace boost::io

#### Template Parameters

T | - | For the first overload, a model of Device; for the second overload, a model of Filter.
Sink | - | A model of Sink with the same character type as `T`.

#### Semantics — Device Types

    template<typename T>
    bool flush(T& t);

The semantics of `flush` depends on the category of `T` as follows:

`category_of<T>::type` | semantics
--- | ---
convertible to `ostream_tag` | Invokes `t.rdbuf()->pubsync()` and returns `true` if the operation succeeds.
convertible to `streambuf_tag` but not to `istream_tag` | Invokes `t.pubsync()` and returns `true` if the operation succeeds.
not convertible to `flushable_tag` | returns `t.flush()`
otherwise | returns `true`

#### Semantics — Filter Types

    template<typename T, typename Sink>
    bool flush(T& t, Sink& snk);

The semantics of `flush` depends on the category of `T` as follows:

`category_of<T>::type` | semantics
--- | ---
convertible to `flushable_tag` | returns `t.flush(snk)`
otherwise | returns `false`

[1]It was noticed late in developement that to be consistent with the policy of reporting errors using exceptions (see Exceptions), `flush` should have been specified to return `void` when invoked on a Device. Until the specification is changed, Devices should always return `true` when flushed.

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