boost IOStreams

Boost.IOStreams provides numerous implementations of the two concepts. Devices which describes data sources and sinks, and stream which describes an interface for formatted input/output based on the interface from the standard library.

Devices

Devices are classes that provide read and write access to objects that are usually outside of a process.

1. using an array as a device with boost::iostreams::array_sink, boost::iostreams::array_source.

#include <boost/iostreams/device/array.hpp>
#include <boost/iostreams/stream.hpp>
#include <string>
#include <iostream>

using namespace boost::iostreams;

int main()
{
  char buffer[];
  array_sink sink{buffer};
  stream<array_sink> os{sink};
  os << "Boost" << std::endl;

  array_source source{buffer};
  stream<array_source> is{source};
  std::string s;
  is >> s;
  std::cout << s << std::endl;
}

Above example uses the device boost::iostreams::array_sink to write data to an array. The array is passed as a parameter to the constructor. Afterwards, the device is connected with a stream of type boost::iostreams::stream. A reference to the device is passed to the constructor of boost::iostreams::stream, and the type of the device is passed as a template parameter to boost::iostreams::stream.

uses the operator<< to write "Boost" to the stream. The stream forwards the data to the device. Because the device is connected to the array, "Boost" is stored in the first five elements of the array.

boost::iostreams::array_source is used like boost::iostreams::array_link. While boost::iostreams::array_sink supports only write operations, boost::iostreams::array_source supports only read. boost::iostreams::array supports both write and read operations.

Please note that boost::iostreams::array_source and boost::iostreams::array_sink receive a reference to an array. The array must not be destroyed while the devices are still in use.

2. using a vector as device with boost::iostreams::back_insert_device

#include <boost/iostreams/device/array.hpp>
#include <boost/iostreams/device/back_inserter.hpp>
#include <boost/iostreams/stream.hpp>
#include <vector>
#include <string>
#include <iostream>

using namespace boost::iostreams;

int main()
{
  std::vector<char> v;
  back_insert_device<std::vector<char>> sink{v};
  stream<back_insert_device<std::vector<char>>> os{sink};
  os << "Boost" << std::endl;

  array_source source{v.data(), v.size()};
  stream<array_source> is{source};
  std::string s;
  is >> s;
  std::cout << s << std::endl;
  return 0;
}

boost::iostreams::back_insert_device can be used to write data to any container that provides the member function insert(). The device calls this member function to forward data to the container. The example above uses boost::iostreams::back_insert_device to write "Boost" to a vector. Afterwards, "Boost" is read from boost::iostreams::array_source.

3. using a file as a device with boost::iostreams::file_source

#include <boost/iostreams/device/file.hpp>
#include <boost/iostreams/stream.hpp>
#include <iostream>

using namespace boost::iostreams;

int main()
{
  file_source f{"main.cpp"};
  if (f.is_open())
  {
    stream<file_source> is{f};
    std::cout << is.rdbuf() << std::endl;
    f.close();
  }
  return ;
}

boost::iostreams::file_source provides is_open() to test whether a file was opened successfully. It also provides the member function close() to explicitly close a file.

Filters

Boost.IOStreams also provides filters, which operate in front of devices to filter data read from or written to devices.

1. using boost::iostreams::regex_filter

#include <boost/iostreams/device/array.hpp>
#include <boost/iostreams/filtering_stream.hpp>
#include <boost/iostreams/filter/regex.hpp>
#include <boost/regex.hpp>
#include <iostream>

using namespace boost::iostreams;

int main()
{
  char buffer[];
  array_sink sink{buffer};
  filtering_ostream os;
  os.push(regex_filter{boost::regex{"Bo+st"}, "C++"});
  os.push(sink);
  os << "Boost" << std::flush;
  os.pop();
  std::cout.write(buffer, );
  return ;
}

The data is sent through a filter of type boost::iostreams::regex_filter, which replaces characters. The filter expects a regular expression and a format string. The format string specifies what the characters should be replaced with.

The filter and the device are connected with the stream boost::iostreams::filtering_ostream. This class provides a member function push(), which the filter and the device are passed to. The filter(s) must be passed before the device; the order is important. You can pass one or more filters, but once a device has been passed, the stream is complete, and you must not call push() again.

The filter boost::iostreams::regex_filter can’t process data character by character because regular expressions need to look at character groups. That’s why boost::iostreams::regex_filter starts filtering only after a write operation is complete and all data is available. This happens when the device is removed from the stream with the member function pop(). Example above calls pop() after “Boost” has been written to the stream. Without the call to pop(), boost::iostreams::regex_filter won’t process any data and won’t forward data to the device.

2. accessing filters in boost::iostreams::filtering_ostream

#include <boost/iostreams/device/array.hpp>
#include <boost/iostreams/filtering_stream.hpp>
#include <boost/iostreams/filter/counter.hpp>
#include <iostream>

using namespace boost::iostreams;

int main()
{
  char buffer[];
  array_sink sink{buffer};
  filtering_ostream os;
  os.push(counter{});
  os.push(sink);
  os << "Boost" << std::flush;
  os.pop();
  counter *c = os.component<counter>();
  std::cout << c->characters() << std::endl;
  std::cout << c->lines() << std::endl;
  return ;
}

The filter boost::iostreams::counter counts characters and lines. This class provides the member function characters() and lines().

boost::iostreams::filtering_stream provides the member function component() to access a filter. Because component() is a template, the type of the filter must be passed as a template parameter. component() returns a pointer to the filter.

3. writing and reading data compressed with ZLIB

#include <boost/iostreams/device/array.hpp>
#include <boost/iostreams/device/back_inserter.hpp>
#include <boost/iostreams/filtering_stream.hpp>
#include <boost/iostreams/filter/zlib.hpp>
#include <vector>
#include <string>
#include <iostream>

using namespace boost::iostreams;

int main()
{
  std::vector<char> v;
  back_insert_device<std::vector<char>> snk{v};
  filtering_ostream os;
  os.push(zlib_compressor{});
  os.push(snk);
  os << "Boost" << std::flush;
  os.pop();

  array_source src{v.data(), v.size()};
  filtering_istream is;
  is.push(zlib_decompressor{});
  is.push(src);
  std::string s;
  is >> s;
  std::cout << s << std::endl;
  return ;
}

Example above uses the stream boost::iostreams::filtering_istream in addition to boost::iostreams::filtering_ostream. This stream is used when you want to read data with filters. In the example, compressed data is written and read again.

Boost.IOStreams provides several data compression filters. The class boost::iostreams::zlib_compressor compresses data in the ZLIB format. To uncompress data in the ZLIB format, use the class boost::iostreams::zlib_decompressor. These filters are added to the streams using push().