Class Template `chain`

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

namespaceboost {namespaceiostreams {template<typename[Mode](#template_params),typename[Ch](#template_params)=char,typename[Tr](#template_params)= std::char_traits<Ch>,typename[Alloc](#template_params)= std::allocator<Ch> >class[chain](#chain);template<typename[Mode](#template_params),typename[Ch](#template_params)=wchar\_t,typename[Tr](#template_params)= std::char_traits<Ch>,typename[Alloc](#template_params)= std::allocator<Ch> >class[wchain](#wchain);template<typename[Mode](#template_params),typename[Ch](#template_params)=char,typename[Tr](#template_params)= std::char_traits<Ch>,typename[Alloc](#template_params)= std::allocator<Ch> >class[chain](chain.html):publicimplementation-defined stream type{public:typedefCh char_type;typedefTr traits_type;typedefMode mode;typedefAlloc allocator_type;typedefimplementation-definedsize_type;[chain](#default_constructor)();[chain](#copy_constructor)(constchain&);

    std::streamsize[read](#read)(char_type* s, std::streamsize n);
    std::streamsize[write](#write)(constchar_type* s, std::streamsize n);[stream\_offset](../functions/positioning.html#synopsis)[seek](#seek)([stream\_offset](../functions/positioning.html#synopsis)off, std::ios_base::seekdir way);conststd::type_info&[component\_type](#component_type)(intn)const;template<typenameT>
    T*[component](#component)(intn)const;template<typenameT>void[push](#policy_push)(constT& t,
               std::streamsize buffer_size =default value,
               std::streamsize pback_size =default value);template<typenameStreamOrStreambuf>void[push](#stream_push)( StreamOrStreambuf& t,
               std::streamsize buffer_size =default value,
               std::streamsize pback_size =default value);void[pop](#pop)();bool[empty](#empty)()const;
    size_type[size](#size)()const;void[reset](#reset)();bool[is\_complete](#is_complete)()const;bool[auto\_close](#auto_close)()const;void[set\_auto\_close](#set_auto_close)(boolclose);bool[sync](#sync)();bool[strict\_sync](#strict_sync)();// Deprecated memberstemplate<intN>conststd::type_info&[component\_type](#component_type)()const;template<intN,typenameT>
    T*[component](#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(constchain& 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(constchar_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](../functions/positioning.html#synopsis)seek([stream\_offset](../functions/positioning.html#synopsis)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`

conststd::type_info& component_type(intn)const;

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

// Deprecatedtemplate<intN>conststd::type_info& component_type()const;

Returns a reference to an instance std::type_info corresponding to the type of the Nth 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<typenameT>
    T* component(intn)const;

Returns a pointer to the nth Filter or Device in this chain, if this chain has size at least n + 1 and the type of the nth 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.

// Deprecatedtemplate<intN,typenameT>
    T* component()const;

Returns a pointer to the Nth Filter or Device in this chain, if this chain has size at least N + 1 and the type of the Nth 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<typenameT>
    void push(constT& 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<typenameStreamOrStreambuffer>
    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:

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

`chain::pop`

voidpop();

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`

boolempty()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`

voidreset();

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`

boolis_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`

boolauto_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`

voidset_auto_close(boolclose);

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`

boolsync();

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`

boolstrict_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<typenameMode,typenameCh =wchar\_t,typenameTr = std::char_traits<Ch>,typenameAlloc = std::allocator<Ch> >classwchain;

Identical to chain, except for the default character type.

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)

Class Template chain

Class Template chain

Description

Headers

Reference

Synopsis

Class Template chain

Template parameters

chain::chain

chain::chain

chain::read

chain::write

chain::seek

chain::component_type

chain::component

chain::push

chain::pop

chain::empty

chain::size

chain::reset

chain::is_complete

chain::auto_close

chain::set_auto_close

chain::sync

chain::strict_sync

Class Template wchain

Class Template `chain`

Class Template `chain`

`chain::chain`

`chain::chain`

`chain::read`

`chain::write`

`chain::seek`

`chain::component_type`

`chain::component`

`chain::push`

`chain::pop`

`chain::empty`

`chain::size`

`chain::reset`

`chain::is_complete`

`chain::auto_close`

`chain::set_auto_close`

`chain::sync`

`chain::strict_sync`

Class Template `wchain`