Update of /cvsroot/boost/boost/libs/iostreams/doc/tutorial
In directory
sc8-pr-cvs3.sourceforge.net:/tmp/cvs-serv19574/libs/iostreams/doc/tutorial
Modified Files:
container_device.html container_sink.html
container_source.html dictionary_filters.html
dual_use_filters.html finite_state_filters.html
shell_comments_filters.html unix2dos_filters.html
writing_filters.html
Log Message:
Added Kim Barrett's patches that merge the changes from 1.33.1 into cvs HEAD.
Index: container_device.html
===================================================================
RCS file:
/cvsroot/boost/boost/libs/iostreams/doc/tutorial/container_device.html,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -d -r1.7 -r1.8
--- container_device.html 12 Aug 2005 13:02:35 -0000 1.7
+++ container_device.html 26 May 2007 12:42:44 -0000 1.8
@@ -27,7 +27,7 @@
<A NAME="container_device"></A>
<H2>2.1.4. Writing a <CODE>container_device</CODE></H2>
-<P>Suppose you want to write a Device for reading from and writing to an STL
container. In order for combined reading and writing to be useful, you will
also need to support seeking within the container. There are several types of
Devices which combine reading and writing, whether there are two separate
character sequences for input and output, or a single combined sequence, and on
whether there are separate position indicators for reading and writing or a
single read/write position indicator. <I>See</I> <A
HREF="../guide/modes.html">Modes</A> for details.</P>
+<P>Suppose you want to write a Device for reading from and writing to an STL
container. In order for combined reading and writing to be useful, you will
also need to support seeking within the container. There are several types of
Devices which combine reading and writing; they differ according to whether
there are two separate character sequences for input and output, or a single
combined sequence, and whether there are separate position indicators for
reading and writing or a single read/write position indicator. <I>See</I> <A
HREF="../guide/modes.html">Modes</A> for details.</P>
<P>A narrow-character Device for read-write access to a single character
sequence with a single position indicator is called a <A
HREF="../concepts/seekable_device.html">SeekableDevice</A>. A typical
SeekableDevice looks like this:</P>
Index: container_sink.html
===================================================================
RCS file: /cvsroot/boost/boost/libs/iostreams/doc/tutorial/container_sink.html,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -d -r1.7 -r1.8
--- container_sink.html 12 Aug 2005 13:02:35 -0000 1.7
+++ container_sink.html 26 May 2007 12:42:44 -0000 1.8
@@ -126,7 +126,7 @@
<P>Note that the Iostreams library provides buffering by default.
Consequently, the stream <CODE>out</CODE> must be flushed before the characters
written are guaranteed to be reflected in the underlying <CODE>string</CODE>.
-<P>Finally, I should mention that the Iostremas library easier ways to append
to an STL-compatible container.
+<P>Finally, I should mention that the Iostreams library offers easier ways to
append to an STL-compatible container.
First, OutputIterators can be added directly to <A
HREF="../guide/filtering_streams.html">filtering streams and stream
buffers</A>. So you could write:</P>
Index: container_source.html
===================================================================
RCS file:
/cvsroot/boost/boost/libs/iostreams/doc/tutorial/container_source.html,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -d -r1.7 -r1.8
--- container_source.html 12 Aug 2005 13:02:35 -0000 1.7
+++ container_source.html 26 May 2007 12:42:44 -0000 1.8
@@ -139,7 +139,7 @@
assert(input == output);
}</PRE>
-<P>Finally, I sould mention that the Iostremas library provides an easier way
to read from an STL container: instances of <A
HREF="../../../range/doc/utility_class.html#iter_range"
TARGET="_top"><CODE>boost::iterator_range</CODE></A> can be added directly to
<A HREF="../guide/filtering_streams.html">filtering streams and stream
buffers</A>. So you could write:</P>
+<P>Finally, I should mention that the Iostreams library provides an easier way
to read from an STL container: instances of <A
HREF="../../../range/doc/utility_class.html#iter_range"
TARGET="_top"><CODE>boost::iterator_range</CODE></A> can be added directly to
<A HREF="../guide/filtering_streams.html">filtering streams and stream
buffers</A>. So you could write:</P>
<PRE CLASS="broken_ie"><SPAN CLASS='preprocessor'>#include</SPAN> <SPAN
CLASS='literal'><cassert></SPAN>
<SPAN CLASS='preprocessor'>#include</SPAN> <SPAN
CLASS='literal'><string></SPAN>
Index: dictionary_filters.html
===================================================================
RCS file:
/cvsroot/boost/boost/libs/iostreams/doc/tutorial/dictionary_filters.html,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -d -r1.6 -r1.7
--- dictionary_filters.html 12 Aug 2005 13:02:35 -0000 1.6
+++ dictionary_filters.html 26 May 2007 12:42:44 -0000 1.7
@@ -86,7 +86,7 @@
<SPAN CLASS="keyword">if</SPAN> (c == <SPAN
CLASS="numeric_literal">EOF</SPAN> || !std::isalpha((<SPAN
CLASS="keyword">unsigned</SPAN> <SPAN CLASS="keyword">char</SPAN>) c)) {
dictionary_.replace(current_word_);
cout.write( current_word_.data(),
-
static_cast<streamsize>(current_word_.size()) );
+ <SPAN
CLASS="keyword">static_cast</SPAN><streamsize>(current_word_.size()) );
current_word_.erase();
<SPAN CLASS="keyword">if</SPAN> (c == <SPAN
CLASS="numeric_literal">EOF</SPAN>)
break;
@@ -233,7 +233,7 @@
<SPAN CLASS="keyword"><SPAN CLASS="keyword">bool</SPAN></SPAN>
write_current_word(Sink& dest)
{
<SPAN CLASS="keyword">using</SPAN> <SPAN
CLASS="keyword">namespace</SPAN> std;
- streamsize amt = static_cast<streamsize>(current_word_.size() -
off_);
+ streamsize amt = <SPAN
CLASS="keyword">static_cast</SPAN><streamsize>(current_word_.size() -
off_);
streamsize result =
iostreams::write(dest, current_word_.data() + off_, amt);
<SPAN CLASS="keyword">if</SPAN> (result == amt) {
@@ -290,7 +290,7 @@
iostreams::write(
dest,
current_word.data() + off,
- <SPAN
CLASS="keyword">static_cast</SPAN><std::streamsize>(current_word.size() - off)
+ <SPAN
CLASS="keyword">static_cast</SPAN><std::streamsize>(current_word.size() -
off)
);
}</PRE>
Index: dual_use_filters.html
===================================================================
RCS file:
/cvsroot/boost/boost/libs/iostreams/doc/tutorial/dual_use_filters.html,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -d -r1.6 -r1.7
--- dual_use_filters.html 12 Aug 2005 13:02:35 -0000 1.6
+++ dual_use_filters.html 26 May 2007 12:42:44 -0000 1.7
@@ -29,7 +29,7 @@
<P>
- It can be confusing to maintain two separate filters — one for input
and the other for output — to implement the same filtering algorithm. One
way to avoid this is to use the <A
HREF="writing_filters.html#filter_helpers">filter helpers</A> mentioned above.
The filter helpers each produce filter which can be used for either input or
output, but not both simultaneously. Such filters are called <A
HREF="../concepts/dual_use_filter.html">Dual-Use Filters</A>.
+ It can be confusing to maintain two separate filters — one for input
and the other for output — to implement the same filtering algorithm. One
way to avoid this is to use the <A
HREF="writing_filters.html#filter_helpers">filter helpers</A> mentioned above.
The filter helpers produce filters which can be used for either input or
output, but not both simultaneously. Such filters are called <A
HREF="../concepts/dual_use_filter.html">Dual-Use Filters</A>.
</P>
<P>
@@ -42,7 +42,7 @@
<SPAN CLASS='keyword'>namespace</SPAN> boost { <SPAN
CLASS='keyword'>namespace</SPAN> iostreams { <SPAN
CLASS='keyword'>namespace</SPAN> example {
-<SPAN CLASS="keyword">class</SPAN> shell_comments_input_filter : <SPAN
CLASS="keyword"><SPAN CLASS="keyword"><SPAN
CLASS="keyword">public</SPAN></SPAN></SPAN> input_filter {
+<SPAN CLASS="keyword">class</SPAN> shell_comments_input_filter : <SPAN
CLASS="keyword"><SPAN CLASS="keyword"><SPAN
CLASS="keyword">public</SPAN></SPAN></SPAN> dual_use_filter {
<SPAN CLASS="keyword">public</SPAN>:
<SPAN CLASS="keyword">explicit</SPAN> shell_comments_input_filter(<SPAN
CLASS="keyword">char</SPAN> comment_char = <SPAN CLASS="literal">'#'</SPAN>)
: comment_char_(comment_char), skip_(<SPAN
CLASS="keyword">false</SPAN>)
@@ -60,8 +60,11 @@
<SPAN CLASS='comment'>/* same as shell_comments_output_filter::put()
*/</SPAN>
}
- <SPAN CLASS="keyword">template</SPAN><<SPAN
CLASS="keyword">typename</SPAN> Source>
- <SPAN CLASS="keyword">void</SPAN> close(Source&) { skip_ = <SPAN
CLASS="keyword">false</SPAN>; }
+ <SPAN CLASS="keyword">template</SPAN><<SPAN
CLASS="keyword">typename</SPAN> Device>
+ <SPAN CLASS="keyword">void</SPAN> close(Device&, std::ios_base::openmode)
+ {
+ skip_ = <SPAN CLASS="keyword">false</SPAN>;
+ }
<SPAN CLASS="keyword">private</SPAN>:
<SPAN CLASS="keyword">char</SPAN> comment_char_;
<SPAN CLASS="keyword"><SPAN CLASS="keyword">bool</SPAN></SPAN> skip_;
Index: finite_state_filters.html
===================================================================
RCS file:
/cvsroot/boost/boost/libs/iostreams/doc/tutorial/finite_state_filters.html,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -d -r1.7 -r1.8
--- finite_state_filters.html 12 Aug 2005 13:02:35 -0000 1.7
+++ finite_state_filters.html 26 May 2007 12:42:44 -0000 1.8
@@ -31,7 +31,7 @@
<H4>Finite State Machines</H4>
<P>
- In this section I show how to construct <A
HREF="../concepts/dual_use_filter.html">Dual-Use Filters</A> from finite state
machines. For purposes of this section, a finite state machine consists of a
collection of <SPAN>states</SPAN>, represented as <CODE>int</CODE>s, a
distinguished <SPAN>initial state</SPAN>, a <SPAN>transition table</SPAN>, a
collection of <SPAN>event handlers</SPAN> and a stack of characters. These
finite state machines were inspired by the finite state machine examples that
accompany the <A HREF="../../../mpl/doc/index.html" TARGET="_top"><CODE>Boost
Metaprogamming library</CODE></A>. <I>See</I>, <I>e.g.</I>, <A
HREF="../../../mpl/example/fsm/player1.cpp"
TARGET="top"><CODE><libs/mpl/example/player1.cpp></CODE></A>
+ In this section I show how to construct <A
HREF="../concepts/dual_use_filter.html">Dual-Use Filters</A> from finite state
machines. For purposes of this section, a finite state machine consists of a
collection of <SPAN>states</SPAN>, represented as <CODE>int</CODE>s, a
distinguished <SPAN>initial state</SPAN>, a <SPAN>transition table</SPAN>, a
collection of <SPAN>event handlers</SPAN> and a stack of characters. These
finite state machines were inspired by the finite state machine examples that
accompany the <A HREF="../../../mpl/doc/index.html" TARGET="_top"><CODE>Boost
Metaprogamming library</CODE></A>. <I>See</I>, <I>e.g.</I>, <A
HREF="../../../mpl/example/fsm/player1.cpp"
TARGET="_top"><CODE><libs/mpl/example/player1.cpp></CODE></A>
</P>
<P>
Index: shell_comments_filters.html
===================================================================
RCS file:
/cvsroot/boost/boost/libs/iostreams/doc/tutorial/shell_comments_filters.html,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -d -r1.7 -r1.8
--- shell_comments_filters.html 12 Aug 2005 13:02:35 -0000 1.7
+++ shell_comments_filters.html 26 May 2007 12:42:44 -0000 1.8
@@ -165,7 +165,7 @@
Here the member variable <CODE>skip_</CODE> plays the same role as the
local variable <CODE>skip</CODE>
<CODE>shell_comments_stdio_filter::do_filter</CODE>. The implementation of
<CODE>get</CODE> is very similar to that of
<CODE>shell_comments_stdio_filter::do_filter</CODE>: the <CODE>while</CODE>
loop reads a character <CODE>c</CODE>, updates <CODE>skip_</CODE> and returns
<CODE>c</CODE> unless <CODE>skip_</CODE> is <CODE>true</CODE>. The main
difference is that you have to handle the special value
<CODE>WOULD_BLOCK</CODE>, which indicates that no input is currently available.
</P>
<P>
- So you see that implementing an <A
HREF="../concepts/input_filter.html"><CODE>InputFilter</CODE></A> from scratch
is a bit more involved than deriving from <A
HREF="../classes/stdio_filter.html"><CODE>stdio_filter</CODE></A>. When writing
an <CODE>InputFilter</CODE> you must be prepared to be interupted at any point
in the middle of the algorithm; when this happens, you must record enough
information about the current state of the algorithm to allow us to pick up
later exactly where you left off. The same is true for <A
HREF="../concepts/output_filter.html"><CODE>OutputFilters</CODE></A>. In fact,
many Inputfilters and OutputFilters can be seen as finite state machines; I
will formalize this idea later. <I>See</I> <A
HREF="finite_state_filters.html">Finite State Filters</A>.
+ So you see that implementing an <A
HREF="../concepts/input_filter.html"><CODE>InputFilter</CODE></A> from scratch
is a bit more involved than deriving from <A
HREF="../classes/stdio_filter.html"><CODE>stdio_filter</CODE></A>. When writing
an <CODE>InputFilter</CODE> you must be prepared to be interupted at any point
in the middle of the algorithm; when this happens, you must record enough
information about the current state of the algorithm to allow you to pick up
later exactly where you left off. The same is true for <A
HREF="../concepts/output_filter.html"><CODE>OutputFilters</CODE></A>. In fact,
many Inputfilters and OutputFilters can be seen as finite state machines; I
will formalize this idea later. <I>See</I> <A
HREF="finite_state_filters.html">Finite State Filters</A>.
</P>
<P>
There's still one problem with <CODE>shell_comments_input_filter</CODE>:
its instances can only be used once. That's because someone might close a
stream while the <CODE>skip_</CODE> flag is set. If the stream were later
reopened — with a fresh sequence of unfiltered data — the first
line of text would be filtered out, regardless of whether it were commented.
@@ -174,7 +174,7 @@
The way to fix this is to make your Filter <A
HREF="../concepts/closable.html">Closable</A>. To do this, you must implement a
member function <CODE>close</CODE>. You must also give your filter a <A
HREF="../guide/traits.html#category_tags">category tag</A> convertible to <A
HREF="../guide/traits.html#category_tags"><CODE>closable_tag</CODE></A>, to
tell the Iostream library that your filter implements <CODE>close</CODE>.
</P>
-<P>Your improved Filter looks like this:</P>
+<P>The improved Filter looks like this:</P>
<PRE CLASS="broken_ie"><SPAN CLASS='keyword'>namespace</SPAN> boost { <SPAN
CLASS='keyword'>namespace</SPAN> iostreams { <SPAN
CLASS='keyword'>namespace</SPAN> example {
Index: unix2dos_filters.html
===================================================================
RCS file:
/cvsroot/boost/boost/libs/iostreams/doc/tutorial/unix2dos_filters.html,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -d -r1.6 -r1.7
--- unix2dos_filters.html 12 Aug 2005 13:02:35 -0000 1.6
+++ unix2dos_filters.html 26 May 2007 12:42:44 -0000 1.7
@@ -78,11 +78,13 @@
<SPAN CLASS="keyword">template</SPAN><<SPAN
CLASS="keyword">typename</SPAN> Source>
<SPAN CLASS="keyword">int</SPAN> get(Source& src)
{
+ <SPAN CLASS='comment'>// Handle unfinished business</SPAN>
<SPAN CLASS="keyword">if</SPAN> (has_linefeed_) {
has_linefeed_ = <SPAN CLASS="keyword">false</SPAN>;
<SPAN CLASS="keyword">return</SPAN> <SPAN
CLASS="literal">'\n'</SPAN>;
}
+ <SPAN CLASS='comment'>// Forward all characters except '\n'</SPAN>
<SPAN CLASS="keyword">int</SPAN> c;
if ((c = iostreams::get(src)) == <SPAN CLASS='literal'>'\n'</SPAN>) {
has_linefeed_ = true;
@@ -100,7 +102,7 @@
} } } <SPAN CLASS='comment'>// End namespace
boost::iostreams:example</SPAN></PRE>
-<P>The implementation of <CODE>get</CODE> can be described as follows. Most of
the time, you simply read a character from <CODE>src</CODE> and return it. The
special values <CODE>EOF</CODE> and <CODE>WOULD_BLOCK</CODE> are treated the
same way: the are simply forwarded <I>as-is</I>. The exception is when
<CODE>iostreams::get</CODE> returns <CODE>'\n'</CODE>. In this case, you return
<CODE>'\r'</CODE> instead and make a note to return <CODE>'\n'</CODE> the next
time get is called.</P>
+<P>The implementation of <CODE>get</CODE> can be described as follows. Most of
the time, you simply read a character from <CODE>src</CODE> and return it. The
special values <CODE>EOF</CODE> and <CODE>WOULD_BLOCK</CODE> are treated the
same way: they are simply forwarded <I>as-is</I>. The exception is when
<CODE>iostreams::get</CODE> returns <CODE>'\n'</CODE>. In this case, you return
<CODE>'\r'</CODE> instead and make a note to return <CODE>'\n'</CODE> the next
time <CODE>get</CODE> is called.</P>
<P>As usual, the member function <CODE>close</CODE> reset's the Filter's
state:</P>
Index: writing_filters.html
===================================================================
RCS file:
/cvsroot/boost/boost/libs/iostreams/doc/tutorial/writing_filters.html,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -d -r1.6 -r1.7
--- writing_filters.html 12 Aug 2005 13:02:35 -0000 1.6
+++ writing_filters.html 26 May 2007 12:42:44 -0000 1.7
@@ -60,7 +60,7 @@
<H4>Selecting a Filter Concept</H4>
<P>
- Suppose you need to write a Filter to perform a given filtering task. How
do you decide whether to write an <A
HREF="../concepts/input_filter.html">InputFilters</A> or <A
HREF="../concepts/output_filter.html">OutputFilters</A>, or to use one of the
Filter helpers? The first two Filter helpers mentioned above, <A
HREF="../classes/aggregate.html"><CODE>aggregate_filter</CODE></A> and <A
HREF="../classes/stdio_filter.html"><CODE>stdio_filter</CODE></A>, have
high-memory usage and only work with character sequences that have a
well-defined end. They allow filtering algorithms to be expressed in a very
straightforward way, however, and so provide a good introduction to filtering.
The third Filter helper, <A
HREF="../classes/symmetric_filter.html"><CODE>symmetric_filter</CODE></A>, is
useful for defining filter based on C-language API such as zlib, libbz2 or
OpenSSL. If none of the Filter helpers are appropriate, you should generally
write an InputFilter if you plan to use the
filter for reading and an OutputFilter if you plan to use it for writing. In
some cases, however, it is much easier to express an algorithm as an
InputFilter than as an OutputFilter, or <I>vice vera</I>. In such cases, you
can write the filter whichever way is easier, and use the class template <A
HREF="../functions/invert.html#inverse"><CODE>inverse</CODE></A> or the
function template <A HREF="../functions/invert.html"><CODE>invert</CODE></A> to
turn an InputFilter into an OutputFilter or <I>vice vera</I>.
+ Suppose you need to write a Filter to perform a given filtering task. How
do you decide whether to write an <A
HREF="../concepts/input_filter.html">InputFilters</A> or <A
HREF="../concepts/output_filter.html">OutputFilters</A>, or to use one of the
Filter helpers? The first two Filter helpers mentioned above, <A
HREF="../classes/aggregate.html"><CODE>aggregate_filter</CODE></A> and <A
HREF="../classes/stdio_filter.html"><CODE>stdio_filter</CODE></A>, have
high-memory usage and only work with character sequences that have a
well-defined end. They allow filtering algorithms to be expressed in a very
straightforward way, however, and so provide a good introduction to filtering.
The third Filter helper, <A
HREF="../classes/symmetric_filter.html"><CODE>symmetric_filter</CODE></A>, is
useful for defining filter based on C-language API such as zlib, libbz2 or
OpenSSL. If none of the Filter helpers are appropriate, you should generally
write an InputFilter if you plan to use the
filter for reading and an OutputFilter if you plan to use it for writing. In
some cases, however, it is much easier to express an algorithm as an
InputFilter than as an OutputFilter, or <I>vice versa</I>. In such cases, you
can write the filter whichever way is easier, and use the class template <A
HREF="../functions/invert.html#inverse"><CODE>inverse</CODE></A> or the
function template <A HREF="../functions/invert.html"><CODE>invert</CODE></A> to
turn an InputFilter into an OutputFilter or <I>vice versa</I>.
</P>
<P>
-------------------------------------------------------------------------
This SF.net email is sponsored by DB2 Express
Download DB2 Express C - the FREE version of DB2 express and take
control of your XML. No limits. Just data. Click to get it now.
http://sourceforge.net/powerbar/db2/
_______________________________________________
Boost-cvs mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/boost-cvs
