Policy-Based Streams and Stream Buffers

Overview
Headers
Reference
Class template streambuf_facade
Class template stream_facade
Examples

Overview

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.

Headers

<boost/iostreams/streambuf_facade.hpp>
<boost/iostreams/stream_facade.hpp>

Reference

Class template streambuf_facade

Description

Policy-based stream buffer template with an interface similar to std::basic_filebuf.

Synopsis

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

Template parameters

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.

Class template stream_facade

[Copy streambuf_facade after all errors are corrected]

Examples

Defining a simple 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();

Reading from an array

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!"