FreeChainXenon/gcc
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Intro.3: More notes.

Browse source 
2001-11-19  Phil Edwards  <pme@gcc.gnu.org>

	* docs/doxygen/Intro.3:  More notes.
	* docs/doxygen/style.css:  Update to default style from Doxygen 1.2.10.
	* include/bits/stl_algobase.h:  Add doxygen hooks for functions.
	* include/ext/hash_map:  Add @file hook.
	* include/ext/hash_set:  Likewise.
	* include/ext/rope:  Likewise.
	* include/ext/ropeimpl.h:  Likewise.
	* include/ext/slist:  Likewise.
	* include/ext/stl_hash_fun.h:  Likewise.
	* include/ext/stl_hashtable.h:  Likewise.
	* include/ext/stl_rope.h:  Likewise.

	* docs/html/17_intro/license.html:  Remove "experimental" sentence.
	* docs/html/19_diagnostics/howto.html:  Document new verbose
	terminate handler.
	* testsuite/27_io/filebuf.cc:  Fix comment, move tweakable parameter
	to more visible (closer to description) position.

	* libsupc++/eh_type.cc:  Formatting tweak.
	* libsupc++/exception:  Likewise.
	* src/vterminate.cc:  Likewise.

	* docs/html/17_intro/porting.html:  Regenerate.
	* docs/html/faq/index.txt:  Regenerate.

From-SVN: r47193
This commit is contained in:
Phil Edwards 2001-11-20 00:51:37 +00:00
parent b73f64948e
commit 1b4a6975f7
20 changed files with 322 additions and 34 deletions
Download patch file Download diff file Expand all files Collapse all files

27
libstdc++-v3/ChangeLog
View file

@ -1,3 +1,30 @@
2001-11-19 Phil Edwards <pme@gcc.gnu.org>
* docs/doxygen/Intro.3: More notes.
* docs/doxygen/style.css: Update to default style from Doxygen 1.2.10.
* include/bits/stl_algobase.h: Add doxygen hooks for functions.
* include/ext/hash_map: Add @file hook.
* include/ext/hash_set: Likewise.
* include/ext/rope: Likewise.
* include/ext/ropeimpl.h: Likewise.
* include/ext/slist: Likewise.
* include/ext/stl_hash_fun.h: Likewise.
* include/ext/stl_hashtable.h: Likewise.
* include/ext/stl_rope.h: Likewise.
* docs/html/17_intro/license.html: Remove "experimental" sentence.
* docs/html/19_diagnostics/howto.html: Document new verbose
terminate handler.
* testsuite/27_io/filebuf.cc: Fix comment, move tweakable parameter
to more visible (closer to description) position.
* libsupc++/eh_type.cc: Formatting tweak.
* libsupc++/exception: Likewise.
* src/vterminate.cc: Likewise.
* docs/html/17_intro/porting.html: Regenerate.
* docs/html/faq/index.txt: Regenerate.
2001-11-18 Jason Merrill <jason@redhat.com>
* libsupc++/eh_personality.cc (__cxa_call_unexpected): Take void*.

3
libstdc++-v3/docs/doxygen/Intro.3
View file

@ -15,7 +15,8 @@ All standard library entities are declared within
and have manual entries beginning with "std_". For example, to see
documentation of the template class
.I std::vector
one would use "man std_vector".
one would use "man std_vector". Some entities do not have a separate man
page; for those see the main listing in "man Namespace_Std".
.P
All the man pages are automatically generated by Doxygen. For more
information on this tool, see the HTML counterpart to these man pages.

11
libstdc++-v3/docs/doxygen/style.css
View file

@ -5,12 +5,15 @@ A.el { text-decoration: none; font-weight: bold }
A.elRef { font-weight: bold }
A.code { text-decoration: none; font-weight: normal; color: #4444ee }
A.codeRef { font-weight: normal; color: #4444ee }
A:hover { text-decoration: none; background-color: #f2f2ff }
DL.el { margin-left: -1cm }
DIV.fragment { width: 100%; border: none; background-color: #eeeeee }
DIV.ah { background-color: black; margin-bottom: 3; margin-top: 3 }
TD.md { background-color: #f2f2ff }
DIV.groupHeader { margin-left: 16; margin-top: 12; margin-bottom: 6; font-weight: bold }
DIV.groupText { margin-left: 16; font-style: italic; font-size: smaller }
DIV.ah { background-color: black; font-weight: bold; color: #ffffff; margin-bottom: 3px; margin-top: 3px }
TD.md { background-color: #f2f2ff; font-weight: bold; }
TD.mdname1 { background-color: #f2f2ff; font-weight: bold; font-style: italic; }
TD.mdname { background-color: #f2f2ff; font-weight: bold; font-style: italic; width: 600px; }
DIV.groupHeader { margin-left: 16px; margin-top: 12px; margin-bottom: 6px; font-weight: bold }
DIV.groupText { margin-left: 16px; font-style: italic; font-size: smaller }
FONT.keyword { color: #008000 }
FONT.keywordtype { color: #604020 }
FONT.keywordflow { color: #e08000 }

3
libstdc++-v3/docs/html/17_intro/license.html
View file

@ -13,9 +13,6 @@
<h1 class="centered"><a name="top">Licenses for the Library</a></h1>
<p><strong>As long as this sentence is in place, this page isn't
official. It is still experimental if you are reading this.</strong></p>
<p>There are two licenses affecting GNU libstdc++-v3: one for the code, and
one for the documentation. Here we will describe both of them, and try
to answer some of the widespread questions. If you have more questions,

4
libstdc++-v3/docs/html/17_intro/porting.html
View file

@ -115,8 +115,8 @@ stream (or one hooked to a pipe) is not allowed by the OS. In this
case, getc()/ungetc() will be used at some key locations in the library
implementation instead of fseek(). Currently, the code path to avoid
fseek() is only enabled when the seek size is 1 character away from the
current stream position. This is known to improve *-unknown-freebsd*
and sparc-sun-solaris2.*.
current stream position. This is known to improve *-unknown-freebsd*,
sparc-sun-solaris2.* and *-*-mingw32*.
<p>Finally, you should bracket the entire file in an include-guard, like
this:

59
libstdc++-v3/docs/html/19_diagnostics/howto.html
View file

@ -26,6 +26,7 @@
<li><a href="#1">Adding data to exceptions</a>
<li><a href="#2">Exception class hierarchy diagram</a>
<li><a href="#3">Concept checkers -- <strong>new and improved!</strong></a>
<li><a href="#4">Verbose <code>terminate</code></a>
</ul>
<hr>
@ -101,7 +102,65 @@
<p>Right now they are off by default. More will be added once
GCC 3.0 is released and we have time to revisit this topic.
</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="4">Verbose <code>terminate</code></a></h2>
<p>If you are having difficulty with uncaught exceptions and want a
little bit of help debugging the causes of the core dumps, you can
make use of a GNU extension in GCC 3.1 and later:
<pre>
#include &lt;exception&gt;
int main()
{
std::set_terminate (__gnu_cxx::verbose_terminate_handler);
...
throw <em>anything</em>;
}</pre>
</p>
<p>The <code> verbose_terminate_handler </code> function obtains the name
of the current exception, attempts to demangle it, and prints it to
stderr. If the exception is derived from <code> std::exception </code>
then the output from <code>what()</code> will be included.
</p>
<p>Any replacement termination function is required to kill the program
without returning; this one calls abort.
</p>
<p>For example:
<pre>
#include &lt;exception&gt;
#include &lt;stdexcept&gt;
struct BLARGH : std::runtime_error
{
BLARGH (const string&amp; whatarg)
: std::runtime_error(whatarg) { }
};
int main (int argc)
{
std::set_terminate (__gnu_cxx::verbose_terminate_handler);
if (argc &gt; 5)
throw BLARGH(&quot;argc is greater than 5!&quot;);
else
throw argc;
}</pre>
</p>
<p>In GCC 3.1 and later, this gives
<pre>
% ./a.out
terminate called after throwing a `int'
Aborted
% ./a.out f f f f f f f f f f f
terminate called after throwing a `BLARGH'
what(): argc is greater than 5!
Aborted
%</pre>
The 'Aborted' line comes from the call to abort(), of course.
</p>
<p>Return <a href="#top">to top of page</a> or
<a href="../faq/index.html">to the FAQ</a>.
</p>

7
libstdc++-v3/docs/html/faq/index.txt
View file

@ -643,9 +643,10 @@ a
All library objects are safe to use in a multithreaded program as long
as each thread carefully locks out access by any other thread while it
uses any object visible to another thread. This requirement includes
both read and write access to objects; do not assume that two threads
may read a shared standard container at the same time.
uses any object visible to another thread. In general, this
requirement includes both read and write access to objects; unless
otherwise documented as safe, do not assume that two threads may
access a shared standard library object at the same time.
See chapters [84]17 (library introduction), [85]23 (containers), and
[86]27 (I/O) for more information.

183
libstdc++-v3/include/bits/stl_algobase.h
View file

@ -155,6 +155,16 @@ namespace std
if (__b < __a) return __b; return __a;
}
/**
* @brief This does what you think it does.
* @param a A thing of arbitrary type.
* @param b Another thing of arbitrary type.
* @return The greater of the parameters.
*
* This is the simple classic generic implementation. It will work on
* temporary expressions, since they are only evaluated once, unlike a
* preprocessor macro.
*/
template<typename _Tp>
inline const _Tp&
max(const _Tp& __a, const _Tp& __b)
@ -165,6 +175,16 @@ namespace std
if (__a < __b) return __b; return __a;
}
/**
* @brief This does what you think it does.
* @param a A thing of arbitrary type.
* @param b Another thing of arbitrary type.
* @param comp A @link s20_3_3_comparisons comparison functor@endlink.
* @return The lesser of the parameters.
*
* This will work on temporary expressions, since they are only evaluated
* once, unlike a preprocessor macro.
*/
template<typename _Tp, typename _Compare>
inline const _Tp&
min(const _Tp& __a, const _Tp& __b, _Compare __comp)
@ -173,6 +193,16 @@ namespace std
if (__comp(__b, __a)) return __b; return __a;
}
/**
* @brief This does what you think it does.
* @param a A thing of arbitrary type.
* @param b Another thing of arbitrary type.
* @param comp A @link s20_3_3_comparisons comparison functor@endlink.
* @return The greater of the parameters.
*
* This will work on temporary expressions, since they are only evaluated
* once, unlike a preprocessor macro.
*/
template<typename _Tp, typename _Compare>
inline const _Tp&
max(const _Tp& __a, const _Tp& __b, _Compare __comp)
@ -295,6 +325,19 @@ namespace std
return __copy_ni2(__first, __last, __result, __Normal());
}
/**
* @brief Copies the range [first,last) into result.
* @param first An input iterator.
* @param last An input iterator.
* @param result An output iterator.
* @return result + (first - last)
*
* This inline function will boil down to a call to @c memmove whenever
* possible. Failing that, if random access iterators are passed, then the
* loop count will be known (and therefore a candidate for compiler
* optimizations such as unrolling). If the input range and the output
* range overlap, then the copy_backward function should be used instead.
*/
template<typename _InputIter, typename _OutputIter>
inline _OutputIter
copy(_InputIter __first, _InputIter __last, _OutputIter __result)
@ -419,6 +462,20 @@ namespace std
__Normal());
}
/**
* @brief Copies the range [first,last) into result.
* @param first An input iterator.
* @param last An input iterator.
* @param result An output iterator.
* @return result - (first - last)
*
* The function has the same effect as copy, but starts at the end of the
* range and works its way to the start, returning the start of the result.
* This inline function will boil down to a call to @c memmove whenever
* possible. Failing that, if random access iterators are passed, then the
* loop count will be known (and therefore a candidate for compiler
* optimizations such as unrolling).
*/
template <typename _BI1, typename _BI2>
inline _BI2
copy_backward(_BI1 __first, _BI1 __last, _BI2 __result)
@ -462,6 +519,20 @@ namespace std
return pair<_RAIter, _OutputIter>(__last, copy(__first, __last, __result));
}
/**
* @brief Copies the range [first,first+count) into [result,result+count).
* @param first An input iterator.
* @param count The number of elements to copy.
* @param result An output iterator.
* @return A std::pair composed of first+count and result+count.
*
* This is an SGI extension.
* This inline function will boil down to a call to @c memmove whenever
* possible. Failing that, if random access iterators are passed, then the
* loop count will be known (and therefore a candidate for compiler
* optimizations such as unrolling).
* @ingroup SGIextensions
*/
template<typename _InputIter, typename _Size, typename _OutputIter>
inline pair<_InputIter, _OutputIter>
copy_n(_InputIter __first, _Size __count, _OutputIter __result)
@ -478,6 +549,17 @@ namespace std
// fill and fill_n
/**
* @brief Fills the range [first,last) with copies of value.
* @param first A forward iterator.
* @param last A forward iterator.
* @param value A reference-to-const of arbitrary type.
* @return Nothing.
*
* This function fills a range with copies of the same value. For one-byte
* types filling contiguous areas of memory, this becomes an inline call to
* @c memset.
*/
template<typename _ForwardIter, typename _Tp>
void
fill(_ForwardIter __first, _ForwardIter __last, const _Tp& __value)
@ -489,6 +571,17 @@ namespace std
*__first = __value;
}
/**
* @brief Fills the range [first,first+n) with copies of value.
* @param first An output iterator.
* @param n The count of copies to perform.
* @param value A reference-to-const of arbitrary type.
* @return The iterator at first+n.
*
* This function fills a range with copies of the same value. For one-byte
* types filling contiguous areas of memory, this becomes an inline call to
* @c memset.
*/
template<typename _OutputIter, typename _Size, typename _Tp>
_OutputIter
fill_n(_OutputIter __first, _Size __n, const _Tp& __value)
@ -552,6 +645,18 @@ namespace std
//--------------------------------------------------
// equal and mismatch
/**
* @brief Finds the places in ranges which don't match.
* @param first1 An input iterator.
* @param last1 An input iterator.
* @param first2 An input iterator.
* @return A pair of iterators pointing to the first mismatch.
*
* This compares the elements of two ranges using @c == and returns a pair
* of iterators. The first iterator points into the first range, the
* second iterator points into the second range, and the elements pointed
* to by the iterators are not equal.
*/
template<typename _InputIter1, typename _InputIter2>
pair<_InputIter1, _InputIter2>
mismatch(_InputIter1 __first1, _InputIter1 __last1,
@ -572,6 +677,20 @@ namespace std
return pair<_InputIter1, _InputIter2>(__first1, __first2);
}
/**
* @brief Finds the places in ranges which don't match.
* @param first1 An input iterator.
* @param last1 An input iterator.
* @param first2 An input iterator.
* @param binary_pred A binary predicate @link s20_3_1_base functor@endlink.
* @return A pair of iterators pointing to the first mismatch.
*
* This compares the elements of two ranges using the binary_pred
* parameter, and returns a pair
* of iterators. The first iterator points into the first range, the
* second iterator points into the second range, and the elements pointed
* to by the iterators are not equal.
*/
template<typename _InputIter1, typename _InputIter2, typename _BinaryPredicate>
pair<_InputIter1, _InputIter2>
mismatch(_InputIter1 __first1, _InputIter1 __last1,
@ -589,6 +708,17 @@ namespace std
return pair<_InputIter1, _InputIter2>(__first1, __first2);
}
/**
* @brief Tests a range for element-wise equality.
* @param first1 An input iterator.
* @param last1 An input iterator.
* @param first2 An input iterator.
* @return A boolean true or false.
*
* This compares the elements of two ranges using @c == and returns true or
* false depending on whether all of the corresponding elements of the
* ranges are equal.
*/
template<typename _InputIter1, typename _InputIter2>
inline bool
equal(_InputIter1 __first1, _InputIter1 __last1,
@ -607,6 +737,19 @@ namespace std
return true;
}
/**
* @brief Tests a range for element-wise equality.
* @param first1 An input iterator.
* @param last1 An input iterator.
* @param first2 An input iterator.
* @param binary_pred A binary predicate @link s20_3_1_base functor@endlink.
* @return A boolean true or false.
*
* This compares the elements of two ranges using the binary_pred
* parameter, and returns true or
* false depending on whether all of the corresponding elements of the
* ranges are equal.
*/
template<typename _InputIter1, typename _InputIter2, typename _BinaryPredicate>
inline bool
equal(_InputIter1 __first1, _InputIter1 __last1,
@ -627,6 +770,20 @@ namespace std
// lexicographical_compare and lexicographical_compare_3way.
// (the latter is not part of the C++ standard.)
/**
* @brief Performs "dictionary" comparison on ranges.
* @param first1 An input iterator.
* @param last1 An input iterator.
* @param first2 An input iterator.
* @param last2 An input iterator.
* @return A boolean true or false.
*
* "Returns true if the sequence of elements defined by the range
* [first1,last1) is lexicographically less than the sequence of elements
* defined by the range [first2,last2). Returns false otherwise."
* (Quoted from [25.3.8]/1.) If the iterators are all character pointers,
* then this is an inline call to @c memcmp.
*/
template<typename _InputIter1, typename _InputIter2>
bool
lexicographical_compare(_InputIter1 __first1, _InputIter1 __last1,
@ -650,6 +807,18 @@ namespace std
return __first1 == __last1 && __first2 != __last2;
}
/**
* @brief Performs "dictionary" comparison on ranges.
* @param first1 An input iterator.
* @param last1 An input iterator.
* @param first2 An input iterator.
* @param last2 An input iterator.
* @param comp A @link s20_3_3_comparisons comparison functor@endlink.
* @return A boolean true or false.
*
* The same as the four-parameter @c lexigraphical_compare, but uses the
* comp parameter instead of @c <.
*/
template<typename _InputIter1, typename _InputIter2, typename _Compare>
bool
lexicographical_compare(_InputIter1 __first1, _InputIter1 __last1,
@ -749,6 +918,20 @@ namespace std
#endif
}
/**
* @brief @c memcmp on steroids.
* @param first1 An input iterator.
* @param last1 An input iterator.
* @param first2 An input iterator.
* @param last2 An input iterator.
* @return An int, as with @c memcmp.
*
* The return value will be less than zero if the first range is
* "lexigraphically less than" the second, greater than zero if the second
* range is "lexigraphically less than" the first, and zero otherwise.
* This is an SGI extension.
* @ingroup SGIextensions
*/
template<typename _InputIter1, typename _InputIter2>
int
lexicographical_compare_3way(_InputIter1 __first1, _InputIter1 __last1,

5
libstdc++-v3/include/ext/hash_map
View file

@ -53,8 +53,9 @@
*
*/
/* NOTE: This is an internal header file, included by other STL headers.
* You should not attempt to use it directly.
/** @file hash_map
* This header file is an extension to the Standard C++ Library. You should
* use the "ext/" path prefix in your @c #include statements.
*/
#ifndef __SGI_STL_INTERNAL_HASH_MAP_H

5
libstdc++-v3/include/ext/hash_set
View file

@ -53,8 +53,9 @@
*
*/
/* NOTE: This is an internal header file, included by other STL headers.
* You should not attempt to use it directly.
/** @file hash_set
* This header file is an extension to the Standard C++ Library. You should
* use the "ext/" path prefix in your @c #include statements.
*/
#ifndef __SGI_STL_INTERNAL_HASH_SET_H

5
libstdc++-v3/include/ext/rope
View file

@ -40,6 +40,11 @@
* purpose. It is provided "as is" without express or implied warranty.
*/
/** @file rope
* This header file is an extension to the Standard C++ Library. You should
* use the "ext/" path prefix in your @c #include statements.
*/
#ifndef __SGI_STL_ROPE
#define __SGI_STL_ROPE

3
libstdc++-v3/include/ext/ropeimpl.h
View file

@ -40,7 +40,8 @@
* purpose. It is provided "as is" without express or implied warranty.
*/
/* NOTE: This is an internal header file, included by other STL headers.
/** @file ropeimpl.h
* This is an internal header file, included by other library headers.
* You should not attempt to use it directly.
*/

5
libstdc++-v3/include/ext/slist
View file

@ -41,8 +41,9 @@
*
*/
/* NOTE: This is an internal header file, included by other STL headers.
* You should not attempt to use it directly.
/** @file slist
* This header file is an extension to the Standard C++ Library. You should
* use the "ext/" path prefix in your @c #include statements.
*/
#ifndef __SGI_STL_INTERNAL_SLIST_H

3
libstdc++-v3/include/ext/stl_hash_fun.h
View file

@ -53,7 +53,8 @@
*
*/
/* NOTE: This is an internal header file, included by other STL headers.
/** @file stl_hash_fun.h
* This is an internal header file, included by other library headers.
* You should not attempt to use it directly.
*/

3
libstdc++-v3/include/ext/stl_hashtable.h
View file

@ -53,7 +53,8 @@
*
*/
/* NOTE: This is an internal header file, included by other STL headers.
/** @file stl_hashtable.h
* This is an internal header file, included by other library headers.
* You should not attempt to use it directly.
*/

3
libstdc++-v3/include/ext/stl_rope.h
View file

@ -40,7 +40,8 @@
* purpose. It is provided "as is" without express or implied warranty.
*/
/* NOTE: This is an internal header file, included by other STL headers.
/** @file stl_rope.h
* This is an internal header file, included by other library headers.
* You should not attempt to use it directly.
*/

3
libstdc++-v3/libsupc++/eh_type.cc
View file

@ -31,7 +31,8 @@
#include <typeinfo>
#include "unwind-cxx.h"
namespace __cxxabiv1 {
namespace __cxxabiv1
{
// Returns the type_info for the currently handled exception [15.3/8], or
// null if there is none.

3
libstdc++-v3/libsupc++/exception
View file

@ -95,7 +95,8 @@ namespace std
bool uncaught_exception() throw();
} // namespace std
namespace __gnu_cxx {
namespace __gnu_cxx
{
/** A replacement for the standard terminate_handler which prints more
information about the terminating exception (if any) on stderr. */
void verbose_terminate_handler ();

3
libstdc++-v3/src/vterminate.cc
View file

@ -36,7 +36,8 @@
using namespace std;
using namespace abi;
namespace __gnu_cxx {
namespace __gnu_cxx
{
/** This is a replacement for the standard terminate_handler which prints
more information about the terminating exception (if any) on stderr. */

8
libstdc++-v3/testsuite/27_io/filebuf.cc
View file

@ -19,12 +19,16 @@
// USA.
// NB: this test assumes that _M_buf_size == 40, and not the usual
// buffer_size length of 8092, so that overflow/underflow can be
// buffer_size length of BUFSIZ (8192), so that overflow/underflow can be
// simulated a bit more readily.
// NRB (Nota Really Bene): setting it to 40 breaks the test, as intended.
// @require@ %-*.tst %-*.txt
// @diff@ %-*.tst %*.txt
const int buffer_size = 8192;
//const int buffer_size = 40;
#include <fstream>
#include <iostream>
#include <testsuite_hooks.h>
@ -46,8 +50,6 @@ derived_filebuf fb_01; // in
derived_filebuf fb_02; // out
derived_filebuf fb_03; // in | out
const int buffer_size = 8192;
// initialize filebufs to be the same size regardless of platform
void test00()