Update of /cvsroot/boost/boost/libs/iostreams/doc/guide
In directory
sc8-pr-cvs3.sourceforge.net:/tmp/cvs-serv19574/libs/iostreams/doc/guide
Modified Files:
concepts.html exceptions.html generic_streams.html
pipelines.html
Log Message:
Added Kim Barrett's patches that merge the changes from 1.33.1 into cvs HEAD.
Index: concepts.html
===================================================================
RCS file: /cvsroot/boost/boost/libs/iostreams/doc/guide/concepts.html,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -d -r1.6 -r1.7
--- concepts.html 12 Aug 2005 13:02:35 -0000 1.6
+++ concepts.html 26 May 2007 12:42:43 -0000 1.7
@@ -41,7 +41,10 @@
The fundamental building blocks of the Iostreams library are the concepts
of a <A HREF="../concepts/source.html">Source</A>, which provides read access
to a sequence of characters, a <A HREF="../concepts/sink.html">Sink</A>, which
provides write access to a sequence of characters, an <A
HREF="../concepts/input_filter.html">InputFilter</A>, which Filters input read
from a Source, and an <A
HREF="../concepts/output_filter.html">OutputFilter</A>, which Filters output
written to a Sink. Sources, Sinks and their refinements are called <SPAN
CLASS="term">Devices</SPAN>. InputFilters, OutputFilter and their refinements
are called <SPAN CLASS="term">Filters</SPAN>.
</P>
<P>
- In general, a Filter or Device may provide access to an <SPAN>input
sequence</SPAN>, for reading, an <SPAN>output sequence</SPAN>, for writing, or
both. The relationship between the two sequences, as well as the operations
that may be performed on them, depends on the Filter or Device type. The
various possible relationships between input and output are referred to as <A
HREF="modes.html">modes</A>.<SUP><A CLASS="footnote_ref" NAME="note_1_ref"
HREF="#note_1">[1]</A></SUP> The Iostreams library provides one Device concept
and one Filter concept for each of eight modes. Source, Sink, InputFilter and
OutputFilter correspond to the the modes <A HREF="modes.html#input">input</A>
and <A HREF="modes.html#output">output</A> and are by far the most important of
the Filter and Device concepts.
+ Standard streams and stream buffers are Devices; for example, input
streams are <A HREF="../concepts/source.html">Sources</A> and output streams
are <A HREF="../concepts/sink.html">Sinks</A>.<A CLASS="footnote_ref"
NAME="note_1_ref" HREF="#note_1"><SUP>[1]</SUP></A>
+</P>
+<P>
+ In general, a Filter or Device may provide access to an <SPAN>input
sequence</SPAN>, for reading, an <SPAN>output sequence</SPAN>, for writing, or
both. The relationship between the two sequences, as well as the operations
that may be performed on them, depends on the Filter or Device type. The
various possible relationships between input and output are referred to as <A
HREF="modes.html">modes</A>.<SUP><A CLASS="footnote_ref" NAME="note_2_ref"
HREF="#note_2">[2]</A></SUP> The Iostreams library provides one Device concept
and one Filter concept for each of eight modes. Source, Sink, InputFilter and
OutputFilter correspond to the the modes <A HREF="modes.html#input">input</A>
and <A HREF="modes.html#output">output</A> and are by far the most important of
the Filter and Device concepts.
</P>
<P>
The most common Device and Filter concepts are documented individually.
Readers new to the Iostreams library should familiarize themselves with the
four central concepts <A HREF="../concepts/source.html">Source</A>, <A
HREF="../concepts/sink.html">Sink</A>, <A
HREF="../concepts/input_filter.html">InputFilter</A> and <A
HREF="../concepts/output_filter.html">OutputFilter</A>. The full sets of
requirements for the Filter and Device concepts are summarized in the
definitions of the concepts <A HREF="../concepts/device.html">Device</A> and <A
HREF="../concepts/filter.html">Filter</A> which form the roots of the concept
hierarchies.
@@ -110,7 +113,11 @@
<HR>
<P>
- <A CLASS="footnote_ref" NAME="note_1"
HREF="#note_1_ref"><SUP>[1]</SUP></A>A more precise definition is given in <A
HREF="modes.html">Modes</A>.
+ <A CLASS="footnote_ref" NAME="note_1"
HREF="#note_1_ref"><SUP>[1]</SUP></A>For complete details, see <A
HREF="../classes/mode.html"><CODE>mode_of</CODE></A>.
+</P>
+
+<P>
+ <A CLASS="footnote_ref" NAME="note_2"
HREF="#note_2_ref"><SUP>[2]</SUP></A>A more precise definition is given in <A
HREF="modes.html">Modes</A>.
</P>
<!-- End Footnotes -->
Index: exceptions.html
===================================================================
RCS file: /cvsroot/boost/boost/libs/iostreams/doc/guide/exceptions.html,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -d -r1.5 -r1.6
--- exceptions.html 12 Aug 2005 13:02:35 -0000 1.5
+++ exceptions.html 26 May 2007 12:42:43 -0000 1.6
@@ -61,7 +61,7 @@
<H5>Policy</H5>
<P>
- The fundamental stream buffer template in the Boost Iostreams library, <A
HREF="generic_streams.html#stream_buffer"><CODE>stream_buffer</CODE></A>,
implements the <CODE>protected virtual</CODE> memeber functions of
<CODE>std::basic_streambuf</CODE> by delegating to the i/o functions <A
HREF="../functions/read.html"><CODE>read</CODE></A>, <A
HREF="../functions/write.html"><CODE>write</CODE></A>, <A
HREF="../functions/put.html"><CODE>put</CODE></A>, <A
HREF="../functions/get.html"><CODE>get</CODE></A>, <I>etc.</I>, which in turn
delegate to member functions of policy classes. <I>These policy class member
functions throw exceptions to report errors.</I> The exceptions are propagated
by the <CODE>protected virtual</CODE> members of <CODE>stream_buffer</CODE> and
by the public members of <CODE>std::basic_streambuf</CODE>.
+ The fundamental stream buffer template in the Boost Iostreams library, <A
HREF="generic_streams.html#stream_buffer"><CODE>stream_buffer</CODE></A>,
implements the <CODE>protected virtual</CODE> memeber functions of
<CODE>std::basic_streambuf</CODE> by delegating to the i/o functions <A
HREF="../functions/read.html"><CODE>read</CODE></A>, <A
HREF="../functions/write.html"><CODE>write</CODE></A>, <A
HREF="../functions/put.html"><CODE>put</CODE></A>, <A
HREF="../functions/get.html"><CODE>get</CODE></A>, <I>etc.</I>, which in turn
delegate to member functions of Filters and Devices. <I>These member functions
throw exceptions to report errors.</I> The exceptions are propagated by the
<CODE>protected virtual</CODE> members of <CODE>stream_buffer</CODE> and by the
public members of <CODE>std::basic_streambuf</CODE>.
</P>
<P>
@@ -72,11 +72,11 @@
<H5>Rationale</H5>
<P>
- An alternative formulation would have been to require policy class member
functions with return type <CODE>std::streamsize</CODE> to return
<CODE>-1</CODE> to indicate errors, and to modify the specification of
functions returning <CODE>void</CODE> so that they return a <CODE>bool</CODE>
indicating success. The decision to rely on exceptions to report errors was
made to allow implementors a means to convey aditional information about the
cause of errors, and to free them from having to remember which return values
are designated as error indicators.
+ An alternative formulation would have been to require Filter and Device
member functions with return type <CODE>std::streamsize</CODE> to return
<CODE>-1</CODE> to indicate errors, and to modify the specification of
functions returning <CODE>void</CODE> so that they return a <CODE>bool</CODE>
indicating success. The decision to rely on exceptions to report errors was
made to allow implementors a means to convey aditional information about the
cause of errors, and to free them from having to remember which return values
are designated as error indicators.
</P>
<P>
- A third possibility would have been to follow the example of
<CODE>std::basic_streambuf</CODE> and allow member functions of policy classes
to signal errors either by throwing exceptions or by returning designated error
indicators. This was rejected because it would have complicated the
specifications of the various <A
HREF="concepts.html#filter_concepts">Filter</A> and <A
HREF="concepts.html#device_concepts">Device</A> concepts and made the internals
of <CODE>stream_buffer</CODE> more difficult to understand and maintain.<SUP><A
CLASS="footnote_ref" NAME="note_2_ref" HREF="#note_2">[2]</A></SUP>
+ A third possibility would have been to follow the example of
<CODE>std::basic_streambuf</CODE> and allow member functions of Filters and
Devices to signal errors either by throwing exceptions or by returning
designated error indicators. This was rejected because it would have
complicated the specifications of the various <A
HREF="concepts.html#filter_concepts">Filter</A> and <A
HREF="concepts.html#device_concepts">Device</A> concepts and made the internals
of <CODE>stream_buffer</CODE> more difficult to understand and maintain.<SUP><A
CLASS="footnote_ref" NAME="note_2_ref" HREF="#note_2">[2]</A></SUP>
</P>
<A NAME="safety"></A>
Index: generic_streams.html
===================================================================
RCS file: /cvsroot/boost/boost/libs/iostreams/doc/guide/generic_streams.html,v
retrieving revision 1.8
retrieving revision 1.9
diff -u -d -r1.8 -r1.9
--- generic_streams.html 12 Aug 2005 13:02:35 -0000 1.8
+++ generic_streams.html 26 May 2007 12:42:44 -0000 1.9
@@ -142,7 +142,7 @@
<TR>
<TR>
<TD VALIGN="top"><A NAME="level"></A><I>T</I></TD><TD WIDTH="2em"
VALIGN="top">-</TD>
- <TD>A model of one of the <A
HREF="concepts.html#device_concepts">Device</A> concepts.</TD>
+ <TD>A <A HREF="../../../../doc/html/CopyConstructible.html"
TARGET="_top">CopyConstructible</A> model of one of the <A
HREF="concepts.html#device_concepts">Device</A> concepts.</TD>
</TR>
<TR>
<TD VALIGN="top"><A NAME="level"></A><I>Tr</I></TD><TD WIDTH="2em"
VALIGN="top">-</TD>
@@ -154,7 +154,7 @@
</TR>
<TR>
<TD VALIGN="top"><A NAME="level"></A><I>Mode</I></TD><TD WIDTH="2em"
VALIGN="top">-</TD>
- <TD>A mode tag <I>convertible to the <CODE>mode_of</CODE> of T</I>.
This parameter is principally for internal use. Specifying a <A
HREF="modes.html#mode_tags">mode tag</A> properly refined by the mode of T can
prevent an unneeded buffer from being allocated in some cases. Defaults to the
mode of T.</TD>
+ <TD>A mode tag <I>convertible to the <A HREF="modes.html">mode</A> of
T</I>. This parameter is principally for internal use. Specifying a <A
HREF="modes.html#mode_tags">mode tag</A> properly refined by the mode of T can
prevent an unneeded buffer from being allocated in some cases. Defaults to the
mode of T.</TD>
</TR>
</TABLE>
@@ -206,7 +206,7 @@
<B>stream_buffer</B>([<SPAN CLASS="keyword">const</SPAN>] U1& u1, <SPAN
CLASS="keyword">const</SPAN> U2& u2, <SPAN CLASS="omitted">...</SPAN>, <SPAN
CLASS="keyword">const</SPAN> UN& uN);</PRE>
<P>
- Each of these members constructs an instance of <CODE>stream_buffer</CODE>
and associates it with an instance of the Device <CODE>T</CODE> constructed
from the given lists of arguments. The <CODE>T</CODE> constructors involved
must take all arguments by value or <CODE>const</CODE> reference.
+ Each of these members constructs an instance of <CODE>stream_buffer</CODE>
and associates it with an instance of the Device <CODE>T</CODE> constructed
from the given lists of arguments. The <CODE>T</CODE> constructor must take all
arguments other than the first by value or <CODE>const</CODE> reference.
</P>
<P>
It is not possible to specify a custom buffer size or putback buffer size
using these constructors.
@@ -236,7 +236,7 @@
<SPAN CLASS="keyword">void</SPAN> <B>open</B>(<SPAN
CLASS="keyword">const</SPAN> U1& u1, <SPAN CLASS="omitted">...</SPAN>, <SPAN
CLASS="keyword">const</SPAN> UN& uN);</PRE>
<P>
- Each of these members associates with <CODE>this</CODE> instance of
<CODE>stream_buffer</CODE> a newly constructed instance of the Device
<CODE>T</CODE> constructed from the given lists of arguments, if there is no
such instance currently associated; otherwise, they throw
<CODE>std::ios_base::failure</CODE>. The <CODE>T</CODE> constructors involved
must take all arguments by value or <CODE>const</CODE> reference.
+ Each of these members associates with <CODE>this</CODE> instance of
<CODE>stream_buffer</CODE> a newly constructed instance of the Device
<CODE>T</CODE> constructed from the given lists of arguments, if there is no
such instance currently associated; otherwise, they throw
<CODE>std::ios_base::failure</CODE>. The <CODE>T</CODE> constructor must take
all arguments other than the first by value or <CODE>const</CODE> reference.
</P>
<P>
It is not possible to specify a custom buffer size or putback buffer size
using these members.
@@ -354,7 +354,7 @@
<TR>
<TR>
<TD VALIGN="top"><A NAME="level"></A><I>T</I></TD><TD WIDTH="2em"
VALIGN="top">-</TD>
- <TD>A model of one of the <A
HREF="concepts.html#device_concepts">Device</A> concepts.</TD>
+ <TD>A <A HREF="../../../../doc/html/CopyConstructible.html"
TARGET="_top">CopyConstructible</A> model of one of the <A
HREF="concepts.html#device_concepts">Device</A> concepts.</TD>
</TR>
<TR>
<TD VALIGN="top"><A NAME="level"></A><I>Tr</I></TD><TD WIDTH="2em"
VALIGN="top">-</TD>
@@ -366,7 +366,7 @@
</TR>
<TR>
<TD VALIGN="top"><A NAME="level"></A><I>Mode</I></TD><TD WIDTH="2em"
VALIGN="top">-</TD>
- <TD>A mode tag <I>convertible to the <CODE>mode_of</CODE> of T</I>.
This parameter is principally for internal use. Specifying a <A
HREF="modes.html#mode_tags">mode tag</A> properly refined by the mode of T can
prevent an unneeded buffer from being allocated in some cases. Defaults to the
mode of T.</TD>
+ <TD>A mode tag <I>convertible to the <A HREF="modes.html">mode</A> of
T</I>. This parameter is principally for internal use. Specifying a <A
HREF="modes.html#mode_tags">mode tag</A> properly refined by the mode of T can
prevent an unneeded buffer from being allocated in some cases. Defaults to the
mode of T.</TD>
</TR>
</TABLE>
Index: pipelines.html
===================================================================
RCS file: /cvsroot/boost/boost/libs/iostreams/doc/guide/pipelines.html,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -d -r1.7 -r1.8
--- pipelines.html 12 Aug 2005 13:02:35 -0000 1.7
+++ pipelines.html 26 May 2007 12:42:44 -0000 1.8
@@ -77,7 +77,7 @@
BOOST_IOSTREAMS_PIPABLE(my_filter, 0)
</PRE>
-<P>No semicolon is required following the macro declaration. The following
example shows a <A
HREF="../classes/filtering_stream.html"><CODE>filtering_stream</CODE></A>
constructed from a pipeline</CODE>.</P>
+<P>No semicolon is required (or allowed) following the macro invocation. The
following example shows a <A
HREF="../classes/filtering_stream.html"><CODE>filtering_stream</CODE></A>
constructed from a pipeline</CODE>.</P>
<PRE CLASS="broken_ie"><SPAN CLASS='preprocessor'>#include</SPAN> <A
CLASS='header' HREF='../../../../boost/iostreams/filtering_stream.hpp'><SPAN
CLASS='literal'><boost/iostreams/filtering_stream.hpp></SPAN></A>
<SPAN CLASS='preprocessor'>#include</SPAN> <A CLASS='header'
HREF='../../../../boost/iostreams/device/file.hpp'><SPAN
CLASS='literal'><boost/iostreams/device/file.hpp></SPAN></A>
@@ -106,10 +106,14 @@
<PRE CLASS="broken_ie">
-<SPAN CLASS='preprocessor'>#define</SPAN> <A CLASS='documented'
HREF="#boost_iostreams_pipable">BOOST_IOSTREAMS_PIPABLE</A>(filter, arity)
<SPAN CLASS='omitted'>...</SPAN>
+<SPAN CLASS='preprocessor'>#define</SPAN> BOOST_IOSTREAMS_PIPABLE(filter,
arity) <SPAN CLASS='omitted'>...</SPAN>
</PRE>
+<H4>Description</H4>
+
+<P>Defines the overloads of <CODE>operator|</CODE> necessary for a <A
HREF="../concepts/filter.html">Filter</A> to appear in pipelines.</P>
+
<A NAME="macro_params"></A>
<H4>Macro parameters</H4>
-------------------------------------------------------------------------
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
