1 //// 2 Copyright 2019 Glen Joseph Fernandes 3 (glenjofe@gmail.com) 4 5 Distributed under the Boost Software License, Version 1.0. 6 (http://www.boost.org/LICENSE_1_0.txt) 7 //// 8 9 # IO State Savers, <boost/io/ios_state.hpp> 10 :toc: 11 :toc-title: 12 :idprefix: 13 14 ## Description 15 16 The header `<boost/io/ios_state.hpp>` covers saving the stream state of objects 17 in the {cpp} IOStreams system. 18 19 ## Rationale 20 21 Sometimes a certain value has to change only for a limited scope. Saver classes 22 save a copy of the current state of some object (or an aspect of an object), 23 and reset the object's state at destruction time, undoing any change the object 24 may have gone through. 25 26 The saver class strategy is helpful when using I/O stream objects. Manipulator 27 objects can change some aspect of a stream during input or output. The state 28 changed by the manipulator usually sticks to its new value after the I/O 29 transaction. This can be a problem if manipulators are used in a function that 30 is not supposed to externally change a stream's state. 31 32 ``` 33 #include <ostream> 34 #include <ios> 35 36 void hex_my_byte(std::ostream& os, char byte) 37 { 38 os << std::hex << static_cast<unsigned>(byte); 39 } 40 ``` 41 42 The `os` stream will retain its new hexadecimal printing mode after the call to 43 `hex_my_byte`. The stream's printing mode can be saved and restored with manual 44 calls to the stream's state inspecting and mutating member functions. The 45 manual method becomes unwieldy if the main functionality is complex and/or 46 needs to be exception safe. A saver class can implement the better 47 "resource acquisition is initialization" strategy. 48 49 See the example below for better code, using saver classes. 50 51 ## Header Synopsis 52 53 ``` 54 namespace boost { 55 namespace io { 56 57 class ios_flags_saver; 58 class ios_precision_saver; 59 class ios_width_saver; 60 class ios_base_all_saver; 61 62 template<class Ch, class Tr = std::char_traits<Ch> > 63 class basic_ios_iostate_saver; 64 65 template<class Ch, class Tr = std::char_traits<Ch> > 66 class basic_ios_exception_saver; 67 68 template<class Ch, class Tr = std::char_traits<Ch> > 69 class basic_ios_tie_saver; 70 71 template<class Ch, class Tr = std::char_traits<Ch> > 72 class basic_ios_rdbuf_saver; 73 74 template<class Ch, class Tr = std::char_traits<Ch> > 75 class basic_ios_fill_saver; 76 77 template<class Ch, class Tr = std::char_traits<Ch> > 78 class basic_ios_locale_saver; 79 80 template<class Ch, class Tr = std::char_traits<Ch> > 81 class basic_ios_all_saver; 82 83 typedef basic_ios_iostate_saver<char> ios_iostate_saver; 84 typedef basic_ios_iostate_saver<wchar_t> wios_iostate_saver; 85 typedef basic_ios_exception_saver<char> ios_exception_saver; 86 typedef basic_ios_exception_saver<wchar_t> wios_exception_saver; 87 typedef basic_ios_tie_saver<char> ios_tie_saver; 88 typedef basic_ios_tie_saver<wchar_t> wios_tie_saver; 89 typedef basic_ios_rdbuf_saver<char> ios_rdbuf_saver; 90 typedef basic_ios_rdbuf_saver<wchar_t> wios_rdbuf_saver; 91 typedef basic_ios_fill_saver<char> ios_fill_saver; 92 typedef basic_ios_fill_saver<wchar_t> wios_fill_saver; 93 typedef basic_ios_locale_saver<char> ios_locale_saver; 94 typedef basic_ios_locale_saver<wchar_t> wios_locale_saver; 95 typedef basic_ios_all_saver<char> ios_all_saver; 96 typedef basic_ios_all_saver<wchar_t> wios_all_saver; 97 98 class ios_iword_saver; 99 class ios_pword_saver; 100 class ios_all_word_saver; 101 102 } // io 103 } // boost 104 ``` 105 106 ## Savers for Basic Standard Attributes 107 108 The basic saver classes have this format: 109 110 [subs=+quotes] 111 ``` 112 class saver { 113 public: 114 typedef std::ios_base state_type; 115 typedef `implementation_defined` aspect_type; 116 117 explicit saver(state_type& s); 118 saver(state_type& s, const aspect_type& new_value); 119 ~saver(); 120 121 void restore(); 122 }; 123 ``` 124 125 The `state_type` is the IOStreams base class `std::ios_base`. The user would 126 usually place an actual input, output, or combined stream object for the 127 state-type parameter, and not a base class object. The first constructor takes 128 a stream object and saves a reference to the stream and the current value of a 129 particular stream attribute. The second constructor works like the first, and 130 uses its second argument to change the stream's attribute to the new 131 `aspect_type` value given. The destructor restores the stream's attribute to 132 the saved value. The restoration can be activated early (and often) with the 133 `restore` member function. 134 135 .Basic IOStreams State Saver Classes 136 [%header,cols=5*] 137 |=== 138 |Class |Saved Attribute |Attribute Type |Reading Method |Writing Method 139 |`ios_flags_saver` 140 |Format control flags 141 |`std::ios_base::fmtflags` 142 |`flags` 143 |`flags` 144 |`ios_precision_saver` 145 |Number of digits to print after decimal point 146 |`std::streamsize` 147 |`precision` 148 |`precision` 149 |`ios_width_saver` 150 |Minimum field width for printing objects 151 |`std::streamsize` 152 |`width` 153 |`width` 154 |=== 155 156 ## Savers for Advanced Standard Attributes 157 158 The saver class templates have this format: 159 160 [subs=+quotes] 161 ``` 162 template<class Ch, class Tr> 163 class saver { 164 public: 165 typedef std::basic_ios<Ch, Tr> state_type; 166 typedef `implementation-defined` aspect_type; 167 168 explicit saver(state_type& s); 169 saver(state_type& s, const aspect_type& new_value); 170 ~saver(); 171 172 void restore(); 173 }; 174 ``` 175 176 The `state_type` is a version of the IOStreams base class template 177 `std::basic_ios<Ch, Tr>`, where `Ch` is a character type and `Tr` is a 178 character traits class. The user would usually place an actual input, 179 output, or combined stream object for the state-type parameter, and not a base 180 class object. The first constructor takes a stream object and saves a reference 181 to the stream and the current value of a particular stream attribute. The 182 second constructor works like the first, and uses its second argument to change 183 the stream's attribute to the new `aspect_type` value given. The destructor 184 restores the stream's attribute to the saved value. The restoration can be 185 activated early (and often) with the `restore` member function. 186 187 .Advanced IOStreams State Saver Class Templates 188 [%header,cols=5*] 189 |=== 190 |Class |Saved Attribute |Attribute Type |Reading Method |Writing Method 191 |`basic_ios_iostate_saver<Ch, Tr>` 192 |Failure state of the stream [1], [2] 193 |`std::ios_base::iostate` 194 |`rdstate` 195 |`clear` 196 |`basic_ios_exception_saver<Ch, Tr>` 197 |Which failure states trigger an exception [1] 198 |`std::ios_base::iostate` 199 |`exceptions` 200 |`exceptions` 201 |`basic_ios_tie_saver<Ch, Tr>` 202 |Output stream synchronized with the stream 203 |`std::basic_ostream<Ch, Tr>*` 204 |`tie` 205 |`tie` 206 |`basic_ios_rdbuf_saver<Ch, Tr>` 207 |Stream buffer associated with the stream [2] 208 |`std::basic_streambuf<Ch, Tr>*` 209 |`rdbuf` 210 |`rdbuf` 211 |`basic_ios_fill_saver<Ch, Tr>` 212 |Character used to pad oversized field widths 213 |`Ch` 214 |`fill` 215 |`fill` 216 |`basic_ios_locale_saver<Ch, Tr>` 217 |Locale information associated with the stream [3] 218 |`std::locale` 219 |`getloc` (from `std::ios_base`) 220 |`imbue` (from `std::basic_ios<Ch, Tr>`) 221 |=== 222 223 ### Notes 224 225 1. When the failure state flags and/or the failure state exception watching 226 flags are changed, an exception is thrown if a match occurs among the two sets 227 of flags. This could mean that the constructor or destructor of these class 228 templates may throw. 229 2. When the associated stream buffer is changed, the stream's failure state set 230 is reset to "good" if the given stream buffer's address is non-NULL, but the 231 "bad" failure state is set if that address is NULL. This means that a saved 232 failure state of "good" may be restored as "bad" if the stream is stripped of 233 an associated stream buffer. Worse, given a NULL stream buffer address, an 234 exception is thrown if the "bad" failure state is being watched. This could 235 mean that the constructor or destructor of these class templates may throw. 236 3. The saver for the locale uses the `std::basic_ios<Ch, Tr>` class to extract 237 their information, although it could have used the functionality in 238 `std::ios_base`. The problem is that the versions of the needed member 239 functions in `ios_base` are not polymorphically related to the ones in 240 `basic_ios`. The stream classes that will be used with the saver classes should 241 use the versions of the member functions closest to them by inheritance, which 242 means the ones in `basic_ios`. 243 244 ## Savers for User-Defined Attributes 245 246 There are three class (templates) for combined attribute savers. The 247 `ios_base_all_saver` saver class combines the functionality of all the basic 248 attribute saver classes. It has a constructor that takes the stream to have its 249 state preserved. The `basic_ios_all_saver` combines the functionality of all 250 the advanced attribute saver class templates and the combined basic attribute 251 saver class. It has a constructor that takes the stream to have its state 252 preserved. The `ios_all_word_saver` saver class combines the saver classes that 253 preserve user-defined formatting information. Its constructor takes the stream 254 to have its attributes saved and the index of the user-defined attributes. The 255 destructor for each class restores the saved state. Restoration can be 256 activated early (and often) for a class with the restore member function. 257 258 ## Example 259 260 The code used in the rationale can be improved at two places. The printing 261 function could use a saver around the code that changes the formatting state. 262 Or the calling function can surround the call with a saver. Or both can be 263 done, especially if the user does not know if the printing function uses a 264 state saver. If the user wants a series of changes back and forth, without 265 surrounding each change within a separate block, the restore member function 266 can be called between each trial. 267 268 ``` 269 #include <boost/io/ios_state.hpp> 270 #include <ios> 271 #include <iostream> 272 #include <ostream> 273 274 void new_hex_my_byte(std::ostream& os, char byte) 275 { 276 boost::io::ios_flags_saver ifs(os); 277 os << std::hex << static_cast<unsigned>(byte); 278 } 279 280 int main() 281 { 282 // ... 283 { 284 boost::io::ios_all_saver ias(std::cout); 285 new_hex_my_byte(std::cout, 'A'); 286 } 287 // ... 288 { 289 boost::io::ios_all_saver ias(std::cerr); 290 new_hex_my_byte(std::cerr, 'b'); 291 ias.restore(); 292 new_hex_my_byte(std::cerr, 'C'); 293 } 294 // ... 295 } 296 ``` 297 298 ## Credits 299 300 ### Daryle Walker 301 302 Started the library. Contributed the initial versions of the format flags, 303 precision, width, and user-defined format flags saver classes. Contributed the 304 initial versions of the success state, success state exception flags, output 305 stream tie, stream buffer, character fill, and locale saver class templates. 306 Contributed the combined attribute classes and class template. Contributed the 307 test file `ios_state_test.cpp`. 308 309 ## History 310 311 ### 20 Dec 2019 312 313 Glen Fernandes made all the saver classes non-copyable. 314 315 ### 28 Feb 2005 316 317 Daryle Walker added the restore member functions, based on suggestions by 318 Gennadiy Rozental and Rob Stewart. 319 320 ### 13 Mar 2002 321 322 Daryle Walker implemented the initial version. 323