User's Guide

3.3 Generic Streams and Stream Buffers

Overview
Headers
Reference
Class template stream_buffer
Class template stream
Examples

Overview

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.

Headers

<boost/iostreams/stream_buffer.hpp>
<boost/iostreams/stream.hpp>

Reference

Class template stream_buffer

Description

Stream buffer template which performs i/o by delegating to a contained Device. The Device type is specified as the first template parameter to stream_buffer. Instances of the the Device type are attached and detached using the member functions open and close.

Synopsis

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 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 U2& u2 ..., 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 U2& u2, ..., const UN& uN);

    bool is_open() const;
    void close();

        // Device access
    
    T& operator*();
    T* operator->();
};

} } // namespace boost::io

Template parameters

T- A CopyConstructible model of one of the Device concepts.
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 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.

stream_buffer::stream_buffer

    stream_buffer();

Constructs a stream_buffer with no associated instance of the Device 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 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 

    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 U2& u2, ..., const UN& uN);

Each of these members constructs an instance of stream_buffer and associates it with an instance of the Device T constructed from the given lists of arguments. The T constructor must take all arguments other than the first 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 Device 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 constructor must take all arguments other than the first 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 Device T associated with this instance of stream_buffer.

stream_buffer::close

    void close();

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

stream_buffer::operator*

    T& operator*();

Returns a reference to the instance of T associated with this stream_buffer, which must be open.

stream_buffer::operator->

    T* operator->();

Returns a pointer to the instance of T associated with this stream_buffer, which must be open.

Class template stream

Description

Stream template which performs i/o by delegating to a contained Device. The Device type is specified as the first template parameter to stream. Instances of the the Device type are attached and detached using the member functions open and close.

The template stream derives from a specialization of std::basic_istream, std::basic_ostream or std::basic_iostream, depending on whether the underlying Device models Source, Sink or both..

Synopsis

namespace boost { namespace iostreams {

template< typename T, 
          typename Tr = std::char_traits<...>, 
          typename Alloc = std::allocator<...>,
          typename Mode = ... >
class stream : public [see Description] {
public:
    typedef typename char_type_of<T>::type  char_type;
    typedef typename Tr                     traits_type;

    [Standard stream buffer typedefs: int_type, off_type, etc.]

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

        // Forwarding constructors

    template<typename U>
    stream([const] U& u);

    template<typename U1, typename U2>
    stream([const] U1& u1, const U2& u2);

        ...

    template<typename U1, ..., typename UN>
    stream([const] U1& u1, const U2& u2, ..., 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 U2& u2, ..., const UN& uN);

    bool is_open() const;
    void close();

        // Device access
    
    T& operator*();
    T* operator->();
};

} } // namespace boost::io

Template parameters

T- A CopyConstructible model of one of the Device concepts.
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 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.

stream::stream

    stream();

Constructs a stream with no associated instance of the Device T. Before the instance can be used for i/o, one of its open() overloads must be invoked.

stream::stream

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

Constructs a stream which is ready to perform i/o, where the parameters have the following interpretations:
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 

    template<typename U>
    stream([const] U& u);

    template<typename U1, typename U2>
    stream([const] U1& u1, const U2& u2);

        ...

    template<typename U1, ..., typename UN>
    stream([const] U1& u1, const U2& u2, ..., const UN& uN);

Each of these members constructs an instance of stream and associates it with an instance of the Device 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::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, 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 U2& u2, ..., const UN& uN);

Each of these members associates with this instance of stream a newly constructed instance of the Device 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::is_open

    bool is_open() const;

Returns true if there is an instance of the Device T associated with this instance of stream.

stream::close

    void close();

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

stream::operator*

    T& operator*();

Returns a reference to the instance of T associated with this stream, which must be open.

stream::operator->

    T* operator->();

Returns a pointer to the instance of T associated with this stream, which must be open.

Examples

Defining a simple ofstream

The following example uses a file_sink 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 02 Feb 2008

© 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)