341 lines
15 KiB
HTML
341 lines
15 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
|
|
<html>
|
|
<head>
|
|
<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 <<cite><a href="../../../boost/io/ios_state.hpp">boost/io/ios_state.hpp</a></cite>></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>
|
|
|
|
<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="#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="#credits">Credits</a>
|
|
<ul>
|
|
<li><a href="#contributors">Contributors</a>
|
|
<li><a href="#history">History</a>
|
|
</ul>
|
|
</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>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 <ostream>
|
|
#include <ios>
|
|
|
|
void hex_my_byte( std::ostream &os, char byte )
|
|
{
|
|
os << std::hex << static_cast<unsigned>(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 "resource
|
|
acquisition is initialization" strategy.</p>
|
|
|
|
<p>See the <a href="#example">example</a> below for better code, using a saver
|
|
class.</p>
|
|
|
|
<h2><a name="header">Header Synopsis</a></h2>
|
|
|
|
<blockquote><pre>#include <iosfwd> <i>// for std::char_traits (declaration)</i>
|
|
|
|
namespace boost
|
|
{
|
|
namespace io
|
|
{
|
|
|
|
class ios_flags_saver;
|
|
class ios_precision_saver;
|
|
class ios_width_saver;
|
|
class ios_base_all_saver;
|
|
|
|
template < typename Ch, class Tr = ::std::char_traits<Ch> >
|
|
class basic_ios_iostate_saver;
|
|
template < typename Ch, class Tr = ::std::char_traits<Ch> >
|
|
class basic_ios_exception_saver;
|
|
template < typename Ch, class Tr = ::std::char_traits<Ch> >
|
|
class basic_ios_tie_saver;
|
|
template < typename Ch, class Tr = ::std::char_traits<Ch> >
|
|
class basic_ios_rdbuf_saver;
|
|
template < typename Ch, class Tr = ::std::char_traits<Ch> >
|
|
class basic_ios_fill_saver;
|
|
template < typename Ch, class Tr = ::std::char_traits<Ch> >
|
|
class basic_ios_locale_saver;
|
|
template < typename Ch, class Tr = ::std::char_traits<Ch> >
|
|
class basic_ios_all_saver;
|
|
|
|
typedef basic_ios_iostate_saver<char> ios_iostate_saver;
|
|
typedef basic_ios_iostate_saver<wchar_t> wios_iostate_saver;
|
|
typedef basic_ios_exception_saver<char> ios_exception_saver;
|
|
typedef basic_ios_exception_saver<wchar_t> wios_exception_saver;
|
|
typedef basic_ios_tie_saver<char> ios_tie_saver;
|
|
typedef basic_ios_tie_saver<wchar_t> wios_tie_saver;
|
|
typedef basic_ios_rdbuf_saver<char> ios_rdbuf_saver;
|
|
typedef basic_ios_rdbuf_saver<wchar_t> wios_rdbuf_saver;
|
|
typedef basic_ios_fill_saver<char> ios_fill_saver;
|
|
typedef basic_ios_fill_saver<wchar_t> wios_fill_saver;
|
|
typedef basic_ios_locale_saver<char> ios_locale_saver;
|
|
typedef basic_ios_locale_saver<wchar_t> wios_locale_saver;
|
|
typedef basic_ios_all_saver<char> ios_all_saver;
|
|
typedef basic_ios_all_saver<wchar_t> wios_all_saver;
|
|
|
|
class ios_iword_saver;
|
|
class ios_pword_saver;
|
|
class ios_all_word_saver;
|
|
|
|
}
|
|
}
|
|
</pre></blockquote>
|
|
|
|
<h2><a name="base_savers">Savers for Basic Standard Attributes</a></h2>
|
|
|
|
<p>The basic saver classes have this format:</p>
|
|
|
|
<blockquote><pre>class <var>saver_class</var>
|
|
{
|
|
typedef std::ios_base state_type;
|
|
typedef <i>implementation_defined</i> aspect_type;
|
|
|
|
explicit saver_class( state_type &s );
|
|
saver_class( state_type &s, <var>aspect_type</var> const &new_value );
|
|
~saver_class();
|
|
};
|
|
</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>
|
|
|
|
<table border="1" align="center">
|
|
<caption>Basic IOStreams State Saver Classes</caption>
|
|
<tr>
|
|
<th>Class</th>
|
|
<th>Saved Attribute</th>
|
|
<th>Attribute Type</th>
|
|
<th>Reading Method</th>
|
|
<th>Writing Method</th>
|
|
</tr>
|
|
<tr>
|
|
<td><code>boost::io::ios_flags_saver</code></td>
|
|
<td>Format control flags</td>
|
|
<td><code>std::ios_base::fmtflags</code></td>
|
|
<td><code>flags</code></td>
|
|
<td><code>flags</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>boost::io::ios_precision_saver</code></td>
|
|
<td>Number of digits to print after decimal point</td>
|
|
<td><code>std::streamsize</code></td>
|
|
<td><code>precision</code></td>
|
|
<td><code>precision</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>boost::io::ios_width_saver</code></td>
|
|
<td>Minimum field width for printing objects</td>
|
|
<td><code>std::streamsize</code></td>
|
|
<td><code>width</code></td>
|
|
<td><code>width</code></td>
|
|
</tr>
|
|
</table>
|
|
|
|
<h2><a name="adv_savers">Savers for Advanced Standard Attributes</a></h2>
|
|
|
|
<p>The saver class templates have this format:</p>
|
|
|
|
<blockquote><pre>template < typename Ch, class Tr >
|
|
class <var>saver_class</var>
|
|
{
|
|
typedef std::basic_ios<Ch, Tr> state_type;
|
|
typedef <i>implementation_defined</i> aspect_type;
|
|
|
|
explicit saver_class( state_type &s );
|
|
saver_class( state_type &s, <var>aspect_type</var> const &new_value );
|
|
~saver_class();
|
|
};
|
|
</pre></blockquote>
|
|
|
|
<p>The <var>state_type</var> is a version of the IOStreams base class template <code>std::basic_ios<Ch, Tr></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>
|
|
<tr>
|
|
<th>Class Template</th>
|
|
<th>Saved Attribute</th>
|
|
<th>Attribute Type</th>
|
|
<th>Reading Method</th>
|
|
<th>Writing Method</th>
|
|
</tr>
|
|
<tr>
|
|
<td><code>boost::io::basic_ios_iostate_saver<Ch, Tr></code></td>
|
|
<td>Success state of the stream</td>
|
|
<td><code>std::ios_base::iostate</code></td>
|
|
<td><code>rdstate</code></td>
|
|
<td><code>clear</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>boost::io::basic_ios_exception_saver<Ch, Tr></code></td>
|
|
<td>Which success states trigger an exception <a href="#Note1">[1]</a></td>
|
|
<td><code>std::ios_base::iostate</code></td>
|
|
<td><code>exceptions</code></td>
|
|
<td><code>exceptions</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>boost::io::basic_ios_tie_saver<Ch, Tr></code></td>
|
|
<td>Output stream synchronized with the stream</td>
|
|
<td><code>std::basic_ostream<Ch, Tr> *</code></td>
|
|
<td><code>tie</code></td>
|
|
<td><code>tie</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>boost::io::basic_ios_rdbuf_saver<Ch, Tr></code></td>
|
|
<td>Stream buffer associated with the stream</td>
|
|
<td><code>std::basic_streambuf<Ch, Tr> *</code></td>
|
|
<td><code>rdbuf</code></td>
|
|
<td><code>rdbuf</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>boost::io::basic_ios_fill_saver<Ch, Tr></code></td>
|
|
<td>Character used to pad oversized field widths</td>
|
|
<td><code>Ch</code></td>
|
|
<td><code>fill</code></td>
|
|
<td><code>fill</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>boost::io::basic_ios_locale_saver<Ch, Tr></code></td>
|
|
<td>Locale information associated with the stream <a href="#Note2">[2]</a></td>
|
|
<td><code>std::locale</code></td>
|
|
<td><code>getloc</code> (from <code>std::ios_base</code>)</td>
|
|
<td><code>imbue</code> (from <code>std::basic_ios<Ch, Tr></code>)</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<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<Ch, Tr></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>
|
|
</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>
|
|
|
|
<blockquote><pre>#include <iosfwd> <i>// for std::ios_base (declaration)</i>
|
|
|
|
class <var>saver_class</var>
|
|
{
|
|
typedef std::ios_base state_type;
|
|
typedef int index_type;
|
|
typedef <i>implementation_defined</i> aspect_type;
|
|
|
|
explicit saver_class( state_type &s, index_type i );
|
|
saver_class( state_type &s, index_type i, <var>aspect_type</var> const &new_value );
|
|
~saver_class();
|
|
};
|
|
</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 <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>
|
|
<tr>
|
|
<th>Class</th>
|
|
<th>Saved Attribute</th>
|
|
<th>Attribute Type</th>
|
|
<th>Reference Method</th>
|
|
</tr>
|
|
<tr>
|
|
<td><code>boost::io::ios_iword_saver</code></td>
|
|
<td>Numeric user-defined format flag</td>
|
|
<td><code>long</code></td>
|
|
<td><code>iword</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>boost::io::ios_pword_saver</code></td>
|
|
<td>Pointer user-defined format flag</td>
|
|
<td><code>void *</code></td>
|
|
<td><code>pword</code></td>
|
|
</tr>
|
|
</table>
|
|
|
|
<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>
|
|
|
|
<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>
|
|
|
|
<blockquote><pre>#include <boost/io/ios_state.hpp>
|
|
#include <ios>
|
|
#include <iostream>
|
|
#include <ostream>
|
|
|
|
void new_hex_my_byte( std::ostream &os, char byte )
|
|
{
|
|
boost::io::ios_flags_saver ifs( os );
|
|
|
|
os << std::hex << static_cast<unsigned>(byte);
|
|
}
|
|
|
|
int main()
|
|
{
|
|
using std::cout;
|
|
|
|
//...
|
|
|
|
{
|
|
boost::io::ios_all_saver ias( cout );
|
|
|
|
new_hex_my_byte( cout, 'A' );
|
|
}
|
|
|
|
//...
|
|
}
|
|
</pre></blockquote>
|
|
|
|
<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>
|
|
</ul>
|
|
|
|
<h2><a name="credits">Credits</a></h2>
|
|
|
|
<h3><a name="contributors">Contributors</a></h3>
|
|
|
|
<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>.
|
|
</dl>
|
|
|
|
<h3><a name="history">History</a></h3>
|
|
|
|
<dl>
|
|
<dt>13 Mar 2002, Daryle Walker
|
|
<dd>Initial version
|
|
</dl>
|
|
|
|
<hr>
|
|
|
|
<p>Revised: 13 March 2002</p>
|
|
|
|
<p>Copyright © 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 "as is" without express or implied warranty, and with no claim as to its suitability for any purpose.</p>
|
|
</body>
|
|
</html> |