diff --git a/doc/ios_state.html b/doc/ios_state.html
index a09bea2..4799f33 100644
--- a/doc/ios_state.html
+++ b/doc/ios_state.html
@@ -4,34 +4,48 @@
I/O Stream-State Saver Library
-
+
-The header boost/io/ios_state.hpp covers saving the stream state of objects in the C++ IOStreams system.
+The header boost/io/ios_state.hpp
+covers saving the stream state of objects in the C++ IOStreams
+system.
- - Contents
-
- Rationale
-
- Header Synopsis
+
- Contents
+ - Rationale
+ - Header Synopsis
- Savers for Basic Standard Attributes
- Savers for Advanced Standard Attributes
- Savers for User-Defined Attributes
- Savers for Combined Attributes
- Example
- - References
+
- References
- Credits
+
- Contributors
+ - History
+
-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.
+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.
-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.
+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.
#include <ostream>
#include <ios>
@@ -42,11 +56,16 @@ void hex_my_byte( std::ostream &os, char byte )
}
-The os stream will retain its new hexadecimal printing mode after the call to hex_my_byte
. 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
+
The os stream will retain its new hexadecimal printing
+mode after the call to hex_my_byte
. 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.
-See the example below for better code, using a saver
-class.
+See the example below for better code, using
+saver classes.
@@ -115,7 +134,15 @@ class ios_all_word_saver;
};
-The state_type is the IOStreams base class std::ios_base
. 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 aspect_type value given. The destructor changes the stream's attribute back to the saved value.
+The state_type is the IOStreams base class
+std::ios_base
. 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 aspect_type value given. The destructor changes the
+stream's attribute back to the saved value.
Basic IOStreams State Saver Classes
@@ -165,7 +192,17 @@ class saver_class
};
-The state_type is a version of the IOStreams base class template std::basic_ios<Ch, Tr>
, where Ch
is a character type and Tr
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 aspect_type value given. The destructor changes the stream's attribute back to the saved value.
+The state_type is a version of the IOStreams base class
+template std::basic_ios<Ch, Tr>
, where
+Ch
is a character type and Tr
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
+aspect_type value given. The destructor changes the stream's
+attribute back to the saved value.
Advanced IOStreams State Saver Class Templates
@@ -178,7 +215,7 @@ class saver_class
boost::io::basic_ios_iostate_saver<Ch, Tr> |
- Success state of the stream |
+ Success state of the stream [1] |
std::ios_base::iostate |
rdstate |
clear |
@@ -223,15 +260,27 @@ class saver_class
Notes
- - 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 destructor of this class template may throw.
- - The saver for the locale uses the
std::basic_ios<Ch, Tr>
class to extract their information, although it could have used the functionality in std::ios_base
. The problem is that the versions of the needed member functions in ios_base
are not
- polymorphicly related to the ones in basic_ios
. 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 basic_ios
.
+ - 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 destructor of these class templates may
+ throw.
+ - The saver for the locale uses the
+
std::basic_ios<Ch, Tr>
class to extract their
+ information, although it could have used the functionality
+ in std::ios_base
. The problem is that the versions
+ of the needed member functions in ios_base
are not
+ polymorphically related to the ones in basic_ios
.
+ 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
+ basic_ios
.
-The saver classes for user-defined formatting information have this format:
+The saver classes for user-defined formatting information have this
+format:
#include <iosfwd> // for std::ios_base (declaration)
@@ -247,9 +296,20 @@ class saver_class
};
-The index i differentiates between specific user-defined formatting attributes. The index can only be determined at run-time (most likely with the class-static std::ios_base::xalloc
member function).
+The index i differentiates between specific user-defined
+formatting attributes. The index can only be determined at run-time
+(most likely with the class-static std::ios_base::xalloc
+member function).
-The state_type is the base class of the IOStreams system, std::ios_base
. 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 aspect_type value given. The destructor changes the stream's attribute back to the saved value.
+The state_type is the base class of the IOStreams system,
+std::ios_base
. 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 aspect_type value given. The destructor
+changes the stream's attribute back to the saved value.
IOStream User-Defined State Saver Classes
@@ -275,11 +335,26 @@ class saver_class
-There are three class (templates) for combined attribute savers. The boost:io::ios_base_all_saver
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 boost::io::basic_ios_all_saver
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 boost::io::ios_all_word_saver
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.
+There are three class (templates) for combined attribute savers. The
+boost:io::ios_base_all_saver
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
+boost::io::basic_ios_all_saver
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
+boost::io::ios_all_word_saver
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.
-The code used in the rationale 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.
+The code used in the rationale 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.
#include <boost/io/ios_state.hpp>
#include <ios>
@@ -312,8 +387,10 @@ int main()
@@ -322,7 +399,14 @@ int main()
- Daryle Walker
-
- 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 ios_state_test.cpp.
+
- 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 ios_state_test.cpp.
@@ -336,6 +420,10 @@ int main()
Revised: 13 March 2002
-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.
+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.