boostorg/io
1
0
Fork 1
mirror of https://github.com/boostorg/io.git synced 2025-07-29 20:07:13 +02:00
Code Issues Packages Projects Releases Wiki Activity

Clarified exception (non-)safety in some destructors; re-flowed text

Browse Source 
[SVN r14666]
This commit is contained in:
Daryle Walker
2002-08-04 06:48:18 +00:00
parent fa5ed210ec
commit fdc0f5f5ab
1 changed files with 118 additions and 30 deletions
Download Patch File Download Diff File Expand all files Collapse all files

148
doc/ios_state.html
View File

@ -4,34 +4,48 @@
<title>I/O Stream-State Saver Library</title>
</head>
<body text="black" bgcolor="white" link="blue" vlink="purple" alink="red">
<h1><img src="../../../c++boost.gif" alt="c++boost.gif (8819 bytes)" align="middle" width="277" height="86">Header &lt;<cite><a href="../../../boost/io/ios_state.hpp">boost/io/ios_state.hpp</a></cite>&gt;</h1>
<h1><img src="../../../c++boost.gif" alt="c++boost.gif (8819 bytes)"
align="middle" width="277" height="86">Header &lt;<cite><a
href="../../../boost/io/ios_state.hpp">boost/io/ios_state.hpp</a></cite>
&gt;</h1>
<p>The header <cite><a href="../../../boost/io/ios_state.hpp">boost/io/ios_state.hpp</a></cite> covers saving the stream state of objects in the C++ IOStreams system.</p>
<p>The header <cite><a
href="../../../boost/io/ios_state.hpp">boost/io/ios_state.hpp</a></cite>
covers saving the stream state of objects in the C++ IOStreams
system.</p>
<h2><a name="contents">Contents</a></h2>
<ol>
<li><a href="#contents">Contents</a>
<li><a href="#rationale">Rationale</a>
<li><a href="#header">Header Synopsis</a>
<li><a href="#contents">Contents</a></li>
<li><a href="#rationale">Rationale</a></li>
<li><a href="#header">Header Synopsis</a></li>
<li><a href="#base_savers">Savers for Basic Standard Attributes</a></li>
<li><a href="#adv_savers">Savers for Advanced Standard Attributes</a></li>
<li><a href="#user_savers">Savers for User-Defined Attributes</a></li>
<li><a href="#combo_savers">Savers for Combined Attributes</a></li>
<li><a href="#example">Example</a></li>
<li><a href="#refer">References</a>
<li><a href="#refer">References</a></li>
<li><a href="#credits">Credits</a>
<ul>
<li><a href="#contributors">Contributors</a>
<li><a href="#history">History</a>
</ul>
<li><a href="#contributors">Contributors</a></li>
<li><a href="#history">History</a></li>
</ul></li>
</ol>
<h2><a name="rationale">Rationale</a></h2>
<p>Sometimes a certain value has to change only for a limited scope. Saver classes save a copy of the current state of some object (or an aspect of an object), and reset the object's state at destruction time, undoing any change the object may have gone through.</p>
<p>Sometimes a certain value has to change only for a limited scope.
Saver classes save a copy of the current state of some object (or an
aspect of an object), and reset the object's state at destruction time,
undoing any change the object may have gone through.</p>
<p>The saver class strategy is helpful when using I/O stream objects. Manipulator objects can change some aspect of a stream during input or output. The state changed by the manipulator usually sticks to its new value after the I/O transaction. This can be a problem if manipulators are used in a function that is not supposed to externally change a stream's state.</p>
<p>The saver class strategy is helpful when using I/O stream objects.
Manipulator objects can change some aspect of a stream during input or
output. The state changed by the manipulator usually sticks to its new
value after the I/O transaction. This can be a problem if manipulators
are used in a function that is not supposed to externally change a
stream's state.</p>
<blockquote><pre>#include &lt;ostream&gt;
#include &lt;ios&gt;
@ -42,11 +56,16 @@ void hex_my_byte( std::ostream &amp;os, char byte )
}
</pre></blockquote>
<p>The <var>os</var> stream will retain its new hexadecimal printing mode after the call to <code>hex_my_byte</code>. The stream's printing mode can be saved and restored with manual calls to the stream's state inspecting and mutating member functions. The manual method becomes unwieldy if the main functionality is complex and/or needs to be exception safe. A saver class can implement the better &quot;resource
<p>The <var>os</var> stream will retain its new hexadecimal printing
mode after the call to <code>hex_my_byte</code>. The stream's printing
mode can be saved and restored with manual calls to the stream's state
inspecting and mutating member functions. The manual method becomes
unwieldy if the main functionality is complex and/or needs to be
exception safe. A saver class can implement the better &quot;resource
acquisition is initialization&quot; strategy.</p>
<p>See the <a href="#example">example</a> below for better code, using a saver
class.</p>
<p>See the <a href="#example">example</a> below for better code, using
saver classes.</p>
<h2><a name="header">Header Synopsis</a></h2>
@ -115,7 +134,15 @@ class ios_all_word_saver;
};
</pre></blockquote>
<p>The <var>state_type</var> is the IOStreams base class <code>std::ios_base</code>. The user would usually place an actual input, output, or combined stream object for the state-type parameter, and not a base class object. The first constructor takes a stream object and saves a reference to the stream and the current value of a particular stream attribute. The second constructor works like the first, and uses its second argument to change the stream's attribute to the new <var>aspect_type</var> value given. The destructor changes the stream's attribute back to the saved value.</p>
<p>The <var>state_type</var> is the IOStreams base class
<code>std::ios_base</code>. The user would usually place an actual
input, output, or combined stream object for the state-type parameter,
and not a base class object. The first constructor takes a stream
object and saves a reference to the stream and the current value of a
particular stream attribute. The second constructor works like the
first, and uses its second argument to change the stream's attribute to
the new <var>aspect_type</var> value given. The destructor changes the
stream's attribute back to the saved value.</p>
<table border="1" align="center">
<caption>Basic IOStreams State Saver Classes</caption>
@ -165,7 +192,17 @@ class <var>saver_class</var>
};
</pre></blockquote>
<p>The <var>state_type</var> is a version of the IOStreams base class template <code>std::basic_ios&lt;Ch, Tr&gt;</code>, where <code>Ch</code> is a character type and <code>Tr</code> is a character traits class. The user would usually place an actual input, output, or combined stream object for the state-type parameter, and not a base class object. The first constructor takes a stream object and saves a reference to the stream and the current value of a particular stream attribute. The second constructor works like the first, and uses its second argument to change the stream's attribute to the new <var>aspect_type</var> value given. The destructor changes the stream's attribute back to the saved value.</p>
<p>The <var>state_type</var> is a version of the IOStreams base class
template <code>std::basic_ios&lt;Ch, Tr&gt;</code>, where
<code>Ch</code> is a character type and <code>Tr</code> is a character
traits class. The user would usually place an actual input, output, or
combined stream object for the state-type parameter, and not a base
class object. The first constructor takes a stream object and saves a
reference to the stream and the current value of a particular stream
attribute. The second constructor works like the first, and uses its
second argument to change the stream's attribute to the new
<var>aspect_type</var> value given. The destructor changes the stream's
attribute back to the saved value.</p>
<table border="1" align="center">
<caption>Advanced IOStreams State Saver Class Templates</caption>
@ -178,7 +215,7 @@ class <var>saver_class</var>
</tr>
<tr>
<td><code>boost::io::basic_ios_iostate_saver&lt;Ch, Tr&gt;</code></td>
<td>Success state of the stream</td>
<td>Success state of the stream <a href="#Note1">[1]</a></td>
<td><code>std::ios_base::iostate</code></td>
<td><code>rdstate</code></td>
<td><code>clear</code></td>
@ -223,15 +260,27 @@ class <var>saver_class</var>
<h3>Notes</h3>
<ol>
<li>When a new success state is activated for exception watching, an exception is thrown if that state is already active. This could mean that the <a name="Note1">destructor of this class template may throw</a>.</li>
<li>The <a name="Note2">saver for the locale uses the <code>std::basic_ios&lt;Ch, Tr&gt;</code> class to extract their information</a>, although it could have used the functionality in <code>std::ios_base</code>. The problem is that the versions of the needed member functions in <code>ios_base</code> are not
polymorphicly related to the ones in <code>basic_ios</code>. The stream classes that will be used with the saver classes should use the versions of the member functions closest to them by
inheritance, which means the ones in <code>basic_ios</code>.</li>
<li>When the success state flags and/or the success state exception
watching flags are changed, an exception is thrown if a new
match occurs among the two sets of flags. This could mean that
the <a name="Note1">destructor of these class templates may
throw</a>.</li>
<li>The <a name="Note2">saver for the locale uses the
<code>std::basic_ios&lt;Ch, Tr&gt;</code> class to extract their
information</a>, although it could have used the functionality
in <code>std::ios_base</code>. The problem is that the versions
of the needed member functions in <code>ios_base</code> are not
polymorphically related to the ones in <code>basic_ios</code>.
The stream classes that will be used with the saver classes
should use the versions of the member functions closest to them
by inheritance, which means the ones in
<code>basic_ios</code>.</li>
</ol>
<h2><a name="user_savers">Savers for User-Defined Attributes</a></h2>
<p>The saver classes for user-defined formatting information have this format:</p>
<p>The saver classes for user-defined formatting information have this
format:</p>
<blockquote><pre>#include &lt;iosfwd&gt; <i>// for std::ios_base (declaration)</i>
@ -247,9 +296,20 @@ class <var>saver_class</var>
};
</pre></blockquote>
<p>The index <var>i</var> differentiates between specific user-defined formatting attributes. The index can only be determined at run-time (most likely with the class-static <code>std::ios_base::xalloc</code> member function).</p>
<p>The index <var>i</var> differentiates between specific user-defined
formatting attributes. The index can only be determined at run-time
(most likely with the class-static <code>std::ios_base::xalloc</code>
member function).</p>
<p>The <var>state_type</var> is the base class of the IOStreams system, <code>std::ios_base</code>. The user would usually place an actual input, output, or combined stream object for the state-type parameter, and not a base class object. The first constructor takes a stream object and index and saves a reference to the stream and the current value of a particular stream attribute. The second constructor works like the first, and uses its third argument to change the stream's attribute to the new <var>aspect_type</var> value given. The destructor changes the stream's attribute back to the saved value.</p>
<p>The <var>state_type</var> is the base class of the IOStreams system,
<code>std::ios_base</code>. The user would usually place an actual
input, output, or combined stream object for the state-type parameter,
and not a base class object. The first constructor takes a stream
object and index and saves a reference to the stream and the current
value of a particular stream attribute. The second constructor works
like the first, and uses its third argument to change the stream's
attribute to the new <var>aspect_type</var> value given. The destructor
changes the stream's attribute back to the saved value.</p>
<table border="1" align="center">
<caption>IOStream User-Defined State Saver Classes</caption>
@ -275,11 +335,26 @@ class <var>saver_class</var>
<h2><a name="combo_savers">Savers for Combined Attributes</a></h2>
<p>There are three class (templates) for combined attribute savers. The <code>boost:io::ios_base_all_saver</code> saver class combines the functionality of all the basic attribute saver classes. It has a constructor that takes the stream to have its state preserved. The <code>boost::io::basic_ios_all_saver</code> combines the functionality of all the advanced attribute saver class templates and the combined basic attribute saver class. It has a constructor that takes the stream to have its state preserved. The <code>boost::io::ios_all_word_saver</code> saver class combines the saver classes that preserve user-defined formatting information. Its constructor takes the stream to have its attributes saved and the index of the user-defined attributes.</p>
<p>There are three class (templates) for combined attribute savers. The
<code>boost:io::ios_base_all_saver</code> saver class combines the
functionality of all the basic attribute saver classes. It has a
constructor that takes the stream to have its state preserved. The
<code>boost::io::basic_ios_all_saver</code> combines the functionality
of all the advanced attribute saver class templates and the combined
basic attribute saver class. It has a constructor that takes the stream
to have its state preserved. The
<code>boost::io::ios_all_word_saver</code> saver class combines the
saver classes that preserve user-defined formatting information. Its
constructor takes the stream to have its attributes saved and the index
of the user-defined attributes.</p>
<h2><a name="example">Example</a></h2>
<p>The code used in the <a href="#rationale">rationale</a> can be improved at two places. The printing function could use a saver around the code that changes the formatting state. Or the calling function can surround the call with a saver. Or both can be done for paranoia's sake.</p>
<p>The code used in the <a href="#rationale">rationale</a> can be
improved at two places. The printing function could use a saver around
the code that changes the formatting state. Or the calling function can
surround the call with a saver. Or both can be done for paranoia's
sake.</p>
<blockquote><pre>#include &lt;boost/io/ios_state.hpp&gt;
#include &lt;ios&gt;
@ -312,8 +387,10 @@ int main()
<h2><a name="refer">References</a></h2>
<ul>
<li>The I/O state saver library header itself: <cite><a href="../../../boost/io/ios_state.hpp">boost/io/ios_state.hpp</a></cite>
<li>Some test/example code: <cite><a href="../test/ios_state_test.cpp">ios_state_test.cpp</a></cite>
<li>The I/O state saver library header itself: <cite><a
href="../../../boost/io/ios_state.hpp">boost/io/ios_state.hpp</a></cite></li>
<li>Some test/example code: <cite><a
href="../test/ios_state_test.cpp">ios_state_test.cpp</a></cite></li>
</ul>
<h2><a name="credits">Credits</a></h2>
@ -322,7 +399,14 @@ int main()
<dl>
<dt><a href="../../../people/daryle_walker.html">Daryle Walker</a>
<dd>Started the library. Contributed the initial versions of the format flags, precision, width, and user-defined format flags saver classes. Contributed the initial versions of the success state, success state exception flags, output stream tie, stream buffer, character fill, and locale saver class templates. Contributed the combined attribute classes and class template. Contributed the test file <cite><a href="../test/ios_state_test.cpp">ios_state_test.cpp</a></cite>.
<dd>Started the library. Contributed the initial versions of the
format flags, precision, width, and user-defined format flags
saver classes. Contributed the initial versions of the success
state, success state exception flags, output stream tie, stream
buffer, character fill, and locale saver class templates.
Contributed the combined attribute classes and class template.
Contributed the test file <cite><a
href="../test/ios_state_test.cpp">ios_state_test.cpp</a></cite>.
</dl>
<h3><a name="history">History</a></h3>
@ -336,6 +420,10 @@ int main()
<p>Revised: 13 March 2002</p>
<p>Copyright &copy; Daryle Walker 2002. Permission to copy, use, modify, sell and distribute this document is granted provided this copyright notice appears in all copies. This document is provided &quot;as is&quot; without express or implied warranty, and with no claim as to its suitability for any purpose.</p>
<p>Copyright &copy; Daryle Walker 2002. Permission to copy, use,
modify, sell and distribute this document is granted provided this
copyright notice appears in all copies. This document is provided
&quot;as is&quot; without express or implied warranty, and with no claim
as to its suitability for any purpose.</p>
</body>
</html>