Bulk documentation merge (copy) from trunk.
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. From-SVN: r51481
This commit is contained in:
parent
34f07ac7f0
commit
ae76aa0ceb
|
@ -1,3 +1,13 @@
|
|||
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.
|
||||
|
||||
2002-03-27 Phil Edwards <pme@gcc.gnu.org>
|
||||
|
||||
* include/bits/stl_algo.h: Remove @maint and @endmaint.
|
||||
|
|
|
@ -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 from the SGI STL subset.
|
|||
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
|
||||
|
|
|
@ -48,10 +48,10 @@ do not have the C code (to which the doxygen comments would be attached),
|
|||
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:
|
||||
|
|
|
@ -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 destroyed when the container is
|
|||
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, algorithmic complexity. For example, if
|
|||
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 retrieval of data based on keys.
|
|||
|
||||
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>.
|
||||
*/
|
||||
|
||||
// // // // // // // // // // // // // // // // // // // // // // // //
|
||||
|
|
|
@ -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/libstdc++/17_intro/C++STYLE">C++STYLE</a>.
|
|||
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 © 1998 by Information Technology Industry Council.
|
||||
</p>
|
||||
|
||||
</body>
|
||||
|
|
|
@ -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_types.3
|
|||
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
|
||||
|
||||
|
|
|
@ -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., "tables.html#67". 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 meet these minimum requirements.
|
|||
<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::value_type</td>
|
||||
<td>T</td>
|
||||
<td>T is Assignable</td>
|
||||
<td>compile time</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td></td>
|
||||
<td></td>
|
||||
<td></td>
|
||||
<td></td>
|
||||
<td>X::reference</td>
|
||||
<td>lvalue of T</td>
|
||||
<td> </td>
|
||||
<td>compile time</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td></td>
|
||||
<td></td>
|
||||
<td></td>
|
||||
<td></td>
|
||||
<td>X::const_reference</td>
|
||||
<td>const lvalue of T</td>
|
||||
<td> </td>
|
||||
<td>compile time</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td></td>
|
||||
<td></td>
|
||||
<td></td>
|
||||
<td></td>
|
||||
<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> </td>
|
||||
<td>post: u.size() == 0</td>
|
||||
<td>constant</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>X();</td>
|
||||
<td> </td>
|
||||
<td>X().size == 0</td>
|
||||
<td>constant</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>X(a);</td>
|
||||
<td> </td>
|
||||
<td>a == X(a)</td>
|
||||
<td>linear</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>X u(a);<br />X u = a;</td>
|
||||
<td> </td>
|
||||
<td>post: u == a. Equivalent to: X u; u = a;</td>
|
||||
<td>linear</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>(&a)->~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> </td>
|
||||
<td>constant</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>a.end()</td>
|
||||
<td>iterator; const_iterator for constant a</td>
|
||||
<td> </td>
|
||||
<td>constant</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>a == b</td>
|
||||
<td>convertible to bool</td>
|
||||
<td>== is an equivalence relation. a.size()==b.size() &&
|
||||
equal(a.begin(),a.end(),b.begin())</td>
|
||||
<td>linear</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>a != b</td>
|
||||
<td>convertible to bool</td>
|
||||
<td>equivalent to !(a==b)</td>
|
||||
<td>linear</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<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&</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> </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> </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> </td>
|
||||
<td>constant</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>a < b</td>
|
||||
<td>convertible to bool</td>
|
||||
<!--<td>lexographical_compare(a.begin,a.end(),b.begin(),b.end())</td>-->
|
||||
<td>pre: < is defined for T and is a total ordering relation</td>
|
||||
<td>linear</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>a > b</td>
|
||||
<td>convertible to bool</td>
|
||||
<!--<td>b < a</td>-->
|
||||
<td> </td>
|
||||
<td>linear</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>a <= b</td>
|
||||
<td>convertible to bool</td>
|
||||
<!--<td>!(a > b)</td>-->
|
||||
<td> </td>
|
||||
<td>linear</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>a >= b</td>
|
||||
<td>convertible to bool</td>
|
||||
<!--<td>!(a < b)</td>-->
|
||||
<td> </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<iterator></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<const_iterator></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></td>
|
||||
<td></td>
|
||||
<td></td>
|
||||
<td></td>
|
||||
<td>X(n,t)<br />X a(n,t)</td>
|
||||
<td> </td>
|
||||
<td>constructs a sequence with n copies of t<br />post: size() == n</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td></td>
|
||||
<td></td>
|
||||
<td></td>
|
||||
<td></td>
|
||||
<td>X(i,j)<br />X a(i,j)</td>
|
||||
<td> </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>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>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></td>
|
||||
<td></td>
|
||||
<td></td>
|
||||
<td></td>
|
||||
<td>a.front()</td>
|
||||
<td>reference; const_reference for constant a</td>
|
||||
<td>*a.begin()</td>
|
||||
<td>vector, list, deque</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td></td>
|
||||
<td></td>
|
||||
<td></td>
|
||||
<td></td>
|
||||
<td>a.back()</td>
|
||||
<td>reference; const_reference for constant a</td>
|
||||
<td>*--a.end()</td>
|
||||
<td>vector, list, deque</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td></td>
|
||||
<td></td>
|
||||
<td></td>
|
||||
<td></td>
|
||||
<td>a.push_front(x)</td>
|
||||
<td>void</td>
|
||||
<td>a.insert(a.begin(),x)</td>
|
||||
<td>list, deque</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td></td>
|
||||
<td></td>
|
||||
<td></td>
|
||||
<td></td>
|
||||
<td>a.push_back(x)</td>
|
||||
<td>void</td>
|
||||
<td>a.insert(a.end(),x)</td>
|
||||
<td>vector, list, deque</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>a.pop_front()</td>
|
||||
<td>void</td>
|
||||
<td>a.erase(a.begin())</td>
|
||||
<td>list, deque</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>a.pop_back()</td>
|
||||
<td>void</td>
|
||||
<td>a.erase(--a.end())</td>
|
||||
<td>vector, list, deque</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>a[n]</td>
|
||||
<td>reference; const_reference for constant a</td>
|
||||
<td>*(a.begin() + n)</td>
|
||||
<td>vector, deque</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>a.at(n)</td>
|
||||
<td>reference; const_reference for constant a</td>
|
||||
<td>*(a.begin() + n)<br />throws out_of_range if n>=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></td>
|
||||
<td></td>
|
||||
<td></td>
|
||||
<td></td>
|
||||
<td>X::key_type</td>
|
||||
<td>Key</td>
|
||||
<td>Key is Assignable</td>
|
||||
<td>compile time</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td></td>
|
||||
<td></td>
|
||||
<td></td>
|
||||
<td></td>
|
||||
<td>X::key_compare</td>
|
||||
<td>Compare</td>
|
||||
<td>defaults to less<key_type></td>
|
||||
<td>compile time</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td></td>
|
||||
<td></td>
|
||||
<td></td>
|
||||
<td></td>
|
||||
<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></td>
|
||||
<td></td>
|
||||
<td></td>
|
||||
<td></td>
|
||||
<td>X(c)<br />X a(c)</td>
|
||||
<td> </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> </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> </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> </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<iterator,bool></td>
|
||||
<td>"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."</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>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>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>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>a.equal_range(k)</td>
|
||||
<td>pair<iterator,iterator>;
|
||||
pair<const_iterator, const_iterator> 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 requirements of <a href="#65">containers</a>.
|
|||
<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>
|
||||
|
||||
|
||||
|
|
|
@ -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.
|
||||
|
|
|
@ -29,6 +29,7 @@
|
|||
<li><a href="#4"><code><foo></code> vs <code><foo.h></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
|
||||
|
@ -267,6 +268,71 @@
|
|||
<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. "Configurable"
|
||||
(or "Not configurable") 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>.
|
||||
</p>
|
||||
|
||||
|
||||
|
||||
<!-- ####################################################### -->
|
||||
|
|
|
@ -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>.
|
||||
|
|
|
@ -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>.
|
||||
|
|
|
@ -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
|
||||
|
@ -11,3 +11,7 @@ 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 $<
|
||||
|
||||
|
|
Loading…
Reference in New Issue