| [12] | 1 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> |
|---|
| 2 | <HTML> |
|---|
| 3 | <HEAD> |
|---|
| 4 | <TITLE>Frequently Asked Questions</TITLE> |
|---|
| 5 | <LINK REL="stylesheet" HREF="../../../boost.css"> |
|---|
| 6 | <LINK REL="stylesheet" HREF="theme/iostreams.css"> |
|---|
| 7 | </HEAD> |
|---|
| 8 | <BODY> |
|---|
| 9 | |
|---|
| 10 | <!-- Begin Banner --> |
|---|
| 11 | |
|---|
| 12 | <H1 CLASS="title">Frequently Asked Questions</H1> |
|---|
| 13 | <HR CLASS="banner"> |
|---|
| 14 | |
|---|
| 15 | <!-- End Banner --> |
|---|
| 16 | |
|---|
| 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> |
|---|
| 28 | </DL> |
|---|
| 29 | |
|---|
| 30 | <HR style="margin-top:1em"> |
|---|
| 31 | |
|---|
| 32 | <A NAME="flush"></A> |
|---|
| 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> |
|---|
| 34 | |
|---|
| 35 | <P> |
|---|
| 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>. |
|---|
| 37 | </P> |
|---|
| 38 | <P> |
|---|
| 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. |
|---|
| 40 | </P> |
|---|
| 41 | |
|---|
| 42 | <A NAME="tee"></A> |
|---|
| 43 | <H4>How do I write to several ostreams at once?</H4> |
|---|
| 44 | |
|---|
| 45 | <P> |
|---|
| 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>. |
|---|
| 47 | </P> |
|---|
| 48 | |
|---|
| 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> |
|---|
| 51 | |
|---|
| 52 | <P> |
|---|
| 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>. |
|---|
| 54 | </P> |
|---|
| 55 | |
|---|
| 56 | <P> |
|---|
| 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>. |
|---|
| 58 | </P> |
|---|
| 59 | |
|---|
| 60 | <A NAME="offsets"></A> |
|---|
| 61 | <H4>How do perform file positioning operations with large (64-bit) offsets?</H4> |
|---|
| 62 | |
|---|
| 63 | <P> |
|---|
| 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>. |
|---|
| 65 | </P> |
|---|
| 66 | |
|---|
| 67 | <P> |
|---|
| 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>. |
|---|
| 69 | </P> |
|---|
| 70 | |
|---|
| 71 | <P> |
|---|
| 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>. |
|---|
| 73 | </P> |
|---|
| 74 | |
|---|
| 75 | <P><I>See</I> <A HREF="functions/positioning.html">Stream Offsets</A>.</P> |
|---|
| 76 | |
|---|
| 77 | <A NAME="stl"></A> |
|---|
| 78 | <H4>How do I read from or write to an STL sequence?</H4> |
|---|
| 79 | |
|---|
| 80 | <P> |
|---|
| 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/utility_class.html#iter_range" 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>. |
|---|
| 83 | </P> |
|---|
| 84 | |
|---|
| 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> |
|---|
| 86 | |
|---|
| 87 | <A NAME="multibyte"></A> |
|---|
| 88 | <H4>How do I write a stream which can read or write multibyte character encodings?</H4> |
|---|
| 89 | |
|---|
| 90 | <P> |
|---|
| 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>. |
|---|
| 92 | </P> |
|---|
| 93 | |
|---|
| 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> |
|---|
| 96 | |
|---|
| 97 | <P> |
|---|
| 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>. |
|---|
| 99 | </P> |
|---|
| 100 | |
|---|
| 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> |
|---|
| 103 | |
|---|
| 104 | <P> |
|---|
| 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. |
|---|
| 106 | </P> |
|---|
| 107 | |
|---|
| 108 | <P> |
|---|
| 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>. |
|---|
| 110 | </P> |
|---|
| 111 | |
|---|
| 112 | <A NAME="pipe"></A> |
|---|
| 113 | <H4>Why do I get errors stating that <CODE>operator|</CODE> is ambiguous?</H4> |
|---|
| 114 | |
|---|
| 115 | <P> |
|---|
| 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>. |
|---|
| 117 | </P> |
|---|
| 118 | |
|---|
| 119 | <A NAME="finite_state"></A> |
|---|
| 120 | <H4>Why do I get errors when compiling the <CODE>finite_state_filter</CODE> examples?</H4> |
|---|
| 121 | |
|---|
| 122 | <P> |
|---|
| 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. |
|---|
| 124 | </P> |
|---|
| 125 | |
|---|
| 126 | <!-- Begin Footer --> |
|---|
| 127 | |
|---|
| 128 | <HR> |
|---|
| 129 | <P CLASS="copyright">Revised |
|---|
| 130 | <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> |
|---|
| 131 | 20 May, 2004 |
|---|
| 132 | <!--webbot bot="Timestamp" endspan i-checksum="38504" --> |
|---|
| 133 | </P> |
|---|
| 134 | |
|---|
| 135 | <P CLASS="copyright">© Copyright <A HREF="http://www.kangaroologic.com" TARGET="_top">Jonathan Turkanis</A>, 2004</P> |
|---|
| 136 | <P CLASS="copyright"> |
|---|
| 137 | 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>) |
|---|
| 138 | </P> |
|---|
| 139 | |
|---|
| 140 | <!-- End Footer --> |
|---|
| 141 | |
|---|
| 142 | </BODY> |
|---|
