Header <boost/io/ios_state.hpp >

The header boost/io/ios_state.hpp covers saving the stream state of objects in the C++ IOStreams system.

Contents

1. Contents
2. Rationale
3. Header Synopsis
4. Savers for Basic Standard Attributes
5. Savers for Advanced Standard Attributes
6. Savers for User-Defined Attributes
7. Savers for Combined Attributes
8. Example
9. References
10. Credits
    • Contributors
    • History

Rationale

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.

#include <ostream>
#include <ios>

void  hex_my_byte( std::ostream &os, char byte )
{
    os << std::hex << static_cast<unsigned>(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 acquisition is initialization" strategy.

See the example below for better code, using saver classes.

Header Synopsis

#include <iosfwd>  // for std::char_traits (declaration)

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;

}
}

Savers for Basic Standard Attributes

The basic saver classes have this format:

class saver_class
{
    typedef std::ios_base           state_type;
    typedef implementation_defined  aspect_type;

    explicit  saver_class( state_type &s );
              saver_class( state_type &s, aspect_type const &new_value );
             ~saver_class();

    void  restore();
};

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 restores the stream's attribute to the saved value. The restoration can be activated early (and often) with the restore member function.

Savers for Advanced Standard Attributes

The saver class templates have this format:

template < typename Ch, class Tr >
class saver_class
{
    typedef std::basic_ios<Ch, Tr>  state_type;
    typedef implementation_defined  aspect_type;

    explicit  saver_class( state_type &s );
              saver_class( state_type &s, aspect_type const &new_value );
             ~saver_class();

    void  restore();
};

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 restores the stream's attribute to the saved value. The restoration can be activated early (and often) with the restore member function.

Notes

1. When the failure state flags and/or the failure state exception watching flags are changed, an exception is thrown if a match occurs among the two sets of flags. This could mean that the constructor or destructor of these class templates may throw.
2. When the associated stream buffer is changed, the stream's failure state set is reset to "good" if the given stream buffer's address is non-NULL, but the "bad" failure state is set if that address is NULL. This means that a saved failure state of "good" may be restored as "bad" if the stream is stripped of an associated stream buffer. Worse, given a NULL stream buffer address, an exception is thrown if the "bad" failure state is being watched. This could mean that the constructor or destructor of these class templates may throw.
3. 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.

Savers for User-Defined Attributes

The saver classes for user-defined formatting information have this format:

#include <iosfwd>  // for std::ios_base (declaration)

class saver_class
{
    typedef std::ios_base           state_type;
    typedef int                     index_type;
    typedef implementation_defined  aspect_type;

    explicit  saver_class( state_type &s, index_type i );
              saver_class( state_type &s, index_type i, aspect_type const &new_value );
             ~saver_class();

    void  restore();
};

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 restores the stream's attribute to the saved value. The restoration can be activated early (and often) with the restore member function.

Savers for Combined 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 destructor for each class restores the saved state. Restoration can be activated early (and often) for a class with the restore member function.

Example

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, especially if the user does not know if the printing function uses a state saver. If the user wants a series of changes back & forth, without surrounding each change within a separate block, the restore member function can be called between each trial.

#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;
    using std::cerr;

    //...

    {
        boost::io::ios_all_saver  ias( cout );

        new_hex_my_byte( cout, 'A' );
    }

    //...

    {
        boost::io::ios_all_saver  ias( cerr );

        new_hex_my_byte( cerr, 'b' );
        ias.restore();
        new_hex_my_byte( cerr, 'C' );
    }

    //...
}

References

• The I/O state saver library header itself: boost/io/ios_state.hpp
• Some test/example code: ios_state_test.cpp

Credits

Contributors

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.

History

28 Feb 2005, Daryle Walker

Added the restore member functions, based on suggestions by Gennadiy Rozental and Rob Stewart

13 Mar 2002, Daryle Walker

Initial version

Revised: 28 February 2005

Copyright 2002, 2005 Daryle Walker. Use, modification, and distribution are subject to the Boost Software License, Version 1.0. (See accompanying file LICENSE_1_0.txt or a copy at <http://www.boost.org/LICENSE_1_0.txt>.)