[boost] Re(post): About iostate.zip 5

From: Daryle Walker (darylew_at_[hidden])
Date: 2002-03-20 15:55:28

In case no one noticed (or cared) before the switch....

on 3/13/02 5:18 PM, Edward D Brey at EdwardDBrey_at_[hidden] wrote:

>> From: Beman Dawes [mailto:bdawes_at_[hidden]]
>> 
>>> Was there perhaps a message(s) that I missed that covers the specific bullet
>>> points of the various reviews?  A search in the group archive on the iostate
>>> subject brought up no messages with itemized responses.
>> 
>> I sent it to Daryle privately.  See below.  Probably should have posted it
>> publicly.
> 
> Sorry, I wasn't clear.  It is the listing of Daryle's opinions regarding each
> of these items in which I am primarily interested.

OK....

> --- begin ---
> 
> ... the ones that seem to me to be [particularly] important are:
> 
> * Docs comments such as request for simple usage examples, etc.

I added one.

> * The request from two people: "A predefined saver that saved all
> formatting adjustments would be quite nice."

I added several combined savers.

> * Naming and namespace issues.
> 
> Geoff Mountfort
> ===============
> 
> -What is your evaluation of the documentation?
> It is too much "how it was done" and not enough user level "how to use".

The rationale shows a function that may need the savers, and the example
shows how the savers can fix the problem.

> Gary Powell
> ===========
> 
> Quick Question:
> Why does it save a state_type * const s;
> vs, a state_type & ?
> If there were default constructors, and therefore a need to set a "null"
> state I'd understand that, but there aren't.

References aren't real objects, so they can't really be a part of a
structure (they're internally turned into something like pointers).  So I
had a pointer to show what was really happening.  But I've changed it now.

> - Documentation:
> Needs a couple of examples for those less proficient with iostate
> issues.
> 
> - Credits:
> I know that I saw an iostate class on c.l.c.m Do a google search, and
> list
> that person(s) as the originator in addition to Daryle Walker.
> 
> I did and found this earlier reference
> http://groups.google.com/groups?q=iostate+group:comp.lang.c%2B%2B.moderated+
> group:comp.lang.c%2B%2B.moderated&hl=en&selm=wwiuliwfky.fsf%40itga.com.au&rn
> um=5
> 
> That a
> Gregory Bond                            ITG Australia Ltd, Melbourne,
> Australia
> <mailto:gnb_at_[hidden]>
> <http://www.bby.com.au/~gnb>
> posted Date: 1998/07/01
> 
> That's not to say that Daryle didn't either re-invent the idea, or that
> it's
> become part and parcel of C++ standard usage, but I think the historical
> acknowledgement should exist.

I didn't know of this reference (until you mentioned it).  I don't know if
it should be mentioned in the docs.

> Keith Burton
> ============
> 
> Question :  could / should it offered the ability to set / unset format
> flags rather than replace them.

I want the all the saver classes to have the same basic structure.  The
capability would mean giving a particular saver class an extra constructor
(parameter).

> Beman Dawes
> ===========
> 
> Docs
> ----
> 
> The docs should begin with an "Introduction" paragraph which should include
> 
> a "hello, world" level example.
> 
> I found myself reading the header to see exactly what classes were
> supplied.  The table isn't horrible, but I'm wondering if others also found
> it a bit unclear as to what exactly is delivered?

I changed the docs to put each general saver category in a separate section,
with separate tables.

> Granularity
> -----------
> 
> The fine granularity of the savers gets in the way for certain
> applications.  For example, I've got some code like this:
> 
> //  function reports job statistics
> void my_show_stats()
> {
>   cout << ... ; // no problem
>   third_party_show_stats(); // alters state of cout:-(
>   cout << ... ; // weird things happen
> }
> 
> So I'd like to rewrite it like this:
> 
> //  function reports job statistics
> void my_show_stats()
> {
>   cout << ... ; // no problem
>   {
>       boost::io::ios_all_saver ioasvr( cout );  // save all state info
>       third_party_show_stats(); // alters state of cout
>   }
>   cout << ... ; // still no problem
> }
> 
> Unless I'm misreading the docs, I can't do that with a single saver because
> the granularity is so fine.
> 
> Instead, I'd have to write up to 11 different savers:
> 
> ios_flags_saver
> ios_precision_saver
> ios_width_saver
> ios_iostate_saver
> ios_exception_saver
> ios_tie_saver
> ios_rdbuf_saver
> ios_fill_saver
> ios_locale_saver
> ios_iword_saver
> ios_pword_saver
> 
> It isn't that the current fine granularity is wrong; it is exactly what is
> needed for some applications.  But for other applications, additional
> superset savers would seem to be useful.  Have you given this any thought?

I've added combined savers.

> Namespace and namespace issues
> ------------------------------
> 
> The submission supplies two headers - <boost/io_fwd.hpp> and
> <boost/io/iostate.hpp>
> 
> The contents of the library are placed in namespace boost::io.
> 
> For consistency, shouldn't the forward declaration header be named
> <boost/io/iostate_fwd.hpp> and placed in the boost/io subdirectory?

No.  The <boost/io_fwd.hpp> header is for everything in the boost::io
namespace.  Future libraries that go in here would change this forwarding
header too.  See the math sub-library for a current example.  The new format
library should go in next to my stuff.  (I should contact format's developer
about rearranging his headers.)  I should post my namespace, forwarding
header, and sub-library philosophy.

> Ed Brey
> =======
> 
> Library naming:
> 
> - Iostate isn't really a suitable name for the library (and hence header
> file), since iostate already has a meaning, which is more specific that what
> you are trying to cover.  (This class saves iostate, plus many other
> properties.)  Perhaps stream_state or ios_state would be better.

Changed (to ios_state).

> Documentation:
> 
> - Contents of index.html should be merged into iostate.html, since this is
> such a small library.  Having the extra level in between the main boost
> library page and the actual documentation of the library slows down
> browsing.  When the user clicks on iostate from the boost library index
> page, the first think that he should see is a brief description and a
> "Hello, world" example.

No.  See my future namespace, forwarding header, and sub-library philosophy
post.

> - The fact that the iostate.html header includes any other headers should not
> be part of the public interface.  Hence, it would be better to show it in the
> documented synopsis.  Part of the problem stems from the fact is that document
> lists a "header synopsis", which isn't exactly what the reader needs to know.
> The information that should be presented is simply a list of classes are
> guaranteed by be declared/defined when a header is included.

So what should I do here?

> Wish list:
> 
> - A predefined saver that saved all formatting adjustments would be quite
> nice.  Specifically, this would combine the savers flags, precision, width,
> fill, and locale.

Added (though not in that combination).

> - A manipulator version would be nice.  A sample usage would be:
> cout << save_stream_format << setw(5) << x;

This would involve combining saver techniques with temporary objects, which
I don't want to tackle (due to the subtle issues).

> --- end of reviews ---

-- 
Daryle Walker
Mac, Internet, and Video Game Junkie
darylew AT mac DOT com