Frequently Asked Questions

Why is data I've written to a filtering_stream not reaching the Sink at the end of the chain?
How do I write to several ostreams at once?
How do I access a Filter or Device after I've added it to a chain or attached it to a stream or stream_buffer?
How do perform file positioning operations with large (64-bit) offsets?
How do I read from or write to an STL sequence?
How do I write a stream which can read or write multibyte character encodings?
Can I swap Filters or Devices in the middle of a sequence of i/o operations?
Why does my filter chain work with std::cout but not with another ostream?
Why do I get errors stating that operator| is ambiguous?
Why do I get errors when compiling the finite_state_filter examples?

Why is data I've written to a filtering_stream not reaching the Sink at the end of the chain?

You may need to flush the stream. Note, however, that there is no guarantee that all data written to a filtering_stream will be forwarded to the final Sink until the stream is closed, unless all the Filters in the underlying chain are Flushable.

It's also possible that a buggy Filter is modifying data in a way you don't expect, e.g., by silently discarding data.

How do I write to several ostreams at once?

Use a tee_filter or tee_device. See tee.

How do I access a Filter or Device after I've added it to a chain or attached it to a stream or stream_buffer?

If you're using a stream or stream_buffer, use operator* or operator->.

If you're using a filtering_stream, filtering_streambuf or chain, use the member function templates component_type and component. Alternatively, add your Filter or Device to the chain by reference, using a reference wrapper.

How do perform file positioning operations with large (64-bit) offsets?

If you're using a raw Device and your compiler supports a 64-bit integral type, you can pass a large offset directly to seek. To convert the return value of seek to an integral type, use position_to_offset.

If you're using a stream_buffer or filtering_streambuf, convert the offset to a std::streampos using offset_to_position, then pass it to pubseekpos. To convert the return value of seek to an integral type, use position_to_offset.

If you're using a stream or filtering_stream, convert the offset to a std::streampos using offset_to_position, then pass it to the overload of seekg or seekp which takes a single std::streampos argument. To convert the return value of seek to an integral type, use position_to_offset.

See Stream Offsets.

How do I read from or write to an STL sequence?

You can append to an STL sequence using a back_insert_device, or the function boost::iostreams::back_inserter. You can read from an STL sequence by adding an instance of boost::itertator_range to a filtering_stream or filtering_streambuf.

See Writing a container_source and Writing a container_sink.

How do I write a stream which can read or write multibyte character encodings?

Use a code_converter. See Code Conversion.

Can I swap Filters or Devices in the middle of a sequence of i/o operations?

If you're performing output, and if all the Filters in you chain are Flushable, then yes. First call strict_sync. If it returns true, you can safely call set_auto_close(false) and pop one or more components without closing the stream. This applies to instances of filtering_stream, filtering_streambuf and chain.

Why does my filter chain work with std::cout but not with another ostream?

The Iostreams library stores streams and stream buffers by reference; consequently, streams and stream buffers must outlive any filter chain to which they are added. This is not a problem for std::cout, since it is guaranteed to live until the end of the program.

Check to make sure that the ostream is not being destroyed before the filtering_stream. If both objects are constructed on the stack within the same block, make sure that the ostream is constructed first.

Why do I get errors stating that operator| is ambiguous?

During overload resolution for an expression involving operator|, your compiler could be considering an implicit conversion from an intergral type to a Pipable Filter. Make sure that all your Pipable Filters have explicit constructors. See Pipelines.

Why do I get errors when compiling the finite_state_filter examples?

The template finite_state_filter requires a highly standard-conforming compiler. See Portability and the Compiler Status Tables for details.