Generic Streams and Stream Buffers

Overview

Headers

Reference

Class template stream_buffer

Class template stream

Examples

The fundamental component provided by the Iostreams library is the class template stream_buffer, a derived class of std::basic_streambuf which performs i/o by delegating to a contained Device. Instances of the Device can be associated and disassociated with an instance of stream_buffer using member functions open and close. The interface is patterned after std::basic_filebuf and std::basic_fstream.

The class template stream is a stream template which derives from one of std::basic_istream, std::basic_ostream and std::basic_iostream depending on the mode of the first template parameter. As with stream_buffer, instances of the Device can by associated and disassociated with an instance of stream using its member functions open and close.

<boost/iostreams/stream_buffer.hpp>

<boost/iostreams/stream.hpp>

namespace boost { namespace iostreams {

template< typename T, 
          typename Tr = std::char_traits<...>, 
          typename Alloc = std::allocator<...>,
          typename Mode = ... >
class stream_buffer : 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.]

    stream_buffer();
    stream_buffer( const T& t,
                      std::streamsize buffer_size = default_value, 
                      std::streamsize pback_size = default_value );

        // Forwarding constructors

    template<typename U>
    stream_buffer(const U& u);

    template<typename U1, typename U2>
    stream_buffer(const U1& u1, const U2& u2);

        ...

    template<typename U1, ..., typename UN>
    stream_buffer(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

stream_buffer::stream_buffer

    stream_buffer();

Constructs a stream_buffer 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.

stream_buffer::stream_buffer

    stream_buffer( const T& t,
                      std::streamsize buffer_size, 
                      std::streamsize pback_size );

Constructs a stream_buffer 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>
    stream_buffer(const U& u);

    template<typename U1, typename U2>
    stream_buffer(const U1& u1, const U2& u2);

        ...

    template<typename U1, ..., typename UN>
    stream_buffer(const U1& u1, ..., const UN& uN);

Each of these members constructs an instance of stream_buffer 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.

stream_buffer::open

    void open( const T& t,
               std::streamsize buffer_size, 
               std::streamsize pback_size );

Assocaites the given instance of T with this instance of stream_buffer, 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 stream_buffer 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.

stream_buffer::is_open

    bool is_open() const;

Returns true if there is an instance of the policy type T associated with this instance of stream_buffer.

stream_buffer::close

    void close();

Disassociates from this instance of stream_buffer any instance of the policy type T currently associated with it, calling cleanup functions as appropriate and destroying the associated instance of T.

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.hpp>
         
    typedef stream<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.hpp>

    const char*                  h = "Hello World!";
    stream<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)