Class Template chain

# Class Template `chain`

Description
Headers
Reference

## Description

Chains are used by filtering streams and stream buffers to manage their underlying sequence of Filters and Devices. A chain represents a sequence of zero or more Filters with an optional Device at the end. If a chain contains a Device, it is considered complete and can be used to perform i/o. When a chain is used for output, data passes through the first filter in the chain, then through the second filter, and so on, and eventually reaches the Device at the end of the chain. When a chain is used for input, data travels in the opposite direction, beginning at the Device at the end of the chain, then passing through the filters in reverse order. By default, if the Device at the end of a chain is popped or if a chain is complete when it is destroyed, all the filters and devices in the chain are closed using the function `close`. This behavior can be modified using the member function `set_auto_close`.

The class template `chain` is parameterized by a mode. All the Filters and Devices which constitute a chain must have modes which refine the mode of the chain. For example, the class `chain<input>` has mode input. All Filters pushed onto such a chain must at least be InputFilters. Any Device pushed onto such a chain must at least be a Source.

Chains are CopyConstructible and Assignable. A copy of a chain represents the same sequence of Filters and Devices as the original chain; the components are not copied.

## Headers

`<boost/iostreams/chain.hpp>`

## Reference

#### Synopsis

    namespace boost { namespace iostreams {

    template< typename Mode,
              typename Ch    = char,
              typename Tr    = std::char_traits<Ch>,
              typename Alloc = std::allocator<Ch> >
    class chain;

    template< typename Mode,
              typename Ch    = wchar_t,
              typename Tr    = std::char_traits<Ch>,
              typename Alloc = std::allocator<Ch> >
    class wchain;

    template< typename Mode,
              typename Ch    = char,
              typename Tr    = std::char_traits<Ch>,
              typename Alloc = std::allocator<Ch> >
    class chain : public implementation-defined stream type {
    public:
        typedef Ch                      char_type;
        typedef Tr                      traits_type;
        typedef Mode                    mode;
        typedef Alloc                   allocator_type;
        typedef implementation-defined  size_type;

        chain();
        chain(const chain&);

        std::streamsize read(char_type* s, std::streamsize n);
        std::streamsize write(const char_type* s, std::streamsize n);
        stream_offset seek(stream_offset off, std::ios_base::seekdir way);

        const std::type_info& component_type(int n) const;

        template<typename T>
        T* component(int n) const;

        template<typename T>
        void push( const T& t,
                   std::streamsize buffer_size = default value,
                   std::streamsize pback_size = default value );

        template<typename StreamOrStreambuf>
        void push( StreamOrStreambuf& t,
                   std::streamsize buffer_size = default value,
                   std::streamsize pback_size = default value );

        void pop();
        bool empty() const;
        size_type size() const;
        void reset();
        bool is_complete() const;
        bool auto_close() const;
        void set_auto_close(bool close);
        bool sync();
        bool strict_sync();

            // Deprecated members

        template<int N>
        const std::type_info& component_type() const;

        template<int N, typename T>
        T* component() const;
    };

    } } // End namespace boost::io

## Class Template `chain`

#### Template parameters

Mode | - | A mode tag.
Ch | - | The character type
Tr | - | The traits type
Alloc | - | A standard library allocator type ([ISO], 20.1.5), used to allocate character buffers

#### `chain::chain`

        chain();

Constructs a `chain` with an empty chain of Filters and Devices.

#### `chain::chain`

        chain(const chain& rhs);

Constructs a `chain` representing the same sequence of Filters and Devices as the given chain.

#### `chain::read`

        std::streamsize read(char_type* s, std::streamsize n);

Invokes `read` on the first filter or device in this chain, which must be non-empty.

#### `chain::write`

        std::streamsize write(const char_type* s, std::streamsize n);

Invokes `write` on the first filter or device in this chain, which must be non-empty.

#### `chain::seek`

        stream_offset seek(stream_offset off, std::ios_base::seekdir way);

Invokes `seek` on the first filter or device in this chain, which must be non-empty.

#### `chain::component_type`

        const std::type_info& component_type(int n) const;

Returns a reference to an instance `std::type_info` corresponding to the type of the `n`th Filter or Device in this chain, which must have size at least `n + 1`. Components are numbered beginning at zero.

        // Deprecated
        template<int N>
        const std::type_info& component_type() const;

Returns a reference to an instance `std::type_info` corresponding to the type of the `N`th Filter or Device in this chain, which must have size at least `N + 1`. Components are numbered beginning at zero. The template argument `N` cannot be deduced, and must therefore be explicitly specified.

This member is deprecated; use the overload of `component_type` that takes an `int` argument instead.

#### `chain::component`

        template<typename T>
        T* component(int n) const;

Returns a pointer to the `n`th Filter or Device in this chain, if this chain has size at least `n + 1` and the type of the `n`th Filter or Device is equal to `T`. Otherwise, returns a null pointer. The template argument `T` cannot be deduced, and must therefore be explicitly specified.

Users of Microsoft Visual Studio versions 6.0-7.0 must use the macro `BOOST_IOSTREAMS_COMPONENT` instead of this function.

        // Deprecated
        template<int N, typename T>
        T* component() const;

Returns a pointer to the `N`th Filter or Device in this chain, if this chain has size at least `N + 1` and the type of the `N`th Filter or Device is equal to `T`. Otherwise, returns a null pointer. The template arguments `N` and `T` cannot be deduced, and must therefore be explicitly specified.

This member is deprecated; use the overload of `component` that takes an `int` argument instead.

#### `chain::push`

        template<typename T>
        void push( const T& t,
                   std::streamsize buffer_size,
                   std::streamsize pback_size );

Appends a copy of `t` to this chain, which must not be complete. The parameters have the following interpretations:

T | - | A CopyConstructible model of one of the Filter or Device concepts whose character type is `Ch` and whose mode refines `Mode`
t | - | An instance of T
buffer_size | - | The size of any buffers that need to be allocated
pback_size | - | The size of the putback buffer, relevant only if `Mode` is a refinement of `input`

An instance of a Filter or Device type `T` which is not CopyConstructible may be appended to the chain in one of two ways:

- by using a reference wrapper, or
- if `T` is a standard stream or stream buffer type, by using the templated overload of `push` taking a non-`const` reference.

If T is a Device, this chain will become complete upon the return of this function, and can then be used to perform i/o.

        template<typename StreamOrStreambuffer>
        void push( StreamOrStreambuffer& t,
                   std::streamsize buffer_size,
                   std::streamsize pback_size );

Appends the given stream or stream buffer to this chain, which must not be complete. The parameters have the following interpretations:

StreamOrStreambuffer | - | A standard stream or stream buffer type whose character type is `Ch` and whose mode refines `Mode`
buffer_size | - | The size of any buffers that need to be allocated
pback_size | - | The size of the putback buffer, relevant only if `Mode` is a refinement of `input`

This chain will become complete upon the return of this function, and can then be used to perform i/o.

#### `chain::pop`

        void pop();

Removes the final Filter or Device from this chain, which must be non-empty. If this chain is complete, `pop` causes each Filter and Device in the chain to be closed using the function `close`, unless the auto-close feature has been disabled using `set_auto_clos`.

#### `chain::empty`

        bool empty() const;

Returns `true` if this chain contains no Filters or Devices.

#### `chain::size`

        size_type size() const;

Returns the number of Filters and Devices in this chain.

#### `chain::reset`

        void reset();

Clears this chain. If this chain is complete, `reset` causes each Filter and Device in the chain to be closed using the function `close`, regardless of whether the auto-close feature has been disabled using `set_auto_close`.

#### `chain::is_complete`

        bool is_complete() const;

Returns `true` if this chain contains a Device. A chain is complete if and only if it is capable of performing i/o.

#### `chain::auto_close`

        bool auto_close() const;

Indicates whether the Filters and Devices in this chain will be closed automatically if `pop` is invoked while the chain is complete. Returns `true` unless the auto-close feature has been disabled using `set_auto_close`.

#### `chain::set_auto_close`

        void set_auto_close(bool close);

Specifies whether the Filters and Devices in this chain will be closed automatically if `pop` is invoked while the chain is complete. Does not prevent the Filters and Devices in this chain from being closed automatically if the chain is complete at destruction.

#### `chain::sync`

        bool sync();

Invokes the function `flush` on each Filter and Device in this chain, which must be complete. Returns `true` unless at least one of these components is Flushable and `flush` returns `false` when invoked on that component. A return value of `true` indicates that no error occurred, but does not guarantee that all buffered data has been successfully forwarded.

#### `chain::strict_sync`

        bool strict_sync();

Identical to `sync` except for the return value, which is `false` unless each Filter in this chain is Flushable and `flush` returns `true` when invoked on each component. A return value of `true` guarantees that all buffered data has been successfully forwarded.

## Class Template `wchain`

    template< typename Mode,
              typename Ch    = wchar_t,
              typename Tr    = std::char_traits<Ch>,
              typename Alloc = std::allocator<Ch> >
    class wchain;

Identical to `chain`, except for the default character type.

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)