filtering_stream
Derived class of std::basic_istream
, std::basic_ostream
or std::basic_iostream
, used to perform filtering. Each filtering_stream
contains a chain of zero or more Filters with an optional Device at the end. If the chain contains a Device, the filtering_stream
is complete and can be used to perform i/o. When a filtering_stream
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 filtering_stream
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 the chain is popped or if the filtering_stream
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
.
filtering_stream
derives from std::basic_istream
, std::basic_ostream
or std::basic_iostream
, depending on its Mode
parameter.
<boost/iostreams/filtering_stream.hpp>
namespace boost { namespace iostreams { template< typename Mode, typename Ch = char, typename Tr = std::char_traits<Ch>, typename Alloc = std::allocator<Ch
>, typename Access = public_ > class filtering_stream; template< typename Mode, typename Ch = wchar_t, typename Tr = std::char_traits<Ch>, typename Alloc = std::allocator<Ch
>, typename Access = public_ > class filtering_wstream; typedef filtering_stream<input> filtering_istream; typedef filtering_stream<output> filtering_ostream; typedef filtering_wstream<input> filtering_wistream; typedef filtering_wstream<output> filtering_wostream; template< typename Mode, typename Ch = char, typename Tr = std::char_traits<Ch>, typename Alloc = std::allocator<Ch
>, typename Access = public_ > class filtering_stream : public implementation-defined stream type { public: typedef Ch char_type; typedef Mode mode; typedef Alloc allocator_type; typedef implementation-defined size_type; filtering_stream(); template<typename T> filtering_stream( const T& t, std::streamsize buffer_size = default value, std::streamsize pback_size = default value ); template<typename StreamOrStreambuf> filtering_stream( StreamOrStreambuf& t, std::streamsize buffer_size = default value, std::streamsize pback_size = default value ); 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
filtering_stream
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 |
Access | - | One of public_ or protected_ , indicating the level of access of the chain interface. Used to hide the chain interface when defining a derived class of filtering_stream |
filtering_stream::filtering_stream
filtering_stream();
Constructs a filtering_stream
with an empty chain of Filters and Devices.
filtering_stream::push
template<typename T> filtering_stream( const T& t, std::streamsize buffer_size, std::streamsize pback_size );
Constructs a filtering_stream
whose chain contains a copy of t
. 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 |
A filtering_stream
may be constructed from an instance of a Filter or Device type T
which is not CopyConstructible in one of two ways:
T
is a standard stream or stream buffer type, by using the constructor taking a non-const
reference.
If T is a Device, the filtering_stream
will become complete upon construction, and can then be used to perform i/o.
template<typename StreamOrStreambuffer> filering_stream( StreamOrStreambuffer& t, std::streamsize buffer_size, std::streamsize pback_size );
Constructs a filtering_stream
whose chain contains a reference to the given stream or stream buffer. 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 |
The filtering_stream
will become complete upon construction, and can then be used to perform i/o.
filtering_stream::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 the underlying 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 the underlying 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.
filtering_stream::component
template<typename T> T* component(int n) const;
Returns a pointer to the n
th Filter or Device in the underlying chain, if the 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 the underlying chain, if the 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.
filtering_stream::push
template<typename T> void push( const T& t, std::streamsize buffer_size, std::streamsize pback_size );
Appends a copy of t
to the underlying 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:
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 filtering_stream
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 the underlying 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 filtering_stream
will become complete upon the return of this function, and can then be used to perform i/o.
filtering_stream::pop
void pop();
Removes the final Filter or Device from the underlying chain, which must be non-empty. If the chain is initially complete, 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_close
filtering_stream::empty
bool empty() const;
Returns true
if the underlying chain is empty.
filtering_stream::size
size_type size() const;
Returns the number Filters and Devices in the underlying chain.
filtering_stream::reset
void reset();
Clears the underlying chain. If the chain is initially complete, causes each Filter and Device in the chain to be closed using the function close
.
filtering_stream::is_complete
bool is_complete() const;
Returns true
if the underlying chain ends in a Device.
filtering_stream::auto_close
bool auto_close() const;
Indicates whether the Filters and Devices in the underlying 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
.
filtering_stream::set_auto_close
void set_auto_close(bool close);
Specifies whether the Filters and Devices in the underlying chain will be closed automatically if pop
is invoked while the chain is complete. Does not prevent the Filters and Devices in the chain from being closed automatically if the chain is complete at destruction.
filtering_stream::sync
bool sync();
Invokes the function flush
on each Filter and Device in the underlying 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.
filtering_stream::strict_sync
bool strict_sync();
Identical to sync
except for the return value, which is false
unless each Filter in the underlying 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.
filtering_wstream
template< typename Mode,
typename Ch = wchar_t,
typename Tr = std::char_traits<Ch>,
typename Alloc = std::allocator<Ch
>,
typename Access = public_ >
class filtering_wstream;
Identical to filtering_stream
, except for the default character type.
© 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)