Tutorial

2.1.2. Writing a `container_source`

Suppose you want to write a Device for reading characters from an STL container. A Device which only supports reading is called a Source. A typical narrow-character Source looks like this:

#include <iosfwd>                          // streamsize
#include <boost/iostreams/categories.hpp>  // source_tag

namespace io = boost::iostreams;

class my_source {
public:
    typedef char        char_type;
    typedef source_tag  category;

    std::streamsize read(char* s, std::streamsize n)
    {
        // Read up to n characters from the underlying data source
        // into the buffer s, returning the number of characters
        // read; return -1 to indicate EOF
    }

    /* Other members */
};

Here the member type char_type indicates the type of characters handled by my_source, which will almost always be char or wchar_t. The member type category indicates which of the fundamental i/o operations are supported by the device. The category tag source_tag indicates that only read is supported.

The member function read reads up to n characters into the buffer s and returns the number of characters read, unless that number is 0 and end-of-stream has been reached, in which case the special value -1 is returned. In general, a Source's member function read may return fewer characters than requested even though end-of-stream has not been reached; such Sources are called non-blocking. Non-blocking Devices do not interact well with standard streams and stream buffers, however, so most devices should be Blocking. See Asynchronous and Non-Blocking I/O.

You could also write the above example as follows:

#include <boost/iostreams/concepts.hpp>  // source

class my_source : public source {
public:
    std::streamsize read(char* s, std::streamsize n);

    /* Other members */
};

Here source is a convenience base class which provides the member types char_type and category, as well as no-op implementations of member functions close and imbue, not needed here.

You're now ready to write your container_source. For simplicity, let's assume that your container's iterators are RandomAccessIterators.

#include <algorithm>                       // copy, min
#include <iosfwd>                          // streamsize
#include <boost/iostreams/categories.hpp>  // source_tag

namespace boost { namespace iostreams { namespace example {

template<typename Container>
class container_source {
public:
    typedef typename Container::value_type  char_type;
    typedef source_tag                      category;
    container_source(Container& container)
        : container_(container), pos_(0)
        { }
    std::streamsize read(char_type* s, std::streamsize n)
    {
        using namespace std;
        streamsize amt = static_cast<streamsize>(container_.size() - pos_);
        streamsize result = (min)(n, amt);
        if (result != 0) {
            std::copy( container_.begin() + pos_, 
                       container_.begin() + pos_ + result, 
                       s );
            pos_ += result;
            return result;
        } else {
            return -1; // EOF
        }
    }
    Container& container() { return container_; }
private:
    typedef typename Container::size_type   size_type;
    Container&  container_;
    size_type   pos_;
};

} } } // End namespace boost::iostreams:example

Here, note that

The member type char_type is defined to be equal to the containers's value_type;
The member type category tells the Iostreams library that container_source is a model of Source; and
A container_source can be constructed from a instance of Container, which is passed and stored by reference, and accessible via the member function container().

The main idea behind the implementation of read() is simple: First, you calculate the number of characters to be read, which is the minimum of the number of unread characters remaining in the container and the number of characters requested. Second, if the number of characters to be read is non-zero, you copy that number of characters from the container into the provided buffer and update the current read position. If the number of characters is zero, i.e., if all the characters in the container have already been consumed by previous calls to read (or if the container was empty to begin with), you return -1 to indicate end-of-stream.

You can read from a container_source as follows

#include <cassert>
#include <string>
#include <boost/iostreams/stream.hpp>
#include <libs/iostreams/example/container_device.hpp> // container_source

namespace io = boost::iostreams;
namespace ex = boost::iostreams::example;

int main()
{
    using namespace std;
    typedef ex::container_source<string> string_source;

    string                     input = "Hello World!";
    string                     output;
    io::stream<string_source>  in(input);
    getline(in, output);
    assert(input == output);
}

Finally, I should mention that the Iostreams library provides an easier way to read from an STL container: instances of boost::iterator_range can be added directly to filtering streams and stream buffers. So you could write:

#include <cassert>
#include <string>
#include <boost/iostreams/filtering_stream.hpp>
#include <boost/range/iterator_range.hpp>

namespace io = boost::iostreams;

int main()
{
    using namespace std;

    string                 input = "Hello World!";
    string                 output;
    io::filtering_istream  in(boost::make_iterator_range(input));
    getline(in, output);
    assert(input == output);
}

Use, modification, and distribution are subject to the Boost Software License, Version 2.0. (See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)

Tutorial

2.1.2. Writing a container_source

2.1.2. Writing a `container_source`