From 664ce87016fc38275e05614ee0907b8dd40f2094 Mon Sep 17 00:00:00 2001 From: Phil Edwards Date: Thu, 21 Nov 2002 07:16:01 +0000 Subject: style.css: Update. 2002-11-21 Phil Edwards * docs/doxygen/style.css: Update. * docs/doxygen/user.cfg.in: Update. * docs/html/documentation.html: Regenerate. * docs/html/17_intro/howto.html: Tweak I/O sentry entry. * docs/html/27_io/howto.html: New section on headers. * docs/html/faq/index.html: Add i386 threading entry. * docs/html/faq/index.txt: Regenerate. * docs/html/ext/lwg-active.html, docs/html/ext/lwg-defects.html: Import R23. From-SVN: r59326 --- libstdc++-v3/docs/html/17_intro/howto.html | 5 +- libstdc++-v3/docs/html/27_io/howto.html | 133 +++++ libstdc++-v3/docs/html/documentation.html | 3 +- libstdc++-v3/docs/html/ext/lwg-active.html | 784 ++++++++++++++++++++++++-- libstdc++-v3/docs/html/ext/lwg-defects.html | 264 ++++----- libstdc++-v3/docs/html/faq/index.html | 15 +- libstdc++-v3/docs/html/faq/index.txt | 832 ++++++++++++++-------------- 7 files changed, 1451 insertions(+), 585 deletions(-) (limited to 'libstdc++-v3/docs/html') diff --git a/libstdc++-v3/docs/html/17_intro/howto.html b/libstdc++-v3/docs/html/17_intro/howto.html index 5888a54..9d10bec 100644 --- a/libstdc++-v3/docs/html/17_intro/howto.html +++ b/libstdc++-v3/docs/html/17_intro/howto.html @@ -261,8 +261,9 @@ on the --enable-libio choice: for stdio, if the written data is already in the stdio buffer, the data may be completely safe!

-

I/O sentry ctor/dtor They can perform additional work - than the minimum required. I don't think we're currently taking +

[27.6.1.1.2],
+ [27.6.2.3] The I/O sentry ctor and dtor can perform + additional work than the minimum required. We are not currently taking advantage of this yet.

[27.7.1.3]/16,
diff --git a/libstdc++-v3/docs/html/27_io/howto.html b/libstdc++-v3/docs/html/27_io/howto.html index b4a5925..d7a984e 100644 --- a/libstdc++-v3/docs/html/27_io/howto.html +++ b/libstdc++-v3/docs/html/27_io/howto.html @@ -34,6 +34,7 @@

  • More on binary I/O
  • Pathetic performance? Ditch C.
  • Threads and I/O
    • +
  • Which header?
    • @@ -558,6 +559,138 @@ "interesting" problems.

    +
    +

    Which header?

    +

    To minimize the time you have to wait on the compiler, it's good to + only include the headers you really need. Many people simply include + <iostream> when they don't need to -- and that can penalize + your runtime as well. Here are some tips on which header to use + for which situations, starting with the simplest. +

    +

    <iosfwd> should be included whenever you simply + need the name of an I/O-related class, such as + "ofstream" or "basic_streambuf". Like the name + implies, these are forward declarations. (A word to all you fellow + old school programmers: trying to forward declare classes like + "class istream;" won't work. Look in the iosfwd header if + you'd like to know why.) For example, +

    + 
    +    #include <iosfwd>
+
+    class MyClass
+    {
+        ....
+        std::ifstream   input_file;
+    };
+
+    extern std::ostream& operator<< (std::ostream&, MyClass&);
+
    +

    <ios> declares the base classes for the entire + I/O stream hierarchy, std::ios_base and std::basic_ios<charT>, the + counting types std::streamoff and std::streamsize, the file + positioning type std::fpos, and the various manipulators like + std::hex, std::fixed, std::noshowbase, and so forth. +

    +

    The ios_base class is what holds the format flags, the state flags, + and the functions which change them (setf(), width(), precision(), + etc). You can also store extra data and register callback functions + through ios_base, but that has been historically underused. Anything + which doesn't depend on the type of characters stored is consolidated + here. +

    +

    The template class basic_ios is the highest template class in the + hierarchy; it is the first one depending on the character type, and + holds all general state associated with that type: the pointer to the + polymorphic stream buffer, the facet information, etc. +

    +

    <streambuf> declares the template class + basic_streambuf, and two standard instantiations, streambuf and + wstreambuf. If you need to work with the vastly useful and capable + stream buffer classes, e.g., to create a new form of storage + transport, this header is the one to include. +

    +

    <istream>/<ostream> are + the headers to include when you are using the >>/<< + interface, or any of the other abstract stream formatting functions. + For example, +

    + 
    +    #include <istream>
+
+    std::ostream& operator<< (std::ostream& os, MyClass& c)
+    {
+       return os << c.data1() << c.data2();
+    }
+
    +

    The std::istream and std::ostream classes are the abstract parents of + the various concrete implementations. If you are only using the + interfaces, then you only need to use the appropriate interface header. +

    +

    <iomanip> provides "extractors and inserters + that alter information maintained by class ios_base and its dervied + classes," such as std::setprecision and std::setw. If you need + to write expressions like os << setw(3); or + is >> setbase(8);, you must include <iomanip>. +

    +

    <sstream>/<fstream> + declare the six stringstream and fstream classes. As they are the + standard concrete descendants of istream and ostream, you will already + know about them. +

    +

    Finally, <iostream> provides the eight standard + global objects (cin, cout, etc). To do this correctly, this header + also provides the contents of the <istream> and <ostream> + headers, but nothing else. The contents of this header look like +

    + 
    +    #include <ostream>
+    #include <istream>
+
+    namespace std
+    {
+        extern istream cin;
+        extern ostream cout;
+        ....
+
+        // this is explained below
+        static ios_base::Init __foo;    // not its real name
+    }
+
    +

    Now, the runtime penalty mentioned previously: the global objects + must be initialized before any of your own code uses them; this is + guaranteed by the standard. Like any other global object, they must + be initialized once and only once. This is typically done with a + construct like the one above, and the nested class ios_base::Init is + specified in the standard for just this reason. +

    +

    How does it work? Because the header is included before any of your + code, the __foo object is constructed before any of + your objects. (Global objects are built in the order in which they + are declared, and destroyed in reverse order.) The first time the + constructor runs, the eight stream objects are set up. +

    +

    The static keyword means that each object file compiled + from a source file containing <iostream> will have its own + private copy of __foo. There is no specified order + of construction across object files (it's one of those pesky NP + problems that make life so interesting), so one copy in each object + file means that the stream objects are guaranteed to be set up before + any of your code which uses them could run, thereby meeting the + requirements of the standard. +

    +

    The penalty, of course, is that after the first copy of + __foo is constructed, all the others are just wasted + processor time. The time spent is merely for an increment-and-test + inside a function call, but over several dozen or hundreds of object + files, that time can add up. (It's not in a tight loop, either.) +

    +

    The lesson? Only include <iostream> when you need to use one of + the standard objects in that source file; you'll pay less startup + time. Only include the header files you need to in general; your + compile times will go down when there's less parsing work to do. +

    + diff --git a/libstdc++-v3/docs/html/documentation.html b/libstdc++-v3/docs/html/documentation.html index a4a79e3..8c40fb0 100644 --- a/libstdc++-v3/docs/html/documentation.html +++ b/libstdc++-v3/docs/html/documentation.html @@ -66,7 +66,7 @@ diff --git a/libstdc++-v3/docs/html/ext/lwg-active.html b/libstdc++-v3/docs/html/ext/lwg-active.html index c8d33f3..a69d6c6 100644 --- a/libstdc++-v3/docs/html/ext/lwg-active.html +++ b/libstdc++-v3/docs/html/ext/lwg-active.html @@ -5,11 +5,11 @@ - + - + @@ -17,10 +17,10 @@ - +
    Doc. no.J16/02-0027 = WG21 N1369J16/02-0048 = WG21 N1390
    Date:10 May 200210 Sep 2002
    Project:
    Reply to:Matt Austern <austern@research.att.com>Matt Austern <austern@apple.com>
    -

    C++ Standard Library Active Issues List (Revision 22)

    +

    C++ Standard Library Active Issues List (Revision 23)

    Reference ISO/IEC IS 14882:1998(E)

    Also see: