# 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 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` 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` 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 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_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 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` 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 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)