This is the mail archive of the libstdc++@gcc.gnu.org mailing list for the libstdc++ project.

Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

[libstdc++ 3.1] Merge docs from trunk

Pretty self-explanatory here.  Nothing but docs/* touched.


2002-03-27  Phil Edwards  <pme@gcc.gnu.org>

	Bulk documentation merge (copy) from trunk.
	* docs/doxygen/Intro.3, docs/doxygen/TODO, docs/doxygen/doxygroups.cc,
	docs/doxygen/mainpage.html, docs/doxygen/run_doxygen,
	docs/doxygen/tables.html, docs/doxygen/user.cfg.in,
	docs/html/Makefile, docs/html/17_intro/howto.html,
	docs/html/19_diagnostics/howto.html, docs/html/20_util/howto.html:
	Merge from trunk.


Index: docs/doxygen/Intro.3
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/doxygen/Intro.3,v
retrieving revision 1.6
diff -u -3 -p -r1.6 Intro.3
--- Intro.3	2002/01/28 22:13:03	1.6
+++ Intro.3	2002/03/27 22:34:18
@@ -1,6 +1,6 @@
 .\" t
 .\" This man page is released under the FDL as part of libstdc++-v3.
-.TH Intro 3 "27 September 2001" "GNU libstdc++-v3" "Standard C++ Library"
+.TH Intro 3 "27 March 2002" "GNU libstdc++-v3" "Standard C++ Library"
 .SH NAME
 Intro \- Introduction to the GNU libstdc++-v3 man pages
 .SH DESCRIPTION
@@ -48,7 +48,7 @@ SGIextensions	A list of the extensions f
 Sequences	Linear containers.
 .TE
 .P
-The HTML documentation goes into more depth.
+The HTML documentation typically goes into much more depth.
 .SH FILES
 Lots!
 .SS Standard Headers
Index: docs/doxygen/TODO
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/doxygen/TODO,v
retrieving revision 1.6
diff -u -3 -p -r1.6 TODO
--- TODO	2002/02/08 07:34:53	1.6
+++ TODO	2002/03/27 22:34:18
@@ -48,10 +48,10 @@ do not have the C code (to which the dox
 this would need to be done in entirely separate files, a la doxygroups.cc.
 
 B)  Huge chunks of containers and strings are described in common "Tables"
-in the standard.  These are being pseudo-duplicated in tables.html.  We can
+in the standard.  These are pseudo-duplicated in tables.html.  We can
 use doxygen hooks like @pre and @see to reference the tables.  Then the
-individual classes would do like the standard does, and only document
-members for which additional info is available.
+individual classes do like the standard does, and only document members for
+which additional info is available.
 
 
 STYLE:
Index: docs/doxygen/doxygroups.cc
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/doxygen/doxygroups.cc,v
retrieving revision 1.7
diff -u -3 -p -r1.7 doxygroups.cc
--- doxygroups.cc	2002/02/08 07:34:53	1.7
+++ doxygroups.cc	2002/03/27 22:34:18
@@ -1,5 +1,8 @@
 
 /*
+   Copyright (C) 2001, 2002 Free Software Foundation, Inc.
+   See license.html for license.
+
    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
@@ -67,9 +70,8 @@ storing your objects.  The objects are d
 itself destroyed.  Note that if you are storing pointers in a container,
 @c delete is @e not automatically called on the pointers before destroying them.
 
-All containers must meet certain requirements.  They would be listed here
-except I'm not certain how much of 14882 can be reproduced without a
-copyright violation.  Reproducing Tables 65 through 69 is a lot of typing...
+All containers must meet certain requirements, summarized in
+<a href="tables.html">tables</a>.
 
 The standard containers are further refined into
 @link Sequences Sequences@endlink and
@@ -92,6 +94,9 @@ the second category of differences, algo
 you need to perform many inserts and removals from the middle of a sequence,
 @c list would be ideal.  But if you need to perform constant-time access to
 random elements of the sequence, then @c list should not be used.
+
+All sequences must meet certain requirements, summarized in
+<a href="tables.html">tables</a>.
 */
 
 /** @addtogroup Assoc_containers Associative Containers
@@ -99,6 +104,11 @@ Associative containers allow fast retrie
 
 Each container type is parameterized on a @c Key type, and an ordering
 relation used to sort the elements of the container.
+
+There should be more text here.
+
+All associative containers must meet certain requirements, summarized in
+<a href="tables.html">tables</a>.
 */
 
 // // // // // // // // // // // // // // // // // // // // // // // //
Index: docs/doxygen/mainpage.html
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/doxygen/mainpage.html,v
retrieving revision 1.2
diff -u -3 -p -r1.2 mainpage.html
--- mainpage.html	2002/02/08 07:34:53	1.2
+++ mainpage.html	2002/03/27 22:34:18
@@ -16,16 +16,16 @@
      directly; it all gets run through Doxygen and re-output.)  So lots of
      tags were all being mangled.
 
-     Funk 'dat.  Now we let Doxygen do whateer it feels like doing for the
+     Funk 'dat.  Now we let Doxygen do whatever it feels like doing for the
      index page, and then we just flat copy this over top of it.  Voila!
-     Tags actually work like they're supposed to.
+     Tags actually work like they're supposed to in HTML.
 -->
 
 <h1>libstdc++-v3 Source Documentation</h1>
 
 <h2> Documentation Overview </h2>
 
-<p class="smallertext">Generated 2002-02-08.</p>
+<p class="smallertext">Generated 2002-03-27.</p>
 
 <p>There are two types of documentation for libstdc++-v3.  One is the
    distribution documentation, which can be read online at
@@ -122,8 +122,8 @@ href="http://gcc.gnu.org/onlinedocs/libs
    Hewlett-Packard Company
    </blockquote>
 </p>
-<p>Part of the generated documentation is quoted from the C++ standard, which
-   is copyright 1998 by Information Technology Industry Council.
+<p>Part of the generated documentation is quoted from the ISO C++ Standard,
+   which is Copyright &copy; 1998 by Information Technology Industry Council.
 </p>
 
 </body>
Index: docs/doxygen/run_doxygen
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/doxygen/run_doxygen,v
retrieving revision 1.13
diff -u -3 -p -r1.13 run_doxygen
--- run_doxygen	2002/02/05 00:14:35	1.13
+++ run_doxygen	2002/03/27 22:34:19
@@ -1,6 +1,7 @@
 #!/bin/sh
 
 # Runs doxygen and massages the output files.
+# Copyright (C) 2001, 2002 Free Software Foundation, Inc.
 #
 # Synopsis:  run_doxygen --mode=[user|maint|man]  v3srcdir  v3builddir
 #
@@ -8,7 +9,7 @@
 
 
 # We can check now that the version of doxygen is >= this variable.
-DOXYVER=1.2.12
+DOXYVER=1.2.14
 doxygen=
 
 find_doxygen() {
@@ -147,6 +148,7 @@ set +e
 
 test $do_html = yes && {
     cp ${srcdir}/docs/doxygen/mainpage.html ${outdir}/html_${mode}/index.html
+    cp ${srcdir}/docs/doxygen/tables.html ${outdir}/html_${mode}/tables.html
     echo ::
     echo :: HTML pages begin with
     echo :: ${outdir}/html_${mode}/index.html
@@ -185,7 +187,8 @@ mv iterator_tags.3          Iterator_typ
 find . -name "[a-z]*" -a ! -name "std_*" -print | xargs rm
 rm -f *.h.3 *config* *.cc.3 *.tcc.3
 rm -f *_t.3  # workaround doxygen template parsing bug for now
-#mkdir trash  # this is used to examine what we would have deleted
+# this is used to examine what we would have deleted, for debugging
+#mkdir trash
 #find . -name "[a-z]*" -a ! -name "std_*" -print | xargs -i mv {} trash
 #mv *.h.3 *config* *.cc.3 *.tcc.3 *_t.3  trash
 
Index: docs/doxygen/tables.html
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/doxygen/tables.html,v
retrieving revision 1.1
diff -u -3 -p -r1.1 tables.html
--- tables.html	2002/02/08 07:34:53	1.1
+++ tables.html	2002/03/27 22:34:19
@@ -6,27 +6,40 @@
 </head>
 
 <body bgcolor="#ffffff">
-<!--
-     Tables can be jumped to with their number, e.g., "tables.html#67".
--->
 
 <h1>Tables</h1>
 
 <p>Most of the requirements on containers are presented in the ISO standard
-   in the form of tables.  In order to avoid massive duplication of effort,
-   we follow the standard's lead and present the information here.
-   Individual classes will only document their departures from these tables
-   (removed functions, additional functions, changes, etc).
+   in the form of tables.  In order to avoid massive duplication of effort
+   while documenting all the classes, we follow the standard's lead and
+   present the base information here.  Individual classes will only document
+   their departures from these tables (removed functions, additional functions,
+   changes, etc).
 </p>
 
-<p>The numbers are the same as those used in the standard.
+<p>We will not try to duplicate all of the surrounding text (footnotes,
+   explanations, etc) from the standard, because that would also entail a
+   duplication of effort.  Some of the surrounding text has been paraphrased
+   here for clarity.  If you are uncertain about the meaning or interpretation
+   of these notes, consult a good textbook, and/or purchase your own copy of
+   the standard (it's cheap, see our FAQ).
 </p>
 
+<p>The table numbers are the same as those used in the standard.  Tables can
+   be jumped to using their number, e.g., &quot;tables.html#67&quot;.  Only
+   Tables 65 through 69 are presented.  Some of the active Defect Reports
+   are also noted or incorporated.
+</p>
+
+<p class="smallertext">This will probably be incomplete for a while because
+filling out the tables is mind-frothingly boring.  Also, the HTML table
+rendering is ugly.  (Update:  mozilla 0.9.9 looks MUCH better.)</p>
+
 <hr />
 
 <a name="65"><p>
 <table cellpadding="3" cellspacing="5" align="center" rules="rows" border="3"
-       cols="3" title="Table 65">
+       cols="4" title="Table 65">
 <caption><h2>Table 65 --- Container Requirements</h2></caption>
 <tr><th colspan="4">
 Anything calling itself a container must meet these minimum requirements.
@@ -34,82 +47,240 @@ Anything calling itself a container must
 <tr>
 <td><strong>expression</strong></td>
 <td><strong>result type</strong></td>
-<td><strong>notes</strong></td>
+<td><strong>notes, pre-/post-conditions, assertions</strong></td>
 <td><strong>complexity</strong></td>
 </tr>
 
+<tr>
+<td>X::value_type</td>
+<td>T</td>
+<td>T is Assignable</td>
+<td>compile time</td>
+</tr>
+
+<tr>
+<td>X::reference</td>
+<td>lvalue of T</td>
+<td>&nbsp;</td>
+<td>compile time</td>
+</tr>
+
+<tr>
+<td>X::const_reference</td>
+<td>const lvalue of T</td>
+<td>&nbsp;</td>
+<td>compile time</td>
+</tr>
+
+<tr>
+<td>X::iterator</td>
+<td>iterator type pointing to T</td>
+<td>Any iterator category except output iterator.
+    Convertible to X::const_iterator.</td>
+<td>compile time</td>
+</tr>
+
+<tr>
+<td>X::const_iterator</td>
+<td>iterator type pointing to const T</td>
+<td>Any iterator category except output iterator.</td>
+<td>compile time</td>
+</tr>
+
+<tr>
+<td>X::difference_type</td>
+<td>signed integral type</td>
+<td>identical to the difference type of X::iterator and X::const_iterator</td>
+<td>compile time</td>
+</tr>
+
+<tr>
+<td>X::size_type</td>
+<td>unsigned integral type</td>
+<td>size_type can represent any non-negative value of difference_type</td>
+<td>compile time</td>
+</tr>
+
+<tr>
+<td>X u;</td>
+<td>&nbsp;</td>
+<td>post: u.size() == 0</td>
+<td>constant</td>
+</tr>
+
+<tr>
+<td>X();</td>
+<td>&nbsp;</td>
+<td>X().size == 0</td>
+<td>constant</td>
+</tr>
+
+<tr>
+<td>X(a);</td>
+<td>&nbsp;</td>
+<td>a == X(a)</td>
+<td>linear</td>
+</tr>
+
+<tr>
+<td>X u(a);<br />X u = a;</td>
+<td>&nbsp;</td>
+<td>post: u == a.  Equivalent to: X u; u = a;</td>
+<td>linear</td>
+</tr>
+
+<tr>
+<td>(&amp;a)-&gt;~X();</td>
+<td>void</td>
+<td>dtor is applied to every element of a; all the memory is deallocated</td>
+<td>linear</td>
+</tr>
+
+<tr>
+<td>a.begin()</td>
+<td>iterator; const_iterator for constant a</td>
+<td>&nbsp;</td>
+<td>constant</td>
+</tr>
+
 <tr>
-<td></td>
-<td></td>
-<td></td>
-<td></td>
+<td>a.end()</td>
+<td>iterator; const_iterator for constant a</td>
+<td>&nbsp;</td>
+<td>constant</td>
 </tr>
 
 <tr>
-<td></td>
-<td></td>
-<td></td>
-<td></td>
+<td>a == b</td>
+<td>convertible to bool</td>
+<td>== is an equivalence relation.  a.size()==b.size() &amp;&amp;
+    equal(a.begin(),a.end(),b.begin())</td>
+<td>linear</td>
 </tr>
 
 <tr>
-<td></td>
-<td></td>
-<td></td>
-<td></td>
+<td>a != b</td>
+<td>convertible to bool</td>
+<td>equivalent to !(a==b)</td>
+<td>linear</td>
 </tr>
 
 <tr>
-<td></td>
-<td></td>
-<td></td>
-<td></td>
+<td>a.swap(b)</td>
+<td>void</td>
+<td>swap(a,b)</td>
+<td>may or may not have constant complexity</td>
 </tr>
+
+<tr>
+<td>r = a</td>
+<td>X&amp;</td>
+<td>r == a</td>
+<td>linear</td>
+</tr>
+
+<!-- a fifth column, "operation semantics," magically appears in the table
+     at this point... wtf?  -->
+<tr>
+<td>a.size()</td>
+<td>size_type</td>
+<!--<td>a.end() - a.begin()</td>-->
+<td>&nbsp;</td>
+<td>may or may not have constant complexity</td>
+</tr>
+
+<tr>
+<td>a.max_size()</td>
+<td>size_type</td>
+<!--<td>size() of the largest possible container</td>-->
+<td>&nbsp;</td>
+<td>may or may not have constant complexity</td>
+</tr>
+
+<tr>
+<td>a.empty()</td>
+<td>convertible to bool</td>
+<!--<td>a.size() == 0</td>-->
+<td>&nbsp;</td>
+<td>constant</td>
+</tr>
+
+<tr>
+<td>a &lt; b</td>
+<td>convertible to bool</td>
+<!--<td>lexographical_compare(a.begin,a.end(),b.begin(),b.end())</td>-->
+<td>pre: &lt; is defined for T and is a total ordering relation</td>
+<td>linear</td>
+</tr>
+
+<tr>
+<td>a &gt; b</td>
+<td>convertible to bool</td>
+<!--<td>b &lt; a</td>-->
+<td>&nbsp;</td>
+<td>linear</td>
+</tr>
+
+<tr>
+<td>a &lt;= b</td>
+<td>convertible to bool</td>
+<!--<td>!(a &gt; b)</td>-->
+<td>&nbsp;</td>
+<td>linear</td>
+</tr>
+
+<tr>
+<td>a &gt;= b</td>
+<td>convertible to bool</td>
+<!--<td>!(a &lt; b)</td>-->
+<td>&nbsp;</td>
+<td>linear</td>
+</tr>
 </table title="Table 65"></p></a>
 
 
 <a name="66"><p>
 <table cellpadding="3" cellspacing="5" align="center" rules="rows" border="3"
-       cols="3" title="Table 66">
+       cols="4" title="Table 66">
 <caption><h2>Table 66 --- Reversible Container Requirements</h2></caption>
 <tr><th colspan="4">
 If a container's iterator is bidirectional or random-access, then the
 container also meets these requirements.
-Foo, bar, and baz are such containers.
+Deque, list, vector, map, multimap, set, and multiset are such containers.
 </th></tr>
 <tr>
 <td><strong>expression</strong></td>
 <td><strong>result type</strong></td>
-<td><strong>notes</strong></td>
+<td><strong>notes, pre-/post-conditions, assertions</strong></td>
 <td><strong>complexity</strong></td>
 </tr>
 
 <tr>
-<td></td>
-<td></td>
-<td></td>
-<td></td>
+<td>X::reverse_iterator</td>
+<td>iterator type pointing to T</td>
+<td>reverse_iterator&lt;iterator&gt;</td>
+<td>compile time</td>
 </tr>
 
 <tr>
-<td></td>
-<td></td>
-<td></td>
-<td></td>
+<td>X::const_reverse_iterator</td>
+<td>iterator type pointing to const T</td>
+<td>reverse_iterator&lt;const_iterator&gt;</td>
+<td>compile time</td>
 </tr>
 
 <tr>
-<td></td>
-<td></td>
-<td></td>
-<td></td>
+<td>a.rbegin()</td>
+<td>reverse_iterator; const_reverse_iterator for constant a</td>
+<td>reverse_iterator(end())</td>
+<td>constant</td>
 </tr>
 
 <tr>
-<td></td>
-<td></td>
-<td></td>
-<td></td>
+<td>a.rend()</td>
+<td>reverse_iterator; const_reverse_iterator for constant a</td>
+<td>reverse_iterator(begin())</td>
+<td>constant</td>
 </tr>
 </table title="Table 66"></p></a>
 
@@ -118,133 +289,330 @@ Foo, bar, and baz are such containers.
 <table cellpadding="3" cellspacing="5" align="center" rules="rows" border="3"
        cols="3" title="Table 67">
 <caption><h2>Table 67 --- Sequence Requirements</h2></caption>
-<tr><th colspan="4">
+<tr><th colspan="3">
 These are in addition to the requirements of <a href="#65">containers</a>.
-Foo, bar, and baz are such containers.
+Deque, list, and vector are such containers.
 </th></tr>
 <tr>
 <td><strong>expression</strong></td>
 <td><strong>result type</strong></td>
-<td><strong>notes</strong></td>
-<td><strong>complexity</strong></td>
+<td><strong>notes, pre-/post-conditions, assertions</strong></td>
+</tr>
+
+<tr>
+<td>X(n,t)<br />X a(n,t)</td>
+<td>&nbsp;</td>
+<td>constructs a sequence with n copies of t<br />post: size() == n</td>
+</tr>
+
+<tr>
+<td>X(i,j)<br />X a(i,j)</td>
+<td>&nbsp;</td>
+<td>constructs a sequence equal to the range [i,j)<br />
+    post: size() == distance(i,j)</td>
 </tr>
 
 <tr>
-<td></td>
-<td></td>
-<td></td>
-<td></td>
+<td>a.insert(p,t)</td>
+<td>iterator (points to the inserted copy of t)</td>
+<td>inserts a copy of t before p</td>
 </tr>
 
 <tr>
-<td></td>
-<td></td>
-<td></td>
-<td></td>
+<td>a.insert(p,n,t)</td>
+<td>void</td>
+<td>inserts n copies of t before p</td>
 </tr>
 
 <tr>
-<td></td>
-<td></td>
-<td></td>
-<td></td>
+<td>a.insert(p,i,j)</td>
+<td>void</td>
+<td>inserts copies of elements in [i,j) before p<br />
+    pre: i, j are not iterators into a</td>
 </tr>
 
 <tr>
-<td></td>
-<td></td>
-<td></td>
-<td></td>
+<td>a.erase(q)</td>
+<td>iterator (points to the element following q (prior to erasure))</td>
+<td>erases the element pointed to by q</td>
 </tr>
+
+<tr>
+<td>a.erase(q1,q1)</td>
+<td>iterator (points to the element pointed to by q2 (prior to erasure))</td>
+<td>erases the elements in the range [q1,q2)</td>
+</tr>
+
+<tr>
+<td>a.clear()</td>
+<td>void</td>
+<td>erase(begin(),end())<br />post: size() == 0</td>
+</tr>
 </table title="Table 67"></p></a>
 
 
 <a name="68"><p>
 <table cellpadding="3" cellspacing="5" align="center" rules="rows" border="3"
-       cols="3" title="Table 68">
+       cols="4" title="Table 68">
 <caption><h2>Table 68 --- Optional Sequence Operations</h2></caption>
 <tr><th colspan="4">
 These operations are only included in containers when the operation can be
 done in constant time.
-Foo, bar, and baz are such containers.
 </th></tr>
 <tr>
 <td><strong>expression</strong></td>
 <td><strong>result type</strong></td>
-<td><strong>notes</strong></td>
-<td><strong>complexity</strong></td>
+<td><strong>operational semantics</strong></td>
+<td><strong>container</strong></td>
+</tr>
+
+<tr>
+<td>a.front()</td>
+<td>reference; const_reference for constant a</td>
+<td>*a.begin()</td>
+<td>vector, list, deque</td>
+</tr>
+
+<tr>
+<td>a.back()</td>
+<td>reference; const_reference for constant a</td>
+<td>*--a.end()</td>
+<td>vector, list, deque</td>
+</tr>
+
+<tr>
+<td>a.push_front(x)</td>
+<td>void</td>
+<td>a.insert(a.begin(),x)</td>
+<td>list, deque</td>
+</tr>
+
+<tr>
+<td>a.push_back(x)</td>
+<td>void</td>
+<td>a.insert(a.end(),x)</td>
+<td>vector, list, deque</td>
 </tr>
 
 <tr>
-<td></td>
-<td></td>
-<td></td>
-<td></td>
+<td>a.pop_front()</td>
+<td>void</td>
+<td>a.erase(a.begin())</td>
+<td>list, deque</td>
 </tr>
 
 <tr>
-<td></td>
-<td></td>
-<td></td>
-<td></td>
+<td>a.pop_back()</td>
+<td>void</td>
+<td>a.erase(--a.end())</td>
+<td>vector, list, deque</td>
 </tr>
 
 <tr>
-<td></td>
-<td></td>
-<td></td>
-<td></td>
+<td>a[n]</td>
+<td>reference; const_reference for constant a</td>
+<td>*(a.begin() + n)</td>
+<td>vector, deque</td>
 </tr>
 
 <tr>
-<td></td>
-<td></td>
-<td></td>
-<td></td>
+<td>a.at(n)</td>
+<td>reference; const_reference for constant a</td>
+<td>*(a.begin() + n)<br />throws out_of_range if n&gt;=a.size()</td>
+<td>vector, deque</td>
 </tr>
 </table title="Table 68"></p></a>
 
 
 <a name="69"><p>
 <table cellpadding="3" cellspacing="5" align="center" rules="rows" border="3"
-       cols="3" title="Table 69">
+       cols="4" title="Table 69">
 <caption><h2>Table 69 --- Associative Container Requirements</h2></caption>
 <tr><th colspan="4">
 These are in addition to the requirements of <a href="#65">containers</a>.
+Map, multimap, set, and multiset are such containers.  An associative
+container supports <em>unique keys</em> (and is written as
+<code>a_uniq</code> instead of <code>a</code>) if it may contain at most
+one element for each key.  Otherwise it supports <em>equivalent keys</em>
+(and is written <code>a_eq</code>).  Examples of the former are set and map,
+examples of the latter are multiset and multimap.
 </th></tr>
 <tr>
 <td><strong>expression</strong></td>
 <td><strong>result type</strong></td>
-<td><strong>notes</strong></td>
+<td><strong>notes, pre-/post-conditions, assertions</strong></td>
 <td><strong>complexity</strong></td>
 </tr>
 
+<tr>
+<td>X::key_type</td>
+<td>Key</td>
+<td>Key is Assignable</td>
+<td>compile time</td>
+</tr>
+
+<tr>
+<td>X::key_compare</td>
+<td>Compare</td>
+<td>defaults to less&lt;key_type&gt;</td>
+<td>compile time</td>
+</tr>
+
+<tr>
+<td>X::value_compare</td>
+<td>a binary predicate type</td>
+<td>same as key_compare for set and multiset; an ordering relation on
+    pairs induced by the first component (Key) for map and multimap</td>
+<td>compile time</td>
+</tr>
+
+<tr>
+<td>X(c)<br />X a(c)</td>
+<td>&nbsp;</td>
+<td>constructs an empty container which uses c as a comparison object</td>
+<td>constant</td>
+</tr>
+
+<tr>
+<td>X()<br />X a</td>
+<td>&nbsp;</td>
+<td>constructs an empty container using Compare() as a comparison object</td>
+<td>constant</td>
+</tr>
+
+<tr>
+<td>X(i,j,c)<br />X a(i,j,c)</td>
+<td>&nbsp;</td>
+<td>constructs an empty container and inserts elements from the range [i,j)
+    into it; uses c as a comparison object</td>
+<td>NlogN in general where N is distance(i,j); linear if [i,j) is
+    sorted with value_comp()</td>
+</tr>
+
+<tr>
+<td>X(i,j)<br />X a(i,j)</td>
+<td>&nbsp;</td>
+<td>same as previous, but uses Compare() as a comparison object</td>
+<td>same as previous</td>
+</tr>
+
+<tr>
+<td>a.key_comp()</td>
+<td>X::key_compare</td>
+<td>returns the comparison object out of which a was constructed</td>
+<td>constant</td>
+</tr>
+
+<tr>
+<td>a.value_comp()</td>
+<td>X::value_compare</td>
+<td>returns an object constructed out of the comparison object</td>
+<td>constant</td>
+</tr>
+
+<tr>
+<td>a_uniq.insert(t)</td>
+<td>pair&lt;iterator,bool&gt;</td>
+<td>&quot;Inserts t if and only if there is no element in the container with
+    key equivalent to the key of t. The bool component of the returned pair
+    is true -iff- the insertion took place, and the iterator component of
+    the pair points to the element with key equivalent to the key of
+    t.&quot;</td> <!-- DR 316 -->
+<td>logarithmic</td>
+</tr>
+
+<tr>
+<td>a_eq.insert(t)</td>
+<td>iterator</td>
+<td>inserts t, returns the iterator pointing to the inserted element</td>
+<td>logarithmic</td>
+</tr>
+
+<tr>
+<td>a.insert(p,t)</td>
+<td>iterator</td>
+<td>possibly inserts t (depending on whether a_uniq or a_eq); returns iterator
+    pointing to the element with key equivalent to the key of t; iterator p
+    is a hint pointing to where the insert should start to search</td>
+<td>logarithmic in general, amortized constant if t is inserted right
+    after p<br />
+    <strong>[but see DR 233 and <a href="
+    http://gcc.gnu.org/onlinedocs/libstdc++/23_containers/howto.html#4";>our
+    specific notes</a>]</strong></td>
+</tr>
+
+<tr>
+<td>a.insert(i,j)</td>
+<td>void</td>
+<td>pre: i, j are not iterators into a.  possibly inserts each element from
+    the range [i,j) (depending on whether a_uniq or a_eq)</td>
+<td>Nlog(size()+N) where N is distance(i,j) in general</td> <!-- DR 264 -->
+</tr>
+
+<tr>
+<td>a.erase(k)</td>
+<td>size_type</td>
+<td>erases all elements with key equivalent to k; returns number of erased
+    elements</td>
+<td>log(size()) + count(k)</td>
+</tr>
+
+<tr>
+<td>a.erase(q)</td>
+<td>void</td>
+<td>erases the element pointed to by q</td>
+<td>amortized constant</td>
+</tr>
+
+<tr>
+<td>a.erase(q1,q2)</td>
+<td>void</td>
+<td>erases all the elements in the range [q1,q2)</td>
+<td>log(size()) + distance(q1,q2)</td>
+</tr>
+
+<tr>
+<td>a.clear()</td>
+<td>void</td>
+<td>erases everthing; post: size() == 0</td>
+<td>linear</td> <!-- DR 224 -->
+</tr>
+
+<tr>
+<td>a.find(k)</td>
+<td>iterator; const_iterator for constant a</td>
+<td>returns iterator pointing to element with key equivalent to k, or
+    a.end() if no such element found</td>
+<td>logarithmic</td>
+</tr>
+
 <tr>
-<td></td>
-<td></td>
-<td></td>
-<td></td>
+<td>a.count(k)</td>
+<td>size_type</td>
+<td>returns number of elements with key equivalent to k</td>
+<td>log(size()) + count(k)</td>
 </tr>
 
 <tr>
-<td></td>
-<td></td>
-<td></td>
-<td></td>
+<td>a.lower_bound(k)</td>
+<td>iterator; const_iterator for constant a</td>
+<td>returns iterator pointing to the first element with key not less than k</td>
+<td>logarithmic</td>
 </tr>
 
 <tr>
-<td></td>
-<td></td>
-<td></td>
-<td></td>
+<td>a.upper_bound(k)</td>
+<td>iterator; const_iterator for constant a</td>
+<td>returns iterator pointing to the first element with key greater than k</td>
+<td>logarithmic</td>
 </tr>
 
 <tr>
-<td></td>
-<td></td>
-<td></td>
-<td></td>
+<td>a.equal_range(k)</td>
+<td>pair&lt;iterator,iterator&gt;;
+    pair&lt;const_iterator, const_iterator&gt; for constant a</td>
+<td>equivalent to make_pair(a.lower_bound(k), a.upper_bound(k))</td>
+<td>logarithmic</td>
 </tr>
 </table title="Table 69"></p></a>
 
@@ -252,6 +620,8 @@ These are in addition to the requirement
 <hr />
 <p class="smallertext"><em>
 See <a href="mainpage.html">mainpage.html</a> for copying conditions.
+See <a href="http://gcc.gnu.org/libstdc++/";>the libstdc++-v3 homepage</a>
+for more information.
 </em></p>
 
 
Index: docs/doxygen/user.cfg.in
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/doxygen/user.cfg.in,v
retrieving revision 1.14
diff -u -3 -p -r1.14 user.cfg.in
--- user.cfg.in	2002/02/08 07:34:53	1.14
+++ user.cfg.in	2002/03/27 22:34:19
@@ -222,9 +222,7 @@ GENERATE_BUGLIST       = YES
 # will result in a user defined paragraph with heading "Side Effects:". 
 # You can put \n's in the value part of an alias to insert newlines.
 
-ALIASES                = "maint=@if maint" \
-                         "endmaint=@endif" \
-	"doctodo=@todo\nDoc me!  See docs/doxygen/TODO and http://gcc.gnu.org/ml/libstdc++/2002-02/msg00003.html for more."
+ALIASES                = "doctodo=@todo\nDoc me!  See docs/doxygen/TODO and http://gcc.gnu.org/ml/libstdc++/2002-02/msg00003.html for more."
 
 # The ENABLED_SECTIONS tag can be used to enable conditional 
 # documentation sections, marked by \if sectionname ... \endif.
@@ -703,7 +701,7 @@ INCLUDE_FILE_PATTERNS  = 
 # or name=definition (no spaces). If the definition and the = are 
 # omitted =1 is assumed.
 
-PREDEFINED             = 
+PREDEFINED             = _GLIBCPP_DEPRECATED
 
 # If the MACRO_EXPANSION and EXPAND_PREDEF_ONLY tags are set to YES then 
 # this tag can be used to specify a list of macro names that should be expanded. 
Index: docs/html/Makefile
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/html/Makefile,v
retrieving revision 1.2
diff -u -3 -p -r1.2 Makefile
--- Makefile	2001/11/06 00:18:37	1.2
+++ Makefile	2002/03/27 22:34:19
@@ -2,7 +2,7 @@
 MAKEINFO=makeinfo
 INC=../../../gcc/doc/include
 
-all: faq/index.txt 17_intro/porting.html
+all: faq/index.txt 17_intro/porting.html 17_intro/porting-howto.html
 
 
 faq/index.txt: faq/index.html
@@ -10,4 +10,8 @@ faq/index.txt: faq/index.html
 
 17_intro/porting.html: 17_intro/porting.texi
 	${MAKEINFO} -I ${INC} --html --no-split $< -o $@
+
+# known to work under RH; this can be cleaned up later if needed
+17_intro/porting-howto.html: 17_intro/porting-howto.xml
+	xltproc -o $@ /usr/share/xml/docbook/xsl-stylesheets-1.48-2/html/docbook.xsl $<
 
Index: docs/html/17_intro/howto.html
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/html/17_intro/howto.html,v
retrieving revision 1.20
diff -u -3 -p -r1.20 howto.html
--- howto.html	2002/02/05 00:14:36	1.20
+++ howto.html	2002/03/27 22:34:20
@@ -29,6 +29,7 @@
    <li><a href="#4"><code>&lt;foo&gt;</code> vs <code>&lt;foo.h&gt;</code></a>
    <li><a href="porting-howto.html">Porting HOWTO</a>
    <li><a href="#5">Behavior specific to libstdc++-v3</a>
+   <li><a href="#6">Preprocessor macros controlling the library</a>
 </ul>
 
 <hr>
@@ -54,20 +55,20 @@
 <h2><a name="3">The Standard C++ library and multithreading</a></h2>
    <p>This section discusses issues surrounding the proper compilation
       of multithreaded applications which use the Standard C++
-      library.  This information is gcc-specific since the C++
+      library.  This information is GCC-specific since the C++
       standard does not address matters of multithreaded applications.
       Unless explicitly prefaced, all information in this section is
-      current as of the gcc 3.0 release and all later point releases.
+      current as of the GCC 3.0 release and all later point releases.
    </p>
-   <p>Earlier gcc releases had a somewhat different approach to
-      threading configuration and proper compilation.  Before gcc 3.0,
+   <p>Earlier GCC releases had a somewhat different approach to
+      threading configuration and proper compilation.  Before GCC 3.0,
       configuration of the threading model was dictated by compiler
       command-line options and macros (both of which were somewhat
       thread-implementation and port-specific).  There were no
       guarantees related to being able to link code compiled with one
-      set of options and macro setting with another set.  For gcc 3.0,
+      set of options and macro setting with another set.  For GCC 3.0,
       configuration of the threading model used with libraries and
-      user-code is performed when gcc is configured and built using
+      user-code is performed when GCC is configured and built using
       the --enable-threads and --disable-threads options.  The ABI is
       stable for symbol name-mangling and limited functional
       compatibility exists between code compiled under different
@@ -83,9 +84,9 @@
       with another thread model useful on the platform.  Other mixes
       may or may not work but are not considered supported.  (Thus, if
       you distribute a shared C++ library in binary form only, it may
-      be best to compile it with a gcc configured with
+      be best to compile it with a GCC configured with
       --enable-threads for maximal interchangeability and usefulness
-      with a user population that may have built gcc with either
+      with a user population that may have built GCC with either
       --enable-threads or --disable-threads.)
    </p>
    <p>When you link a multithreaded application, you will probably
@@ -262,6 +263,71 @@
    </p>
    <p><strong>[27.8.1.4]/16</strong> Calling <code>fstream::sync</code> when
       a get area exists will... whatever <code>fflush()</code> does, I think.
+   </p>
+   <p>Return <a href="#top">to top of page</a> or
+      <a href="../faq/index.html">to the FAQ</a>.
+   </p>
+
+<hr>
+<h2><a name="6">Preprocessor macros controlling the library</a></h2>
+   <p>Some of the semantics of the libstdc++-v3 implementation are
+      controlled by preprocessor macros, both during build/installation and
+      during compilation of user code.  Many of these choices are made when
+      the library is built and installed (actually, during
+      <a href="../configopts.html">the configuration step</a>, with the
+      various --enable/--disable choices being translated to #define/#undef).
+   </p>
+   <p>All library macros begin with <code>_GLIBCPP_</code>.  The fact that
+      these symbols start with a leading underscore should give you a clue
+      that (by default) they aren't meant to be changed by the user.  :-)
+   </p>
+   <p>These macros are all gathered in the file <code>c++config.h</code>,
+      which is generated during installation.  <strong>You must assume that
+      these macros cannot be redefined by your own code</strong>, unless we
+      document otherwise here.  Some of the choices control code which has
+      already been compiled (i.e., libstdc++.a/.so).  If you explicitly
+      #define or #undef these macros, the <em>headers</em> may see different
+      code paths, but the <em>libraries</em> which you link against will not.
+      If you want to experiment with different values, you must change the
+      config headers before building/installing the library.
+   </p>
+   <p>Below are macros which, for 3.1 and later, you may change yourself,
+      in your own code with #define/#undef or with -D/-U compiler flags.
+      The default state of the symbol is listed.  &quot;Configurable&quot;
+      (or &quot;Not configurable&quot;) means that the symbol is initially
+      chosen (or not) based on --enable/--disable options at configure time.
+    <dl>
+    <dt><code>_GLIBCPP_DEPRECATED</code></dt>
+    <dd>Undefined by default.  Not configurable.  Turning this on enables
+        older ARM-style iostreams code, and other anachronisms.  This may be
+        useful in updating old C++ programs which no longer meet the
+        requirements of the language.
+    </dd>
+    <!--
+     Can this actually be turned off and still produce a working lib?  Must
+     check.  -pme
+     No, it can't.  Hmmm.  -pme
+    <dt><code>_GLIBCPP_RESOLVE_LIB_DEFECTS</code></dt>
+    <dd>Defined by default.  Not configurable.  The library follows
+        corrections and updates from the ISO committee, see
+        <a href="../faq/index.html#5_2">here</a> and
+        <a href="../ext/howto.html#5">here</a> for more on this feature.
+        If you have code which depends on the first version of the standard,
+        you might try undefining this macro.
+    </dd>
+    -->
+    <dt><code>_GLIBCPP_CONCEPT_CHECKS</code></dt>
+    <dd>Undefined by default.  Configurable.  When defined, performs
+        compile-time checking on certain template instantiations to detect
+        violations of the requirements of the standard.  This is described
+        in more detail <a href="../19_diagnostics/howto.html#3">here</a>.
+    </dd>
+    <!--
+    <dt><code></code></dt>
+    <dd>
+    </dd>
+    -->
+    </dl>
    </p>
    <p>Return <a href="#top">to top of page</a> or
       <a href="../faq/index.html">to the FAQ</a>.
Index: docs/html/19_diagnostics/howto.html
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/html/19_diagnostics/howto.html,v
retrieving revision 1.14
diff -u -3 -p -r1.14 howto.html
--- howto.html	2002/01/28 22:13:04	1.14
+++ howto.html	2002/03/27 22:34:20
@@ -102,6 +102,8 @@
    <p>For GCC 3.0 and 3.1 they are off by default.  They can be enabled at
       configure time with
       <a href="../configopts.html"><code>--enable-concept-checks</code></a>.
+      For 3.1 you can instead #define _GLIBCPP_CONCEPT_CHECKS to enable them
+      on a per-translation-unit basis.
    </p>
    <p>Return <a href="#top">to top of page</a> or
       <a href="../faq/index.html">to the FAQ</a>.
Index: docs/html/20_util/howto.html
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/html/20_util/howto.html,v
retrieving revision 1.12
diff -u -3 -p -r1.12 howto.html
--- howto.html	2001/11/23 16:29:00	1.12
+++ howto.html	2002/03/27 22:34:20
@@ -134,8 +134,8 @@
       get slightly the wrong idea.  In the interest of not reinventing
       the wheel, we will refer you to the introduction to the functor
       concept written by SGI as part of their STL, in
-      <a href="http://www.sgi.com/Technology/STL/functors.html";>their
-      http://www.sgi.com/Technology/STL/functors.html</a>.
+      <a href="http://www.sgi.com/tech/stl/functors.html";>their
+      http://www.sgi.com/tech/stl/functors.html</a>.
    </p>
    <p>Return <a href="#top">to top of page</a> or
       <a href="../faq/index.html">to the FAQ</a>.
Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]