From 79e790677d5a0088d60da607ef0c93c1c06becb5 Mon Sep 17 00:00:00 2001
From: Benjamin Kosnik <bkoz@redhat.com>
Date: Mon, 10 Dec 2007 00:38:36 +0000
Subject: howto.html: Update.
2007-12-09 Benjamin Kosnik <bkoz@redhat.com>
* docs/html/ext/howto.html: Update.
* docs/html/ext/sgiexts.html: Same.
* docs/html/ext/concurrence.html: New. Document extensions.
* docs/html/17_intro/api.html: Move some bits...
* docs/html/17_intro/backwards_compatibility.html: here. New. Add
compatibility suggestions, move existing ones.
* docs/html/17_intro/howto.html: Update info.
* docs/html/18_support/howto.html: Tweak.
* docs/html/faq/index.html: Update thread info.
* docs/html/documentation.html: Add links.
* docs/html/20_util/allocator.html: Update info.
* include/precompiled/stdc++.h: Add C++0x includes if appropriate.
* testsuite/17_intro/headers/c++200x/all.cc: Same.
From-SVN: r130732
---
libstdc++-v3/docs/html/17_intro/api.html | 623 +++---------
.../html/17_intro/backwards_compatibility.html | 1073 ++++++++++++++++++++
libstdc++-v3/docs/html/17_intro/howto.html | 599 +++++++----
libstdc++-v3/docs/html/18_support/howto.html | 8 +-
libstdc++-v3/docs/html/20_util/allocator.html | 78 +-
libstdc++-v3/docs/html/documentation.html | 35 +-
libstdc++-v3/docs/html/ext/concurrence.html | 342 +++++++
libstdc++-v3/docs/html/ext/howto.html | 17 +-
libstdc++-v3/docs/html/ext/sgiexts.html | 38 +-
libstdc++-v3/docs/html/faq/index.html | 20 +-
10 files changed, 2088 insertions(+), 745 deletions(-)
create mode 100644 libstdc++-v3/docs/html/17_intro/backwards_compatibility.html
create mode 100644 libstdc++-v3/docs/html/ext/concurrence.html
(limited to 'libstdc++-v3/docs/html')
diff --git a/libstdc++-v3/docs/html/17_intro/api.html b/libstdc++-v3/docs/html/17_intro/api.html
index bfe7b20..983d044 100644
--- a/libstdc++-v3/docs/html/17_intro/api.html
+++ b/libstdc++-v3/docs/html/17_intro/api.html
@@ -5,8 +5,8 @@
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
- <meta name="AUTHOR" content="bkoz@gcc.gnu.org (Benjamin Kosnik), Felix Natter" />
- <meta name="KEYWORDS" content="C++, libstdc++, API, deprecate backward" />
+ <meta name="AUTHOR" content="bkoz@gcc.gnu.org (Benjamin Kosnik)" />
+ <meta name="KEYWORDS" content="C++, libstdc++, API, evolution, deprecate" />
<meta name="DESCRIPTION" content="API evolution and deprecation history" />
<meta name="GENERATOR" content="emacs and ten fingers" />
<title>API Evolution and Deprecation History</title>
@@ -22,7 +22,7 @@
<p class="fineprint"><em>
The latest version of this document is always available at
<a href="http://gcc.gnu.org/onlinedocs/libstdc++/17_intro/api.html">
- http://gcc.gnu.org/onlinedocs/libstdc++/17_intro/abi.html</a>.
+ http://gcc.gnu.org/onlinedocs/libstdc++/17_intro/api.html</a>.
</em></p>
<p><em>
@@ -30,565 +30,260 @@
</em></p>
<!-- ####################################################### -->
+
<hr />
<h3 class="left">
- <a name="C++ API v1">First.</a>
+ <a name="intro">API Evolution, Deprecation, and History of User Visible Changes</a>
</h3>
-<p>2.72</p>
-<p> The first generation GNU C++ library was called libg++. It had a
-working relationship with at least two kinds of dinosaur. Sadly, the
-details were not pried away from the estate.
+<p> A list of user-visible changes, by release version.
</p>
-<p>
+<h3 class="left">
+ <a name="3.0">3.0</a>
+</h3>
+<p>
+Extensions moved to <code>include/ext</code>.
</p>
-<p>Known Issues include many of the limitations of its immediate ancestor.</p>
-
-<h5>No <code>ios_base</code></h5>
-
-<p> At least some older implementations don't have <code>std::ios_base</code>, so you should use <code>std::ios::badbit</code>, <code>std::ios::failbit</code> and <code>std::ios::eofbit</code> and <code>std::ios::goodbit</code>.
+<p>
+Include files from the SGI/HP sources that pre-date the ISO standard
+are added. These files are placed into
+the <code>include/backward</code> directory and a deprecated warning
+is added that notifies on inclusion (<code>-Wno-deprecated</code>
+deactivates the warning.)
</p>
-<h5>No <code>cout</code> in <code>ostream.h</code>, no <code>cin</code> in <code>istream.h</code></h5>
-
-<p>
- In earlier versions of the standard,
- <tt><fstream.h></tt>,
- <tt><ostream.h></tt>
- and <tt><istream.h></tt>
- used to define
- <code>cout</code>, <code>cin</code> and so on. ISO C++ specifies that one needs to include
- <tt><iostream></tt>
- explicitly to get the required definitions.
- </p>
-<p> Some include adjustment may be required.</p>
+<p>Deprecated include <backward/strstream> added.</p>
+<p>Removal of include <builtinbuf.h>, <indstream.h>, <parsestream.h>, <PlotFile.h>, <SFile.h>, <stdiostream.h>, and <stream.h>.</p>
-<p>This project is no longer maintained or supported, and the sources
-archived. The code is considered replaced and rewritten.
-</p>
-<hr />
<h3 class="left">
- <a name="C++ API v1">Second.</a>
+ <a name="3.1">3.1</a>
</h3>
-<p> The second generation GNU C++ library was called libstdc++, or
-libstdc++-v2. It was a separate GNU project, although reliably paired
-with GCC. It spans the time between libg++ and pre-ISO C++.
-</p>
-
-<p>egcs 1.x</p>
-<p>2.95</p>
-<p>2.96</p>
-<p>Portability Notes</p>
-<p>Implementation Limitations</p>
-
-<h5>Namespace <code>std::</code> not supported.</h5>
-
-<p>
- Some care is required to support C++ compiler and or library
- implementation that do not have the standard library in
- <code>namespace std</code>.
- </p>
-<p>
- The following sections list some possible solutions to support compilers
- that cannot ignore <code>std::</code>-qualified names.
- </p>
-
-<p> First, see if the compiler has a flag for this. Namespace
- back-portability-issues are generally not a problem for g++
- compilers that do not have libstdc++ in <code>std::</code>, as
- the compilers use <code>-fno-honor-std</code> (ignore
- <code>std::</code>, <code>:: = std::</code>) by default. That
- is, the responsibility for enabling or disabling
- <code>std::</code> is on the user; the maintainer does not have
- to care about it. This probably applies to some other compilers
- as well.
- </p>
-
-<p>Second, experiment with a variety of pre-processor tricks.</p>
-
-<p> By defining <code>std</code> as a macro, fully-qualified namespace calls become global. Volia.
-
-<pre class="programlisting">
-#ifdef WICKEDLY_OLD_COMPILER
-# define std
-#endif
-</pre>
-(thanks to Juergen Heinzl who posted this solution on gnu.gcc.help)
-
-<p>Define a macro <code>NAMESPACE_STD</code>, which is defined to
-either "" or "std" based on a compile-type
-test. On GNU systems, this can be done with autotools by means of an
-autoconf test (see below) for <code>HAVE_NAMESPACE_STD</code>, then
-using that to set a value for the <code>NAMESPACE_STD</code> macro.
-At that point, one is able to use <code>NAMESPACE_STD::string</code>,
-which will evaluate to <code>std::string</code> or
-<code>::string</code> (ie, in the global namespace on systems that do
-not put <code>string</code> in <code>std::</code>). </p>
-
-<p>
-<pre>
-dnl @synopsis AC_CXX_HAVE_STD_NAMESPACE
-dnl
-dnl If the compiler supports the std namespace, define
-dnl HAVE_STD_NAMESPACE.
-dnl
-dnl @category Cxx
-dnl @author Todd Veldhuizen
-dnl @author Luc Maisonobe <luc@spaceroots.org>
-dnl @version 2004-02-04
-dnl @license AllPermissive
-
-AC_DEFUN([AC_CXX_HAVE_STD_NAMESPACE],
-[AC_CACHE_CHECK(whether the compiler supports the std namespace,
-ac_cv_cxx_have_std_namespace,
-[AC_LANG_SAVE
- AC_LANG_CPLUSPLUS
- AC_TRY_COMPILE([#include <iostream>
- std::istream& is = std::cin;
- ],[return 0;],
- ac_cv_cxx_have_std_namespace=yes, ac_cv_cxx_have_std_namespace=no)
- AC_LANG_RESTORE
-])
-if test "$ac_cv_cxx_have_std_namespace" = yes; then
- AC_DEFINE(HAVE_STD_NAMESPACE,,[define if the compiler supports the std namespace])
-fi
-])
-</pre>
-
-<h5>Illegal iterator usage.</h5>
<p>
- The following illustrate implementation-allowed illegal iterator
- use, and then correct use. <div class="itemizedlist"><ul
- type="disc"> <li><p>you cannot do
- <code>ostream::operator<<(iterator)</code> to print the
- address of the iterator => use <code>operator<<
- &*iterator</code> instead ?
- </p></li>
-<li><p>you cannot clear an iterator's reference
- (<code>iterator = 0</code>) => use
- <code>iterator = iterator_type();</code> ?
- </p></li>
-<li><p>
-<code>if (iterator)</code> won't work any
- more => use <code>if (iterator != iterator_type())</code>
- ?</p></li>
-</ul>
+Extensions from SGI/HP moved from <code>namespace std</code>
+to <code>namespace __gnu_cxx</code>. As part of this, the following
+new includes are
+added: <ext/algorithm>, <ext/functional>, <ext/iterator>, <ext/memory>, and <ext/numeric>.
+</p>
-<h5><code>isspace</code> from <tt><cctype></tt> is a macro
-</h5>
+<p>
+Extensions to <code>basic_filebuf</code> introduced: <code>__gnu_cxx::enc_filebuf</code>, and <code>__gnu_cxx::stdio_filebuf</code>.
+</p>
-<p> Glibc 2.0.x and 2.1.x define <tt><ctype.h></tt>
-functionality as macros (isspace, isalpha etc.).
+<p>
+Extensions to tree data structures added in <ext/rb_tree>.
</p>
<p>
-This implementations of libstdc++, however, keep these functions as
-macros, and so it is not back-portable to use fully qualified
-names. For example:
+Removal of <ext/tree>, moved to <backward/tree.h>.
</p>
-<pre>
-#include <cctype>
-int main() { std::isspace('X'); }
-</pre>
-<p>Results in something like this:
-</p>
+<h3 class="left">
+ <a name="3.2">3.2</a>
+</h3>
+<p>Symbol versioning introduced for shared library.</p>
-<pre>
-std:: (__ctype_b[(int) ( ( 'X' ) )] & (unsigned short int) _ISspace ) ;
-</pre>
+<p>Removal of include <backward/strstream.h>.</p>
+<h3 class="left">
+ <a name="3.3">3.3</a>
+</h3>
+<p>Allocator changes. Change <code>__malloc_alloc</code> to <code>malloc_allocator</code> and <code>__new_alloc</code> to <code>new_allocator</code>. </p>
-<p> A solution is to modify a header-file so that the compiler tells
-<tt><ctype.h></tt> to define functions instead of macros:
-</p>
+<p>Error handling in iostreams cleaned up, made consistent. </p>
-<pre>
-// This keeps isalnum, et al from being propagated as macros.
-#if __linux__
-# define __NO_CTYPE 1
-#endif
-</pre>
-<p>Then, include <ctype.h>
+<h3 class="left">
+ <a name="3.4">3.4</a>
+</h3>
+<p>
+Large file support.
</p>
-<p>
-Another problem arises if you put a <code>using namespace std;</code>
-declaration at the top, and include <tt><ctype.h></tt>. This
-will result in ambiguities between the definitions in the global
-namespace (<tt><ctype.h></tt>) and the definitions in namespace
-<code>std::</code> (<code><cctype></code>).
+<p> Extensions for generic characters and <code>char_traits</code> added in <ext/pod_char_traits.h>.
</p>
-<h5>No <code>vector::at</code>, <code>deque::at</code>, <code>string::at</code></h5>
+<p>
+Support for <code>wchar_t</code> specializations of <code>basic_filebuf</code> enhanced to support <code>UTF-8</code> and <code>Unicode</code>, depending on host. More hosts support basic <code>wchar_t</code> functionality.
+</p>
<p>
- One solution is to add an autoconf-test for this:
-</p>
-<pre>
-AC_MSG_CHECKING(for container::at)
-AC_TRY_COMPILE(
-[
-#include <vector>
-#include <deque>
-#include <string>
-
-using namespace std;
-],
-[
-deque<int> test_deque(3);
-test_deque.at(2);
-vector<int> test_vector(2);
-test_vector.at(1);
-string test_string("test_string");
-test_string.at(3);
-],
-[AC_MSG_RESULT(yes)
-AC_DEFINE(HAVE_CONTAINER_AT)],
-[AC_MSG_RESULT(no)])
-</pre>
+Support for <code>char_traits</code> beyond builtin types.
+</p>
<p>
-If you are using other (non-GNU) compilers it might be a good idea
-to check for <code>string::at</code> separately.
+Conformant <code>allocator</code> class and usage in containers. As
+part of this, the following extensions are
+added: <ext/bitmap_allocator.h>, <ext/debug_allocator.h>, <ext/mt_allocator.h>, <ext/malloc_allocator.h>,<ext/new_allocator.h>, <ext/pool_allocator.h>.
</p>
-<h5>No <code>std::char_traits<char>::eof</code></h5>
<p>
-Use some kind of autoconf test, plus this:
-</p>
-<pre>
-#ifdef HAVE_CHAR_TRAITS
-#define CPP_EOF std::char_traits<char>::eof()
-#else
-#define CPP_EOF EOF
-#endif
-</pre>
-
-<h5>No <code>string::clear</code></h5>
+Debug mode first appears.
+</p>
<p>
- There are two functions for deleting the contents of a string:
- <code>clear</code> and <code>erase</code> (the latter
- returns the string).
- <pre class="programlisting">
- void
- clear() { _M_mutate(0, this->size(), 0); }
- </pre>
- <pre class="programlisting">
- basic_string&
- erase(size_type __pos = 0, size_type __n = npos)
- {
- return this->replace(_M_check(__pos), _M_fold(__pos, __n),
- _M_data(), _M_data());
- }
- </pre>
- Unfortunately, ut <code>clear</code> is not
- implemented in this version, so you should use
- <code>erase</code> (which is probably faster than
- <code>operator=(charT*)</code>).
-</p>
-
-<h5>Removal of <code>ostream::form</code> and
-<code>istream::scan</code> extensions.</h5>
-
-<p> These are no longer supported. Please use
- <a href="#sec-stringstream" title="Using stringstreams">
- stringstreams</a> instead.
-</p>
-
-<h5>No <code>basic_stringbuf</code>, <code>basic_stringstream<code></h5>
+PCH support.
+</p>
<p>
- Libstdc++ provides the new
- <code>i/ostringstream</code>-classes, (<tt><sstream></tt>), but for compatibility
- with older implementations you still have to use
- <code>i/ostrstream</code> (<tt><strstream></tt>):
- <pre >
- #ifdef HAVE_SSTREAM
- #include <sstream>
- #else
- #include <strstream>
- #endif
- </pre>
- <div class="itemizedlist"><ul type="disc">
-<li><p> <code>strstream</code> is considered to be
- deprecated
- </p></li>
-<li><p> <code>strstream</code> is limited to
- <code>char</code>
- </p></li>
-<li><p> with <code>ostringstream</code> you don't
- have to take care of terminating the string or freeing its
- memory
- </p></li>
-<li><p> <code>istringstream</code> can be re-filled
- (clear(); str(input);)
- </p></li>
-</ul></div>
-<p>
- You can then use output-stringstreams like this:
- <pre >
- #ifdef HAVE_SSTREAM
- std::ostringstream oss;
- #else
- std::ostrstream oss;
- #endif
- oss << "Name=" << m_name << ", number=" << m_number << std::endl;
- ...
- #ifndef HAVE_SSTREAM
- oss << std::ends; // terminate the char*-string
- #endif
- // str() returns char* for ostrstream and a string for ostringstream
- // this also causes ostrstream to think that the buffer's memory
- // is yours
- m_label.set_text(oss.str());
- #ifndef HAVE_SSTREAM
- // let the ostrstream take care of freeing the memory
- oss.freeze(false);
- #endif
- </pre>
-<p>
- Input-stringstreams can be used similarly:
-</p>
-
-<pre>
-std::string input;
-...
-#ifdef HAVE_SSTREAM
-std::istringstream iss(input);
-#else
-std::istrstream iss(input.c_str());
-#endif
-
-int i;
-iss >> i;
-</pre>
-
-<p> One (the only?) restriction is that an istrstream cannot be re-filled:
-</p>
-
-<pre >
-std::istringstream iss(numerator);
-iss >> m_num;
-// this is not possible with istrstream
-iss.clear();
-iss.str(denominator);
-iss >> m_den;
- </pre>
-
-<p>
-If you don't care about speed, you can put these conversions in
- a template-function:
-</p>
-<pre >
-template <class X>
-void fromString(const string& input, X& any)
-{
-#ifdef HAVE_SSTREAM
-std::istringstream iss(input);
-#else
-std::istrstream iss(input.c_str());
-#endif
-X temp;
-iss >> temp;
-if (iss.fail())
-throw runtime_error(..)
-any = temp;
-}
-</pre>
-
-<p> Another example of using stringstreams is in <a href="../21_strings/howto.html" target="_top">this howto</a>.
+Macro guard for libstdc++ changed, from _GLIBCPP_ to _GLIBCXX_.
</p>
-<p> There is additional information in the libstdc++-v2 info files, in
-particular "info iostream".
+<p>
+Extension <ext/stdio_sync_filebuf.h> added.
</p>
-<h5>Little or no wide character support</h5>
-
-<h5>No templatized iostreams</h5>
-
-<h5>Thread safety issues.</h5>
-
-<p>This project is no longer maintained or supported, and the sources
-archived. The code is considered replaced and rewritten.
+<p>
+Extension <ext/demangle.h> added.
</p>
-<hr />
<h3 class="left">
- <a name="C++ API v1">Third.</a>
+ <a name="4.0">4.0</a>
</h3>
-<p> The third generation GNU C++ library is called libstdc++, or
-libstdc++-v3.
+<p>
+TR1 features first appear.
</p>
- <p>The subset commonly known as the Standard Template Library
- (chapters 23 through 25, mostly) is adapted from the final release
- of the SGI STL, with extensive changes.
- </p>
-
- <p>A more formal description of the V3 goals can be found in the
- official <a href="../17_intro/DESIGN">design document</a>.
- </p>
-
-
-<p>Portability Notes</p>
-
-<h5>Pre-ISO headers moved to backwards</h5>
-<p> The pre-ISO C++ headers (iostream.h etc.) are available, but inclusion
- generates a warning that you are using deprecated headers.
+<p>
+Extension allocator <ext/array_allocator.h> added.
</p>
- <p>This compatibility layer is constructed by including the
- standard C++ headers, and injecting any items in
- <code>std::</code> into the global namespace.
- </p>
- <p>For those of you new to ISO C++ (welcome, time travelers!), no,
- that isn't a typo. Yes, the headers really have new names.
- Marshall Cline's C++ FAQ Lite has a good explanation in <a
- href="http://www.parashift.com/c++-faq-lite/coding-standards.html#faq-27.4">item
- [27.4]</a>.
- </p>
-
-<p> Some include adjustment may be required.</p>
-
-<h5>Extension headers hash_map, hash_set moved to ext</h5>
+<p>
+Extension <code>codecvt</code> specializations moved to <ext/codecvt_specializations.h>.
+</p>
-<p> Header files <code>hash_map</code> and <code>hash_set</code>
-moved to <code>ext/hash_map</code> and <code>ext/hash_set</code>,
-respectively. At the same time, all types in these files are enclosed
-in <code>namespace __gnu_cxx</code>.
+<p>
+Removal of <ext/demangle.h>.
</p>
-<h5>
-No <code>ios::nocreate/ios::noreplace</code>.
-</h5>
+<h3 class="left">
+ <a name="4.1">4.1</a>
+</h3>
-<p> The existence of <code>ios::nocreate</code> being used for
-input-streams has been confirmed, most probably because the author
-thought it would be more correct to specify nocreate explicitly. So
-it can be left out for input-streams.
+<p>
+Removal of <cassert> from all standard headers: now has to be explicitly included for <code>std::assert</code> calls.
</p>
-<p>For output streams, "nocreate" is probably the default,
-unless you specify <code>std::ios::trunc</code> ? To be safe, you can
-open the file for reading, check if it has been opened, and then
-decide whether you want to create/replace or not. To my knowledge,
-even older implementations support <code>app</code>, <code>ate</code>
-and <code>trunc</code> (except for <code>app</code> ?).
+<p> Extensions for policy-based data structures first added. New includes,
+types, namespace <code>pb_assoc</code>.
</p>
-<h5>
-No <code>stream::attach(int fd)</code>.
-</h5>
-
-<p>
- Phil Edwards writes: It was considered and rejected for the ISO
- standard. Not all environments use file descriptors. Of those
- that do, not all of them use integers to represent them.
- </p>
-<p>
- For a portable solution (among systems which use
- filedescriptors), you need to implement a subclass of
- <code>std::streambuf</code> (or
- <code>std::basic_streambuf<..></code>) which opens a file
- given a descriptor, and then pass an instance of this to the
- stream-constructor.
- </p>
-
-<p>
- An extension is available that implements this.
- <code><ext/stdio_filebuf.h></code> contains a derived class called
- <a href="http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/class____gnu__cxx_1_1stdio__filebuf.html"><code>__gnu_cxx::stdio_filebuf</code></a>.
- This class can be constructed from a C <code>FILE*</code> or a file
- descriptor, and provides the <code>fd()</code> function.
- </p>
-
-<p>
- For another example of this, refer to
- <a href="http://www.josuttis.com/cppcode/fdstream.html" target="_top">fdstream example</a>
- by Nicolai Josuttis.
+<p> Extensions for typelists added in <ext/typelist.h>.
</p>
-<p><a href="http://gcc.gnu.org/bugzilla/buglist.cgi?cmdtype=runnamed&namedcmd=libstdc%2B%2B">Known Issues</a></p>
-
-<h5>
-container iterator types are not necessarily container value_type*
-</h5>
-
-<p>API History, User Visible Changes</p>
+<p> Extension for policy-based <code>basic_string</code> first added: <code>__gnu_cxx::__versa_string</code> in <ext/vstring.h>.
+</p>
-<p>3.0.0</p>
+<h3 class="left">
+ <a name="4.2">4.2</a>
+</h3>
+<p> Default visibility attributes applied to <code>namespace std</code>. Support for <code>-fvisibility</code>.
+</p>
-<p>3.1.0</p>
-<p>3.2.0</p>
-<p>3.3.0</p>
+<p>TR1 <random>, <complex>, and C compatibility headers added.</p>
+<p> Extensions for concurrent programming consolidated
+into <ext/concurrence.h> and <ext/atomicity.h>,
+including change of namespace to <code>__gnu_cxx</code> in some
+cases. Added types
+include <code>_Lock_policy</code>, <code>__concurrence_lock_error</code>, <code>__concurrence_unlock_error</code>, <code>__mutex</code>, <code>__scoped_lock</code>.</p>
-<p>3.4.0</p>
+<p> Extensions for type traits consolidated
+into <ext/type_traits.h>. Additional traits are added
+(<code>__conditional_type</code>, <code>__enable_if</code>, others.)
+</p>
-Macro guard for libstdc++ changed, from _GLIBCPP_ to _GLIBCXX_, to
-accomodate a request from the C Pre Processor maintainer.
+<p> Extensions for policy-based data structures revised. New includes,
+types, namespace moved to <code>__pb_ds</code>.
+</p>
-<p>4.0.0</p>
-<p>4.1.0</p>
+<p> Extensions for debug mode modified: now nested in <code>namespace
+std::__debug</code> and extensions in <code>namespace
+__gnu_cxx::__debug</code>.</p>
-<cassert> how has to be explicitly included for <code>std::assert</code> calls.
+<p> Extensions added: <ext/typelist.h>
+and <ext/throw_allocator.h>.
+</p>
-<p>4.2.0</p>
+<h3 class="left">
+ <a name="4.3">4.3</a>
+</h3>
-<p>4.3.0</p>
+<p>
+C++0X features first appear.
+</p>
-Header streamlining.
+<p>TR1 <regex> and <cmath>'s mathematical special function added.</p>
+<p>
Backward include edit.
+</p>
+<ul>
+ <li> Removed: <algobase.h> <algo.h> <alloc.h> <bvector.h> <complex.h>
+defalloc.h> <deque.h> <fstream.h> <function.h> <hash_map.h> <hash_set.h>
+hashtable.h> <heap.h> <iomanip.h> <iostream.h> <istream.h> <iterator.h>
+list.h> <map.h> <multimap.h> <multiset.h> <new.h> <ostream.h> <pair.h> <queue.h>
+rope.h> <set.h> <slist.h> <stack.h> <streambuf.h> <stream.h> <tempbuf.h>
+<tree.h> <vector.h>
+ </li>
+ <li> Added: <hash_map> and <hash_set></li>
+ <li> Added in C++0x: <auto_ptr.h> and <binders.h></li>
+</ul>
-PCH files built but not installed.
-
-Namespace pb_ds moved to __gnu_pb_ds.
+<p>
+Header dependency streamlining.
+</p>
-C++OX features appear.
+<ul>
+ <li><algorithm> no longer includes <climits>, <cstring>, or <iosfwd> </li>
+ <li><bitset> no longer includes <istream> or <ostream>, adds <iosfwd> </li>
+ <li><functional> no longer includes <cstddef></li>
+ <li><iomanip> no longer includes <istream>, <istream>, or <functional>, adds <ioswd> </li>
+ <li><numeric> no longer includes <iterator></li>
+ <li><string> no longer includes <algorithm> or <memory></li>
+
+ <li><valarray> no longer includes <numeric> or <cstdlib></li>
+ <li><tr1/hashtable> no longer includes <memory> or <functional></li>
+ <li><tr1/memory> no longer includes <algorithm></li>
+ <li><tr1/random> no longer includes <algorithm> or <fstream></li>
+</ul>
-<hr />
-<h3 class="left">
- <a name="C++ API v1">Fourth, and future</a>
-</h3>
+<p>
+Debug mode for <unordered_map> and <unordered_set>.
+</p>
-<hr />
-<h3 class="left">
- <a name="Deprecation">Deprecation and Backwards Compatibility</a>
-</h3>
+<p>
+Parallel mode first appears.
+</p>
-<hr />
-<h3 class="left">
- <a name="Links">Links</a>
-</h3>
+<p>Variadic template implementations of items in <tuple> and
+ <functional>.
+</p>
-<p>
-<a href="http://www.kegel.com/gcc/gcc4.html">Migrating to gcc-4.1</a>, by Dan Kegel.
+<p>Default <code>what</code> implementations give more elaborate
+ exception strings for <code>bad_cast</code>,
+ <code>bad_typeid</code>, <code>bad_exception</code>, and
+ <code>bad_alloc</code>.
</p>
<p>
-<a href="http://lists.debian.org/debian-gcc/2006/03/msg00405.html">Building the whole Debian archive with GCC 4.1: a summary</a>, by Martin Michlmayr
+PCH binary files no longer installed. Instead, the source files are installed.
</p>
<p>
-<a href="http://annwm.lbl.gov/~leggett/Atlas/gcc-3.2.html">Migration guide for GCC-3.2</a>
+Namespace pb_ds moved to __gnu_pb_ds.
</p>
</body>
diff --git a/libstdc++-v3/docs/html/17_intro/backwards_compatibility.html b/libstdc++-v3/docs/html/17_intro/backwards_compatibility.html
new file mode 100644
index 0000000..bc1497b
--- /dev/null
+++ b/libstdc++-v3/docs/html/17_intro/backwards_compatibility.html
@@ -0,0 +1,1073 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<!DOCTYPE html
+ PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+<head>
+ <meta name="AUTHOR" content="bkoz@gcc.gnu.org (Benjamin Kosnik), Felix Natter" />
+ <meta name="KEYWORDS" content="C++, libstdc++, API, backward, compatibility" />
+ <meta name="DESCRIPTION" content="Backwards Compatibility" />
+ <meta name="GENERATOR" content="emacs and ten fingers" />
+ <title>Backwards Compatibility</title>
+<link rel="StyleSheet" href="lib3styles.css" type="text/css" />
+<link rel="Start" href="documentation.html" type="text/html"
+ title="GNU C++ Standard Library" />
+<link rel="Copyright" href="17_intro/license.html" type="text/html" />
+</head>
+<body>
+
+<h1 class="centered"><a name="top">Backwards Compatibility</a></h1>
+
+<p class="fineprint"><em>
+ The latest version of this document is always available at
+ <a href="http://gcc.gnu.org/onlinedocs/libstdc++/17_intro/backwards_compatibility.html">
+ http://gcc.gnu.org/onlinedocs/libstdc++/17_intro/backwards_compatibility.html</a>.
+</em></p>
+
+<p><em>
+ To the <a href="http://gcc.gnu.org/libstdc++/">libstdc++ homepage</a>.
+</em></p>
+
+<!-- ####################################################### -->
+<hr />
+<h3 class="left">
+ <a name="v1">First.</a>
+</h3>
+
+<p> The first generation GNU C++ library was called libg++. It was a
+separate GNU project, although reliably paired with GCC. Rumors imply
+that it had a working relationship with at least two kinds of
+dinosaur.
+</p>
+
+<p>Known Issues include many of the limitations of its immediate ancestor.</p>
+
+<p>Portability notes and known implementation limitations are as follows.</p>
+
+<h5>No <code>ios_base</code></h5>
+
+<p> At least some older implementations don't have <code>std::ios_base</code>, so you should use <code>std::ios::badbit</code>, <code>std::ios::failbit</code> and <code>std::ios::eofbit</code> and <code>std::ios::goodbit</code>.
+</p>
+
+<h5>No <code>cout</code> in <code>ostream.h</code>, no <code>cin</code> in <code>istream.h</code></h5>
+
+<p>
+ In earlier versions of the standard,
+ <tt><fstream.h></tt>,
+ <tt><ostream.h></tt>
+ and <tt><istream.h></tt>
+ used to define
+ <code>cout</code>, <code>cin</code> and so on. ISO C++ specifies that one needs to include
+ <tt><iostream></tt>
+ explicitly to get the required definitions.
+ </p>
+<p> Some include adjustment may be required.</p>
+
+
+<p>This project is no longer maintained or supported, and the sources
+archived. The code is considered replaced and rewritten.
+</p>
+
+<hr />
+<h3 class="left">
+ <a name="v2">Second.</a>
+</h3>
+<p> The second generation GNU C++ library was called libstdc++, or
+libstdc++-v2. It spans the time between libg++ and pre-ISO C++
+standardization and is usually associated with the following GCC
+releases: egcs 1.x, gcc 2.95, and gcc 2.96.
+</p>
+
+<p> The STL portions of this library are based on SGI/HP STL release 3.11.
+</p>
+
+<p>Portability notes and known implementation limitations are as follows.</p>
+
+<h5>Namespace <code>std::</code> not supported</h5>
+
+<p>
+ Some care is required to support C++ compiler and or library
+ implementation that do not have the standard library in
+ <code>namespace std</code>.
+ </p>
+<p>
+ The following sections list some possible solutions to support compilers
+ that cannot ignore <code>std::</code>-qualified names.
+ </p>
+
+<p> First, see if the compiler has a flag for this. Namespace
+ back-portability-issues are generally not a problem for g++
+ compilers that do not have libstdc++ in <code>std::</code>, as
+ the compilers use <code>-fno-honor-std</code> (ignore
+ <code>std::</code>, <code>:: = std::</code>) by default. That
+ is, the responsibility for enabling or disabling
+ <code>std::</code> is on the user; the maintainer does not have
+ to care about it. This probably applies to some other compilers
+ as well.
+ </p>
+
+<p>Second, experiment with a variety of pre-processor tricks.</p>
+
+<p> By defining <code>std</code> as a macro, fully-qualified namespace calls become global. Volia. </p>
+
+<pre>
+#ifdef WICKEDLY_OLD_COMPILER
+# define std
+#endif
+</pre>
+(thanks to Juergen Heinzl who posted this solution on gnu.gcc.help)
+
+<p>Another pre-processor based approach is to define a
+macro <code>NAMESPACE_STD</code>, which is defined to either
+"" or "std" based on a compile-type test. On GNU
+systems, this can be done with autotools by means of an autoconf test
+(see below) for <code>HAVE_NAMESPACE_STD</code>, then using that to
+set a value for the <code>NAMESPACE_STD</code> macro. At that point,
+one is able to use <code>NAMESPACE_STD::string</code>, which will
+evaluate to <code>std::string</code> or
+<code>::string</code> (ie, in the global namespace on systems that do
+not put <code>string</code> in <code>std::</code>). </p>
+
+<pre style="background: #c0c0c0">
+dnl @synopsis AC_CXX_NAMESPACE_STD
+dnl
+dnl If the compiler supports namespace std, define
+dnl HAVE_NAMESPACE_STD.
+dnl
+dnl @category Cxx
+dnl @author Todd Veldhuizen
+dnl @author Luc Maisonobe <luc@spaceroots.org>
+dnl @version 2004-02-04
+dnl @license AllPermissive
+AC_DEFUN([AC_CXX_NAMESPACE_STD], [
+ AC_CACHE_CHECK(if g++ supports namespace std,
+ ac_cv_cxx_have_std_namespace,
+ [AC_LANG_SAVE
+ AC_LANG_CPLUSPLUS
+ AC_TRY_COMPILE([#include <iostream>
+ std::istream& is = std::cin;],,
+ ac_cv_cxx_have_std_namespace=yes, ac_cv_cxx_have_std_namespace=no)
+ AC_LANG_RESTORE
+ ])
+ if test "$ac_cv_cxx_have_std_namespace" = yes; then
+ AC_DEFINE(HAVE_NAMESPACE_STD,,[Define if g++ supports namespace std. ])
+ fi
+])
+</pre>
+
+<h5>Illegal iterator usage</h5>
+<p>
+ The following illustrate implementation-allowed illegal iterator
+ use, and then correct use.
+</p>
+
+<ul> <li><p>you cannot do
+ <code>ostream::operator<<(iterator)</code> to print the
+ address of the iterator => use <code>operator<<
+ &*iterator</code> instead
+ </p></li>
+<li><p>you cannot clear an iterator's reference
+ (<code>iterator = 0</code>) => use
+ <code>iterator = iterator_type();</code>
+ </p></li>
+<li><p>
+<code>if (iterator)</code> won't work any
+ more => use <code>if (iterator != iterator_type())</code>
+ </p></li>
+</ul>
+
+<h5><code>isspace</code> from <tt><cctype></tt> is a macro
+</h5>
+
+<p> Glibc 2.0.x and 2.1.x define <tt><ctype.h></tt>
+functionality as macros (isspace, isalpha etc.).
+</p>
+
+<p>
+This implementations of libstdc++, however, keep these functions as
+macros, and so it is not back-portable to use fully qualified
+names. For example:
+</p>
+
+<pre>
+#include <cctype>
+int main() { std::isspace('X'); }
+</pre>
+
+<p>Results in something like this:
+</p>
+
+<pre>
+std:: (__ctype_b[(int) ( ( 'X' ) )] & (unsigned short int) _ISspace ) ;
+</pre>
+
+
+<p> A solution is to modify a header-file so that the compiler tells
+<tt><ctype.h></tt> to define functions instead of macros:
+</p>
+
+<pre>
+// This keeps isalnum, et al from being propagated as macros.
+#if __linux__
+# define __NO_CTYPE 1
+#endif
+</pre>
+
+<p>Then, include <ctype.h>
+</p>
+
+<p>
+Another problem arises if you put a <code>using namespace std;</code>
+declaration at the top, and include <tt><ctype.h></tt>. This
+will result in ambiguities between the definitions in the global
+namespace (<tt><ctype.h></tt>) and the definitions in namespace
+<code>std::</code> (<code><cctype></code>).
+</p>
+
+<h5>No <code>vector::at</code>, <code>deque::at</code>, <code>string::at</code></h5>
+
+<p>
+ One solution is to add an autoconf-test for this:
+</p>
+<pre style="background: #c0c0c0">
+AC_MSG_CHECKING(for container::at)
+AC_TRY_COMPILE(
+[
+#include <vector>
+#include <deque>
+#include <string>
+
+using namespace std;
+],
+[
+deque<int> test_deque(3);
+test_deque.at(2);
+vector<int> test_vector(2);
+test_vector.at(1);
+string test_string("test_string");
+test_string.at(3);
+],
+[AC_MSG_RESULT(yes)
+AC_DEFINE(HAVE_CONTAINER_AT)],
+[AC_MSG_RESULT(no)])
+</pre>
+
+<p>
+If you are using other (non-GNU) compilers it might be a good idea
+to check for <code>string::at</code> separately.
+</p>
+
+<h5>No <code>std::char_traits<char>::eof</code></h5>
+
+<p>
+Use some kind of autoconf test, plus this:
+</p>
+<pre>
+#ifdef HAVE_CHAR_TRAITS
+#define CPP_EOF std::char_traits<char>::eof()
+#else
+#define CPP_EOF EOF
+#endif
+</pre>
+
+<h5>No <code>string::clear</code></h5>
+
+<p>
+ There are two functions for deleting the contents of a string:
+ <code>clear</code> and <code>erase</code> (the latter
+ returns the string).
+</p>
+
+<pre>
+void
+clear() { _M_mutate(0, this->size(), 0); }
+</pre>
+<pre>
+basic_string&
+erase(size_type __pos = 0, size_type __n = npos)
+{
+ return this->replace(_M_check(__pos), _M_fold(__pos, __n),
+ _M_data(), _M_data());
+}
+</pre>
+
+<p>
+ Unfortunately, ut <code>clear</code> is not
+ implemented in this version, so you should use
+ <code>erase</code> (which is probably faster than
+ <code>operator=(charT*)</code>).
+</p>
+
+<h5>Removal of <code>ostream::form</code> and
+<code>istream::scan</code> extensions</h5>
+
+<p> These are no longer supported. Please use
+ <a href="#sec-stringstream" title="Using stringstreams">
+ stringstreams</a> instead.
+</p>
+
+<h5>No <code>basic_stringbuf</code>, <code>basic_stringstream</code></h5>
+
+<p>
+Although the ISO standard
+<code>i/ostringstream</code>-classes are provided, (<tt><sstream></tt>), for compatibility with older implementations the pre-ISO <code>i/ostrstream</code> (<tt><strstream></tt>) interface is also provided, with these caveats:
+</p>
+
+ <div class="itemizedlist"><ul type="disc">
+<li><p> <code>strstream</code> is considered to be
+ deprecated
+ </p></li>
+<li><p> <code>strstream</code> is limited to
+ <code>char</code>
+ </p></li>
+<li><p> with <code>ostringstream</code> you don't
+ have to take care of terminating the string or freeing its
+ memory
+ </p></li>
+<li><p> <code>istringstream</code> can be re-filled
+ (clear(); str(input);)
+ </p></li>
+</ul></div>
+<p>
+ You can then use output-stringstreams like this:
+</p>
+
+<pre>
+#ifdef HAVE_SSTREAM
+# include <sstream>
+#else
+# include <strstream>
+#endif
+
+#ifdef HAVE_SSTREAM
+ std::ostringstream oss;
+#else
+ std::ostrstream oss;
+#endif
+
+oss << "Name=" << m_name << ", number=" << m_number << std::endl;
+...
+#ifndef HAVE_SSTREAM
+ oss << std::ends; // terminate the char*-string
+#endif
+
+// str() returns char* for ostrstream and a string for ostringstream
+// this also causes ostrstream to think that the buffer's memory
+// is yours
+m_label.set_text(oss.str());
+#ifndef HAVE_SSTREAM
+ // let the ostrstream take care of freeing the memory
+ oss.freeze(false);
+#endif
+</pre>
+
+<p>
+ Input-stringstreams can be used similarly:
+</p>
+
+<pre>
+std::string input;
+...
+#ifdef HAVE_SSTREAM
+std::istringstream iss(input);
+#else
+std::istrstream iss(input.c_str());
+#endif
+
+int i;
+iss >> i;
+</pre>
+
+<p> One (the only?) restriction is that an istrstream cannot be re-filled:
+</p>
+
+<pre>
+std::istringstream iss(numerator);
+iss >> m_num;
+// this is not possible with istrstream
+iss.clear();
+iss.str(denominator);
+iss >> m_den;
+ </pre>
+
+<p>
+If you don't care about speed, you can put these conversions in
+ a template-function:
+</p>
+<pre>
+template <class X>
+void fromString(const string& input, X& any)
+{
+#ifdef HAVE_SSTREAM
+std::istringstream iss(input);
+#else
+std::istrstream iss(input.c_str());
+#endif
+X temp;
+iss >> temp;
+if (iss.fail())
+throw runtime_error(..)
+any = temp;
+}
+</pre>
+
+<p> Another example of using stringstreams is in <a href="../21_strings/howto.html" target="_top">this howto</a>.
+</p>
+
+<p> There is additional information in the libstdc++-v2 info files, in
+particular "info iostream".
+</p>
+
+<h5>Little or no wide character support</h5>
+
+<h5>No templatized iostreams</h5>
+
+<h5>Thread safety issues</h5>
+
+<p>This project is no longer maintained or supported, and the sources
+archived. The code is considered replaced and rewritten.
+</p>
+
+
+<hr />
+<h3 class="left">
+ <a name="v3">Third.</a>
+</h3>
+<p> The third generation GNU C++ library is called libstdc++, or
+libstdc++-v3.
+</p>
+
+ <p>The subset commonly known as the Standard Template Library
+ (chapters 23 through 25, mostly) is adapted from the final release
+ of the SGI STL (version 3.3), with extensive changes.
+ </p>
+
+ <p>A more formal description of the V3 goals can be found in the
+ official <a href="../17_intro/DESIGN">design document</a>.
+ </p>
+
+<p>Portability notes and known implementation limitations are as follows.</p>
+
+<h5>Pre-ISO headers moved to backwards or removed</h5>
+
+<p> The pre-ISO C++ headers
+ (<code>iostream.h</code>, <code>defalloc.h</code> etc.) are
+ available, unlike previous libstdc++ versions, but inclusion
+ generates a warning that you are using deprecated headers.
+</p>
+
+ <p>This compatibility layer is constructed by including the
+ standard C++ headers, and injecting any items in
+ <code>std::</code> into the global namespace.
+ </p>
+ <p>For those of you new to ISO C++ (welcome, time travelers!), no,
+ that isn't a typo. Yes, the headers really have new names.
+ Marshall Cline's C++ FAQ Lite has a good explanation in <a
+ href="http://www.parashift.com/c++-faq-lite/coding-standards.html#faq-27.4">item
+ [27.4]</a>.
+ </p>
+
+<p> Some include adjustment may be required. What follows is an
+autoconf test that defines <code>PRE_STDCXX_HEADERS</code> when they
+exist.</p>
+
+<pre style="background: #c0c0c0">
+# AC_HEADER_PRE_STDCXX
+AC_DEFUN([AC_HEADER_PRE_STDCXX], [
+ AC_CACHE_CHECK(for pre-ISO C++ include files,
+ ac_cv_cxx_pre_stdcxx,
+ [AC_LANG_SAVE
+ AC_LANG_CPLUSPLUS
+ ac_save_CXXFLAGS="$CXXFLAGS"
+ CXXFLAGS="$CXXFLAGS -Wno-deprecated"
+
+ # Omit defalloc.h, as compilation with newer compilers is problematic.
+ AC_TRY_COMPILE([
+ #include <new.h>
+ #include <iterator.h>
+ #include <alloc.h>
+ #include <set.h>
+ #include <hashtable.h>
+ #include <hash_set.h>
+ #include <fstream.h>
+ #include <tempbuf.h>
+ #include <istream.h>
+ #include <bvector.h>
+ #include <stack.h>
+ #include <rope.h>
+ #include <complex.h>
+ #include <ostream.h>
+ #include <heap.h>
+ #include <iostream.h>
+ #include <function.h>
+ #include <multimap.h>
+ #include <pair.h>
+ #include <stream.h>
+ #include <iomanip.h>
+ #include <slist.h>
+ #include <tree.h>
+ #include <vector.h>
+ #include <deque.h>
+ #include <multiset.h>
+ #include <list.h>
+ #include <map.h>
+ #include <algobase.h>
+ #include <hash_map.h>
+ #include <algo.h>
+ #include <queue.h>
+ #include <streambuf.h>
+ ],,
+ ac_cv_cxx_pre_stdcxx=yes, ac_cv_cxx_pre_stdcxx=no)
+ CXXFLAGS="$ac_save_CXXFLAGS"
+ AC_LANG_RESTORE
+ ])
+ if test "$ac_cv_cxx_pre_stdcxx" = yes; then
+ AC_DEFINE(PRE_STDCXX_HEADERS,,[Define if pre-ISO C++ header files are present. ])
+ fi
+])
+</pre>
+
+<p>Porting between pre-ISO headers and ISO headers is simple: headers
+like <vector.h> can be replaced with <vector> and a using
+directive <code>using namespace std;</code> can be put at the global
+scope. This should be enough to get this code compiling, assuming the
+other usage is correct.
+</p>
+
+<h5>Extension headers hash_map, hash_set moved to ext or backwards</h5>
+
+<p> Header files <code>hash_map</code> and <code>hash_set</code> moved
+to <code>ext/hash_map</code> and <code>ext/hash_set</code>,
+respectively. At the same time, all types in these files are enclosed
+in <code>namespace __gnu_cxx</code>. Later versions move deprecate
+these files, and suggest using TR1's <code>unordered_map</code>
+and <code>unordered_set</code> instead.
+</p>
+
+<p>The following autoconf tests check for working HP/SGI hash containers.
+</p>
+
+<pre style="background: #c0c0c0">
+# AC_HEADER_EXT_HASH_MAP
+AC_DEFUN([AC_HEADER_EXT_HASH_MAP], [
+ AC_CACHE_CHECK(for ext/hash_map,
+ ac_cv_cxx_ext_hash_map,
+ [AC_LANG_SAVE
+ AC_LANG_CPLUSPLUS
+ ac_save_CXXFLAGS="$CXXFLAGS"
+ CXXFLAGS="$CXXFLAGS -Werror"
+ AC_TRY_COMPILE([#include <ext/hash_map>], [using __gnu_cxx::hash_map;],
+ ac_cv_cxx_ext_hash_map=yes, ac_cv_cxx_ext_hash_map=no)
+ CXXFLAGS="$ac_save_CXXFLAGS"
+ AC_LANG_RESTORE
+ ])
+ if test "$ac_cv_cxx_ext_hash_map" = yes; then
+ AC_DEFINE(HAVE_EXT_HASH_MAP,,[Define if ext/hash_map is present. ])
+ fi
+])
+</pre>
+
+<pre style="background: #c0c0c0">
+# AC_HEADER_EXT_HASH_SET
+AC_DEFUN([AC_HEADER_EXT_HASH_SET], [
+ AC_CACHE_CHECK(for ext/hash_set,
+ ac_cv_cxx_ext_hash_set,
+ [AC_LANG_SAVE
+ AC_LANG_CPLUSPLUS
+ ac_save_CXXFLAGS="$CXXFLAGS"
+ CXXFLAGS="$CXXFLAGS -Werror"
+ AC_TRY_COMPILE([#include <ext/hash_set>], [using __gnu_cxx::hash_set;],
+ ac_cv_cxx_ext_hash_set=yes, ac_cv_cxx_ext_hash_set=no)
+ CXXFLAGS="$ac_save_CXXFLAGS"
+ AC_LANG_RESTORE
+ ])
+ if test "$ac_cv_cxx_ext_hash_set" = yes; then
+ AC_DEFINE(HAVE_EXT_HASH_SET,,[Define if ext/hash_set is present. ])
+ fi
+])
+</pre>
+
+
+<h5>
+No <code>ios::nocreate/ios::noreplace</code>.
+</h5>
+
+<p> The existence of <code>ios::nocreate</code> being used for
+input-streams has been confirmed, most probably because the author
+thought it would be more correct to specify nocreate explicitly. So
+it can be left out for input-streams.
+</p>
+
+<p>For output streams, "nocreate" is probably the default,
+unless you specify <code>std::ios::trunc</code> ? To be safe, you can
+open the file for reading, check if it has been opened, and then
+decide whether you want to create/replace or not. To my knowledge,
+even older implementations support <code>app</code>, <code>ate</code>
+and <code>trunc</code> (except for <code>app</code> ?).
+</p>
+
+
+<h5>
+No <code>stream::attach(int fd)</code>
+</h5>
+
+<p>
+ Phil Edwards writes: It was considered and rejected for the ISO
+ standard. Not all environments use file descriptors. Of those
+ that do, not all of them use integers to represent them.
+ </p>
+
+<p>
+ For a portable solution (among systems which use
+ filedescriptors), you need to implement a subclass of
+ <code>std::streambuf</code> (or
+ <code>std::basic_streambuf<..></code>) which opens a file
+ given a descriptor, and then pass an instance of this to the
+ stream-constructor.
+ </p>
+
+<p>
+ An extension is available that implements this.
+ <code><ext/stdio_filebuf.h></code> contains a derived class called
+ <a href="http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/class____gnu__cxx_1_1stdio__filebuf.html"><code>__gnu_cxx::stdio_filebuf</code></a>.
+ This class can be constructed from a C <code>FILE*</code> or a file
+ descriptor, and provides the <code>fd()</code> function.
+ </p>
+
+<p>
+ For another example of this, refer to
+ <a href="http://www.josuttis.com/cppcode/fdstream.html" target="_top">fdstream example</a>
+ by Nicolai Josuttis.
+</p>
+
+<h5>
+Support for C++98 dialect.
+</h5>
+
+<p>Check for complete library coverage of the C++1998/2003 standard.
+</p>
+
+<pre style="background: #c0c0c0">
+
+# AC_HEADER_STDCXX_98
+AC_DEFUN([AC_HEADER_STDCXX_98], [
+ AC_CACHE_CHECK(for ISO C++ 98 include files,
+ ac_cv_cxx_stdcxx_98,
+ [AC_LANG_SAVE
+ AC_LANG_CPLUSPLUS
+ AC_TRY_COMPILE([
+ #include <cassert>
+ #include <cctype>
+ #include <cerrno>
+ #include <cfloat>
+ #include <ciso646>
+ #include <climits>
+ #include <clocale>
+ #include <cmath>
+ #include <csetjmp>
+ #include <csignal>
+ #include <cstdarg>
+ #include <cstddef>
+ #include <cstdio>
+ #include <cstdlib>
+ #include <cstring>
+ #include <ctime>
+
+ #include <algorithm>
+ #include <bitset>
+ #include <complex>
+ #include <deque>
+ #include <exception>
+ #include <fstream>
+ #include <functional>
+ #include <iomanip>
+ #include <ios>
+ #include <iosfwd>
+ #include <iostream>
+ #include <istream>
+ #include <iterator>
+ #include <limits>
+ #include <list>
+ #include <locale>
+ #include <map>
+ #include <memory>
+ #include <new>
+ #include <numeric>
+ #include <ostream>
+ #include <queue>
+ #include <set>
+ #include <sstream>
+ #include <stack>
+ #include <stdexcept>
+ #include <streambuf>
+ #include <string>
+ #include <typeinfo>
+ #include <utility>
+ #include <valarray>
+ #include <vector>
+ ],,
+ ac_cv_cxx_stdcxx_98=yes, ac_cv_cxx_stdcxx_98=no)
+ AC_LANG_RESTORE
+ ])
+ if test "$ac_cv_cxx_stdcxx_98" = yes; then
+ AC_DEFINE(STDCXX_98_HEADERS,,[Define if ISO C++ 1998 header files are present. ])
+ fi
+])
+</pre>
+
+
+<h5>
+Support for C++TR1 dialect.
+</h5>
+
+<p>Check for library coverage of the TR1 standard.
+</p>
+
+<pre style="background: #c0c0c0">
+
+# AC_HEADER_STDCXX_TR1
+AC_DEFUN([AC_HEADER_STDCXX_TR1], [
+ AC_CACHE_CHECK(for ISO C++ TR1 include files,
+ ac_cv_cxx_stdcxx_tr1,
+ [AC_LANG_SAVE
+ AC_LANG_CPLUSPLUS
+ AC_TRY_COMPILE([
+ #include <tr1/array>
+ #include <tr1/ccomplex>
+ #include <tr1/cctype>
+ #include <tr1/cfenv>
+ #include <tr1/cfloat>
+ #include <tr1/cinttypes>
+ #include <tr1/climits>
+ #include <tr1/cmath>
+ #include <tr1/complex>
+ #include <tr1/cstdarg>
+ #include <tr1/cstdbool>
+ #include <tr1/cstdint>
+ #include <tr1/cstdio>
+ #include <tr1/cstdlib>
+ #include <tr1/ctgmath>
+ #include <tr1/ctime>
+ #include <tr1/cwchar>
+ #include <tr1/cwctype>
+ #include <tr1/functional>
+ #include <tr1/memory>
+ #include <tr1/random>
+ #include <tr1/regex>
+ #include <tr1/tuple>
+ #include <tr1/type_traits>
+ #include <tr1/unordered_set>
+ #include <tr1/unordered_map>
+ #include <tr1/utility>
+ ],,
+ ac_cv_cxx_stdcxx_tr1=yes, ac_cv_cxx_stdcxx_tr1=no)
+ AC_LANG_RESTORE
+ ])
+ if test "$ac_cv_cxx_stdcxx_tr1" = yes; then
+ AC_DEFINE(STDCXX_TR1_HEADERS,,[Define if ISO C++ TR1 header files are present. ])
+ fi
+])
+</pre>
+
+<p>An alternative is to check just for specific TR1 includes, such as <unordered_map> and <unordered_set>.
+</p>
+
+<pre style="background: #c0c0c0">
+# AC_HEADER_TR1_UNORDERED_MAP
+AC_DEFUN([AC_HEADER_TR1_UNORDERED_MAP], [
+ AC_CACHE_CHECK(for tr1/unordered_map,
+ ac_cv_cxx_tr1_unordered_map,
+ [AC_LANG_SAVE
+ AC_LANG_CPLUSPLUS
+ AC_TRY_COMPILE([#include <tr1/unordered_map>], [using std::tr1::unordered_map;],
+ ac_cv_cxx_tr1_unordered_map=yes, ac_cv_cxx_tr1_unordered_map=no)
+ AC_LANG_RESTORE
+ ])
+ if test "$ac_cv_cxx_tr1_unordered_map" = yes; then
+ AC_DEFINE(HAVE_TR1_UNORDERED_MAP,,[Define if tr1/unordered_map is present. ])
+ fi
+])
+</pre>
+
+<pre style="background: #c0c0c0">
+# AC_HEADER_TR1_UNORDERED_SET
+AC_DEFUN([AC_HEADER_TR1_UNORDERED_SET], [
+ AC_CACHE_CHECK(for tr1/unordered_set,
+ ac_cv_cxx_tr1_unordered_set,
+ [AC_LANG_SAVE
+ AC_LANG_CPLUSPLUS
+ AC_TRY_COMPILE([#include <tr1/unordered_set>], [using std::tr1::unordered_set;],
+ ac_cv_cxx_tr1_unordered_set=yes, ac_cv_cxx_tr1_unordered_set=no)
+ AC_LANG_RESTORE
+ ])
+ if test "$ac_cv_cxx_tr1_unordered_set" = yes; then
+ AC_DEFINE(HAVE_TR1_UNORDERED_SET,,[Define if tr1/unordered_set is present. ])
+ fi
+])
+</pre>
+
+
+
+<h5>
+Support for C++0x dialect.
+</h5>
+
+<p>Check for baseline language coverage in the compiler for the C++0xstandard.
+</p>
+
+<pre style="background: #c0c0c0">
+# AC_COMPILE_STDCXX_OX
+AC_DEFUN([AC_COMPILE_STDCXX_0X], [
+ AC_CACHE_CHECK(if g++ supports C++0x features without additional flags,
+ ac_cv_cxx_compile_cxx0x_native,
+ [AC_LANG_SAVE
+ AC_LANG_CPLUSPLUS
+ AC_TRY_COMPILE([
+ template <typename T>
+ struct check
+ {
+ static_assert(sizeof(int) <= sizeof(T), "not big enough");
+ };
+
+ typedef check<check<bool>> right_angle_brackets;
+
+ int a;
+ decltype(a) b;
+
+ typedef check<int> check_type;
+ check_type c;
+ check_type&& cr = c;],,
+ ac_cv_cxx_compile_cxx0x_native=yes, ac_cv_cxx_compile_cxx0x_native=no)
+ AC_LANG_RESTORE
+ ])
+
+ AC_CACHE_CHECK(if g++ supports C++0x features with -std=c++0x,
+ ac_cv_cxx_compile_cxx0x_cxx,
+ [AC_LANG_SAVE
+ AC_LANG_CPLUSPLUS
+ ac_save_CXXFLAGS="$CXXFLAGS"
+ CXXFLAGS="$CXXFLAGS -std=c++0x"
+ AC_TRY_COMPILE([
+ template <typename T>
+ struct check
+ {
+ static_assert(sizeof(int) <= sizeof(T), "not big enough");
+ };
+
+ typedef check<check<bool>> right_angle_brackets;
+
+ int a;
+ decltype(a) b;
+
+ typedef check<int> check_type;
+ check_type c;
+ check_type&& cr = c;],,
+ ac_cv_cxx_compile_cxx0x_cxx=yes, ac_cv_cxx_compile_cxx0x_cxx=no)
+ CXXFLAGS="$ac_save_CXXFLAGS"
+ AC_LANG_RESTORE
+ ])
+
+ AC_CACHE_CHECK(if g++ supports C++0x features with -std=gnu++0x,
+ ac_cv_cxx_compile_cxx0x_gxx,
+ [AC_LANG_SAVE
+ AC_LANG_CPLUSPLUS
+ ac_save_CXXFLAGS="$CXXFLAGS"
+ CXXFLAGS="$CXXFLAGS -std=gnu++0x"
+ AC_TRY_COMPILE([
+ template <typename T>
+ struct check
+ {
+ static_assert(sizeof(int) <= sizeof(T), "not big enough");
+ };
+
+ typedef check<check<bool>> right_angle_brackets;
+
+ int a;
+ decltype(a) b;
+
+ typedef check<int> check_type;
+ check_type c;
+ check_type&& cr = c;],,
+ ac_cv_cxx_compile_cxx0x_gxx=yes, ac_cv_cxx_compile_cxx0x_gxx=no)
+ CXXFLAGS="$ac_save_CXXFLAGS"
+ AC_LANG_RESTORE
+ ])
+
+ if test "$ac_cv_cxx_compile_cxx0x_native" = yes ||
+ test "$ac_cv_cxx_compile_cxx0x_cxx" = yes ||
+ test "$ac_cv_cxx_compile_cxx0x_gxx" = yes; then
+ AC_DEFINE(HAVE_STDCXX_0X,,[Define if g++ supports C++0x features. ])
+ fi
+])
+</pre>
+
+
+<p>Check for library coverage of the C++0xstandard.
+</p>
+
+<pre style="background: #c0c0c0">
+
+# AC_HEADER_STDCXX_0X
+AC_DEFUN([AC_HEADER_STDCXX_0X], [
+ AC_CACHE_CHECK(for ISO C++ 0x include files,
+ ac_cv_cxx_stdcxx_0x,
+ [AC_REQUIRE([AC_COMPILE_STDCXX_0X])
+ AC_LANG_SAVE
+ AC_LANG_CPLUSPLUS
+ ac_save_CXXFLAGS="$CXXFLAGS"
+ CXXFLAGS="$CXXFLAGS -std=gnu++0x"
+
+ AC_TRY_COMPILE([
+ #include <cassert>
+ #include <ccomplex>
+ #include <cctype>
+ #include <cerrno>
+ #include <cfenv>
+ #include <cfloat>
+ #include <cinttypes>
+ #include <ciso646>
+ #include <climits>
+ #include <clocale>
+ #include <cmath>
+ #include <csetjmp>
+ #include <csignal>
+ #include <cstdarg>
+ #include <cstdbool>
+ #include <cstddef>
+ #include <cstdint>
+ #include <cstdio>
+ #include <cstdlib>
+ #include <cstring>
+ #include <ctgmath>
+ #include <ctime>
+ #include <cwchar>
+ #include <cwctype>
+
+ #include <algorithm>
+ #include <array>
+ #include <bitset>
+ #include <complex>
+ #include <deque>
+ #include <exception>
+ #include <fstream>
+ #include <functional>
+ #include <iomanip>
+ #include <ios>
+ #include <iosfwd>
+ #include <iostream>
+ #include <istream>
+ #include <iterator>
+ #include <limits>
+ #include <list>
+ #include <locale>
+ #include <map>
+ #include <memory>
+ #include <new>
+ #include <numeric>
+ #include <ostream>
+ #include <queue>
+ #include <random>
+ #include <regex>
+ #include <set>
+ #include <sstream>
+ #include <stack>
+ #include <stdexcept>
+ #include <streambuf>
+ #include <string>
+ #include <tuple>
+ #include <typeinfo>
+ #include <type_traits>
+ #include <unordered_map>
+ #include <unordered_set>
+ #include <utility>
+ #include <valarray>
+ #include <vector>
+ ],,
+ ac_cv_cxx_stdcxx_0x=yes, ac_cv_cxx_stdcxx_0x=no)
+ AC_LANG_RESTORE
+ CXXFLAGS="$ac_save_CXXFLAGS"
+ ])
+ if test "$ac_cv_cxx_stdcxx_0x" = yes; then
+ AC_DEFINE(STDCXX_0X_HEADERS,,[Define if ISO C++ 0x header files are present. ])
+ fi
+])
+</pre>
+
+<p>As is the case for TR1 support, these autoconf macros can be made for a finer-grained, per-header-file check. For <unordered_map>
+</p>
+
+<pre style="background: #c0c0c0">
+
+# AC_HEADER_UNORDERED_MAP
+AC_DEFUN([AC_HEADER_UNORDERED_MAP], [
+ AC_CACHE_CHECK(for unordered_map,
+ ac_cv_cxx_unordered_map,
+ [AC_REQUIRE([AC_COMPILE_STDCXX_0X])
+ AC_LANG_SAVE
+ AC_LANG_CPLUSPLUS
+ ac_save_CXXFLAGS="$CXXFLAGS"
+ CXXFLAGS="$CXXFLAGS -std=gnu++0x"
+ AC_TRY_COMPILE([#include <unordered_map>], [using std::unordered_map;],
+ ac_cv_cxx_unordered_map=yes, ac_cv_cxx_unordered_map=no)
+ CXXFLAGS="$ac_save_CXXFLAGS"
+ AC_LANG_RESTORE
+ ])
+ if test "$ac_cv_cxx_unordered_map" = yes; then
+ AC_DEFINE(HAVE_UNORDERED_MAP,,[Define if unordered_map is present. ])
+ fi
+])
+</pre>
+
+<pre style="background: #c0c0c0">
+# AC_HEADER_UNORDERED_SET
+AC_DEFUN([AC_HEADER_UNORDERED_SET], [
+ AC_CACHE_CHECK(for unordered_set,
+ ac_cv_cxx_unordered_set,
+ [AC_REQUIRE([AC_COMPILE_STDCXX_0X])
+ AC_LANG_SAVE
+ AC_LANG_CPLUSPLUS
+ ac_save_CXXFLAGS="$CXXFLAGS"
+ CXXFLAGS="$CXXFLAGS -std=gnu++0x"
+ AC_TRY_COMPILE([#include <unordered_set>], [using std::unordered_set;],
+ ac_cv_cxx_unordered_set=yes, ac_cv_cxx_unordered_set=no)
+ CXXFLAGS="$ac_save_CXXFLAGS"
+ AC_LANG_RESTORE
+ ])
+ if test "$ac_cv_cxx_unordered_set" = yes; then
+ AC_DEFINE(HAVE_UNORDERED_SET,,[Define if unordered_set is present. ])
+ fi
+])
+</pre>
+
+
+<h5>
+Container iterator_type is not necessarily container value_type*
+</h5>
+
+
+<hr />
+<h3 class="left">
+ <a name="v4">Fourth, and future</a>
+</h3>
+
+<hr />
+<h3 class="left">
+ <a name="Links">Links</a>
+</h3>
+
+<p>
+<a href="http://www.kegel.com/gcc/gcc4.html">Migrating to gcc-4.1</a>, by Dan Kegel.
+</p>
+
+<p>
+<a href="http://lists.debian.org/debian-gcc/2006/03/msg00405.html">Building the whole Debian archive with GCC 4.1: a summary</a>, by Martin Michlmayr
+</p>
+
+<p>
+<a href="http://annwm.lbl.gov/~leggett/Atlas/gcc-3.2.html">Migration guide for GCC-3.2</a>
+</p>
+
+</body>
+</html>
+
diff --git a/libstdc++-v3/docs/html/17_intro/howto.html b/libstdc++-v3/docs/html/17_intro/howto.html
index d3bd6df..3e1bba0 100644
--- a/libstdc++-v3/docs/html/17_intro/howto.html
+++ b/libstdc++-v3/docs/html/17_intro/howto.html
@@ -34,123 +34,309 @@
<hr />
<h1>Contents</h1>
<ul>
- <li><a href="#2.1">Header Files</a></li>
- <li><a href="#5">Implementation specific behavior</a></li>
+ <li><a href="#2.0">Header Files</a></li>
+ <li><a href="#3.0">Namespaces</a></li>
<li><a href="#6">Macros</a></li>
- <li><a href="#3">Multithreading</a></li>
+ <li><a href="#5">Implementation specific behavior</a></li>
+ <li><a href="#7">Multithreading</a></li>
</ul>
<hr />
<!-- ####################################################### -->
-<h2><a name="2.1">Header Files</a></h2>
- <p>The C++ standard specifies 50 header files that must be
+<h2><a name="2.0">Header Files</a></h2>
+ <p>The C++ standard specifies the entire set of header files that must be
available to all hosted implementations. Actually, the word
"files" is a misnomer, since the contents of the headers
don't necessarily have to be in any kind of external file. The
- only rule is that when one <code>#include</code>'s a certain header, the
- contents of that header, as defined by the Standard, become
+ only rule is that when one <code>#include</code>'s a header, the
+ contents of that header become
available, no matter how.
</p>
-<p>C++98/03 include files:
+<p>That said, in practice files are used.</p>
+
+<p> There are two main types of include files: header files related to
+a specific version of the ISO C++ standard (called Standard Headers),
+and all others (TR1, C++ ABI, and Extensions).</p>
+
+<p>Two dialects of standard headers are supported, corresponding to
+the 1998 standard as updated for 2003, and the draft of the upcoming
+200x standard.
+</p>
+
+<p>C++98/03 include files. These are available in the default compilation mode, ie <code>-std=c++98</code> or <code>-std=gnu++98</code>.
</p>
-<pre>
-C++ Library Headers
-algorithm ios new stack
-bitset iosfwd numeric stdexcept
-complex iostream ostream streambuf
- istream queue string
-deque iterator
-exception limits typeinfo
-fstream list set
-functional locale map
-iomanip memory sstream
-
-C++ Headers for C Library Facilities
-cassert cfloat cmath cstddef
-ccomplex csetjmp cstdio ctime
-cctype ciso646 csignal
-cerrno climits cstdarg cstdlib cwchar
- clocale cstring cwctype
-</pre>
-<p>C++0x include files:
+<center><table border="1"><caption>C++98 Library Headers</caption>
+<tr><td><algorithm></td><td><iomanip></td><td><list></td><td><ostream></td><td><streambuf></td></tr>
+<tr><td><bitset></td><td><ios></td><td><locale></td><td><queue></td><td><string></td></tr>
+<tr><td><complex></td><td><iosfwd></td><td><map></td><td><set></td><td><typeinfo></td></tr>
+<tr><td><deque></td><td><iostream></td><td><memory></td><td><sstream></td><td><utility></td></tr>
+<tr><td><exception></td><td><istream></td><td><new></td><td><stack></td><td><valarray></td></tr>
+<tr><td><fstream></td><td><iterator></td><td><numeric></td><td><stdexcept></td><td><vector></td></tr>
+<tr><td><functional></td><td><limits></td></tr>
+</table></center>
+
+<p></p>
+
+<center><table border="1"><caption>C++98 Headers for C Library Facilities</caption>
+<tr><td><cassert></td><td><ciso646></td><td><csetjmp></td><td><cstdio></td><td><ctime></td></tr>
+<tr><td><cctype></td><td><climits></td><td><csignal></td><td><cstdlib></td><td><cwchar></td></tr>
+<tr><td><cerrno></td><td><clocale></td><td><cstdarg></td><td><cstring></td><td><cwctype></td></tr>
+<tr><td><cfloat></td><td><cmath></td><td><cstddef></td></tr>
+</table></center>
+
+<p>C++0x include files. These are only available in C++0x compilation mode, ie <code>-std=c++0x</code> or <code>-std=gnu++0x</code>.
</p>
+
+<center><table border="1"><caption>C++0x Library Headers</caption>
+<tr><td><algorithm></td><td><iomanip></td><td><locale></td><td><regex></td><td><tuple></td></tr>
+<tr><td><array></td><td><ios></td><td><map></td><td><set></td><td><typeinfo></td></tr>
+<tr><td><bitset></td><td><iosfwd></td><td><memory></td><td><sstream></td><td><type_traits></td></tr>
+<tr><td><complex></td><td><iostream></td><td><new></td><td><stack></td><td><unordered_map></td></tr>
+<tr><td><deque></td><td><istream></td><td><numeric></td><td><stdexcept></td><td><unordered_set></td></tr>
+<tr><td><exception></td><td><iterator></td><td><ostream></td><td><streambuf></td><td><utility></td></tr>
+<tr><td><fstream></td><td><limits></td><td><queue></td><td><string></td><td><valarray></td></tr>
+<tr><td><functional></td><td><list></td><td><random></td><td><system_error></td><td><vector></td></tr>
+</table></center>
+
+<p></p>
+
+<center><table border="1"><caption>C++0x Headers for C Library Facilities</caption>
+<tr><td><cassert></td><td><cfloat></td><td><cmath></td><td><cstddef></td><td><ctgmath></td></tr>
+<tr><td><ccomplex></td><td><cinttypes></td><td><csetjmp></td><td><cstdint></td><td><ctime></td></tr>
+<tr><td><cctype></td><td><ciso646></td><td><csignal></td><td><cstdio></td><td><cuchar></td></tr>
+<tr><td><cerrno></td><td><climits></td><td><cstdarg></td><td><cstdlib></td><td><cwchar></td></tr>
+<tr><td><cfenv></td><td><clocale></td><td><cstdbool></td><td><cstring></td><td><cwctype></td></tr>
+</table></center>
+
+
+<p>In addition, TR1 includes as:
+</p>
+
+<center><table border="1"><caption>TR1 Library Headers</caption>
+<tr><td><tr1/array></td><td><tr1/memory></td><td><tr1/regex></td><td><tr1/type_traits></td><td><tr1/unordered_set></td></tr>
+<tr><td><tr1/complex></td><td><tr1/random></td><td><tr1/tuple></td><td><tr1/unordered_map></td><td><tr1/utility></td></tr>
+<tr><td><tr1/functional></td></tr>
+</table></center>
+
+<p></p>
+
+<center><table border="1"><caption>TR1 Headers for C Library Facilities</caption>
+<tr><td><tr1/cmath></td><td><tr1/cfloat></td><td><tr1/cstdarg></td><td><tr1/cstdio></td><td><tr1/ctime></td></tr>
+<tr><td><tr1/ccomplex></td><td><tr1/cinttypes></td><td><tr1/cstdbool></td><td><tr1/cstdlib></td><td><tr1/cwchar></td></tr>
+<tr><td><tr1/cfenv></td><td><tr1/climits></td><td><tr1/cstdint></td><td><tr1/ctgmath></td><td><tr1/cwctype><td></tr>
+</table></center>
+
+<p>Also included are files for the C++ ABI interface:
+</p>
+<center><table border="1"><caption>C++ ABI Headers</caption>
+<tr><td><cxxabi.h></td><td><cxxabi_forced.h></td></tr>
+</table></center>
+
+<p>And a large variety of extensions.
+</p>
+
+<center><table border="1"><caption>Extension Headers</caption>
+<tr><td><ext/algorithm></td><td><ext/debug_allocator.h></td><td><ext/mt_allocator.h></td><td><ext/pod_char_traits.h></td><td><ext/stdio_sync_filebuf.h></td></tr>
+<tr><td><ext/array_allocator.h></td><td><ext/enc_filebuf.h></td><td><ext/new_allocator.h></td><td><ext/pool_allocator.h></td><td><ext/throw_allocator.h></td></tr>
+<tr><td><ext/atomicity.h></td><td><ext/functional></td><td><ext/numeric></td><td><ext/rb_tree></td><td><ext/typelist.h><td></tr>
+<tr><td><ext/bitmap_allocator.h></td><td><ext/iterator></td><td><ext/numeric_traits.h></td><td><ext/rope></td><td><ext/type_traits.h></td></tr>
+<tr><td><ext/codecvt_specializations.h></td><td><ext/malloc_allocator.h></td><td><ext/pb_ds/assoc_container.h></td><td><ext/slist></td><td><ext/vstring.h></td></tr>
+<tr><td><ext/concurrence.h></td><td><ext/memory></td><td><ext/pb_ds/priority_queue.h></td><td><ext/stdio_filebuf.h></td></tr>
+</table></center>
+
+<p></p>
+
+<center><table border="1"><caption>Extension Debug Headers</caption>
+<tr><td><debug/bitset></td><td><debug/list></td><td><debug/set></td><td><debug/unordered_map></td><td><debug/vector></td></tr>
+<tr><td><debug/deque></td><td><debug/map></td><td><debug/string></td><td><debug/unordered_set></td></tr>
+</table></center>
+
+<p></p>
+
+<center><table border="1"><caption>Extension Parallel Headers</caption>
+<tr><td><parallel/algorithm></td><td><parallel/numeric></td></tr>
+</table></center>
+
+<hr />
+<h2><a name="2.1">Recipes for mixing headers</code></a></h2>
+
+<p> A few simple rules.
+</p>
+
+<p>First, mixing different dialects of the standard headers is not
+possible. It's an all-or-nothing affair. Thus, code like
+</p>
+
<pre>
-C++ Library Headers
-algorithm ios new stack
-array iosfwd numeric stdexcept
-bitset iostream ostream streambuf
-complex istream queue string
-deque iterator random system_error
-exception limits regex tuple
-fstream list set type_traits
-functional locale map typeinfo
-iomanip memory sstream
-
-C++ Headers for C Library Facilities
-cassert cfloat cmath cstddef ctgmath
-ccomplex cinttypes csetjmp cstdio ctime
-cctype ciso646 csignal cstdint cuchar
-cerrno climits cstdarg cstdlib cwchar
-cfenv clocale cstdbool cstring cwctype
+#include <array>
+#include <functional>
</pre>
-<p>In addition, TR1 includes as:
+<p>Implies C++0x mode. To use the entities in <array>, the C++0x
+compilation mode must be used, which implies the C++0x functionality
+(and deprecations) in <functional> will be present.
+</p>
+
+<p>Second, the other headers can be included with either dialect of
+the standard headers, although features and types specific to C++0x
+are still only enabled when in C++0x compilation mode. So, to use
+rvalue references with <code>__gnu_cxx::vstring</code>, or to use the
+debug-mode versions of <code>std::unordered_map</code>, one must use
+the <code>std=gnu++0x</code> compiler flag. (Or <code>std=c++0x</code>, of course.)
</p>
+
+<p>A special case of the second rule is the mixing of TR1 and C++0x
+facilities. It is possible (although not especially prudent) to
+include both the TR1 version and the C++0x version of header in the
+same translation unit:
+</p>
+
<pre>
-C++ Library Headers
-tr1/array, tr1/complex, tr1/functional, tr1/memory, tr1/random,
-tr1/regex, tr1/tuple, tr1/type_traits, tr1/unordered_map,
-tr1/unordered_set, tr1/utility
-
-C++ Headers for C Library Facilities
-tr1/cmath, tr1/ccomplex, tr1/cfenv, tr1/cfloat, tr1/cinttypes,
-tr1/climits, tr1/cstdarg, tr1/cstdbool, tr1/cstdint, tr1/cstdio,
-tr1/cstdlib, tr1/ctgmath, tr1/ctime, tr1/cwchar, tr1/cwctype
-
-C++ Compatibility Headers for C Library Facilities
-tr1/complex.h, tr1/ctype.h, tr1/float.h, tr1/limits.h, tr1/math.h,
-tr1/stdarg.h, tr1/stdbool.h, tr1/stdint.h, tr1/stdio.h, tr1/stdlib.h,
-tr1/tgmath.h, tr1/wchar.h, tr1/wctype.h
+#include <tr1/type_traits>
+#include <type_traits>
</pre>
+<p> Several parts of C++0x diverge quite substantially from TR1 predecessors.
+</p>
+
+
<hr />
-<h2><a name="2.2">Headers and <code>namespace std::</code></a></h2>
+<h2><a name="2.2">The C Headers and <code>namespace std</code></a></h2>
<p>
- You should not use the C-headers (except for system-level
- headers) from C++ programs. Instead, you should use a set of
- headers that are named by prepending 'c' and, as usual,
- omitting the extension (.h). For example, instead of using
- <tt><math.h></tt>, you
- should use <tt><cmath></tt>. In some cases this has
- the advantage that the C++-header is more standardized than
- the C-header (i.e. <tt><ctime></tt> (almost)
- corresponds to either <tt><time.h></tt> or <tt><sys/time.h></tt>).
-
- The standard specifies that if you include the C-style header
- (<tt><math.h></tt> in
- this case), the symbols will be available both in the global
- namespace and in namespace <code>std::</code> (but
- libstdc++ does not yet have fully compliant headers) On the
- other hand, if you include only the new header (i.e. <tt><cmath></tt>), the symbols
- will only be defined in namespace <code>std::</code>
- (and macros will be converted to inline-functions).
+ The standard specifies that if one includes the C-style header
+ (<math.h> in this case), the symbols will be available
+ in the global namespace and perhaps in
+ namespace <code>std::</code> (but this is no longer a firm
+ requirement.) One the other hand, including the C++-style
+ header (<cmath>) guarantees that the entities will be
+ found in namespace std and perhaps in the global namespace.
</p>
-<p>FIXME: this is no longer accurate.</p>
-
<p>
- For more information on this, and for information on how the
- GNU C++ implementation might reuse ("shadow") the C
- library-functions, have a look at <a href="http://www.cantrip.org/cheaders.html" target="_top">
- www.cantrip.org</a>.
- </p>
+Usage of C++-style headers is recommended, as then
+C-linkage names can be disambiguated by explicit qualification, such
+as by <code>std::abort</code>. In addition, the C++-style headers can
+use function overloading to provide a simpler interface to certain
+families of C-functions. For instance in <cmath>, the
+function <code>std::sin</code> has overloads for all the builtin
+floating-point types. This means that <code>std::sin</code> can be
+used uniformly, instead of a combination
+of <code>std::sinf</code>, <code>std::sin</code>,
+and <code>std::sinl</code>.
+</p>
+
+<hr />
+<h2><a name="2.3">Precompiled Headers</a></h2>
+
+<p>There are three base header files that are provided. They can be
+used to precompile the standard headers and extensions into binary
+files that may the be used to speed compiles that use these headers.
+</p>
+
+
+<ul>
+<li>stdc++.h
+<p>Includes all standard headers. Actual content varies depending on
+language dialect.
+</p>
+</li>
+
+<li>stdtr1c++.h
+<p>Includes all of <stdc++.h>, and adds all the TR1 headers.
+</p>
+</li>
+
+<li>extc++.h
+<p>Includes all of <stdtr1c++.h>, and adds all the Extension headers.
+</p></li>
+</ul>
+
+<p>How to construct a .gch file from one of these base header files.</p>
+
+<p>First, find the include directory for the compiler. One way to do
+this is:</p>
+
+<pre>
+g++ -v hello.cc
+
+#include <...> search starts here:
+ /mnt/share/bld/H-x86-gcc.20071201/include/c++/4.3.0
+...
+End of search list.
+</pre>
+
+
+<p>Then, create a precompiled header file with the same flags that
+will be used to compile other projects.</p>
+
+<pre>
+g++ -Winvalid-pch -x c++-header -g -O2 -o ./stdc++.h.gch /mnt/share/bld/H-x86-gcc.20071201/include/c++/4.3.0/x86_64-unknown-linux-gnu/bits/stdc++.h
+</pre>
+
+<p>The resulting file will be quite large: the current size is around
+thirty megabytes. </p>
+
+<p>How to use the resulting file.</p>
+
+<pre>
+g++ -I. -include stdc++.h -H -g -O2 hello.cc
+</pre>
+
+<p>Verification that the PCH file is being used is easy:</p>
+
+<pre>
+g++ -Winvalid-pch -I. -include stdc++.h -H -g -O2 hello.cc -o test.exe
+! ./stdc++.h.gch
+. /mnt/share/bld/H-x86-gcc.20071201/include/c++/4.3.0/iostream
+. /mnt/share/bld/H-x86-gcc.20071201include/c++/4.3.0/string
+</pre>
+
+<p>The exclamation point to the left of the <code>stdc++.h.gch</code> listing means that the generated PCH file was used, and thus the </p>
+<p></p>
+
+<p> Detailed information about creating precompiled header files can be found in the GCC <a href="http://gcc.gnu.org/onlinedocs/gcc/Precompiled-Headers.html">documentation</a>.
+</p>
+
<hr />
-<h2><a name="2.5">Namespace <code>std::</code></a></h2>
+<h2><a name="3.0">Namespaces</a></h2>
+
+
+<p> There are three main namespaces.
+</p>
+
+<ul>
+<li>std
+<p>The ISO C++ standards specify that "all library entities are defined
+within namespace std." This includes namepaces nested
+within <code>namespace std</code>, such as <code>namespace
+std::tr1</code>.
+</p>
+</li>
+<li>abi
+<p>Specified by the C++ ABI. This ABI specifies a number of type and
+function APIs supplemental to those required by the ISO C++ Standard,
+but necessary for interoperability.
+</p>
+</li>
+
+<li>__gnu_
+<p>Indicating one of several GNU extensions. Choices
+include <code>__gnu_cxx</code>, <code>__gnu_debug</code>, <code>__gnu_parallel</code>,
+and <code>__gnu_pbds</code>.
+</p></li>
+</ul>
+
+<p> A complete list of implementation namespaces (including namespace contents) is available in the generated source <a href="http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/namespaces.html">documentation</a>.
+</p>
+
+
+<hr />
+<h2><a name="3.1">Namespace <code>std::</code></a></h2>
<p>
One standard requirement is that the library components are defined
@@ -167,37 +353,46 @@ should not be used in a global context, like header files.
qualified name</i></span> for each library symbol
(i.e. <code>std::string</code>, <code>std::cout</code>) Always can be
used, and usually enhanced, by strategic use of typedefs. (In the
-cases where the qualified verbage becomes unweidly.)
+cases where the qualified verbiage becomes unwieldy.)
</p></li>
</ul></div>
<hr />
-<h2><a name="2.6">Using namespace composition</a></h2>
+<h2><a name="3.2">Using namespace composition</a></h2>
<p>
- <a href="http://gtkmm.sourceforge.net" target="_top">Gtk--</a> defines
- most of its classes in namespace Gtk::. Thus, it was possible to
- adapt Gtk-- to namespace std:: by using a C++-feature called
+Best practice in programming suggests sequestering new data or
+functionality in a sanely-named, unique namespace whenever
+possible. This is considered an advantage over dumping everything in
+the global namespace, as then name look-up can be explicitly enabled or
+disabled as above, symbols are consistently mangled without repetitive
+naming prefixes or macros, etc.
+</p>
+
+<p>For instance, consider a project that defines most of its classes in <code>namespace gtk</code>. It is possible to
+ adapt <code>namespace gtk</code> to <code>namespace std</code> by using a C++-feature called
<span class="emphasis"><i>namespace composition</i></span>. This is what happens if
- you put a <span class="emphasis"><i>using</i></span>-declaration into a
+ a <span class="emphasis"><i>using</i></span>-declaration is put into a
namespace-definition: the imported symbol(s) gets imported into the
currently active namespace(s). For example:
</p>
- <pre class="programlisting">
- namespace Gtk {
- using std::string;
- class Window { ... }
- }
- </pre>
+<pre class="programlisting">
+namespace gtk
+{
+ using std::string;
+ using std::tr1::array;
+
+ class Window { ... };
+}
+</pre>
<p>
In this example, <code>std::string</code> gets imported into
- namespace Gtk::. The result is that you don't have to use
- <code>std::string</code> in this header, but still
+ <code>namespace gtk</code>. The result is that use of
+ <code>std::string</code> inside namespace gtk can just use <code>string</code>, without the explicit qualification.
+ As an added bonus,
<code>std::string</code> does not get imported into
- the global namespace (::) unless the user does
- <code>using namespace Gtk;</code> (which is not recommended
- practice for Gtk--, so it is not a problem). Additionally, the
- <code>using</code>-declarations are wrapped in macros that
+ the global namespace. Additionally, a more elaborate arrangement can be made for backwards compatibility and portability, whereby the
+ <code>using</code>-declarations can wrapped in macros that
are set based on autoconf-tests to either "" or i.e. <code>using
std::string;</code> (depending on whether the system has
libstdc++ in <code>std::</code> or not). (ideas from
@@ -206,7 +401,103 @@ cases where the qualified verbage becomes unweidly.)
</p>
<hr />
-<h2><a name="3">The Standard C++ library and multithreading</a></h2>
+<h2><a name="6">Macros for libstdc++</a></h2>
+
+ <p>All pre-processor switches and configurations are all gathered
+ in the file <code>c++config.h</code>, which is generated during
+ the libstdc++ configuration and build process, and included by
+ files part of the public libstdc++ API. Most of these macros
+ should not be used by consumers of libstdc++, and are reserved
+ for internal implementation use. <strong>These macros cannot be
+ redefined</strong>. However, a select handful of these macro
+ control libstdc++ extensions and extra features, or provide
+ versioning information for the API, and are able to be used.
+ </p>
+
+ <p>All library macros begin with <code>_GLIBCXX_</code> (except for
+ versions 3.1.x to 3.3.x, which use <code>_GLIBCPP_</code>).
+ </p>
+
+ <p>Below is the macro which users may check for library version
+ information. </p>
+
+ <dl>
+ <dt><code>__GLIBCXX__</code></dt> <dd>The current version of
+ libstdc++ in compressed ISO date format, form of an unsigned
+ long. For details on the value of this particular macro for a
+ particular release, please consult this <a href="abi.html">
+ document</a>.</dd> </dl>
+
+ <p>Below are the macros which users may change with #define/#undef or
+ with -D/-U compiler flags. The default state of the symbol is
+ listed.</p>
+
+ <p>"Configurable" (or "Not configurable") means
+ that the symbol is initially chosen (or not) based on
+ --enable/--disable options at library build and configure time
+ (documented <a href="../configopts.html">here</a>), with the
+ various --enable/--disable choices being translated to
+ #define/#undef).
+ </p>
+
+ <p> "ABI" means that changing from the default value may
+ mean changing the ABI of compiled code. In other words, these
+ choices control code which has already been compiled (i.e., in a
+ binary such as 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.
+ Experimenting with different values with the expectation of
+ consistent linkage requires changing the config headers before
+ building/installing the library.
+ </p>
+
+ <dl>
+ <dt><code>_GLIBCXX_DEPRECATED</code></dt>
+ <dd>Defined by default. Not configurable. ABI-changing. Turning this off
+ removes older ARM-style iostreams code, and other anachronisms
+ from the API. This macro is dependent on the version of the
+ standard being tracked, and as a result may give different results for
+ <code>-std=c++98</code> and <code>-std=c++0x</code>. This may
+ be useful in updating old C++ code which no longer meet the
+ requirements of the language, or for checking current code
+ against new language standards. </dd>
+
+ <dt><code>_GLIBCXX_FORCE_NEW</code></dt> <dd>Undefined by
+ default. When defined, memory allocation and allocators controlled
+ by libstdc++ call operator new/delete without caching and
+ pooling. Configurable via
+ <code>--enable-libstdcxx-allocator</code>. ABI-changing.
+ </dd>
+
+
+ <dt><code>_GLIBCXX_CONCEPT_CHECKS</code></dt> <dd>Undefined by
+ default. Configurable via <code>--enable-concept-checks</code>.
+ 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>_GLIBCXX_DEBUG</code></dt>
+ <dd>Undefined by default. When defined, compiles
+ user code using the <a href="../ext/debug.html#safe">libstdc++ debug
+ mode</a>.
+ </dd>
+ <dt><code>_GLIBCXX_DEBUG_PEDANTIC</code></dt>
+ <dd>Undefined by default. When defined while
+ compiling with the <a href="../ext/debug.html#safe">libstdc++ debug
+ mode</a>, makes the debug mode extremely picky by making the use
+ of libstdc++ extensions and libstdc++-specific behavior into
+ errors.
+ </dd>
+ <dt><code>_GLIBCXX_PARALLEL</code></dt>
+ <dd>Undefined by default. When defined, compiles
+ user code using the <a href="../ext/parallel_mode.html">libstdc++ parallel
+ mode</a>.
+ </dd>
+ </dl>
+
+<hr />
+<h2><a name="7">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++
@@ -419,107 +710,11 @@ cases where the qualified verbage becomes unweidly.)
<a href="../faq/index.html">to the FAQ</a>.
</p>
-<hr />
-<h2><a name="6">Macros for libstdc++</a></h2>
-
- <p>All pre-processor switches and configurations are all gathered
- in the file <code>c++config.h</code>, which is generated during
- the libstdc++ configuration and build process, and included by
- files part of the public libstdc++ API. Most of these macros
- should not be used by consumers of libstdc++, and are reserved
- for internal implementation use. <strong>These macros cannot be
- redefined</strong>. However, a select handful of these macro
- control libstdc++ extensions and extra features, or provide
- versioning information for the API, and are able to be used.
- </p>
-
- <p>All library macros begin with <code>_GLIBCXX_</code> (except for
- versions 3.1.x to 3.3.x, which use <code>_GLIBCPP_</code>).
- </p>
-
- <p>Below is the macro which users may check for library version
- information. </p>
-
- <dl>
- <dt><code>__GLIBCXX__</code></dt> <dd>The current version of
- libstdc++ in compressed ISO date format, form of an unsigned
- long. For details on the value of this particular macro for a
- particular release, please consult this <a href="abi.html">
- document</a>.</dd> </dl>
-
- <p>Below are the macros which users may change with #define/#undef or
- with -D/-U compiler flags. The default state of the symbol is
- listed.</p>
-
- <p>"Configurable" (or "Not configurable") means
- that the symbol is initially chosen (or not) based on
- --enable/--disable options at library build and configure time
- (documented <a href="../configopts.html">here</a>), with the
- various --enable/--disable choices being translated to
- #define/#undef).
- </p>
-
- <p> "ABI" means that changing from the default value may
- mean changing the ABI of compiled code. In other words, these
- choices control code which has already been compiled (i.e., in a
- binary such as 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.
- Experimenting with different values with the expectation of
- consistent linkage requires changing the config headers before
- building/installing the library.
- </p>
-
- <dl>
- <dt><code>_GLIBCXX_DEPRECATED</code></dt>
- <dd>Defined by default. Not configurable. ABI-changing. Turning this off
- removes older ARM-style iostreams code, and other anachronisms
- from the API. This macro is dependent on the version of the
- standard being tracked, and as a result may give different results for
- <code>-std=c++98</code> and <code>-std=c++0x</code>. This may
- be useful in updating old C++ code which no longer meet the
- requirements of the language, or for checking current code
- against new language standards. </dd>
-
- <dt><code>_GLIBCXX_FORCE_NEW</code></dt> <dd>Undefined by
- default. When defined, memory allocation and allocators controlled
- by libstdc++ call operator new/delete without caching and
- pooling. Configurable via
- <code>--enable-libstdcxx-allocator</code>. ABI-changing.
- </dd>
-
-
- <dt><code>_GLIBCXX_CONCEPT_CHECKS</code></dt> <dd>Undefined by
- default. Configurable via <code>--enable-concept-checks</code>.
- 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>_GLIBCXX_DEBUG</code></dt>
- <dd>Undefined by default. When defined, compiles
- user code using the <a href="../ext/debug.html#safe">libstdc++ debug
- mode</a>.
- </dd>
- <dt><code>_GLIBCXX_DEBUG_PEDANTIC</code></dt>
- <dd>Undefined by default. When defined while
- compiling with the <a href="../ext/debug.html#safe">libstdc++ debug
- mode</a>, makes the debug mode extremely picky by making the use
- of libstdc++ extensions and libstdc++-specific behavior into
- errors.
- </dd>
- <dt><code>_GLIBCXX_PARALLEL</code></dt>
- <dd>Undefined by default. When defined, compiles
- user code using the <a href="../ext/parallel_mode.html">libstdc++ parallel
- mode</a>.
- </dd>
-
<!--
<dt><code></code></dt>
<dd>
</dd>
-->
- </dl>
<p>Return <a href="#top">to top of page</a> or
<a href="../faq/index.html">to the FAQ</a>.
</p>
diff --git a/libstdc++-v3/docs/html/18_support/howto.html b/libstdc++-v3/docs/html/18_support/howto.html
index 87dd8a5..dc5bc2a 100644
--- a/libstdc++-v3/docs/html/18_support/howto.html
+++ b/libstdc++-v3/docs/html/18_support/howto.html
@@ -281,9 +281,6 @@
</p>
<pre>
std::set_terminate(std::abort);</pre>
- <p>Return <a href="#top">to top of page</a> or
- <a href="../faq/index.html">to the FAQ</a>.
- </p>
<p>
This function will attempt to write to stderr. If your application
@@ -292,6 +289,11 @@
unspecified manner.
</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="5">Dynamic memory management</a></h2>
<p>There are six flavors each of <code>new</code> and
diff --git a/libstdc++-v3/docs/html/20_util/allocator.html b/libstdc++-v3/docs/html/20_util/allocator.html
index 409c08b..951c12d 100644
--- a/libstdc++-v3/docs/html/20_util/allocator.html
+++ b/libstdc++-v3/docs/html/20_util/allocator.html
@@ -84,34 +84,47 @@
</h3>
<p>The easiest way of fulfilling the requirements is to call operator new
each time a container needs memory, and to call operator delete each
- time the container releases memory. <strong>BUT</strong>
- <a href="http://gcc.gnu.org/ml/libstdc++/2001-05/msg00105.html">this
- method is horribly slow</a>.
- </p>
- <p>Or we can keep old memory around, and reuse it in a pool to save time.
- The old libstdc++-v2 used a memory pool, and so do we. As of 3.0,
- <a href="http://gcc.gnu.org/ml/libstdc++/2001-05/msg00136.html">it's
- on by default</a>. The pool is shared among all the containers in the
- program: when your program's std::vector<int> gets cut in half
- and frees a bunch of its storage, that memory can be reused by the
- private std::list<WonkyWidget> brought in from a KDE library
- that you linked against. And we don't have to call operators new and
- delete to pass the memory on, either, which is a speed bonus.
- <strong>BUT</strong>...
- </p>
- <p>What about threads? No problem: in a threadsafe environment, the
- memory pool is manipulated atomically, so you can grow a container in
- one thread and shrink it in another, etc. <strong>BUT</strong> what
- if threads in libstdc++ aren't set up properly?
- <a href="../faq/index.html#5_6">That's been answered already</a>.
- </p>
- <p><strong>BUT</strong> what if you want to use your own allocator? What
- if you plan on using a runtime-loadable version of malloc() which uses
- shared telepathic anonymous mmap'd sections serializable over a
- network, so that memory requests <em>should</em> go through malloc?
- And what if you need to debug it?
- </p>
+ time the container releases memory. This method may be
+ <a href="http://gcc.gnu.org/ml/libstdc++/2001-05/msg00105.html">slower</a>
+ than caching the allocations and re-using previously-allocated
+ memory, but has the advantage of working correctly across a wide
+ variety of hardware and operating systems, including large
+ clusters. The <code>__gnu_cxx::new_allocator</code> implements
+ the simple operator new and operator delete semantics, while <code>__gnu_cxx::malloc_allocator</code> implements much the same thing, only with the C language functions <code>std::malloc</code> and <code>std::free</code>.
+ </p>
+
+<p> Another approach is to use intelligence within the allocator class
+to cache allocations. This extra machinery can take a variety of
+forms: a bitmap index, an index into an exponentially increasing
+power-of-two-sized buckets, or simpler fixed-size pooling cache. The
+cache is shared among all the containers in the program: when your
+program's std::vector<int> gets cut in half and frees a bunch of
+its storage, that memory can be reused by the private
+std::list<WonkyWidget> brought in from a KDE library that you
+linked against. And operators new and delete are not always called to
+pass the memory on, either, which is a speed bonus. Examples of
+allocators that use these techniques
+are <code>__gnu_cxx::bitmap_allocator</code>, <code>__gnu_cxx::pool_allocator</code>,
+and <code>__gnu_cxx::__mt_alloc</code>.
+</p>
+<p>Depending on the implementation techniques used, the underlying
+operating system, and compilation environment, scaling caching
+allocators can be tricky. In particular, order-of-destruction and
+order-of-creation for memory pools may be difficult to pin down with
+certainty, which may create problems when used with plugins or loading
+and unloading shared objects in memory. As such, using caching
+allocators on systems that do not
+support <code>abi::__cxa_atexit</code> is not recommended.
+</p>
+
+ <p>Versions of libstdc++ prior to 3.4 cache allocations in a memory
+ pool, instead of passing through to call the global allocation
+ operators (ie, <code>__gnu_cxx::pool_allocator</code>). More
+ recent versions default to the
+ simpler <code>__gnu_cxx::new_allocator</code>.
+ </p>
+
<h3 class="left">
<a name="stdallocator">Implementation details of <code>std::allocator</code></a>
</h3>
@@ -335,6 +348,11 @@
<td><ext/array_allocator.h></td>
<td>4.0.0</td>
</tr>
+ <tr>
+ <td>__gnu_cxx::throw_allocator<T></td>
+ <td><ext/throw_allocator.h></td>
+ <td>4.2.0</td>
+ </tr>
</table>
<p>More details on each of these extension allocators follows. </p>
@@ -371,6 +389,12 @@
size is checked, and assert() is used to guarantee they match.
</p>
</li>
+ <li><code>throw_allocator</code>
+ <p> Includes memory tracking and marking abilities as well as hooks for
+ throwing exceptinos at configurable intervals (including random,
+ all, none).
+ </p>
+ </li>
<li><code>__pool_alloc</code>
<p> A high-performance, single pool allocator. The reusable
memory is shared among identical instantiations of this type.
diff --git a/libstdc++-v3/docs/html/documentation.html b/libstdc++-v3/docs/html/documentation.html
index 92ce87b..d2a736f 100644
--- a/libstdc++-v3/docs/html/documentation.html
+++ b/libstdc++-v3/docs/html/documentation.html
@@ -26,7 +26,7 @@ href="http://gcc.gnu.org/libstdc++">project</a> to implement the ISO
annex D, extensions as described by TR1, and future C++ library
standards still in progress. For those who want to see exactly how far
the project has come, or just want the latest bleeding-edge code, the
-up-to-date source is always publically available over anonymous SVN,
+up-to-date source is always publicly available over anonymous SVN,
and can be browsed over the <a
href="http://gcc.gnu.org/svn.html">web</a>.
</p>
@@ -34,13 +34,6 @@ href="http://gcc.gnu.org/svn.html">web</a>.
<p>Stable versions of libstdc++ are included with releases of
<a href="http://gcc.gnu.org/releases.html">the GCC compilers</a>.
</p>
-<!--
- The list below is automatically generated. To make changes in the text,
- edit the appropriate HOWTO file and run "make" in this directory. In
- those files, you may reorder entries as you like, but DO NOT change the
- "#number"s in anchors, for they are used elsewhere and in bookmarks.
--->
-<!-- beginlist -->
<ul>
<li>Introduction
<ul>
@@ -77,26 +70,27 @@ href="http://gcc.gnu.org/svn.html">web</a>.
<ul>
<li>Header Files
<ul>
- <li><a href="17_intro/howto.html#2.1">Available headers</a></li>
- <li><a href="17_intro/howto.html#2.2">Headers and <code>namespace std</code></a></li>
- <li>Pre-compiled headers</li>
+ <li><a href="17_intro/howto.html#2.0">Available headers</a></li>
+ <li><a href="17_intro/howto.html#2.1">Mixing headers</a></li>
+ <li><a href="17_intro/howto.html#2.2">The C Headers and <code>namespace std</code></a></li>
+ <li><a href="17_intro/howto.html#2.3">Precompiled Headers</a></li>
</ul>
</li>
<li>Namespaces
<ul>
- <li><a href="17_intro/howto.html#2.5">Namespace <code>std::</code></a></li>
- <li><a href="17_intro/howto.html#2.6">Using namespace composition</a></li>
+ <li><a href="17_intro/howto.html#3.0">Available namespaces</li>
+ <li><a href="17_intro/howto.html#3.1">Namespace <code>std::</code></a></li>
+ <li><a href="17_intro/howto.html#3.2">Using namespace composition</a></li>
</ul>
</li>
<li><a href="17_intro/howto.html#6">Macros</a></li>
+ <li>Command line options</li>
<li>Concurrency
<ul>
- <li>Atomic Operations</li>
- <li><a href="17_intro/howto.html#3">Thread safety overview</a></li>
-
<li><a href="faq/index.html#5_6">Is it thread safe?</a></li>
+ <li><a href="17_intro/howto.html#7">Thread safety history and evolution</a></li>
<li><a href="23_containers/howto.html#3">Containers</a></li>
<li><a href="27_io/howto.html#9">IO</a></li>
</ul>
@@ -122,8 +116,15 @@ href="http://gcc.gnu.org/svn.html">web</a>.
<li>Diagnostics
<ul>
+ <li>Exceptions
+
+ <ul>
<li>Exception class hierarchy</li>
<li><a href="19_diagnostics/howto.html#1">Adding data to exceptions</a></li>
+ <li>Cancellation</li>
+ </ul>
+ </li>
+
<li><a href="19_diagnostics/howto.html#3">Concept checking</a></li>
</ul>
</li>
@@ -248,6 +249,7 @@ href="http://gcc.gnu.org/svn.html">web</a>.
</ul>
</li>
<li><a href="ext/../18_support/howto.html#6">Demangling</a></li>
+ <li><a href="ext/concurrence.html">Concurrency: Threads and Atomics</a></li>
</ul>
</li>
@@ -277,6 +279,7 @@ href="http://gcc.gnu.org/svn.html">web</a>.
<li><a href="17_intro/porting.html">Porting to new hardware or operating systems.</a></li>
<li><a href="17_intro/abi.html">ABI Policy and Guidelines</a></li>
<li><a href="17_intro/api.html">API Evolution and Deprecation History</a></li>
+ <li><a href="17_intro/backwards_compatibility.html">Backwards Compatibility</a></li>
</ul>
</li>
diff --git a/libstdc++-v3/docs/html/ext/concurrence.html b/libstdc++-v3/docs/html/ext/concurrence.html
new file mode 100644
index 0000000..e621bc9
--- /dev/null
+++ b/libstdc++-v3/docs/html/ext/concurrence.html
@@ -0,0 +1,342 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<!DOCTYPE html
+ PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+<head>
+ <meta name="AUTHOR" content="bkoz@gcc.gnu.org (Benjamin Kosnik)" />
+ <meta name="KEYWORDS" content="C++, libstdc++, MT, thread, pthread, mutex, loc, atomic" />
+ <meta name="DESCRIPTION" content="Concurrency Support" />
+ <meta name="GENERATOR" content="emacs and ten fingers" />
+ <title>Concurrency Support</title>
+<link rel="StyleSheet" href="lib3styles.css" type="text/css" />
+<link rel="Start" href="documentation.html" type="text/html"
+ title="GNU C++ Standard Library" />
+<link rel="Copyright" href="17_intro/license.html" type="text/html" />
+</head>
+<body>
+
+<h1 class="centered"><a name="top">Concurrency Support</a></h1>
+
+<p class="fineprint"><em>
+ The latest version of this document is always available at
+ <a href="http://gcc.gnu.org/onlinedocs/libstdc++/17_intro/concurrence.html">
+ http://gcc.gnu.org/onlinedocs/libstdc++/17_intro/concurrence.html</a>.
+</em></p>
+
+<p><em>
+ To the <a href="http://gcc.gnu.org/libstdc++/">libstdc++ homepage</a>.
+</em></p>
+
+
+<!-- ####################################################### -->
+
+<hr />
+
+
+<p>The interface for concurrency support is divided into two files:
+<ext/atomicity.h> which provides support for atomic operations,
+and <ext/concurrence.h>, which provides mutex and lock objects
+as well as compile-time data structures for querying thread
+support.</p>
+
+<p>It is expected that support for concurrence will evolve into what
+is specified in the draft C++0x standard.</p>
+
+<h3 class="left">
+ <a name="atomic_api">Atomics Interface</a>
+</h3>
+
+<p>
+Two functions and one type form the base of atomic support.
+</p>
+
+
+<p>The type <code>_Atomic_word</code> is a signed integral type
+supporting atomic operations.
+</p>
+
+<p>
+The two functions functions are:
+</p>
+
+<pre>
+_Atomic_word
+__exchange_and_add_dispatch(volatile _Atomic_word*, int);
+
+void
+__atomic_add_dispatch(volatile _Atomic_word*, int);
+</pre>
+
+<p>Both of these functions are declared in the header file
+<ext/atomicity.h>, and are in <code>namespace __gnu_cxx</code>.
+</p>
+
+<ul>
+<li>
+<code>
+__exchange_and_add_dispatch
+</code>
+<p>Adds the second argument's value to the first argument. Returns the old value.
+</p>
+</li>
+<li>
+<code>
+__atomic_add_dispatch
+</code>
+<p>Adds the second argument's value to the first argument. Has no return value.
+</p>
+</li>
+</ul>
+
+</p>
+These functions forward to one of several specialized helper
+functions, depending on the circumstances. For instance,
+</p>
+
+<p>
+<code>
+__exchange_and_add_dispatch
+</code>
+</p>
+
+<p>
+Calls through to either of:
+</p>
+
+<ul>
+<li><code>__exchange_and_add</code>
+<p>Multi-thread version. Inlined if compiler-generated builtin atomics
+can be used, otherwise resolved at link time to a non-builtin code
+sequence.
+</p>
+</li>
+
+<li><code>__exchange_and_add_single</code>
+<p>Single threaded version. Inlined.</p>
+</li>
+</ul>
+
+<p>However, only <code>__exchange_and_add_dispatch</code>
+and <code>__atomic_add_dispatch</code> should be used. These functions
+can be used in a portable manner, regardless of the specific
+environment. They are carefully designed to provide optimum efficiency
+and speed, abstracting out atomic accesses when they are not required
+(even on hosts that support compiler intrinsics for atomic
+operations.)
+</p>
+
+<p>
+In addition, there are two macros
+</p>
+
+<p>
+<code>
+_GLIBCXX_READ_MEM_BARRIER
+</code>
+</p>
+<p>
+<code>
+GLIBCXX_WRITE_MEM_BARRIER
+</code>
+</p>
+
+<p>
+Which expand to the appropriate write and read barrier required by the
+host hardware and operating system.
+</p>
+
+<h3 class="left">
+ <a name="pthread_api">Pthread Interface</a>
+</h3>
+
+<p>A thin layer above IEEE 1003.1 (ie pthreads) is used to abastract
+the thread interface for GCC. This layer is called "gthread," and is
+comprised of one header file that wraps the host's default thread layer with
+a POSIX-like interfaces.
+</p>
+
+<p> The file <gthr-default.h> points to the deduced wrapper for
+the current host. In libstdc++ implementation files,
+<bits/gthr.h> is used to select the proper gthreads file.
+</p>
+
+<p>Within libstdc++ sources, all calls to underlying thread functionality
+use this layer. More detail as to the specific interface can be found in the source <a href="http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/gthr_8h-source.html">documentation</a>.
+</p>
+
+<p>By design, the gthread layer is interoperable with the types,
+functions, and usage found in the usual <pthread.h> file,
+including <code>pthread_t</code>, <code>pthread_once_t</code>, <code>pthread_create</code>,
+etc.
+</p>
+
+<h3 class="left">
+ <a name="concur_api">Concurrence Interface</a>
+</h3>
+
+<p>The file <ext/concurrence.h> contains all the higher-level
+constructs for playing with threads. In contrast to the atomics layer,
+the concurrence layer consists largely of types. All types are defined within <code>namespace __gnu_cxx</code>.
+</p>
+
+<p>
+These types can be used in a portable manner, regardless of the
+specific environment. They are carefully designed to provide optimum
+efficiency and speed, abstracting out underlying thread calls and
+accesses when compiling for single-threaded situations (even on hosts
+that support multiple threads.)
+</p>
+
+<p>The enumerated type <code>_Lock_policy</code> details the set of
+available locking
+policies: <code>_S_single</code>, <code>_S_mutex</code>,
+and <code>_S_atomic</code>.
+</p>
+
+<ul>
+<li><code>_S_single</code>
+<p>Indicates single-threaded code that does not need locking.
+</p>
+
+</li>
+<li><code>_S_mutex</code>
+<p>Indicates multi-threaded code using thread-layer abstractions.
+</p>
+</li>
+<li><code>_S_atomic</code>
+<p>Indicates multi-threaded code using atomic operations.
+</p>
+</li>
+</ul>
+
+<p>The compile-time constant <code>__default_lock_policy</code> is set
+to one of the three values above, depending on characteristics of the
+host environment and the current compilation flags.
+</p>
+
+<p>Two more datatypes make up the rest of the
+interface: <code>__mutex</code>, and <code>__scoped_lock</code>.
+</p>
+
+<p>
+</p>
+
+<p>The scoped lock idiom is well-discussed within the C++
+community. This version takes a <code>__mutex</code> reference, and
+locks it during construction of <code>__scoped_locke</code> and
+unlocks it during destruction. This is an efficient way of locking
+critical sections, while retaining exception-safety.
+</p>
+
+<p>Typical usage of the last two constructs is demonstrated as follows:
+</p>
+
+<pre>
+#include <ext/concurrence.h>
+
+namespace
+{
+ __gnu_cxx::__mutex safe_base_mutex;
+} // anonymous namespace
+
+namespace other
+{
+ void
+ foo()
+ {
+ __gnu_cxx::__scoped_lock sentry(safe_base_mutex);
+ for (int i = 0; i < max; ++i)
+ {
+ _Safe_iterator_base* __old = __iter;
+ __iter = __iter->_M_next;
+ __old->_M_detach_single();
+ }
+}
+</pre>
+
+<p>In this sample code, an anonymous namespace is used to keep
+the <code>__mutex</code> private to the compilation unit,
+and <code>__scoped_lock</code> is used to guard access to the critical
+section within the for loop, locking the mutex on creation and freeing
+the mutex as control moves out of this block.
+</p>
+
+<p>Several exception classes are used to keep track of
+concurrence-related errors. These classes
+are: <code>__concurrence_lock_error</code>, <code>__concurrence_unlock_error</code>, <code>__concurrence_wait_error</code>,
+and <code>__concurrence_broadcast_error</code>.
+</p>
+
+
+
+<h3 class="left">
+ <a name="atomic_impl">Details on builtin atomic support and library fallbacks</a>
+</h3>
+
+<p>The functions for atomic operations described above are either
+implemented via compiler intrinsics (if the underlying host is
+capable) or by library fallbacks.</p>
+
+<p>Compiler intrinsics (builtins) are always preferred. However, as
+the compiler builtins for atomics are not universally implemented,
+using them directly is problematic, and can result in undefined
+function calls. (An example of an undefined symbol from the use
+of <code>__sync_fetch_and_add</code> on an unsupported host is a
+missing reference to <code>__sync_fetch_and_add_4</code>.)
+</p>
+
+<p>In addition, on some hosts the compiler intrinsics are enabled
+conditionally, via the <code>-march</code> command line flag. This makes
+usage vary depending on the target hardware and the flags used during
+compile.
+</p>
+
+<p> If builtins are possible, <code>_GLIBCXX_ATOMIC_BUILTINS</code>
+will be defined.
+</p>
+
+
+<p>For the following hosts, intrinsics are enabled by default.
+</p>
+
+<ul>
+ <li>alpha</li>
+ <li>ia64</li>
+ <li>powerpc</li>
+ <li>s390</li>
+</ul>
+
+<p>For others, some form of <code>-march</code> may work. On
+non-ancient x86 hardware, <code>-march=native</code> usually does the
+trick.</p>
+
+<p> For hosts without compiler intrinsics, but with capable
+hardware, hand-crafted assembly is selected. This is the case for the following hosts:
+</p>
+
+<ul>
+ <li>cris</li>
+ <li>hppa</li>
+ <li>i386</li>
+ <li>i486</li>
+ <li>m48k</li>
+ <li>mips</li>
+ <li>sparc</li>
+</ul>
+
+<p>And for the rest, a simulated atomic lock via pthreads.
+</p>
+
+<p> Detailed information about compiler intrinsics for atomic operations can be found in the GCC <a href="http://gcc.gnu.org/onlinedocs/gcc/Atomic-Builtins.html"> documentation</a>.
+</p>
+
+<p> More details on the library fallbacks from the porting <a href="http://gcc.gnu.org/onlinedocs/libstdc++/17_intro/porting.html#Thread%20safety">section</a>.
+</p>
+
+
+
+</body>
+</html>
+
diff --git a/libstdc++-v3/docs/html/ext/howto.html b/libstdc++-v3/docs/html/ext/howto.html
index 3171355..2e88c66 100644
--- a/libstdc++-v3/docs/html/ext/howto.html
+++ b/libstdc++-v3/docs/html/ext/howto.html
@@ -74,18 +74,13 @@
are deprecated but available as backwards-compatible extensions,
as discussed further below. <code><rope></code> is the
SGI specialization for large strings ("rope,"
- "large strings," get it? love those SGI folks).
+ "large strings," get it? Love that geeky humor.)
<code><slist></code> is a singly-linked list, for when the
doubly-linked <code>list<></code> is too much space
overhead, and <code><rb_tree></code> exposes the red-black
tree classes used in the implementation of the standard maps and
sets.
</p>
- <p>Okay, about those hashing classes... these classes have been
- deprecated by the unordered_set, unordered_multiset, unordered_map,
- unordered_multimap containers in TR1 and the upcoming C++0x, and
- may be removed in future releases.
- </p>
<p>Each of the associative containers map, multimap, set, and multiset
have a counterpart which uses a
<a href="http://www.sgi.com/tech/stl/HashFunction.html">hashing
@@ -111,11 +106,13 @@
components, and if you aren't scared about the possibility of
pathological cases, you'll probably get better performance from
hash_map.</em></blockquote>
- <p>(Side note: for those of you wondering, <strong>"Why wasn't a hash
- table included in the Standard in the first #!$@ place?"</strong>
- I'll give a quick answer: it was proposed, but too late and in too
- unorganized a fashion.)
+
+ <p>Okay, about the SGI hashing classes... these classes have been
+ deprecated by the unordered_set, unordered_multiset, unordered_map,
+ unordered_multimap containers in TR1 and the upcoming C++0x, and
+ may be removed in future releases.
</p>
+
<p>Return <a href="#top">to top of page</a> or
<a href="../faq/index.html">to the FAQ</a>.
</p>
diff --git a/libstdc++-v3/docs/html/ext/sgiexts.html b/libstdc++-v3/docs/html/ext/sgiexts.html
index 7f9b8c0..64b8e31 100644
--- a/libstdc++-v3/docs/html/ext/sgiexts.html
+++ b/libstdc++-v3/docs/html/ext/sgiexts.html
@@ -9,7 +9,7 @@
<meta name="KEYWORDS" content="libstdc++, libstdc++, GCC, g++, STL, SGI" />
<meta name="DESCRIPTION" content="SGI extensions preserved in libstdc++." />
<meta name="GENERATOR" content="vi and eight fingers" />
- <title>SGI extensions to the library in libstdc++</title>
+ <title>HP/SGI STL extensions</title>
<link rel="StyleSheet" href="../lib3styles.css" type="text/css" />
<link rel="Start" href="../documentation.html" type="text/html"
title="GNU C++ Standard Library" />
@@ -19,29 +19,29 @@
</head>
<body>
-<h1 class="centered"><a name="top">SGI extensions to the library in
-libstdc++</a></h1>
+<h1 class="centered"><a name="top">HP/SGI STL extensions</a></h1>
-<p>This page describes the extensions that SGI made to their version of the
- STL subset of the Standard C++ Library. For a time we
- <a href="../faq/index.html#5_3">tracked and imported changes and updates
- from most of the SGI STL</a>, up through their (apparently) final release.
- Their extensions were mostly preserved.
+<p>This page describes the extensions that SGI made to the STL subset
+ of the Standard C++ Library, which also includes work from the
+ originating HP codebase. This work is the basis for much of
+ libstdc++, and where possible these extensions have been
+ preserved.
</p>
-<p>They are listed according to the chapters of the library that they
- extend (see <a href="../documentation.html#3">the chapter-specific notes</a>
- for a description). Not every chapter may have extensions, and the
- extensions may come and go. Also, this page is incomplete because the
- author is pressed for time. Check back often; the latest change was on
- $Date: 2003/04/16 17:02:47 $ (UTC).
+<p>What follows is a listing of these extensions, according to the
+ chapters of the library that they extend
+ (see <a href="../documentation.html#3">the chapter-specific
+ notes</a> for a description). Not every chapter has extensions,
+ and existing extensions may be removed (or moved) as their
+ functionality is standardized.
</p>
-<p>Descriptions range from the scanty to the verbose. You should also check
- the <a href="../documentation.html#4">generated documentation</a> for notes
- and comments, especially for entries marked with '*'. For more complete
- doumentation, see the SGI website. For <em>really</em> complete
- documentation, buy a copy of Matt Austern's book. *grin*
+<p>Descriptions range from the scanty to the verbose. Also check
+ the <a href="../documentation.html#4">generated documentation</a>
+ for notes and comments, especially for entries marked with '*'.
+ For more complete doumentation, see the SGI website.
+ For <em>really</em> complete documentation, consider perusing a
+ copy of Matt Austern's book "Generic Programming and the STL."
</p>
<p>Back to the <a href="howto.html">libstdc++ extensions</a>.
diff --git a/libstdc++-v3/docs/html/faq/index.html b/libstdc++-v3/docs/html/faq/index.html
index e353a1f..ff6cd65 100644
--- a/libstdc++-v3/docs/html/faq/index.html
+++ b/libstdc++-v3/docs/html/faq/index.html
@@ -1052,14 +1052,26 @@ http://clisp.cons.org/~haible/gccinclude-glibc-2.2-compat.diff
<hr />
<h2><a name="5_6">5.6 Is libstdc++ thread-safe?</a></h2>
- <p>libstdc++ strives to be thread-safe when all of the following
+ <p>The library strives to be thread-safe when all of the following
conditions are met:
</p>
<ul>
<li>The system's libc is itself thread-safe,</li>
- <li><code>gcc -v</code> reports a thread model other than 'single',</li>
- <li>[pre-3.3 only] a non-generic implementation of atomicity.h
- exists for the architecture in question.</li>
+ <li>The compiler in use reports a thread model other than 'single'. This can be tested via output from <code>gcc -v</code>. Multi-thread capable versions of gcc output something like this:
+<pre>
+%gcc -v
+Using built-in specs.
+...
+Thread model: posix
+gcc version 4.1.2 20070925 (Red Hat 4.1.2-33)
+</pre>
+
+<p>Look for "Thread model" lines that aren't equal to "single."</p>
+ </li>
+ <li>Requisite command-line flags are used for atomic operations and threading. Examples of this include <code>-pthread</code> and <code>-march=native</code>, although specifics vary depending on the host environment. See <a href="http://gcc.gnu.org/onlinedocs/gcc/Option-Summary.html">Machine Dependent Options</a>.</li>
+ <li>An implementation of atomicity.h functions
+ exists for the architecture in question. See the internals documentation for more <a href="../ext/concurrence.html">details</a>.</li>
+
</ul>
<p>The user-code must guard against concurrent method calls which may
access any particular library object's state. Typically, the
--
cgit v1.1