From a66dac2ccc29e8e1b142aaa98d220502a9e046a9 Mon Sep 17 00:00:00 2001 From: Glen Fernandes Date: Fri, 13 Dec 2019 22:04:32 -0500 Subject: [PATCH] Convert documentation to asciidoc --- doc/Jamfile | 23 +++ doc/index.html | 67 ------ doc/io.adoc | 33 +++ doc/ios_state.adoc | 316 ++++++++++++++++++++++++++++ doc/ios_state.html | 468 ------------------------------------------ doc/quoted.adoc | 131 ++++++++++++ doc/quoted_manip.html | 164 --------------- index.html | 19 +- meta/libraries.json | 6 +- 9 files changed, 517 insertions(+), 710 deletions(-) create mode 100644 doc/Jamfile delete mode 100644 doc/index.html create mode 100644 doc/io.adoc create mode 100644 doc/ios_state.adoc delete mode 100644 doc/ios_state.html create mode 100644 doc/quoted.adoc delete mode 100644 doc/quoted_manip.html diff --git a/doc/Jamfile b/doc/Jamfile new file mode 100644 index 0000000..ddfa1ad --- /dev/null +++ b/doc/Jamfile @@ -0,0 +1,23 @@ +# Copyright 2019 Glen Joseph Fernandes +# (glenjofe@gmail.com) +# +# Distributed under the Boost Software License, Version 1.0. +# (http://www.boost.org/LICENSE_1_0.txt) + +import asciidoctor ; + +html span.html : span.adoc ; + +install html_ : span.html : html ; + +pdf span.pdf : span.adoc ; +explicit span.pdf ; + +install pdf_ : span.pdf : pdf ; +explicit pdf_ ; + +alias boostdoc ; +explicit boostdoc ; + +alias boostrelease : html_ ; +explicit boostrelease ; diff --git a/doc/index.html b/doc/index.html deleted file mode 100644 index 4885739..0000000 --- a/doc/index.html +++ /dev/null @@ -1,67 +0,0 @@ - - - -Boost I/O Library - - - - - - - - - - - - -
boost.png (6897 bytes)HomeLibrariesPeopleFAQMore
- -

Boost Input/Output Library

- - - - - - - - - - - - - - -
Header / DocsContents
- <boost/io_fwd.hpp> - - Forward declaration header. -
- <boost/io/ios_state.hpp>
-
documentation - 		- State-saving classes for various IOStream attributes. -
- -

Rationale

- -

The I/O sub-library of Boost helps segregate the large number of -Boost headers. This sub-library should contain various items to use -with/for the standard I/O library.

- -
- -

Revised: 26 Feb 2002

- -

Copyright 2002 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>.)

- - diff --git a/doc/io.adoc b/doc/io.adoc new file mode 100644 index 0000000..b535100 --- /dev/null +++ b/doc/io.adoc @@ -0,0 +1,33 @@ +//// +Copyright 2019 Glen Joseph Fernandes +(glenjofe@gmail.com) + +Distributed under the Boost Software License, Version 1.0. +(http://www.boost.org/LICENSE_1_0.txt) +//// + +# Boost.IO +Daryle Walker, Beman Dawes +:idprefix: +:source-language: cpp +:toc: left + +The I/O sub-library of Boost helps segregate the large number of Boost headers. +This sub-library should contain various items to use with/for the standard I/O +library. + +:leveloffset: +1 + +include::ios_state.adoc[] +include::quoted.adoc[] + +:leveloffset: -1 + +## Copyright and License + +* Copyright 2002 Daryle Walker +* Copyright 2002, 2006, 2007, 2009, 2010 Beman Dawes +* Copyright 2019 Glen Joseph Fernandes + +Distributed under the +http://www.boost.org/LICENSE_1_0.txt[Boost Software License, Version 1.0]. diff --git a/doc/ios_state.adoc b/doc/ios_state.adoc new file mode 100644 index 0000000..dec2d41 --- /dev/null +++ b/doc/ios_state.adoc @@ -0,0 +1,316 @@ +//// +Copyright 2019 Glen Joseph Fernandes +(glenjofe@gmail.com) + +Distributed under the Boost Software License, Version 1.0. +(http://www.boost.org/LICENSE_1_0.txt) +//// + +# ios_state, +:toc: +:toc-title: +:idprefix: + +## Description + +The header `` covers saving the stream state of objects +in the {cpp} IOStreams system. + +## 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 +#include + +void hex_my_byte(std::ostream& os, char byte) +{ + os << std::hex << static_cast(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 + +``` +namespace boost { +namespace io { + +class ios_flags_saver; +class ios_precision_saver; +class ios_width_saver; +class ios_base_all_saver; + +template > +class basic_ios_iostate_saver; + +template > +class basic_ios_exception_saver; + +template > +class basic_ios_tie_saver; + +template > +class basic_ios_rdbuf_saver; + +template > +class basic_ios_fill_saver; + +template > +class basic_ios_locale_saver; + +template > +class basic_ios_all_saver; + +typedef basic_ios_iostate_saver ios_iostate_saver; +typedef basic_ios_iostate_saver wios_iostate_saver; +typedef basic_ios_exception_saver ios_exception_saver; +typedef basic_ios_exception_saver wios_exception_saver; +typedef basic_ios_tie_saver ios_tie_saver; +typedef basic_ios_tie_saver wios_tie_saver; +typedef basic_ios_rdbuf_saver ios_rdbuf_saver; +typedef basic_ios_rdbuf_saver wios_rdbuf_saver; +typedef basic_ios_fill_saver ios_fill_saver; +typedef basic_ios_fill_saver wios_fill_saver; +typedef basic_ios_locale_saver ios_locale_saver; +typedef basic_ios_locale_saver wios_locale_saver; +typedef basic_ios_all_saver ios_all_saver; +typedef basic_ios_all_saver wios_all_saver; + +class ios_iword_saver; +class ios_pword_saver; +class ios_all_word_saver; + +} // io +} // boost +``` + +## Savers for Basic Standard Attributes + +The basic saver classes have this format: + +[subs=+quotes] +``` +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, const aspect_type& 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. + +.Basic IOStreams State Saver Classes +[%header,cols=5*] +|=== +|Class |Saved Attribute |Attribute Type |Reading Method |Writing Method +|`ios_flags_saver` +|Format control flags +|`std::ios_base::fmtflags` +|`flags` +|`flags` +|`ios_precision_saver` +|Number of digits to print after decimal point +|`std::streamsize` +|`precision` +|`precision` +|`ios_width_saver` +|Minimum field width for printing objects +|`std::streamsize` +|`width` +|`width` +|=== + +## Savers for Advanced Standard Attributes + +The saver class templates have this format: + +[subs=+quotes] +``` +template +class saver_class { + typedef std::basic_ios state_type; + typedef `implementation-defined` aspect_type; + + explicit saver_class(state_type& s); + saver_class(state_type& s, const aspect_type& new_value); + ~saver_class(); + + void restore(); +}; +``` + +The `state_type` is a version of the IOStreams base class template +`std::basic_ios`, 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. + +.Advanced IOStreams State Saver Class Templates +[%header,cols=5*] +|=== +|Class |Saved Attribute |Attribute Type |Reading Method |Writing Method +|`basic_ios_iostate_saver` +|Failure state of the stream [1], [2] +|`std::ios_base::iostate` +|`rdstate` +|`clear` +|`basic_ios_exception_saver` +|Which failure states trigger an exception [1] +|`std::ios_base::iostate` +|`exceptions` +|`exceptions` +|`basic_ios_tie_saver` +|Output stream synchronized with the stream +|`std::basic_ostream*` +|`tie` +|`tie` +|`basic_ios_rdbuf_saver` +|Stream buffer associated with the stream [2] +|`std::basic_streambuf*` +|`rdbuf` +|`rdbuf` +|`basic_ios_fill_saver` +|Character used to pad oversized field widths +|`Ch` +|`fill` +|`fill` +|`basic_ios_locale_saver` +|Locale information associated with the stream [3] +|`std::locale` +|`getloc` (from `std::ios_base`) +|`imbue` (from `std::basic_ios`) +|=== + +### 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` 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 + +There are three class (templates) for combined attribute savers. The +`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 `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 `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 +#include +#include +#include + +void new_hex_my_byte(std::ostream& os, char byte) +{ + boost::io::ios_flags_saver ifs(os); + os << std::hex << static_cast(byte); +} + +int main() +{ + // ... + { + boost::io::ios_all_saver ias(std::cout); + new_hex_my_byte(std::cout, 'A'); + } + // ... + { + boost::io::ios_all_saver ias(std::cerr); + new_hex_my_byte(std::cerr, 'b'); + ias.restore(); + new_hex_my_byte(std::cerr, 'C'); + } + // ... +} +``` + +## Credits + +### 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 implemented the initial version. diff --git a/doc/ios_state.html b/doc/ios_state.html deleted file mode 100644 index 9be4fa2..0000000 --- a/doc/ios_state.html +++ /dev/null @@ -1,468 +0,0 @@ - - - -I/O Stream-State Saver Library - - -

boost.png (6897 bytes)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. -
  2. Rationale
    3. -
  3. Header Synopsis
    4. -
  4. Savers for Basic Standard Attributes
    5. -
  5. Savers for Advanced Standard Attributes
    6. -
  6. Savers for User-Defined Attributes
    7. -
  7. Savers for Combined Attributes
    8. -
  8. Example
    9. -
  9. References
    10. -
  10. Credits -
    11. -
- -

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.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Basic IOStreams State Saver Classes
ClassSaved AttributeAttribute TypeReading MethodWriting Method
boost::io::ios_flags_saverFormat control flagsstd::ios_base::fmtflagsflagsflags
boost::io::ios_precision_saverNumber of digits to print after decimal pointstd::streamsizeprecisionprecision
boost::io::ios_width_saverMinimum field width for printing objectsstd::streamsizewidthwidth
- -

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.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Advanced IOStreams State Saver Class Templates
Class TemplateSaved AttributeAttribute TypeReading MethodWriting Method
boost::io::basic_ios_iostate_saver<Ch, Tr>Failure state of the stream [1], [2]std::ios_base::iostaterdstateclear
boost::io::basic_ios_exception_saver<Ch, Tr>Which failure states trigger an exception [1]std::ios_base::iostateexceptionsexceptions
boost::io::basic_ios_tie_saver<Ch, Tr>Output stream synchronized with the streamstd::basic_ostream<Ch, Tr> *tietie
boost::io::basic_ios_rdbuf_saver<Ch, Tr>Stream buffer associated with the stream [2]std::basic_streambuf<Ch, Tr> *rdbufrdbuf
boost::io::basic_ios_fill_saver<Ch, Tr>Character used to pad oversized field widthsChfillfill
boost::io::basic_ios_locale_saver<Ch, Tr>Locale information associated with the stream [3]std::localegetloc (from std::ios_base)imbue (from std::basic_ios<Ch, Tr>)
- -

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. -
  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. -
  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.
    4. -
- -

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.

- - - - - - - - - - - - - - - - - - - - - -
IOStream User-Defined State Saver Classes
ClassSaved AttributeAttribute TypeReference Method
boost::io::ios_iword_saverNumeric user-defined format flaglongiword
boost::io::ios_pword_saverPointer user-defined format flagvoid *pword
- -

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

- - - -

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>.)

- - diff --git a/doc/quoted.adoc b/doc/quoted.adoc new file mode 100644 index 0000000..19a0eab --- /dev/null +++ b/doc/quoted.adoc @@ -0,0 +1,131 @@ +//// +Copyright 2019 Glen Joseph Fernandes +(glenjofe@gmail.com) + +Distributed under the Boost Software License, Version 1.0. +(http://www.boost.org/LICENSE_1_0.txt) +//// + +# quoted, +:toc: +:toc-title: +:idprefix: + +## Introduction + +C++ Standard library stream I/O for strings that contain embedded spaces can +produce unexpected results. For example, + +``` +std::stringstream ss; +std::string original = "fooled you"; +std::string roundtrip; + +ss << original; +ss >> roundtrip; + +std::cout << original; // outputs: fooled you +std::cout << roundtrip; // outputs: fooled + +assert(original == roundtrip); // assert will fire +``` + +The Boost quoted stream I/O manipulator places delimiters, defaulted to the +double-quote ("), around strings on output, and strips off the delimiters on +input. This ensures strings with embedded spaces round-trip as desired. For +example, + +``` +std::stringstream ss; +std::string original = "fooled you"; +std::string roundtrip; + +ss << quoted(original); +ss >> quoted(roundtrip); + +std::cout << quoted(original); // outputs: "fooled you" +std::cout << roundtrip; // outputs: fooled you + +assert(original == roundtrip); // assert will not fire +``` + +If the string contains the delimiter character, on output that character will +be preceded by an escape character, as will the escape character itself: + +``` +std::cout << quoted("'Jack & Jill'", '&', '\''); // outputs: '&'Jack && Jill&'' +``` + +## Header synopsis + +[subs=+quotes] +``` +namespace boost { +namespace io { + +template +`unspecified-type1` +quoted(const std::basic_string& string, + Char escape='\\', Char delim='\"'); + +template +`unspecified-type2` +quoted(const Char* string, Char escape='\\', Char delim='\"'); + +template +`unspecified-type3` +quoted(std::basic_string& string, + Char escape='\\', Char delim='\"'); + +} // io +} // boost +``` + +*unspecified-type1*, *unspecified-type2*, and *unspecified-type3* are +implementation supplied types with implementation supplied `operator<<`: + +[subs=+quotes] +``` +template +std::basic_ostream& +operator<<(std::basic_ostream& os, + const `unspecified-typeN`& proxy); +``` + +Effects:: Inserts characters into `os`: +* `delim` +* Each character in `string`. If the character to be output is equal to +`escape` or `delim`, as determined by `operator==`, first output `escape`. +* `delim` +Remarks:: `string`, `escape`, and `delim` have the type and value of the +corresponding arguments of the call to the `quoted` function that constructed +`proxy`. +Returns:: `os`. + +*unspecified-type3* is an implementation supplied type with an implementation +supplied `operator>>`: + +[subs=+quotes] +``` +template +std::basic_istream& +operator>>(std::basic_istream& is, + const `unspecified-type3`& proxy); +``` + +Effects:: Extracts characters from `os`: +* If the first character extracted is equal to `delim`, as determined by +`operator==`, then: +** Turn off the `skipws` flag. +** `string.clear()` +** Until an unescaped `delim` character is reached or `is.not_good()`, extract +characters from `os` and append them to string, except that if an escape is +reached, ignore it and append the next character to string. +** Discard the final `delim` character. +** Restore the `skipws` flag to its original value. +* Otherwise, `os >> string`. + +Remarks:: `string`, `escape`, and `delim` have the type and value of the +corresponding arguments of the call to the `quoted` function that constructed +`proxy`. +Returns:: `is`. diff --git a/doc/quoted_manip.html b/doc/quoted_manip.html deleted file mode 100644 index fc50042..0000000 --- a/doc/quoted_manip.html +++ /dev/null @@ -1,164 +0,0 @@ - - - - - - Boost "quoted" I/O manipulator - - - - - - - - - - - - - -
boost.png (6897 bytes) -

"Quoted" - I/O Manipulators
- for Strings

-
- - - - - -
-

"Quoted" - I/O Manipulators - for Strings are not yet accepted into Boost as public components. Thus the - header file is currently located in <boost/io/detail/quoted_manip.hpp>

- -

Introduction

-

C++ Standard library stream I/O for strings that contain embedded spaces -can produce unexpected results. For example,

-
- 
std::stringstream ss;
-std::string original = "fooled you";
-std::string round_trip;
-
-ss << original;
-ss >> round_trip;
-
-std::cout << original;   // outputs: fooled you
-std::cout << round_trip; // outputs: fooled
-
-assert(original == round_trip); // assert will fire
-
-

The Boost quoted stream I/O manipulator places delimiters, defaulted -to the double-quote ("), around strings on output, and strips off -the delimiters on input. This ensures strings with embedded spaces round-trip as -desired. For example,

-
- 
std::stringstream ss;
-std::string original = "fooled you";
-std::string round_trip;
-
-ss << quoted(original);
-ss >> quoted(round_trip);
-
-std::cout << quoted(original); // outputs: "fooled you"
-std::cout << round_trip;       // outputs: fooled you
-
-assert(original == round_trip); // assert will not fire
-
-

If the string contains the delimiter character, on output that character will -be preceded by an escape character, as will the escape character itself:

-
- 
std::cout << quoted("'Jack & Jill'", '&', '\'');  // outputs: '&'Jack && Jill&''
-
-

Header <boost/io/quoted_manip.hpp> synopsis

-
namespace boost
-{
-  namespace io
-  {
-    // manipulator for const std::basic_string&
-
-    template <class Char, class Traits, class Alloc>
-    unspecified-type1 quoted(const std::basic_string<Char, Traits, Alloc>& string,
-                             Char escape='\\', Char delim='\"');
-
-    // manipulator for const C-string*
-
-    template <class Char>
-    unspecified-type2 quoted(const Char* string,
-                             Char escape='\\', Char delim='\"');
-
-    // manipulator for non-const std::basic_string&
-
-    template <class Char, class Traits, class Alloc>
-    unspecified-type3 quoted(std::basic_string<Char, Traits, Alloc>& string,
-                             Char escape='\\', Char delim='\"');
-  }
-}
-

unspecified_type1, unspecified_type2, -and unspecified_type3 are implementation supplied -types with implementation supplied operator<<:

-
- 
template <class Char, class Traits>
-  std::basic_ostream<Char, Traits>&
-    operator<<(std::basic_ostream<Char, Traits>& os, const unspecified_typeN& proxy);
-

Effects: Inserts characters into os:

-
    -
  • delim.
    • -
  • Each character in string. If the character to be output is - equal to escape or delim, as determined by - operator==, first output escape.
    • -
  • delim.
    • -
-

Remarks: string, escape, and delim -have the type and value of the corresponding arguments of the call to the -quoted function that constructed proxy.

-

Returns: os.

-
-

unspecified_type3 is an implementation supplied -type with an implementation supplied operator>>:

-
- 
template <class Char, class Traits>
-  std::basic_istream<Char, Traits>&
-    operator>>(std::basic_istream<Char, Traits>& is, const unspecified_type3& proxy);
-

Effects: Extracts characters from os:

-
    -
  • If the first character extracted is equal to delim, as determined by - operator==, then:
      -
    • Turn off the skipws flag.
      • -
    • string.clear()
      • -
    • Until an unescaped delim character is reached or - is.not_good(), extract - characters from os and append them to string, - except that if an escape is reached, ignore it and append the - next character to string.
      • -
    • Discard the final delim character.
      • -
    • Restore the skipws flag to its original value.
      • -
    -
    • -
  • Otherwise, os >> string.
    • -
-

Remarks: string, escape, and delim -have the type and value of the corresponding arguments of the call to the -quoted function that constructed proxy.

-

Returns: is.

-
-

Acknowledgements

-

The quoted() stream manipulator emerged from discussions on the -Boost developers mailing list. Participants included Beman Dawes, Rob Stewart, -Alexander Lamaison, Eric Niebler, Vicente Botet, Andrey Semashev, Phil Richards, -and Rob Murray. Eric Niebler's suggestions provided the basis for the name and -form of the templates.

-
-

Copyright Beman Dawes, 2002, 2006, 2007, 2009, 2010

-

Distributed under the Boost Software License, Version 1.0. See -www.boost.org/LICENSE_1_0.txt

-

Revised -08 March 2013

- - - diff --git a/index.html b/index.html index 098815d..caa266d 100644 --- a/index.html +++ b/index.html @@ -1,14 +1,17 @@ + + - + + +Span -Automatic redirection failed, please go to -doc/index.html. 
-

Copyright Beman Dawes, 2001

-

Distributed under the Boost Software License, Version 1.0. (See accompanying -file LICENSE_1_0.txt or copy -at www.boost.org/LICENSE_1_0.txt) -

+Redirecting you to IO. diff --git a/meta/libraries.json b/meta/libraries.json index 1e2b3e9..3259e18 100644 --- a/meta/libraries.json +++ b/meta/libraries.json @@ -2,10 +2,10 @@ "key": "io", "name": "IO State Savers", "authors": [ - "Daryle Walker" + "Daryle Walker", + "Beman Dawes" ], - "description": "The I/O sub-library of Boost helps segregate the large number of Boost headers. This sub-library should contain various items to use with/for the standard I/O library.", - "documentation": "doc/ios_state.html", + "description": "Utilities for using the standard I/O library.", "category": [ "IO" ],