Boost logo

Boost :

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.


> --- 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
> group:comp.lang.c%2B%2B.moderated&hl=en&
> um=5
> That a
> Gregory Bond ITG Australia Ltd, Melbourne,
> Australia
> <mailto:gnb_at_[hidden]>
> <>
> 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

> 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

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

Boost list run by bdawes at, gregod at, cpdaniel at, john at