From 04b7c941e90c9f6df2c35121b36264941ec28dd5 Mon Sep 17 00:00:00 2001 From: Phil Edwards Date: Wed, 27 Mar 2002 21:41:36 +0000 Subject: Intro.3: Date tweak. 2002-03-27 Phil Edwards * docs/doxygen/Intro.3: Date tweak. * docs/doxygen/TODO: Update. * docs/doxygen/doxygroups.cc: Point to tables.html. * docs/doxygen/mainpage.html: Date tweak. * docs/doxygen/run_doxygen: Version tweak. Copy tables.html over. * docs/doxygen/tables.html: Fill in the blanks. * docs/doxygen/user.cfg.in (ALIASES): Remove maint and endmaint. * include/bits/stl_algo.h: Likewise; use expanded form. * include/bits/stl_alloc.h: Likewise. * include/bits/stl_construct.h: Likewise. * include/bits/stl_deque.h: Likewise. * include/bits/stl_iterator_base_types.h: Likewise. * include/bits/stl_list.h: Likewise. * include/bits/stl_relops.h: Likewise. * include/bits/stl_tempbuf.h: Likewise. * include/bits/stl_vector.h: Likewise. * include/std/std_memory.h: Likewise. * include/bits/stl_deque.h: Point into tables.html and add @ingroup. * include/bits/stl_list.h: Likewise. * include/bits/stl_vector.h: Likewise. From-SVN: r51471 --- libstdc++-v3/docs/doxygen/Intro.3 | 4 +- libstdc++-v3/docs/doxygen/TODO | 6 +- libstdc++-v3/docs/doxygen/doxygroups.cc | 16 +- libstdc++-v3/docs/doxygen/mainpage.html | 10 +- libstdc++-v3/docs/doxygen/run_doxygen | 7 +- libstdc++-v3/docs/doxygen/tables.html | 576 ++++++++++++++++++++++++++------ libstdc++-v3/docs/doxygen/user.cfg.in | 4 +- 7 files changed, 502 insertions(+), 121 deletions(-) (limited to 'libstdc++-v3/docs') diff --git a/libstdc++-v3/docs/doxygen/Intro.3 b/libstdc++-v3/docs/doxygen/Intro.3 index 3e963aa..fc44025 100644 --- a/libstdc++-v3/docs/doxygen/Intro.3 +++ b/libstdc++-v3/docs/doxygen/Intro.3 @@ -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 diff --git a/libstdc++-v3/docs/doxygen/TODO b/libstdc++-v3/docs/doxygen/TODO index 375cd5f..6629933 100644 --- a/libstdc++-v3/docs/doxygen/TODO +++ b/libstdc++-v3/docs/doxygen/TODO @@ -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: diff --git a/libstdc++-v3/docs/doxygen/doxygroups.cc b/libstdc++-v3/docs/doxygen/doxygroups.cc index 8af04b1..c6139f3 100644 --- a/libstdc++-v3/docs/doxygen/doxygroups.cc +++ b/libstdc++-v3/docs/doxygen/doxygroups.cc @@ -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 +tables. 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 +tables. */ /** @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 +tables. */ // // // // // // // // // // // // // // // // // // // // // // // // diff --git a/libstdc++-v3/docs/doxygen/mainpage.html b/libstdc++-v3/docs/doxygen/mainpage.html index 88ea279..431344b 100644 --- a/libstdc++-v3/docs/doxygen/mainpage.html +++ b/libstdc++-v3/docs/doxygen/mainpage.html @@ -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. -->

libstdc++-v3 Source Documentation

Documentation Overview

-

Generated 2002-02-08.

+

Generated 2002-03-27.

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. Hewlett-Packard Company

-

Part of the generated documentation is quoted from the C++ standard, which - is copyright 1998 by Information Technology Industry Council. +

Part of the generated documentation is quoted from the ISO C++ Standard, + which is Copyright © 1998 by Information Technology Industry Council.

diff --git a/libstdc++-v3/docs/doxygen/run_doxygen b/libstdc++-v3/docs/doxygen/run_doxygen index e93c947..7b3b7f5 100644 --- a/libstdc++-v3/docs/doxygen/run_doxygen +++ b/libstdc++-v3/docs/doxygen/run_doxygen @@ -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 diff --git a/libstdc++-v3/docs/doxygen/tables.html b/libstdc++-v3/docs/doxygen/tables.html index d38e461..2382d25 100644 --- a/libstdc++-v3/docs/doxygen/tables.html +++ b/libstdc++-v3/docs/doxygen/tables.html @@ -6,27 +6,40 @@ -

Tables

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

-

The numbers are the same as those used in the standard. +

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

+

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

+ +

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

+

+ cols="4" title="Table 65"> - + - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - - - - + + + + - - - - + + + + - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Table 65 --- Container Requirements
Anything calling itself a container must meet these minimum requirements. @@ -34,82 +47,240 @@ Anything calling itself a container must meet these minimum requirements.
expression result typenotesnotes, pre-/post-conditions, assertions complexity
X::value_typeTT is Assignablecompile time
X::referencelvalue of T compile time
X::const_referenceconst lvalue of T compile time
X::iteratoriterator type pointing to TAny iterator category except output iterator. + Convertible to X::const_iterator.compile time
X::const_iteratoriterator type pointing to const TAny iterator category except output iterator.compile time
X::difference_typesigned integral typeidentical to the difference type of X::iterator and X::const_iteratorcompile time
X::size_typeunsigned integral typesize_type can represent any non-negative value of difference_typecompile time
X u; post: u.size() == 0constant
X(); X().size == 0constant
X(a); a == X(a)linear
X u(a);
X u = a;		 post: u == a. Equivalent to: X u; u = a;linear
(&a)->~X();voiddtor is applied to every element of a; all the memory is deallocatedlinear
a.begin()iterator; const_iterator for constant a constant
a.end()iterator; const_iterator for constant a constant
a == bconvertible to bool== is an equivalence relation. a.size()==b.size() && + equal(a.begin(),a.end(),b.begin())linear
a != bconvertible to boolequivalent to !(a==b)linear
a.swap(b)voidswap(a,b)may or may not have constant complexity
r = aX&r == alinear
a.size()size_type may or may not have constant complexity
a.max_size()size_type may or may not have constant complexity
a.empty()convertible to bool constant
a < bconvertible to boolpre: < is defined for T and is a total ordering relationlinear
a > bconvertible to bool linear
a <= bconvertible to bool linear
a >= bconvertible to bool linear

+ cols="4" title="Table 66"> - + - - - - + + + + - - - - + + + + - - - - + + + + - - - - + + + +

Table 66 --- Reversible Container Requirements
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.
expression result typenotesnotes, pre-/post-conditions, assertions complexity
X::reverse_iteratoriterator type pointing to Treverse_iterator<iterator>compile time
X::const_reverse_iteratoriterator type pointing to const Treverse_iterator<const_iterator>compile time
a.rbegin()reverse_iterator; const_reverse_iterator for constant areverse_iterator(end())constant
a.rend()reverse_iterator; const_reverse_iterator for constant areverse_iterator(begin())constant

@@ -118,133 +289,330 @@ Foo, bar, and baz are such containers. - - - + + + + + + + + + + + + + - - - - + + + - - - - + + + - - - - + + + - - - - + + + + + + + + + + + + + + +

Table 67 --- Sequence Requirements

+
These are in addition to the requirements of containers. -Foo, bar, and baz are such containers. +Deque, list, and vector are such containers.
expression result typenotescomplexitynotes, pre-/post-conditions, assertions
X(n,t)
X a(n,t)		 constructs a sequence with n copies of t
post: size() == n
X(i,j)
X a(i,j)		 constructs a sequence equal to the range [i,j)
+ post: size() == distance(i,j)
a.insert(p,t)iterator (points to the inserted copy of t)inserts a copy of t before p
a.insert(p,n,t)voidinserts n copies of t before p
a.insert(p,i,j)voidinserts copies of elements in [i,j) before p
+ pre: i, j are not iterators into a
a.erase(q)iterator (points to the element following q (prior to erasure))erases the element pointed to by q
a.erase(q1,q1)iterator (points to the element pointed to by q2 (prior to erasure))erases the elements in the range [q1,q2)
a.clear()voiderase(begin(),end())
post: size() == 0

+ cols="4" title="Table 68"> - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - - - - + + + + - - - - + + + + - - - - + + + + - - - - + + + +

Table 68 --- Optional Sequence Operations
These operations are only included in containers when the operation can be done in constant time. -Foo, bar, and baz are such containers.
expression result typenotescomplexityoperational semanticscontainer
a.front()reference; const_reference for constant a*a.begin()vector, list, deque
a.back()reference; const_reference for constant a*--a.end()vector, list, deque
a.push_front(x)voida.insert(a.begin(),x)list, deque
a.push_back(x)voida.insert(a.end(),x)vector, list, deque
a.pop_front()voida.erase(a.begin())list, deque
a.pop_back()voida.erase(--a.end())vector, list, deque
a[n]reference; const_reference for constant a*(a.begin() + n)vector, deque
a.at(n)reference; const_reference for constant a*(a.begin() + n)
throws out_of_range if n>=a.size()		vector, deque

+ cols="4" title="Table 69"> - + - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - - - - + + + + - - - - + + + + - - - - + + + +

Table 69 --- Associative Container Requirements
These are in addition to the requirements of containers. +Map, multimap, set, and multiset are such containers. An associative +container supports unique keys (and is written as +a_uniq instead of a) if it may contain at most +one element for each key. Otherwise it supports equivalent keys +(and is written a_eq). Examples of the former are set and map, +examples of the latter are multiset and multimap.
expression result typenotesnotes, pre-/post-conditions, assertions complexity
X::key_typeKeyKey is Assignablecompile time
X::key_compareComparedefaults to less<key_type>compile time
X::value_comparea binary predicate typesame as key_compare for set and multiset; an ordering relation on + pairs induced by the first component (Key) for map and multimapcompile time
X(c)
X a(c)		 constructs an empty container which uses c as a comparison objectconstant
X()
X a		 constructs an empty container using Compare() as a comparison objectconstant
X(i,j,c)
X a(i,j,c)		 constructs an empty container and inserts elements from the range [i,j) + into it; uses c as a comparison objectNlogN in general where N is distance(i,j); linear if [i,j) is + sorted with value_comp()
X(i,j)
X a(i,j)		 same as previous, but uses Compare() as a comparison objectsame as previous
a.key_comp()X::key_comparereturns the comparison object out of which a was constructedconstant
a.value_comp()X::value_comparereturns an object constructed out of the comparison objectconstant
a_uniq.insert(t)pair<iterator,bool>"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." logarithmic
a_eq.insert(t)iteratorinserts t, returns the iterator pointing to the inserted elementlogarithmic
a.insert(p,t)iteratorpossibly 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 searchlogarithmic in general, amortized constant if t is inserted right + after p
+ [but see DR 233 and our + specific notes]
a.insert(i,j)voidpre: i, j are not iterators into a. possibly inserts each element from + the range [i,j) (depending on whether a_uniq or a_eq)Nlog(size()+N) where N is distance(i,j) in general
a.erase(k)size_typeerases all elements with key equivalent to k; returns number of erased + elementslog(size()) + count(k)
a.erase(q)voiderases the element pointed to by qamortized constant
a.erase(q1,q2)voiderases all the elements in the range [q1,q2)log(size()) + distance(q1,q2)
a.clear()voiderases everthing; post: size() == 0linear
a.find(k)iterator; const_iterator for constant areturns iterator pointing to element with key equivalent to k, or + a.end() if no such element foundlogarithmic
a.count(k)size_typereturns number of elements with key equivalent to klog(size()) + count(k)
a.lower_bound(k)iterator; const_iterator for constant areturns iterator pointing to the first element with key not less than klogarithmic
a.upper_bound(k)iterator; const_iterator for constant areturns iterator pointing to the first element with key greater than klogarithmic
a.equal_range(k)pair<iterator,iterator>; + pair<const_iterator, const_iterator> for constant aequivalent to make_pair(a.lower_bound(k), a.upper_bound(k))logarithmic

@@ -252,6 +620,8 @@ These are in addition to the requirements of containers.

See mainpage.html for copying conditions. +See the libstdc++-v3 homepage +for more information.

diff --git a/libstdc++-v3/docs/doxygen/user.cfg.in b/libstdc++-v3/docs/doxygen/user.cfg.in index 475dd53..bb9809a 100644 --- a/libstdc++-v3/docs/doxygen/user.cfg.in +++ b/libstdc++-v3/docs/doxygen/user.cfg.in @@ -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. -- cgit v1.1