streambuf_facade
stream_facade
The fundamental component provided by the Iostreams library is the class template streambuf_facade
, a derived class of std::basic_streambuf
which performs i/o by delegating to a contained instance of a policy class. The policy class must model one of the various Filter or Device concepts. Instances of the policy class can be associated and disassociated with an instance of streambuf_facade
using member functions open
and close
. The interface is patterned after std::basic_filebuf
and std::basic_fstream
.
The class template stream_facade
is a policy-based stream template which derives from one of std::basic_istream
, std::basic_ostream
and std::basic_iostream
depending on the mode of the policy class. As with streambuf_facade
, instances of the policy class can by associated and disassociated with an instance of stream_facade
using its member functions open
and close
.
<boost/iostreams/streambuf_facade.hpp>
<boost/iostreams/stream_facade.hpp>
streambuf_facade
Policy-based stream buffer template with an interface similar to std::basic_filebuf
.
namespace boost { namespace iostreams { template< typename T, typename Tr = std::char_traits<...>, typename Alloc = std::allocator<...>, typename Mode = ... > class streambuf_facade : public std::basic_streambuf<...> { public: typedef T policy_type; typedef typename char_type_of<T>::type char_type; typedef typename Tr traits_type; [Standard stream buffer typedefs: int_type, off_type, etc.] streambuf_facade(); streambuf_facade( const T& t, std::streamsize buffer_size = default_value, std::streamsize pback_size = default_value ); // Forwarding constructors template<typename U> streambuf_facade(const U& u); template<typename U1, typename U2> streambuf_facade(const U1& u1, const U2& u2); ... template<typename U1, ..., typename UN> streambuf_facade(const U1& u1, ..., const UN& uN); void open( const T& t, std::streamsize buffer_size = default_value, std::streamsize pback_size = default_value ); // Forwarding overloads of open() template<typename U> void open(const U& u); template<typename U1, typename U2> void open(const U1& u1, const U2& u2); ... template<typename U1, ..., typename UN> void open(const U1& u1, ..., const UN& uN); bool is_open() const; void close(); }; } } // namespace boost::io
T | - | A model of one of the Filter or Device concepts. Specializations of streambuf_facade with Filter types are used internally by the Iostreams library to construct chains of Filters and Devices. Users of the library never need to specialize streambuf_facade with a Filter type. |
Tr | - | A C++ standard library charatcer traits type ([ISO], 21.1.1) with char_type equal to the character type Ch of T. Defaults to std::char_traits<Ch> . |
Alloc | - | A C++ standard library allocator type ([ISO], 20.1.5), used to allocate any required character buffers. Defaults to std::allocator<Ch> , where Ch is the character type of T. |
Mode | - | A mode tag convertible to the mode_of of T. This parameter is principally for internal use. Specifying a mode tag properly refined by the mode of T can prevent an unneeded buffer from being allocated in some cases. Defaults to the mode of T. |
streambuf_facade::streambuf_facade
streambuf_facade();
Constructs a streambuf_facade
with no associated instance of the policy type T
. Before the instance can be used for i/o, one of its open()
overloads must be invoked.
streambuf_facade::streambuf_facade
streambuf_facade( const T& t,
std::streamsize buffer_size,
std::streamsize pback_size );
Constructs a streambuf_facade
which is ready to perform i/o, where the parameters have the following interpretations:
t | - | An instance of the policy type |
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 |
template<typename U> streambuf_facade(const U& u); template<typename U1, typename U2> streambuf_facade(const U1& u1, const U2& u2); ... template<typename U1, ..., typename UN> streambuf_facade(const U1& u1, ..., const UN& uN);
Each of these members constructs an instance of streambuf_facade
and associates it with an instance of the policy type T
constructed from the given lists of arguments. The T
constructors involved must take all arguments by value or const
reference.
It is not possible to specify a custom buffer size or putback buffer size using these constructors.
streambuf_facade::open
void open( const T& t,
std::streamsize buffer_size,
std::streamsize pback_size );
Assocaites the given instance of T
with this
instance of streambuf_facade
, if there is no such instance currently associated; otherwise, throws std::ios_base::failure
. The second parameter determines the size of any buffers that need to be allocated; a value of zero indicates that i/o should be unbuffered. The third parameter determines the size of the putback buffer; it is relevant only if Mode
is a refinement of input
.
template<typename U> void open(const U& u); template<typename U1, typename U2> void open(const U1& u1, const U2& u2); ... template<typename U1, ..., typename UN> void open(const U1& u1, ..., const UN& uN);
Each of these members associates with this
instance of streambuf_facade
a newly constructed instance of the policy type T
constructed from the given lists of arguments, if there is no such instance currently associated; otherwise, they throw std::ios_base::failure
. The T
constructors involved must take all arguments by value or const
reference.
It is not possible to specify a custom buffer size or putback buffer size using these members.
streambuf_facade::is_open
bool is_open() const;
Returns true if there is an instance of the policy type T
associated with this
instance of streambuf_facade
.
streambuf_facade::close
void close();
Disassociates from this
instance of streambuf_facade
any instance of the policy type T
currently associated with it, calling cleanup functions as appropriate and destroying the associated instance of T
.
stream_facade
[Copy streambuf_facade
after all errors are corrected]
ofstream
The following example uses a File-Based Device to define a class similar to a std::ofstream
.
#include <boost/iostreams/device/file.hpp> #include <boost/iostreams/stream_facade.hpp> typedef stream_facade<file_sink> ofstream; ofstream out("HeavyArtillery.txt"); // Wilfred Owen out << "Reach at that Arrogance which needs thy harm,\n" "And beat it down before its sins grow worse.\n"; out.close();
The following example uses an array_source
to construct an input stream from a C-style string.
#include <cstring> #include <iostream> #include <string> #include <boost/iostreams/device/array.hpp> #include <boost/iostreams/stream_facade.hpp> const char* h = "Hello World!"; stream_facade<array_source> in(h, std::strlen(h)); std::string hello; std::getline(in, hello); std::cout << hello << "\n"; // Prints "Hello World!"
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)