howto.html: Add anchor name.

2001-09-25  Phil Edwards  <pme@gcc.gnu.org>

	* docs/html/20_util/howto.html:  Add anchor name.
	* docs/html/23_containers/howto.html:  Line wrapping, another link.
	* docs/html/25_algorithms/howto.html:  Another note.

	* docs/html/ext/howto.html:  Link to SGI extensions.  List DRs and
	link to them...
	* docs/html/ext/lwg-active.html:  ...in this new file (from R19),
	* docs/html/ext/lwg-defects.html:  and this new file (from R19).
	* docs/html/ext/sgiexts.html:  New file.  Mention SGI extensions
	carried over to libstdc++-v3.
	* docs/html/faq/index.html:  Link to SGI extensions.  Mention the
	"missing .." pseudobug.
	* docs/html/faq/index.txt:  Regenerate.

	* include/bits/ios_base.h:  DR-related comment cleanup.
	* include/bits/istream.tcc:  Likewise.
	* include/bits/locale_facets.h:  Likewise.
	* include/bits/locale_facets.tcc:  Likewise.
	* include/bits/ostream.tcc:  Likewise.
	* include/bits/std_bitset.h:  Likewise.
	* include/bits/std_iosfwd.h:  Likewise.
	* include/bits/std_istream.h:  Likewise.
	* include/bits/std_ostream.h:  Likewise.
	* include/bits/std_streambuf.h:  Likewise.
	* include/bits/stl_pair.h:  Likewise.
	* include/bits/streambuf_iterator.h:  Likewise.

	* include/bits/std_map.h:  Remove unused header inclusion guard
	_CPP_BITS_STL_TREE_H from around bits/stl_tree.h.
	* include/bits/std_set.h:  Likewise.

	* include/bits/stl_function.h:  Doxygen markup.
	* docs/doxygen/doxygroups.cc:  New file, specifying module grouping.
	* libsupc++/typeinfo:  Doxygen markup tweak.

From-SVN: r45816

libstdc++-v3/ChangeLog

+2001-09-25  Phil Edwards  <pme@gcc.gnu.org>
+
+	* docs/html/20_util/howto.html:  Add anchor name.
+	* docs/html/23_containers/howto.html:  Line wrapping, another link.
+	* docs/html/25_algorithms/howto.html:  Another note.
+
+	* docs/html/ext/howto.html:  Link to SGI extensions.  List DRs and
+	link to them...
+	* docs/html/ext/lwg-active.html:  ...in this new file (from R19),
+	* docs/html/ext/lwg-defects.html:  and this new file (from R19).
+	* docs/html/ext/sgiexts.html:  New file.  Mention SGI extensions
+	carried over to libstdc++-v3.
+	* docs/html/faq/index.html:  Link to SGI extensions.  Mention the
+	"missing .." pseudobug.
+	* docs/html/faq/index.txt:  Regenerate.
+
+	* include/bits/ios_base.h:  DR-related comment cleanup.
+	* include/bits/istream.tcc:  Likewise.
+	* include/bits/locale_facets.h:  Likewise.
+	* include/bits/locale_facets.tcc:  Likewise.
+	* include/bits/ostream.tcc:  Likewise.
+	* include/bits/std_bitset.h:  Likewise.
+	* include/bits/std_iosfwd.h:  Likewise.
+	* include/bits/std_istream.h:  Likewise.
+	* include/bits/std_ostream.h:  Likewise.
+	* include/bits/std_streambuf.h:  Likewise.
+	* include/bits/stl_pair.h:  Likewise.
+	* include/bits/streambuf_iterator.h:  Likewise.
+
+	* include/bits/std_map.h:  Remove unused header inclusion guard
+	_CPP_BITS_STL_TREE_H from around bits/stl_tree.h.
+	* include/bits/std_set.h:  Likewise.
+
+	* include/bits/stl_function.h:  Doxygen markup.
+	* docs/doxygen/doxygroups.cc:  New file, specifying module grouping.
+	* libsupc++/typeinfo:  Doxygen markup tweak.
+
 2001-09-20  Scott Johnston <scott@accom.com>
 	    Peter Schmid <schmid@snake.iap.physik.tu-darmstadt.de>
 

libstdc++-v3/docs/doxygen/doxygroups.cc

+
+// This just provides documentation for stuff that doesn't need to be in the
+// source headers themselves.  It is a ".cc" file for the sole cheesy reason
+// that it triggers many different text editors into doing Nice Things when
+// typing comments.  However, it is mentioned nowhere except the *cfg.in files.
+
+/** @addtogroup SGIextensions
+ *
+ *  Because libstdc++-v3 based its implementation of the STL subsections of
+ *  the library on the SGI 3.3 implementation, we inherited their extensions
+ *  as well.
+ *
+ *  They are additionally documented in the
+ *  <a href="http://gcc.gnu.org/onlinedocs/libstdc++/documentation.html">
+ *  online documentation</a>, a copy of which is also shipped with the
+ *  library source code (in .../docs/html/documentation.html).  You can also
+ *  read the documentation <a href="http://www.sgi.com/tech/stl/">on SGI's
+ *  site</a>, which is still running even though the code is not maintained.
+ *
+ *  <strong>NB</strong> that the following notes are pulled from various
+ *  comments all over the place, so they may seem stilted.
+ *  <hr>
+*/
+

libstdc++-v3/docs/html/20_util/howto.html

@@ -8,7 +8,7 @@
    <meta NAME="GENERATOR" CONTENT="vi and eight fingers">
    <title>libstdc++-v3 HOWTO:  Chapter 20</title>
 <link REL=StyleSheet HREF="../lib3styles.css">
-<!-- $Id: howto.html,v 1.4 2001/05/30 21:55:00 pme Exp $ -->
+<!-- $Id: howto.html,v 1.5 2001/09/17 23:24:39 pme Exp $ -->
 </head>
 <body>
 
@@ -171,6 +171,7 @@
       <code>operator==</code> functions (for types like MyClass) or builtin
       comparisons (for types like int, char, etc).
    </p>
+   <a name="pairlt">
    <p>The less-than operator is a bit odd the first time you see it.  It
       is defined as evaluating to:
       <PRE>
@@ -180,6 +181,7 @@
       The other operators are not defined using the <code>rel_ops</code>
       functions above, but their semantics are the same.
    </p>
+   </a>
    <p>Finally, there is a template function called <code>make_pair</code>
       that takes two references-to-const objects and returns an
       instance of a pair instantiated on their respective types:
@@ -200,7 +202,7 @@
 <P CLASS="fineprint"><em>
 Comments and suggestions are welcome, and may be sent to
 <a href="mailto:libstdc++@gcc.gnu.org">the mailing list</a>.
-<br> $Id: howto.html,v 1.4 2001/05/30 21:55:00 pme Exp $
+<br> $Id: howto.html,v 1.5 2001/09/17 23:24:39 pme Exp $
 </em></p>
 
 

libstdc++-v3/docs/html/23_containers/howto.html

@@ -8,7 +8,7 @@
    <meta NAME="GENERATOR" CONTENT="vi and eight fingers">
    <title>libstdc++-v3 HOWTO:  Chapter 23</title>
 <link REL=StyleSheet HREF="../lib3styles.css">
-<!-- $Id: howto.html,v 1.8 2001/09/15 00:41:11 pme Exp $ -->
+<!-- $Id: howto.html,v 1.9 2001/09/17 23:24:39 pme Exp $ -->
 </head>
 <body>
 
@@ -140,7 +140,8 @@
    <p><B>A container&lt;bool&gt;.&nbsp;&nbsp;</B>  The Committee made provision
       for the space savings possible with that (N/8) usage previously mentioned,
       so that you don't have to do wasteful things like
-      <code>Container&lt;char&gt;</code> or <code>Container&lt;short int&gt;</code>.
+      <code>Container&lt;char&gt;</code> or
+      <code>Container&lt;short int&gt;</code>.
       Specifically, <code>vector&lt;bool&gt;</code> is required to be
       specialized for that space savings.
    </p>
@@ -158,12 +159,14 @@
    <p><B>Extremely weird solutions.&nbsp;&nbsp;</B>  If you have access to
       the compiler and linker at runtime, you can do something insane, like
       figuring out just how many bits you need, then writing a temporary 
-      source code file.  That file contains an instantiation of <code>bitset</code>
+      source code file.  That file contains an instantiation of
+      <code>bitset</code>
       for the required number of bits, inside some wrapper functions with
       unchanging signatures.  Have your program then call the
       compiler on that file using Position Independant Code, then open the
       newly-created object file and load those wrapper functions.  You'll have
-      an instantiation of <code>bitset&lt;N&gt;</code> for the exact <code>N</code>
+      an instantiation of <code>bitset&lt;N&gt;</code> for the exact
+      <code>N</code>
       that you need at the time.  Don't forget to delete the temporary files.
       (Yes, this <em>can</em> be, and <em>has been</em>, done.)
    </p>
@@ -178,6 +181,9 @@
       along the lines of the third category, the author would love to hear
       from you...
    </p>
+   <p>Also note that the implementation of bitset used in libstdc++-v3 has
+      <a href="../ext/sgiexts.html#ch23">some extensions</a>.
+   </p>
    <p>Return <a href="#top">to top of page</a> or
       <a href="../faq/index.html">to the FAQ</a>.
    </p>
@@ -363,7 +369,7 @@
 <P CLASS="fineprint"><em>
 Comments and suggestions are welcome, and may be sent to
 <a href="mailto:libstdc++@gcc.gnu.org">the mailing list</a>.
-<br> $Id: howto.html,v 1.8 2001/09/15 00:41:11 pme Exp $
+<br> $Id: howto.html,v 1.9 2001/09/17 23:24:39 pme Exp $
 </em></p>
 
 

libstdc++-v3/docs/html/25_algorithms/howto.html

@@ -8,7 +8,7 @@
    <meta NAME="GENERATOR" CONTENT="vi and eight fingers">
    <title>libstdc++-v3 HOWTO:  Chapter 25</title>
 <link REL=StyleSheet HREF="../lib3styles.css">
-<!-- $Id: howto.html,v 1.4 2001/09/15 00:41:11 pme Exp $ -->
+<!-- $Id: howto.html,v 1.5 2001/09/17 23:24:39 pme Exp $ -->
 </head>
 <body>
 
@@ -24,7 +24,7 @@
 <h1>Contents</h1>
 <ul>
    <li><a href="#1">Prerequisites</a>
-   <li><a href="#2">Topic</a>
+   <li><a href="#2">Special <code>swap</code>s</a>
 </ul>
 
 <hr>
@@ -71,8 +71,18 @@
    </p>
 
 <hr>
-<h2><a name="2">Topic</a></h2>
-   <p>Blah.
+<h2><a name="2">Special <code>swap</code>s</a></h2>
+   <p>If you call <code> std::swap(x,y); </code> where x and y are standard
+      containers, then the call will automatically be replaced by a call to
+      <code> x.swap(y); </code> instead.
+   </p>
+   <p>This allows member functions of each container class to take over, and
+      containers' swap functions should have O(1) complexity according to
+      the standard.  (And while &quot;should&quot; allows implementations to
+      behave otherwise and remain compliant, this implementation does in
+      fact use constant-time swaps.)  This should not be surprising, since
+      for two containers of the same type to swap contents, only some
+      internal pointers to storage need to be exchanged.
    </p>
    <p>Return <a href="#top">to top of page</a> or
       <a href="../faq/index.html">to the FAQ</a>.
@@ -87,7 +97,7 @@
 <P CLASS="fineprint"><em>
 Comments and suggestions are welcome, and may be sent to
 <a href="mailto:libstdc++@gcc.gnu.org">the mailing list</a>.
-<br> $Id: howto.html,v 1.4 2001/09/15 00:41:11 pme Exp $
+<br> $Id: howto.html,v 1.5 2001/09/17 23:24:39 pme Exp $
 </em></p>
 
 

libstdc++-v3/docs/html/ext/howto.html

@@ -8,7 +8,7 @@
    <meta NAME="GENERATOR" CONTENT="vi and eight fingers">
    <title>libstdc++-v3 HOWTO:  Extensions</title>
 <link REL=StyleSheet HREF="../lib3styles.css">
-<!-- $Id: howto.html,v 1.5 2001/05/30 21:55:04 pme Exp $ -->
+<!-- $Id: howto.html,v 1.6 2001/09/17 23:24:40 pme Exp $ -->
 </head>
 <body>
 
@@ -37,9 +37,10 @@
 <h1>Contents</h1>
 <ul>
    <li><a href="#1">Ropes and trees and hashes, oh my!</a>
-   <li><a href="#2">Added members</a>
+   <li><a href="#2">Added members and types</a>
    <li><a href="#3">Allocators</a>
    <li><a href="#4">Compile-time checks</a>
+   <li><a href="#5">LWG Issues</a>
 </ul>
 
 <hr>
@@ -106,15 +107,19 @@
    </p>
 
 <hr>
-<h2><a name="2">Added members</a></h2>
+<h2><a name="2">Added members and types</a></h2>
    <p>Some of the classes in the Standard Library have additional
-      publicly-available members.  Of those, some are intended purely for
-      the implementors, for example, additional typedefs.  Those won't be
-      described here (or anywhere else).  This list will grow slowly, since
-      we expect it to be rare -- most extensions will be self-contained.
+      publicly-available members, and some classes are themselves not in
+      the standard.  Of those, some are intended purely for the implementors,
+      for example, additional typedefs.  Those won't be described here
+      (or anywhere else).
    </p>
    <p>
     <ul>
+     <li>The extensions added by SGI are so numerous that they have
+         <a href="sgiexts.html">their own page</a>.  Since the SGI STL is no
+         longer actively maintained, we will try and keep this code working
+         ourselves.
      <li><code>filebuf</code>s have another ctor with this signature:<br>
 <code>basic_filebuf(__c_file_type*, ios_base::openmode, int_type);</code>
          <br>This comes in very handy in a number of places, such as
@@ -157,7 +162,149 @@
       <a href="../faq/index.html">to the FAQ</a>.
    </p>
 
+<hr>
+<h2><a name="5">LWG Issues</a></h2>
+   <p>Everybody's got issues.  Even the C++ Standard Library.
+   </p>
+   <p>The Library Working Group, or LWG, is the ISO subcommittee responsible
+      for making changes to the library.  They periodically publish an
+      Issues List containing problems and possible solutions.  As they reach
+      a consensus on proposed solutions, we often incorporate the solution
+      into libstdc++-v3.
+   </p>
+   <p>Here are the issues which have resulted in code changes to the library.
+      The links are to the specific defect reports from a <strong>partial
+      copy </strong> of the
+      Issues List.  You can read the full version online at the ISO C++
+      Committee homepage, linked to on the GCC &quot;Readings&quot; page.  If
+      you spend a lot of time reading the issues, we recommend downloading
+      the ZIP file and reading them locally.
+   </p>
+   <p>(NB:  <strong>partial copy</strong> means that not all links within
+      the lwg-*.html pages will work.
+      Specifically, links to defect reports that have not been accorded full
+      DR status will probably break.  Rather than trying to mirror the
+      entire issues list on our overworked web server, we recommend you go
+      to the LWG homepage instead.)
+   </p>
+   <p>
+      If a DR is not listed here, we may simply not have gotten to it yet;
+      feel free to submit a patch.  Search the include/bits and src
+      directories for appearances of _GLIBCPP_RESOLVE_LIB_DEFECTS for
+      examples of style.  Note that we usually do not make changes to the code
+      until an issue has reached <a href="lwg-active.html#DR">DR</a> status.
+   </p>
+   <p><dl>
+<!-- FIXME:  locale_facets.h/tcc has a fix for get/num_get which I can't ID. -->
+
+    <dt><a href="lwg-defects.html#5">5</a>:
+        <em>string::compare specification questionable</em>
+    <dd>This should be two overloaded functions rather than a single function.
+
+    <dt><a href="lwg-defects.html#17">17</a>:
+        <em>Bad bool parsing</em>
+    <dd>Apparently extracting Boolean values was messed up...
+
+    <dt><a href="lwg-defects.html#25">25</a>:
+        <em>String operator&lt;&lt; uses width() value wrong</em>
+    <dd>Padding issues.
+
+    <dt><a href="lwg-defects.html#48">48</a>:
+        <em>Use of non-existent exception constructor</em>
+    <dd>An instance of <code>ios_base::failure</code> is constructed instead.
+
+    <dt><a href="lwg-defects.html#49">49</a>:
+        <em>Underspecification of ios_base::sync_with_stdio</em>
+    <dd>The return type is the <em>previous</em> state of synchronization.
+
+    <dt><a href="lwg-defects.html#50">50</a>:
+        <em>Copy constructor and assignment operator of ios_base</em>
+    <dd>These members functions are declared <code>private</code> and are
+        thus inaccessible.  Specifying the correct semantics of
+        &quot;copying stream state&quot; was deemed too complicated.
+
+    <dt><a href="lwg-defects.html#68">68</a>:
+        <em>Extractors for char* should store null at end</em>
+    <dd>And they do now.  An editing glitch in the last item in the list of
+        [27.6.1.2.3]/7.
+
+    <dt><a href="lwg-defects.html#74">74</a>:
+        <em>Garbled text for codecvt::do_max_length</em>
+    <dd>The text of the standard was gibberish.  Typos gone rampant.
+
+    <dt><a href="lwg-defects.html#83">83</a>:
+        <em>string::npos vs. string::max_size()</em>
+    <dd>Safety checks on the size of the string should test against
+        <code>max_size()</code> rather than <code>npos</code>.
 
+    <dt><a href="lwg-defects.html#109">109</a>:
+        <em>Missing binders for non-const sequence elements</em>
+    <dd>The <code>binder1st</code> and <code>binder2nd</code> didn't have an
+        <code>operator()</code> taking a non-const parameter.
+
+    <dt><a href="lwg-defects.html#110">110</a>:
+        <em>istreambuf_iterator::equal not const</em>
+    <dd>This was not a const member function.  Note that the DR says to
+        replace the function with a const one; we have instead provided an
+        overloaded version with identical contents.
+
+    <dt><a href="lwg-defects.html#129">129</a>:
+        <em>Need error indication from seekp() and seekg()</em>
+    <dd>These functions set <code>failbit</code> on error now.
+
+    <dt><a href="lwg-defects.html#136">136</a>:
+        <em>seekp, seekg setting wrong streams?</em>
+    <dd><code>seekp</code> should only set the output stream, and
+        <code>seekg</code> should only set the input stream.
+
+<!--<dt><a href="lwg-defects.html#159">159</a>:
+        <em>Strange use of underflow()</em>
+    <dd>In fstream.tcc, the basic_filebuf&lt;&gt;::showmanyc() function
+        should probably not be calling <code>underflow()</code>.-->
+
+    <dt><a href="lwg-active.html#167">167</a>:
+        <em>Improper use of traits_type::length()</em>
+    <dd><code>op&lt;&lt;</code> with a <code>const char*</code> was
+        calculating an incorrect number of characters to write.
+
+    <dt><a href="lwg-defects.html#181">181</a>:
+        <em>make_pair() unintended behavior</em>
+    <dd>This function used to take its arguments as reference-to-const, now
+        it copies them (pass by value).
+
+    <dt><a href="lwg-defects.html#195">195</a>:
+        <em>Should basic_istream::sentry's constructor ever set eofbit?</em>
+    <dd>Yes, it can, specifically if EOF is reached while skipping whitespace.
+
+    <dt><a href="lwg-defects.html#211">211</a>:
+        <em>operator&gt;&gt;(istream&amp;, string&amp;) doesn't set failbit</em>
+    <dd>If nothing is extracted into the string, <code>op&gt;&gt;</code> now
+        sets <code>failbit</code> (which can cause an exception, etc, etc).
+
+    <dt><a href="lwg-defects.html#214">214</a>:
+        <em>set::find() missing const overload</em>
+    <dd>Both <code>set</code> and <code>multiset</code> were missing
+        overloaded find, lower_bound, upper_bound, and equal_range functions
+        for const instances.
+
+    <dt><a href="lwg-defects.html#251">251</a>:
+        <em>basic_stringbuf missing allocator_type</em>
+    <dd>This nested typdef was originally not specified.
+
+    <dt><a href="lwg-defects.html#265">265</a>:
+        <em>std::pair::pair() effects overly restrictive</em>
+    <dd>The default ctor would build its members from copies of temporaries;
+        now it simply uses their respective default ctors.
+
+<!--
+    <dt><a href="lwg-defects.html#"></a>:
+        <em></em>
+    <dd>
+
+-->
+   </dl></p>
+   <p>Return <a href="#top">to top of page</a> or
+      <a href="../faq/index.html">to the FAQ</a>.
 
 
 <!-- ####################################################### -->
@@ -166,7 +313,7 @@
 <P CLASS="fineprint"><em>
 Comments and suggestions are welcome, and may be sent to
 <a href="mailto:libstdc++@gcc.gnu.org">the mailing list</a>.
-<br> $Id: howto.html,v 1.5 2001/05/30 21:55:04 pme Exp $
+<br> $Id: howto.html,v 1.6 2001/09/17 23:24:40 pme Exp $
 </em></p>
 
 

libstdc++-v3/docs/html/ext/sgiexts.html

+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN">
+<html>
+<head>
+   <meta NAME="AUTHOR" CONTENT="pme@gcc.gnu.org (Phil Edwards)">
+   <meta NAME="KEYWORDS" CONTENT="libstdc++, libstdc++-v3, GCC, g++, STL, SGI">
+   <meta NAME="DESCRIPTION" CONTENT="SGI extensions preserved in libstdc++-v3.">
+   <meta NAME="GENERATOR" CONTENT="vi and eight fingers">
+   <title>SGI extensions to the library in libstdc++-v3</title>
+<link REL=StyleSheet HREF="lib3styles.css">
+<!-- $Id: explanations.html,v 1.2 2001/09/17 23:24:38 pme Exp $ -->
+</head>
+<body>
+
+<h1 CLASS="centered"><a name="top">SGI extensions to the library in
+libstdc++-v3</a></h1>
+
+<p>This page describes the extensions that SGI made to their version of the
+   STL subset of the Standard C++ Library.  For a time we
+   <a href="../faq/index.html#5_3">tracked and imported changes and updates
+   from most of the SGI STL</a>, up through their (apparently) final release.
+   Their extensions were mostly preserved.
+</p>
+
+<p>They are listed according to the chapters of the library that they
+   extend (see <a href="../documentation.html#3">the chapter-specific notes</a>
+   for a description).  Not every chapter may have extensions, and the
+   extensions may come and go.  Also, this page is incomplete because the
+   author is pressed for time.  Check back often; the latest change was on
+   $Date$ (UTC).
+</p>
+
+<p>Descriptions range from the scanty to the verbose.  You should also check
+   the <a href="../documentation.html#4">generated documentation</a> for notes
+   and comments, especially for entries marked with '*'.  For more complete
+   doumentation, see the SGI website.  For <em>really</em> complete
+   documentation, buy a copy of Matt Austern's book.  *grin*
+</p>
+
+<p>Back to the <a href="howto.html">libstdc++-v3 extensions</a>.
+
+
+<!-- ####################################################### -->
+<hr>
+<a name="ch20"><h3>Chapter 20</h3></a>
+<p>The &lt;functional&gt; header contains many additional functors and
+   helper functions, extending section 20.3.  They are implemented in the
+   file stl_function.h:
+ <ul>
+  <li><code>identity_element</code> for addition and multiplication. *
+  <li>The functor <code>identity</code>, whose op() returns the argument
+      unchanged. *
+  <li>Composition functors <code>unary_function</code> and
+      <code>binary_function</code>, and their helpers <code>compose1</code>
+      and <code>compose2</code>. *
+  <li><code>select1st</code> and <code>select2nd</code>, to strip pairs. *
+  <li><code>project1st</code> and <code>project2nd</code>. *
+  <li>A set of functors/functions which always return the same result.  They
+      are <code>constant_void_fun, constant_binary_fun, constant_unary_fun,
+      constant0, constant1, and constant2. *
+  <li>The class <code>subtractive_rng</code>. *
+  <li>mem_fun adaptor helpers mem_fun1 and mem_fun1_ref are provided for
+      backwards compatibility.
+</ul></p>
+<p>20.4.3 is extended with a special version of
+   <code>get_temporary_buffer</code> taking a second argument.  The argument
+   is a pointer, which is ignored, but can be used to specify the template
+   type (instead of using explicit function template arguments like the
+   standard version does).  That is, in addition to
+   <pre>
+   get_temporary_buffer&lt;int&gt;(5);</pre>
+   you can also use
+   <pre>
+   get_temporary_buffer(5, (int*)0);</pre>
+</p>
+<p>A class <code>temporary_buffer</code> is given in stl_tempbuf.h. *
+</p>
+<p>The specialized algorithms of section 20.4.4 are extended with
+   <code>uninitialized_copy_n</code>. *
+</p>
+<p>Return <a href="howto.html">to the main extensions page</a> or
+   <a href="http://gcc.gnu.org/libstdc++/">to the homepage</a>.
+</p>
+
+
+<hr>
+<a name="ch23"><h3>Chapter 23</h3></a>
+<p>A few extensions and nods to backwards-compatability have been made with
+   containers.  Those dealing with older SGI-style allocators are dealt with
+   elsewhere.  The remaining ones all deal with bits:
+</p>
+<p>The old pre-standard <code>bit_vector</code> class is present for
+   backwards compatibility.  It is simply a typedef for the
+   <code>vector&lt;bool&gt;</code> specialization.
+</p>
+<p>The <code>bitset</code> class has a number of extensions, described in the
+   rest of this item.  First, we'll mention that this implementation of
+   <code>bitset&lt;N&gt;</code> is specialized for cases where N number of
+   bits will fit into a single word of storage.  If your choice of N is
+   within that range (&lt;=32 on i686-pc-linux-gnu, for example), then all
+   of the operations will be faster.
+</p>
+<p>There are
+   versions of single-bit test, set, reset, and flip member functions which
+   do no range-checking.  If we call them member functions of an instantiation
+   of &quot;bitset&lt;N&gt;,&quot; then their names and signatures are:
+   <pre>
+   bitset&lt;N&gt;&amp;   _Unchecked_set   (size_t pos);
+   bitset&lt;N&gt;&amp;   _Unchecked_set   (size_t pos, int val);
+   bitset&lt;N&gt;&amp;   _Unchecked_reset (size_t pos);
+   bitset&lt;N&gt;&amp;   _Unchecked_flip  (size_t pos);
+   bool         _Unchecked_test  (size_t pos);</pre>
+   Note that these may in fact be removed in the future, although we have
+   no present plans to do so (and there doesn't seem to be any immediate
+   reason to).
+</p>
+<p>
+   The semantics of member function <code>operator[]</code> are not specified 
+   in the C++ standard.  A long-standing defect report calls for sensible
+   obvious semantics, which are already implemented here:  <code>op[]</code>
+   on a const bitset returns a bool, and for a non-const bitset returns a
+   <code>reference</code> (a nested type).  However, this implementation does
+   no range-checking on the index argument, which is in keeping with other
+   containers' <code>op[]</code> requirements.  The defect report's proposed
+   resolution calls for range-checking to be done.  We'll just wait and see...
+</p>
+<p>Finally, two additional searching functions have been added.  They return
+   the index of the first &quot;on&quot; bit, and the index of the first
+   &quot;on&quot; bit that is after <code>prev</code>, respectively:
+   <pre>
+   size_t _Find_first() const;
+   size_t _Find_next (size_t prev) const;</pre>
+   The same caveat given for the _Unchecked_* functions applies here also.
+</p>
+<p>Return <a href="howto.html">to the main extensions page</a> or
+   <a href="http://gcc.gnu.org/libstdc++/">to the homepage</a>.
+</p>
+
+
+<hr>
+<a name="ch24"><h3>Chapter 24</h3></a>
+<p>24.3.2 describes <code>struct iterator</code>, which didn't exist in the
+   original HP STL implementation (the language wasn't rich enough at the
+   time).  For backwards compatibility, base classes are provided which
+   declare the same nested typedefs:
+   <ul>
+    <li>input_iterator
+    <li>output_iterator
+    <li>forward_iterator
+    <li>bidirectional_iterator
+    <li>random_access_iterator
+   </ul>
+</p>
+<p>24.3.4 describes iterator operation <code>distance</code>, which takes
+   two iterators and returns a result.  It is extended by another signature
+   which takes two iterators and a reference to a result.  The result is
+   modified, and the function returns nothing.
+</p>
+<p>Return <a href="howto.html">to the main extensions page</a> or
+   <a href="http://gcc.gnu.org/libstdc++/">to the homepage</a>.
+</p>
+
+
+<hr>
+<a name="ch25"><h3>Chapter 25</h3></a>
+<p>25.1.6 (count, count_if) is extended with two more versions of count
+   and count_if.  The standard versions return their results.  The
+   additional signatures return void, but take a final parameter by
+   reference to which they assign their results, e.g.,
+   <pre>
+   void count (first, last, value, n);</pre>
+</p>
+<p>25.2 (mutating algorithms) is extended with two families of signatures,
+   random_sample and random_sample_n.
+</p>
+<p>25.2.1 (copy) is extended with
+   <pre>
+   copy_n (_InputIter first, _Size count, _OutputIter result);</pre>
+   which copies the first 'count' elements at 'first' into 'result'.
+</p>
+<p>25.3 (sorting 'n' heaps 'n' stuff) is extended with some helper
+   predicates.  Look in the doxygen-generated pages for notes on these.
+   <ul>
+    <li><code>is_heap</code> tests whether or not a range is a heap.
+    <li><code>is_sorted</code> tests whether or not a range is sorted in
+        nondescending order.
+   </ul>
+</p>
+<p>25.3.8 (lexigraphical_compare) is extended with
+   <pre>
+   lexicographical_compare_3way(_InputIter1 first1, _InputIter1 last1,
+                                 _InputIter2 first2, _InputIter2 last2)</pre>
+   which does... what?
+</p>
+<p>Return <a href="howto.html">to the main extensions page</a> or
+   <a href="http://gcc.gnu.org/libstdc++/">to the homepage</a>.
+</p>
+
+
+<hr>
+<a name="ch26"><h3>Chapter 26</h3></a>
+<p>26.4, the generalized numeric operations such as accumulate, are extended
+   with the following functions:
+   <pre>
+   power (x, n);
+   power (x, n, moniod_operation);</pre>
+   Returns, in FORTRAN syntax, &quot;x ** n&quot; where n&gt;=0.  In the
+   case of n == 0, returns the <a href="#ch20">identity element</a> for the
+   monoid operation.  The two-argument signature uses multiplication (for
+   a true &quot;power&quot; implementation), but addition is supported as well.
+   The operation functor must be associative.
+</p>
+<p>The <code>iota</code> function wins the award for Extension With the
+   Coolest Name.  It &quot;assigns sequentially increasing values to a range.
+   That is, it assigns value to *first, value + 1 to *(first + 1) and so
+   on.&quot;  Quoted from SGI documentation.
+   <pre>
+   void iota(_ForwardIter first, _ForwardIter last, _Tp value);</pre>
+</p>
+<p>Return <a href="howto.html">to the main extensions page</a> or
+   <a href="http://gcc.gnu.org/libstdc++/">to the homepage</a>.
+</p>
+
+
+<!-- ####################################################### -->
+
+<hr>
+<P CLASS="fineprint"><em>
+$Id: explanations.html,v 1.2 2001/09/17 23:24:38 pme Exp $
+</em></p>
+
+
+</body>
+</html>

libstdc++-v3/docs/html/faq/index.html

@@ -9,7 +9,7 @@
   ** Locations of "the most recent snapshot is the Nth" text are 
   ** answers 1_1, 1_4, 4_1, 5_6.
 -->
-<!-- $Id: index.html,v 1.10 2001/07/18 21:37:06 pme Exp $ -->
+<!-- $Id: index.html,v 1.11 2001/09/17 23:24:40 pme Exp $ -->
 </head>
 <body>
 
@@ -368,6 +368,25 @@ which is no longer available, thanks deja...-->
    the mailing list or look through recent archives.   The RELEASE-
    NOTES and BUGS files are generally kept up-to-date.</em> 
 
+   <p>For 3.0.1, the most common &quot;bug&quot; is an apparently missing
+      &quot;<code>../</code>&quot; in include/Makefile, resulting in files
+      like gthr.h and gthr-single.h not being found.
+   </p>
+   <p>Please read
+      <a href="http://gcc.gnu.org/install/configure.html">the configuration
+      instructions for GCC</a>,
+      specifically the part about configuring in a seperate build directory,
+      and how strongly recommended it is.  Building in the source directory
+      is fragile, is rarely tested, and tends to break, as in this case.
+      Work has already gone into the source tree to make this less painful
+      for the next release.
+   </p>
+   <p><strong>Please do not report this as a bug.  We know about it.</strong>
+      Reporting this -- or any other problem that's already been fixed --
+      hinders the development of GCC, because we have to take time to
+      respond to your report.  Thank you.
+   </p>
+
    <h2><a name="4_1">4.1 What works already?</a></h2>
       <p>This is a verbatim clip from the &quot;Status&quot; section
           of the RELEASE-NOTES for the latest snapshot.
@@ -572,7 +591,8 @@ http://clisp.cons.org/~haible/gccinclude-glibc-2.2-compat.diff
          libstdc++.  Some of that is already happening, see 4.2.  Some of
          those changes are being predicted by the library maintainers, and
          we add code to the library based on what the current proposed
-         resolution specifies.
+         resolution specifies.  Those additions are listed in
+	 <a href="../ext/howto.html#5">the extensions page</a>.
       </p>
       <li><p>Performance tuning.  Lots of performance tuning.  This too is
          already underway for post-3.0 releases, starting with memory
@@ -678,7 +698,7 @@ HREF="http://gcc.gnu.org/ml/libstdc++/1999/msg00084.html">speculation</a>.
 <P CLASS="fineprint"><em>
 Comments and suggestions are welcome, and may be sent to
 <a href="mailto:libstdc++@gcc.gnu.org">the mailing list</a>.
-<br> $Id: index.html,v 1.10 2001/07/18 21:37:06 pme Exp $
+<br> $Id: index.html,v 1.11 2001/09/17 23:24:40 pme Exp $
 </em></p>
 
 

libstdc++-v3/include/bits/ios_base.h

@@ -146,7 +146,7 @@ namespace std
     {
     public:
 #ifdef _GLIBCPP_RESOLVE_LIB_DEFECTS
-      // Can't do exception(_msg) as defined in 27.4.2.1.1
+      //48.  Use of non-existent exception constructor
       explicit 
       failure(const string& __str) throw();
 
@@ -397,6 +397,7 @@ namespace std
     ios_base();
 
 #ifdef _GLIBCPP_RESOLVE_LIB_DEFECTS
+  //50.  Copy constructor and assignment operator of ios_base
   private:
     ios_base(const ios_base&);
 

libstdc++-v3/include/bits/istream.tcc

@@ -1176,7 +1176,7 @@ namespace std
 	  __in.width(0);
 	}
 #ifdef _GLIBCPP_RESOLVE_LIB_DEFECTS
-// 2000-02-01 Number to be determined
+//211.  operator>>(istream&, string&) doesn't set failbit
       if (!__extracted)
 	__in.setstate (ios_base::failbit);
 #endif

libstdc++-v3/include/bits/locale_facets.h

@@ -580,6 +580,7 @@ namespace std
       { return do_get(__in, __end, __io, __err, __v); }
 
 #ifdef _GLIBCPP_RESOLVE_LIB_DEFECTS
+      //XXX.  What number?
       iter_type 
       get(iter_type __in, iter_type __end, ios_base& __io,
 	  ios_base::iostate& __err, short& __v) const
@@ -661,6 +662,7 @@ namespace std
       do_get(iter_type, iter_type, ios_base&, ios_base::iostate&, bool&) const;
 
 #ifdef _GLIBCPP_RESOLVE_LIB_DEFECTS
+      //XXX.  What number?
       virtual iter_type 
       do_get(iter_type, iter_type, ios_base&, ios_base::iostate&, short&) const;
       virtual iter_type 

libstdc++-v3/include/bits/locale_facets.tcc

@@ -663,6 +663,7 @@ namespace std
 
 #ifdef _GLIBCPP_RESOLVE_LIB_DEFECTS
   // NB: This is an unresolved library defect #17
+  //17.  Bad bool parsing
   template<typename _CharT, typename _InIter>
     _InIter
     num_get<_CharT, _InIter>::
@@ -734,6 +735,7 @@ namespace std
 #endif
 
 #ifdef _GLIBCPP_RESOLVE_LIB_DEFECTS
+  //XXX.  Which number?  Presumably same as in locale_facets.h...
   template<typename _CharT, typename _InIter>
     _InIter
     num_get<_CharT, _InIter>::

libstdc++-v3/include/bits/ostream.tcc

@@ -644,6 +644,7 @@ namespace std
       typedef basic_ostream<_CharT, _Traits> __ostream_type;
 #ifdef _GLIBCPP_RESOLVE_LIB_DEFECTS
 // 167.  Improper use of traits_type::length()
+// Note that this is only in 'Review' status.
       typedef char_traits<char>		     __ctraits_type;
 #endif
       typename __ostream_type::sentry __cerb(__out);

libstdc++-v3/include/bits/std_bitset.h

@@ -55,11 +55,6 @@
 // individual bits.  This allows us to specialize _Base_bitset for the
 // important special case where the bitset is only a single word.
 
-// The C++ standard does not define the precise semantics of operator[].
-// In this implementation the const version of operator[] is equivalent
-// to test(), except that it does no range checking.  The non-const version
-// returns a reference to a bit, again without doing any range checking.
-
 
 #include <bits/std_cstddef.h>     // for size_t
 #include <bits/std_cstring.h>     // for memset
@@ -618,6 +613,9 @@ public:
 
   // element access:
   //for b[i];
+  // _GLIBCPP_RESOLVE_LIB_DEFECTS Note that this implementation already
+  // resolves DR 11 (items 1 and 2), but does not do the range-checking
+  // required by that DR's resolution.  -pme
   reference operator[](size_t __pos) { return reference(*this,__pos); }
   bool operator[](size_t __pos) const { return _Unchecked_test(__pos); }
 

libstdc++-v3/include/bits/std_iosfwd.h

@@ -93,7 +93,7 @@ namespace std
     class ostreambuf_iterator;
 
 #ifdef _GLIBCPP_RESOLVE_LIB_DEFECTS
-  // Not included.
+  // Not included.   (??? Apparently no LWG number?)
   class ios_base; 
 #endif
 

libstdc++-v3/include/bits/std_istream.h

@@ -202,7 +202,7 @@ namespace std
 
     private:
 #ifdef _GLIBCPP_RESOLVE_LIB_DEFECTS
-      // Not defined.
+      // Not defined.  (Side effect of DR 50.)
       __istream_type& 
       operator=(const __istream_type&);
 

libstdc++-v3/include/bits/std_map.h

@@ -58,9 +58,7 @@
 
 #pragma GCC system_header
 
-#ifndef _CPP_BITS_STL_TREE_H  
 #include <bits/stl_tree.h>
-#endif
 #include <bits/stl_map.h>
 #include <bits/stl_multimap.h>
 

libstdc++-v3/include/bits/std_ostream.h

@@ -170,7 +170,7 @@ namespace std
 
     private:
 #ifdef _GLIBCPP_RESOLVE_LIB_DEFECTS
-      // Not defined.
+      // Not defined.  (Side effect of DR 50.)
       __ostream_type& 
       operator=(const __ostream_type&);
 

libstdc++-v3/include/bits/std_set.h

@@ -58,9 +58,7 @@
 
 #pragma GCC system_header
 
-#ifndef _CPP_BITS_STL_TREE_H  /* XXX is this guard needed? */
 #include <bits/stl_tree.h>
-#endif
 #include <bits/stl_set.h>
 #include <bits/stl_multiset.h>
 

libstdc++-v3/include/bits/std_streambuf.h

@@ -513,6 +513,7 @@ namespace std
 #endif
 
 #ifdef _GLIBCPP_RESOLVE_LIB_DEFECTS
+    // Side effect of DR 50.
     private:
       basic_streambuf(const __streambuf_type&);
 

libstdc++-v3/include/bits/stl_pair.h

@@ -95,7 +95,7 @@ inline bool operator==(const pair<_T1, _T2>& __x, const pair<_T1, _T2>& __y)
   return __x.first == __y.first && __x.second == __y.second; 
 }
 
-/// ...put link to onlinedocs here...
+/// http://gcc.gnu.org/onlinedocs/libstdc++/20_util/howto.html#pairlt
 template <class _T1, class _T2>
 inline bool operator<(const pair<_T1, _T2>& __x, const pair<_T1, _T2>& __y)
 { 
@@ -134,8 +134,9 @@ inline bool operator>=(const pair<_T1, _T2>& __x, const pair<_T1, _T2>& __y) {
  *  @return   A newly-constructed pair<> object of the appropriate type.
  *
  *  The standard requires that the objects be passed by reference-to-const,
- *  but LWG issue #181 says they should be passed by const value.
- */
+ *  but LWG issue #181 says they should be passed by const value.  We follow
+ *  the LWG by default.
+*/
 template <class _T1, class _T2>
 #ifdef _GLIBCPP_RESOLVE_LIB_DEFECTS
 //181.  make_pair() unintended behavior

libstdc++-v3/include/bits/streambuf_iterator.h

@@ -173,7 +173,7 @@ namespace std
 
 #ifdef _GLIBCPP_RESOLVE_LIB_DEFECTS
       // 110 istreambuf_iterator::equal not const
-      // NB: there is also number 111 pending on this function.
+      // NB: there is also number 111 (NAD, Future) pending on this function.
       bool 
       equal(const istreambuf_iterator& __b) const
       {

libstdc++-v3/libsupc++/typeinfo

@@ -78,7 +78,7 @@ namespace std
     
   public:
     // the public interface
-    /** Returns an \e implementation-defined byte string; this is not
+    /** Returns an @e implementation-defined byte string; this is not
      *  portable between compilers!  */
     const char* name() const
     { return __name; }