Commit 8f94053d by Phil Edwards

TODO: Update.

2002-02-08  Phil Edwards  <pme@gcc.gnu.org>

	* docs/doxygen/TODO:  Update.
	* docs/doxygen/doxygroups.cc:  Tweak __gnu_cxx description.
	* docs/doxygen/mainpage.html:  Add TODO list link.
	* docs/doxygen/user.cfg.in:  Add @doctodo hook.
	* docs/doxygen/tables.html:  New file, emoty structure only.

	* include/bits/stl_iterator.h:  Doxygenate just about everything.
	* include/bits/stl_iterator_base_funcs.h:  Ditto, clean up spaces.
	* include/bits/stl_iterator_base_types.h:  Add notes.

From-SVN: r49608
parent 6478d7c9
2002-02-08 Phil Edwards <pme@gcc.gnu.org>
* docs/doxygen/TODO: Update.
* docs/doxygen/doxygroups.cc: Tweak __gnu_cxx description.
* docs/doxygen/mainpage.html: Add TODO list link.
* docs/doxygen/user.cfg.in: Add @doctodo hook.
* docs/doxygen/tables.html: New file, emoty structure only.
* include/bits/stl_iterator.h: Doxygenate just about everything.
* include/bits/stl_iterator_base_funcs.h: Ditto, clean up spaces.
* include/bits/stl_iterator_base_types.h: Add notes.
2002-02-07 Stephan Buys <sbproxy@icon.co.za> 2002-02-07 Stephan Buys <sbproxy@icon.co.za>
* include/bits/stl_map.h: Tweak doxygen markup. * include/bits/stl_map.h: Tweak doxygen markup.
......
...@@ -7,6 +7,13 @@ documented in the course of doing other headers. ...@@ -7,6 +7,13 @@ documented in the course of doing other headers.
"Untouched" means I've deliberately skipped it for various reasons, or "Untouched" means I've deliberately skipped it for various reasons, or
haven't gotten to it yet. It /will/ be done (by somebody, eventually.) haven't gotten to it yet. It /will/ be done (by somebody, eventually.)
If you document an area and need to skip (for whatever reason) a non-trivial
entity (i.e., one that should be documented), go ahead and add the comment
markup, and use the homegrown @doctodo tag. See include/bits/stl_iterator.h
for examples of this. Doing so will at least cause doxygen to consider the
entitiy as documented and include it in the output. It will also add the
entity to the generated TODO page.
Area Still needs to be doxygen-documented Area Still needs to be doxygen-documented
----------------------------------------------------------- -----------------------------------------------------------
...@@ -18,7 +25,8 @@ c20 Note A ...@@ -18,7 +25,8 @@ c20 Note A
c21 Untouched, Note B c21 Untouched, Note B
c22 Untouched c22 Untouched
c23 See doxygroups.cc and Note B. c23 See doxygroups.cc and Note B.
c24 Untouched c24 stl_iterator.h (__normal_iterator, other small TODO bits)
stream iterators
c25 stl_algo.h (lots of stuff) c25 stl_algo.h (lots of stuff)
c26 <complex>, <valarray>, stl_numeric.h[26.4], Note A c26 <complex>, <valarray>, stl_numeric.h[26.4], Note A
c27 Untouched c27 Untouched
...@@ -40,8 +48,7 @@ do not have the C code (to which the doxygen comments would be attached), ...@@ -40,8 +48,7 @@ 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. 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" B) Huge chunks of containers and strings are described in common "Tables"
in the standard. How to reproduce this information? I suspect we should in the standard. These are being pseudo-duplicated in tables.html. We can
simply write some HTML tables (say, one <table> per Table per file), and
use doxygen hooks like @pre and @see to reference the tables. Then the use doxygen hooks like @pre and @see to reference the tables. Then the
individual classes would do like the standard does, and only document individual classes would do like the standard does, and only document
members for which additional info is available. members for which additional info is available.
......
...@@ -13,14 +13,17 @@ ...@@ -13,14 +13,17 @@
* @brief Everything defined by the ISO C++ Standard is within namespace std. * @brief Everything defined by the ISO C++ Standard is within namespace std.
*/ */
/** @namespace __gnu_cxx /** @namespace __gnu_cxx
* @brief Non-standard things. * @brief This namespace serves two purposes.
* *
* This namespace is used for * This namespace is used for two things:
* - sequestering internal (implementation-only) names away from the * - sequestering internal (implementation-only) names away from the
* global namespace * global namespace; these are details of the implementation and should
* - GNU extensions * not be touched by users
* - GNU extensions for public use
* *
* This is still fluid and changing rapidly. * This is still fluid and changing rapidly. Currently the rule is: if an
* entitity is found in the user-level documentation, it falls into the
* second category.
*/ */
// // // // // // // // // // // // // // // // // // // // // // // // // // // // // // // // // // // // // // // // // // // // // // // //
......
...@@ -25,7 +25,7 @@ ...@@ -25,7 +25,7 @@
<h2> Documentation Overview </h2> <h2> Documentation Overview </h2>
<p class="smallertext">Generated 2002-02-04.</p> <p class="smallertext">Generated 2002-02-08.</p>
<p>There are two types of documentation for libstdc++-v3. One is the <p>There are two types of documentation for libstdc++-v3. One is the
distribution documentation, which can be read online at distribution documentation, which can be read online at
...@@ -97,6 +97,7 @@ href="http://gcc.gnu.org/onlinedocs/libstdc++/17_intro/C++STYLE">C++STYLE</a>. ...@@ -97,6 +97,7 @@ href="http://gcc.gnu.org/onlinedocs/libstdc++/17_intro/C++STYLE">C++STYLE</a>.
<li><a href="namespacemembers.html">Namespace Members</a> <li><a href="namespacemembers.html">Namespace Members</a>
<li><a href="functions.html">Compound Members</a> <li><a href="functions.html">Compound Members</a>
<li><a href="globals.html">File Members</a> <li><a href="globals.html">File Members</a>
<li><a href="todo.html">TODO List</a> (This is incomplete... how ironic.)
</ul> </ul>
</p> </p>
......
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head><meta http-equiv="Content-Type" content="text/html;charset=iso-8859-1">
<title>Tables</title>
<link href="style.css" rel="stylesheet" type="text/css">
</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).
</p>
<p>The numbers are the same as those used in the standard.
</p>
<hr />
<a name="65"><p>
<table cellpadding="3" cellspacing="5" align="center" rules="rows" border="3"
cols="3" 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.
</th></tr>
<tr>
<td><strong>expression</strong></td>
<td><strong>result type</strong></td>
<td><strong>notes</strong></td>
<td><strong>complexity</strong></td>
</tr>
<tr>
<td></td>
<td></td>
<td></td>
<td></td>
</tr>
<tr>
<td></td>
<td></td>
<td></td>
<td></td>
</tr>
<tr>
<td></td>
<td></td>
<td></td>
<td></td>
</tr>
<tr>
<td></td>
<td></td>
<td></td>
<td></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">
<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.
</th></tr>
<tr>
<td><strong>expression</strong></td>
<td><strong>result type</strong></td>
<td><strong>notes</strong></td>
<td><strong>complexity</strong></td>
</tr>
<tr>
<td></td>
<td></td>
<td></td>
<td></td>
</tr>
<tr>
<td></td>
<td></td>
<td></td>
<td></td>
</tr>
<tr>
<td></td>
<td></td>
<td></td>
<td></td>
</tr>
<tr>
<td></td>
<td></td>
<td></td>
<td></td>
</tr>
</table title="Table 66"></p></a>
<a name="67"><p>
<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">
These are in addition to the requirements of <a href="#65">containers</a>.
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>
</tr>
<tr>
<td></td>
<td></td>
<td></td>
<td></td>
</tr>
<tr>
<td></td>
<td></td>
<td></td>
<td></td>
</tr>
<tr>
<td></td>
<td></td>
<td></td>
<td></td>
</tr>
<tr>
<td></td>
<td></td>
<td></td>
<td></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">
<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>
</tr>
<tr>
<td></td>
<td></td>
<td></td>
<td></td>
</tr>
<tr>
<td></td>
<td></td>
<td></td>
<td></td>
</tr>
<tr>
<td></td>
<td></td>
<td></td>
<td></td>
</tr>
<tr>
<td></td>
<td></td>
<td></td>
<td></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">
<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>.
</th></tr>
<tr>
<td><strong>expression</strong></td>
<td><strong>result type</strong></td>
<td><strong>notes</strong></td>
<td><strong>complexity</strong></td>
</tr>
<tr>
<td></td>
<td></td>
<td></td>
<td></td>
</tr>
<tr>
<td></td>
<td></td>
<td></td>
<td></td>
</tr>
<tr>
<td></td>
<td></td>
<td></td>
<td></td>
</tr>
<tr>
<td></td>
<td></td>
<td></td>
<td></td>
</tr>
</table title="Table 69"></p></a>
<hr />
<p class="smallertext"><em>
See <a href="mainpage.html">mainpage.html</a> for copying conditions.
</em></p>
</body>
</html>
...@@ -201,7 +201,7 @@ TAB_SIZE = 4 ...@@ -201,7 +201,7 @@ TAB_SIZE = 4
# disable (NO) the todo list. This list is created by putting \todo # disable (NO) the todo list. This list is created by putting \todo
# commands in the documentation. # commands in the documentation.
GENERATE_TODOLIST = NO GENERATE_TODOLIST = YES
# The GENERATE_TESTLIST tag can be used to enable (YES) or # The GENERATE_TESTLIST tag can be used to enable (YES) or
# disable (NO) the test list. This list is created by putting \test # disable (NO) the test list. This list is created by putting \test
...@@ -223,7 +223,8 @@ GENERATE_BUGLIST = YES ...@@ -223,7 +223,8 @@ GENERATE_BUGLIST = YES
# You can put \n's in the value part of an alias to insert newlines. # You can put \n's in the value part of an alias to insert newlines.
ALIASES = "maint=@if maint" \ ALIASES = "maint=@if maint" \
"endmaint=@endif" "endmaint=@endif" \
"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 # The ENABLED_SECTIONS tag can be used to enable conditional
# documentation sections, marked by \if sectionname ... \endif. # documentation sections, marked by \if sectionname ... \endif.
......
// Functions used by iterators -*- C++ -*- // Functions used by iterators -*- C++ -*-
// Copyright (C) 2001 Free Software Foundation, Inc. // Copyright (C) 2001, 2002 Free Software Foundation, Inc.
// //
// This file is part of the GNU ISO C++ Library. This library is free // This file is part of the GNU ISO C++ Library. This library is free
// software; you can redistribute it and/or modify it under the // software; you can redistribute it and/or modify it under the
...@@ -56,89 +56,118 @@ ...@@ -56,89 +56,118 @@
/** @file stl_iterator_base_funcs.h /** @file stl_iterator_base_funcs.h
* This is an internal header file, included by other library headers. * This is an internal header file, included by other library headers.
* You should not attempt to use it directly. * You should not attempt to use it directly.
*
* This file contains all of the general iterator-related utility
* functions, such as distance() and advance().
*/ */
#ifndef __GLIBCPP_INTERNAL_ITERATOR_BASE_FUNCS_H #ifndef __GLIBCPP_INTERNAL_ITERATOR_BASE_FUNCS_H
#define __GLIBCPP_INTERNAL_ITERATOR_BASE_FUNCS_H #define __GLIBCPP_INTERNAL_ITERATOR_BASE_FUNCS_H
// This file contains all of the general iterator-related utility
// functions, such as distance() and advance().
// The internal file stl_iterator.h contains predefined iterators,
// such as front_insert_iterator and istream_iterator.
#pragma GCC system_header #pragma GCC system_header
#include <bits/concept_check.h> #include <bits/concept_check.h>
// Since this entire file is within namespace std, there's no reason to
// waste two spaces along the left column. Thus the leading indentation is
// slightly violated from here on.
namespace std namespace std
{ {
template<typename _InputIterator> template<typename _InputIterator>
inline typename iterator_traits<_InputIterator>::difference_type inline typename iterator_traits<_InputIterator>::difference_type
__distance(_InputIterator __first, _InputIterator __last, input_iterator_tag) __distance(_InputIterator __first, _InputIterator __last, input_iterator_tag)
{ {
// concept requirements // concept requirements
__glibcpp_function_requires(_InputIteratorConcept<_InputIterator>) __glibcpp_function_requires(_InputIteratorConcept<_InputIterator>)
typename iterator_traits<_InputIterator>::difference_type __n = 0;
while (__first != __last) { typename iterator_traits<_InputIterator>::difference_type __n = 0;
++__first; ++__n; while (__first != __last) {
} ++__first; ++__n;
return __n;
} }
return __n;
template<typename _RandomAccessIterator> }
inline typename iterator_traits<_RandomAccessIterator>::difference_type
__distance(_RandomAccessIterator __first, _RandomAccessIterator __last, template<typename _RandomAccessIterator>
random_access_iterator_tag) inline typename iterator_traits<_RandomAccessIterator>::difference_type
{ __distance(_RandomAccessIterator __first, _RandomAccessIterator __last,
// concept requirements random_access_iterator_tag)
__glibcpp_function_requires(_RandomAccessIteratorConcept<_RandomAccessIterator>) {
return __last - __first; // concept requirements
} __glibcpp_function_requires(_RandomAccessIteratorConcept<_RandomAccessIterator>)
return __last - __first;
template<typename _InputIterator> }
inline typename iterator_traits<_InputIterator>::difference_type
distance(_InputIterator __first, _InputIterator __last) /**
{ * @brief A generalization of pointer arithmetic.
// concept requirements -- taken care of in __distance * @param first An input iterator.
return __distance(__first, __last, __iterator_category(__first)); * @param last An input iterator.
} * @return The distance between them.
*
template<typename _InputIter, typename _Distance> * Returns @c n such that first + n == last. This requires that @p last
inline void * must be reachable from @p first. Note that @c n may be negative.
__advance(_InputIter& __i, _Distance __n, input_iterator_tag) *
{ * For random access iterators, this uses their @c + and @c - operations
// concept requirements * and are constant time. For other %iterator classes they are linear time.
__glibcpp_function_requires(_InputIteratorConcept<_InputIter>) */
template<typename _InputIterator>
inline typename iterator_traits<_InputIterator>::difference_type
distance(_InputIterator __first, _InputIterator __last)
{
// concept requirements -- taken care of in __distance
return __distance(__first, __last, __iterator_category(__first));
}
template<typename _InputIter, typename _Distance>
inline void
__advance(_InputIter& __i, _Distance __n, input_iterator_tag)
{
// concept requirements
__glibcpp_function_requires(_InputIteratorConcept<_InputIter>)
while (__n--) ++__i;
}
template<typename _BidirectionalIterator, typename _Distance>
inline void
__advance(_BidirectionalIterator& __i, _Distance __n,
bidirectional_iterator_tag)
{
// concept requirements
__glibcpp_function_requires(_BidirectionalIteratorConcept<_BidirectionalIterator>)
if (__n > 0)
while (__n--) ++__i; while (__n--) ++__i;
} else
while (__n++) --__i;
template<typename _BidirectionalIterator, typename _Distance> }
inline void
__advance(_BidirectionalIterator& __i, _Distance __n, bidirectional_iterator_tag) template<typename _RandomAccessIterator, typename _Distance>
{ inline void
// concept requirements __advance(_RandomAccessIterator& __i, _Distance __n,
__glibcpp_function_requires(_BidirectionalIteratorConcept<_BidirectionalIterator>) random_access_iterator_tag)
if (__n > 0) {
while (__n--) ++__i; // concept requirements
else __glibcpp_function_requires(_RandomAccessIteratorConcept<_RandomAccessIterator>)
while (__n++) --__i; __i += __n;
} }
template<typename _RandomAccessIterator, typename _Distance> /**
inline void * @brief A generalization of pointer arithmetic.
__advance(_RandomAccessIterator& __i, _Distance __n, random_access_iterator_tag) * @param i An input iterator.
{ * @param n The "delta" by which to change @p i.
// concept requirements * @return Nothing.
__glibcpp_function_requires(_RandomAccessIteratorConcept<_RandomAccessIterator>) *
__i += __n; * This increments @p i by @p n. For bidirectional and random access
} * iterators, @p n may be negative, in which case @p i is decremented.
*
template<typename _InputIterator, typename _Distance> * For random access iterators, this uses their @c + and @c - operations
inline void * and are constant time. For other %iterator classes they are linear time.
advance(_InputIterator& __i, _Distance __n) */
{ template<typename _InputIterator, typename _Distance>
// concept requirements -- taken care of in __advance inline void
__advance(__i, __n, __iterator_category(__i)); advance(_InputIterator& __i, _Distance __n)
} {
// concept requirements -- taken care of in __advance
__advance(__i, __n, __iterator_category(__i));
}
} // namespace std } // namespace std
......
// Types used in iterator implementation -*- C++ -*- // Types used in iterator implementation -*- C++ -*-
// Copyright (C) 2001 Free Software Foundation, Inc. // Copyright (C) 2001, 2002 Free Software Foundation, Inc.
// //
// This file is part of the GNU ISO C++ Library. This library is free // This file is part of the GNU ISO C++ Library. This library is free
// software; you can redistribute it and/or modify it under the // software; you can redistribute it and/or modify it under the
...@@ -90,9 +90,12 @@ namespace std ...@@ -90,9 +90,12 @@ namespace std
/** /**
* This class does nothing but define nested typedefs. Iterator classes * This class does nothing but define nested typedefs. %Iterator classes
* can inherit from this class to save some work. The typedefs are then * can inherit from this class to save some work. The typedefs are then
* used in specializations and overloading. * used in specializations and overloading.
*
* In particular, there are no default implementations of requirements
* such as @c operator++ and the like. (How could there be?)
*/ */
template<typename _Category, typename _Tp, typename _Distance = ptrdiff_t, template<typename _Category, typename _Tp, typename _Distance = ptrdiff_t,
typename _Pointer = _Tp*, typename _Reference = _Tp&> typename _Pointer = _Tp*, typename _Reference = _Tp&>
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment