1 <!DOCTYPE HTML PUBLIC
"-//W3C//DTD HTML 4.01 Transitional//EN">
4 <TITLE>Frequently Asked Questions
</TITLE>
5 <LINK REL=
"stylesheet" HREF=
"../../../boost.css">
6 <LINK REL=
"stylesheet" HREF=
"theme/iostreams.css">
12 <H1 CLASS=
"title">Frequently Asked Questions
</H1>
17 <DL class=
"page-index" style=
"margin-top:1em">
18 <DT><A href=
"#flush">Why is data I've written to a
<CODE>filtering_stream
</CODE> not reaching the Sink at the end of the chain?
</A></DT>
19 <DT><A href=
"#tee">How do I write to several ostreams at once?
</A></DT>
20 <DT><A href=
"#component_access">How do I access a Filter or Device after I've added it to a chain or attached it to a
<CODE>stream
</CODE> or
<CODE>stream_buffer?
</CODE></A></DT>
21 <DT><A href=
"#offsets">How do perform file positioning operations with large (
64-bit) offsets?
</A></DT>
22 <DT><A href=
"#stl">How do I read from or write to an STL sequence?
</A></DT>
23 <DT><A href=
"#multibyte">How do I write a stream which can read or write multibyte character encodings?
</A></DT>
24 <DT><A href=
"#auto_close">Can I swap Filters or Devices in the middle of a sequence of i/o operations?
</CODE></A></DT>
25 <DT><A href=
"#lifetime">Why does my filter chain work with
<CODE>std::cout
</CODE> but not with another
<CODE>ostream
</CODE>?
</A></DT>
26 <DT><A href=
"#pipe">Why do I get errors stating that
<CODE>operator|
</CODE> is ambiguous?
</A></DT>
27 <DT><A href=
"#finite_state">Why do I get errors when compiling the
<CODE>finite_state_filter
</CODE> examples?
</A></DT>
30 <HR style=
"margin-top:1em">
33 <H4>Why is data I've written to a
<CODE>filtering_stream
</CODE> not reaching the Sink at the end of the chain?
</H4>
36 You may need to flush the stream. Note, however, that there is no guarantee that all data written to a
<A HREF=
"classes/filtering_stream.html"><CODE>filtering_stream
</CODE></A> will be forwarded to the final Sink until the stream is closed, unless all the Filters in the underlying
<A HREF=
"classes/chain.html"><CODE>chain
</CODE></A> are
<A HREF=
"concepts/flushable.html">Flushable
</A>.
39 It's also possible that a buggy Filter is modifying data in a way you don't expect,
<I>e.g.
</I>, by silently discarding data.
43 <H4>How do I write to several ostreams at once?
</H4>
46 Use a
<A HREF=
"functions/tee.html#tee_filter"><CODE>tee_filter
</CODE></A> or
<A HREF=
"functions/tee.html#tee_device"><CODE>tee_device
</CODE></A>.
<I>See
</I> <A HREF=
"functions/tee.html"><CODE>tee
</CODE></A>.
49 <A NAME=
"component_access"></A>
50 <H4>How do I access a Filter or Device after I've added it to a chain or attached it to a
<CODE>stream
</CODE> or
<CODE>stream_buffer?
</CODE></H4>
53 If you're using a
<A HREF=
"guide/generic_streams.html#stream"><CODE>stream
</CODE></A> or
<A HREF=
"guide/generic_streams.html#stream_buffer"><CODE>stream_buffer
</CODE></A>, use
<CODE>operator*
</CODE> or
<CODE>operator-
></CODE>.
57 If you're using a
<A HREF=
"classes/filtering_stream.html"><CODE>filtering_stream
</CODE></A>,
<A HREF=
"classes/filtering_streambuf.html"><CODE>filtering_streambuf
</CODE></A> or
<A HREF=
"classes/chain.html"><CODE>chain
</CODE></A>, use the member function templates
<A HREF=
"classes/chain.html#component_type"><CODE>component_type
</CODE></A> and
<A HREF=
"classes/chain.html#component"><CODE>component
</CODE></A>. Alternatively, add your Filter or Device to the chain by reference, using a
<A HREF=
"../../../doc/html/ref.html" TARGET=
"_top">reference wrapper
</A>.
60 <A NAME=
"offsets"></A>
61 <H4>How do perform file positioning operations with large (
64-bit) offsets?
</H4>
64 If you're using a raw Device and your compiler supports a
64-bit integral type, you can pass a large offset directly to
<CODE>seek
</CODE>. To convert the return value of seek to an integral type, use
<A HREF=
"functions/positioning.html#position_to_offset"><CODE>position_to_offset
</CODE></A>.
68 If you're using a
<A HREF=
"guide/generic_streams.html#stream_buffer"><CODE>stream_buffer
</CODE></A> or
<A HREF=
"classes/filtering_streambuf.html"><CODE>filtering_streambuf
</CODE></A>, convert the offset to a
<CODE>std::streampos
</CODE> using
<A HREF=
"functions/positioning.html#offset_to_position"><CODE>offset_to_position
</CODE></A>, then pass it to
<CODE>pubseekpos
</CODE>. To convert the return value of seek to an integral type, use
<A HREF=
"functions/positioning.html#position_to_offset"><CODE>position_to_offset
</CODE></A>.
72 If you're using a
<A HREF=
"guide/generic_streams.html#stream"><CODE>stream
</CODE></A> or
<A HREF=
"classes/filtering_stream.html"><CODE>filtering_stream
</CODE></A>, convert the offset to a
<CODE>std::streampos
</CODE> using
<A HREF=
"functions/positioning.html#offset_to_position"><CODE>offset_to_position
</CODE></A>, then pass it to the overload of
<CODE>seekg
</CODE> or
<CODE>seekp
</CODE> which takes a single
<CODE>std::streampos
</CODE> argument. To convert the return value of seek to an integral type, use
<A HREF=
"functions/positioning.html#position_to_offset"><CODE>position_to_offset
</CODE></A>.
75 <P><I>See
</I> <A HREF=
"functions/positioning.html">Stream Offsets
</A>.
</P>
78 <H4>How do I read from or write to an STL sequence?
</H4>
81 You can append to an STL sequence using a
<A HREF=
"classes/back_inserter.html"><CODE>back_insert_device
</CODE></A>, or the function
<A HREF=
"classes/back_inserter.html#back_inserter"><CODE>boost::iostreams::back_inserter
</CODE></A>. You can read from an STL sequence
82 by adding an instance of
<A HREF=
"../../range/doc/html/range/reference/utilities/iterator_range.html" TARGET=
"_top"><CODE>boost::itertator_range
</CODE></A> to a
<A HREF=
"classes/filtering_stream.html"><CODE>filtering_stream
</CODE></A> or
<A HREF=
"classes/filtering_streambuf.html"><CODE>filtering_streambuf
</CODE></A>.
85 <P><I>See
</I> <A HREF=
"tutorial/container_source.html">Writing a
<CODE>container_source
</CODE></A> and
<A HREF=
"tutorial/container_sink.html">Writing a
<CODE>container_sink
</CODE></A>.
</P>
87 <A NAME=
"multibyte"></A>
88 <H4>How do I write a stream which can read or write multibyte character encodings?
</H4>
91 Use a
<A HREF=
"classes/code_converter.html"><CODE>code_converter
</CODE></A>.
<I>See
</I> <A HREF=
"guide/code_conversion.html"><CODE>Code Conversion
</CODE></A>.
94 <A NAME=
"auto_close"></A>
95 <H4>Can I swap Filters or Devices in the middle of a sequence of i/o operations?
</H4>
98 If you're performing output, and if all the Filters in you chain are
<A HREF=
"concepts/flushable.html">Flushable
</A>, then yes. First call
<A HREF=
"classes/chain.html#strict_sync"><CODE>strict_sync
</CODE></A>. If it returns
<CODE>true
</CODE>, you can safely call
<CODE><A HREF=
"classes/chain.html#set_auto_close">set_auto_close
</A>(false)
</CODE> and
<A HREF=
"classes/chain.html#pop"><CODE>pop
</CODE></A> one or more components without closing the stream. This applies to instances of
<A HREF=
"classes/filtering_stream.html"><CODE>filtering_stream
</CODE></A>,
<A HREF=
"classes/filtering_streambuf.html"><CODE>filtering_streambuf
</CODE></A> and
<A HREF=
"classes/chain.html"><CODE>chain
</CODE></A>.
101 <A NAME=
"lifetime"></A>
102 <H4>Why does my filter chain work with
<CODE>std::cout
</CODE> but not with another
<CODE>ostream
</CODE>?
</H4>
105 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
<CODE>std::cout
</CODE>, since it is guaranteed to live until the end of the program.
109 Check to make sure that the
<CODE>ostream
</CODE> is not being destroyed before the
<CODE>filtering_stream
</CODE>. If both objects are constructed on the stack within the same block, make sure that the
<CODE>ostream
</CODE> is constructed
<I>first
</I>.
113 <H4>Why do I get errors stating that
<CODE>operator|
</CODE> is ambiguous?
</H4>
116 During overload resolution for an expression involving
<CODE>operator|
</CODE>, your compiler could be considering an implicit conversion from an intergral type to a
<A HREF=
"concepts/pipable.html">Pipable
</A> Filter. Make sure that all your Pipable Filters have
<CODE>explicit
</CODE> constructors.
<I>See
</I> <A HREF=
"guide/pipelines.html">Pipelines
</A>.
119 <A NAME=
"finite_state"></A>
120 <H4>Why do I get errors when compiling the
<CODE>finite_state_filter
</CODE> examples?
</H4>
123 The template
<CODE>finite_state_filter
</CODE> requires a highly standard-conforming compiler. See
<A HREF=
"portability.html">Portability
</A> and the
<A HREF=
"http://www.boost.org/status/compiler_status.html" TARGET=
"_top">Compiler Status Tables
</A> for details.
126 <!-- Begin Footer -->
130 <P CLASS=
"copyright">© Copyright
2008 <a href=
"http://www.coderage.com/" target=
"_top">CodeRage, LLC
</a><br/>© Copyright
2004-
2007 <a href=
"http://www.coderage.com/turkanis/" target=
"_top">Jonathan Turkanis
</a></P>
131 <P CLASS=
"copyright">
132 Distributed under the Boost Software License, Version
1.0. (See accompanying file LICENSE_1_0.txt or copy at
<A HREF=
"http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt
</A>)