API Evolution and Deprecation History

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

+ 3.0 +

No ios_base

At least some older implementations don't have std::ios_base, so you should use std::ios::badbit, std::ios::failbit and std::ios::eofbit and std::ios::goodbit. +

+Include files from the SGI/HP sources that pre-date the ISO standard +are added. These files are placed into +the include/backward directory and a deprecated warning +is added that notifies on inclusion (-Wno-deprecated +deactivates the warning.)

No cout in ostream.h, no cin in istream.h

- In earlier versions of the standard, - <fstream.h>, - <ostream.h> - and <istream.h> - used to define - cout, cin and so on. ISO C++ specifies that one needs to include - <iostream> - explicitly to get the required definitions. -

Removal of include <builtinbuf.h>, <indstream.h>, <parsestream.h>, <PlotFile.h>, <SFile.h>, <stdiostream.h>, and <stream.h>.

This project is no longer maintained or supported, and the sources -archived. The code is considered replaced and rewritten. -

- Second. + 3.1

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

Namespace std:: not supported.

- Some care is required to support C++ compiler and or library - implementation that do not have the standard library in - namespace std. -

- The following sections list some possible solutions to support compilers - that cannot ignore std::-qualified names. -

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 std::, as - the compilers use -fno-honor-std (ignore - std::, :: = std::) by default. That - is, the responsibility for enabling or disabling - std:: is on the user; the maintainer does not have - to care about it. This probably applies to some other compilers - as well. -

By defining std as a macro, fully-qualified namespace calls become global. Volia. - -

Define a macro NAMESPACE_STD, 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 HAVE_NAMESPACE_STD, then -using that to set a value for the NAMESPACE_STD macro. -At that point, one is able to use NAMESPACE_STD::string, -which will evaluate to std::string or -::string (ie, in the global namespace on systems that do -not put string in std::).

Illegal iterator usage.

- The following illustrate implementation-allowed illegal iterator - use, and then correct use.

you cannot do - ostream::operator<<(iterator) to print the - address of the iterator => use operator<< - &*iterator instead ? -
you cannot clear an iterator's reference - (iterator = 0) => use - iterator = iterator_type(); ? -
-if (iterator) won't work any - more => use if (iterator != iterator_type()) - ?

+Extensions from SGI/HP moved from namespace std +to namespace __gnu_cxx. As part of this, the following +new includes are +added: <ext/algorithm>, <ext/functional>, <ext/iterator>, <ext/memory>, and <ext/numeric>. +

`isspace` from `<cctype>` is a macro -

+Extensions to basic_filebuf introduced: __gnu_cxx::enc_filebuf, and __gnu_cxx::stdio_filebuf. +

Glibc 2.0.x and 2.1.x define <ctype.h> -functionality as macros (isspace, isalpha etc.). +

+Extensions to tree data structures added in <ext/rb_tree>.

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

 
-#include <cctype> 
-int main() { std::isspace('X'); } 
-

Results in something like this: -

+ 3.2 +

Symbol versioning introduced for shared library.

 
-std:: (__ctype_b[(int) ( ( 'X' ) )] & (unsigned short int) _ISspace ) ; 
-

Removal of include <backward/strstream.h>.

+ 3.3 +

Allocator changes. Change __malloc_alloc to malloc_allocator and __new_alloc to new_allocator.

A solution is to modify a header-file so that the compiler tells -<ctype.h> to define functions instead of macros: -

Error handling in iostreams cleaned up, made consistent.

-// This keeps isalnum, et al from being propagated as macros. 
-#if __linux__
-# define __NO_CTYPE 1
-#endif
-

Then, include <ctype.h> +

+ 3.4 +

+Large file support.

-Another problem arises if you put a using namespace std; -declaration at the top, and include <ctype.h>. This -will result in ambiguities between the definitions in the global -namespace (<ctype.h>) and the definitions in namespace -std:: (<cctype>). +

Extensions for generic characters and char_traits added in <ext/pod_char_traits.h>.

No `vector::at`, `deque::at`, `string::at`

+Support for wchar_t specializations of basic_filebuf enhanced to support UTF-8 and Unicode, depending on host. More hosts support basic wchar_t functionality. +

- One solution is to add an autoconf-test for this: -

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

+Support for char_traits beyond builtin types. +

-If you are using other (non-GNU) compilers it might be a good idea -to check for string::at separately. +Conformant allocator 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>.

No `std::char_traits<char>::eof`

-Use some kind of autoconf test, plus this: -

 
-#ifdef HAVE_CHAR_TRAITS
-#define CPP_EOF std::char_traits<char>::eof()
-#else
-#define CPP_EOF EOF
-#endif
-

- -

No `string::clear`

+Debug mode first appears. +

- There are two functions for deleting the contents of a string: - clear and erase (the latter - returns the string). -

-	void 
-	clear() { _M_mutate(0, this->size(), 0); }
-

-	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()); 
-	}
-

- Unfortunately, ut clear is not - implemented in this version, so you should use - erase (which is probably faster than - operator=(charT*)). -

- -

Removal of `ostream::form` and -`istream::scan` extensions.

- -

These are no longer supported. Please use - - stringstreams instead. -

- -

No `basic_stringbuf`, `basic_stringstream`


+PCH support.
+
 
 
-      Libstdc++ provides the new
-      i/ostringstream-classes, (<sstream>), but for compatibility
-      with older implementations you still have to use
-      i/ostrstream (<strstream>):
-      
-	#ifdef HAVE_SSTREAM
-	#include <sstream>
-	#else
-	#include <strstream>
-	#endif
-      
-      
- strstream is considered to be
-	    deprecated
-	  
- strstream is limited to
-	    char
-	  
- with ostringstream you don't
-	    have to take care of terminating the string or freeing its
-	    memory
-	  
- istringstream can be re-filled
-	    (clear(); str(input);)
-	  
-
-
-      You can then use output-stringstreams like this:
-      
-	#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
-      
-
-      Input-stringstreams can be used similarly:
-
-      
- 
-std::string input;
-...
-#ifdef HAVE_SSTREAM
-std::istringstream iss(input);
-#else
-std::istrstream iss(input.c_str());
-#endif
-
-int i;
-iss >> i; 
-
-
- One (the only?) restriction is that an istrstream cannot be re-filled:
-
-      
--std::istringstream iss(numerator);
-iss >> m_num;
-// this is not possible with istrstream
-iss.clear();
-iss.str(denominator);
-iss >> m_den;
- 
- 
-
-If you don't care about speed, you can put these conversions in
-      a template-function:
-      
--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;
-}
-
-
- Another example of using stringstreams is in this howto.
+Macro guard for libstdc++ changed, from _GLIBCPP_ to _GLIBCXX_.
 
 
- There is additional information in the libstdc++-v2 info files, in
-particular "info iostream".
+

+Extension <ext/stdio_sync_filebuf.h> added.
 
 
-Little or no wide character support
-
-No templatized iostreams
-
-Thread safety issues.
-
-This project is no longer maintained or supported, and the sources
-archived.  The code is considered replaced and rewritten.
+

+Extension <ext/demangle.h> added.
 
 
 
-
 
-  Third.
+  4.0
 
- The third generation GNU C++ library is called libstdc++, or
-libstdc++-v3.
+

+TR1 features first appear.
 
 
-      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.
-      
-
-      A more formal description of the V3 goals can be found in the
-         official design document.
-      
-
-
-Portability Notes
-
-Pre-ISO headers moved to backwards
- The pre-ISO C++ headers (iostream.h etc.) are available, but inclusion
-      generates a warning that you are using deprecated headers.    
+

+Extension allocator <ext/array_allocator.h> added.
 
 
-    This compatibility layer is constructed by including the
-    standard C++ headers, and injecting any items in
-    std:: into the global namespace.
-   
-   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 item
-      [27.4].
-   
-
- Some include adjustment may be required.
-
-Extension headers hash_map, hash_set moved to ext
+
+Extension codecvt specializations moved to <ext/codecvt_specializations.h>.
+
 
- Header files hash_map and hash_set
-moved to ext/hash_map and ext/hash_set,
-respectively. At the same time, all types in these files are enclosed
-in namespace __gnu_cxx.
+

+Removal of <ext/demangle.h>.
 
 
 
-
-No ios::nocreate/ios::noreplace.
-
+
+  4.1
+
 
- The existence of ios::nocreate 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.
+

+Removal of <cassert> from all standard headers: now has to be explicitly included for std::assert calls.
 
 
-For output streams, "nocreate" is probably the default,
-unless you specify std::ios::trunc ? 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 app, ate
-and trunc (except for app ?).
+
 Extensions for policy-based data structures first added. New includes,
+types, namespace pb_assoc.
 
 
 
-
-No stream::attach(int fd).
-
-
-
-      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.
-      
 
-
-      For a portable solution (among systems which use
-      filedescriptors), you need to implement a subclass of
-      std::streambuf (or
-      std::basic_streambuf<..>) which opens a file
-      given a descriptor, and then pass an instance of this to the
-      stream-constructor. 
-    
-
-
-      An extension is available that implements this.
-      <ext/stdio_filebuf.h> contains a derived class called
-      __gnu_cxx::stdio_filebuf.
-      This class can be constructed from a C FILE* or a file
-      descriptor, and provides the fd() function.
-    
-
-
- For another example of this, refer to
-      fdstream example 
-      by Nicolai Josuttis.
+
 Extensions for typelists added in <ext/typelist.h>.
 
 
-Known Issues
-
-
-container iterator types are not necessarily container value_type*
-
-
-API History, User Visible Changes
+ Extension for policy-based basic_string first added: __gnu_cxx::__versa_string in <ext/vstring.h>.
+
 
-3.0.0
+
+  4.2
+
 
+ Default visibility attributes applied to namespace std. Support for -fvisibility.
+
 
-3.1.0
-3.2.0
-3.3.0
+TR1 <random>, <complex>, and C compatibility headers added.
 
+ Extensions for concurrent programming consolidated
+into <ext/concurrence.h> and <ext/atomicity.h>,
+including change of namespace to __gnu_cxx in some
+cases. Added types
+include _Lock_policy, __concurrence_lock_error, __concurrence_unlock_error, __mutex, __scoped_lock.
 
-3.4.0
+ Extensions for type traits consolidated
+into <ext/type_traits.h>. Additional traits are added
+(__conditional_type, __enable_if, others.)
+
 
-Macro guard for libstdc++ changed, from _GLIBCPP_ to _GLIBCXX_, to
-accomodate a request from the C Pre Processor maintainer.
+ Extensions for policy-based data structures revised. New includes,
+types, namespace moved to __pb_ds.
+
 
-4.0.0
-4.1.0
+ Extensions for debug mode modified: now nested in namespace
+std::__debug and extensions in namespace
+__gnu_cxx::__debug.
 
- how has to be explicitly included for std::assert calls.
+ Extensions added: <ext/typelist.h>
+and <ext/throw_allocator.h>.
+
 
-4.2.0
+
+  4.3
+
 
-4.3.0
+
+C++0X features first appear.
+
 
-Header streamlining.
+TR1 <regex> and <cmath>'s mathematical special function added.
 
+
 Backward include edit.
+
+
+   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>
+  
+   Added: <hash_map> and <hash_set>
+   Added in C++0x: <auto_ptr.h> and <binders.h>
+
 
-PCH files built but not installed. 
-
-Namespace pb_ds moved to __gnu_pb_ds.
+
+Header dependency streamlining.
+
 
-C++OX features appear.
+
+  <algorithm> no longer includes <climits>, <cstring>, or <iosfwd> 
+  <bitset> no longer includes <istream> or <ostream>, adds <iosfwd> 
+  <functional> no longer includes <cstddef>
+  <iomanip> no longer includes <istream>, <istream>, or <functional>, adds <ioswd> 
+  <numeric> no longer includes <iterator>
+  <string> no longer includes <algorithm> or <memory>
+
+  <valarray> no longer includes <numeric> or <cstdlib>
+  <tr1/hashtable> no longer includes <memory> or <functional>
+  <tr1/memory> no longer includes <algorithm>
+  <tr1/random> no longer includes <algorithm> or <fstream>
+
 
-
-
-  Fourth, and future
-
+
+Debug mode for <unordered_map> and <unordered_set>.
+
 
-
-
-  Deprecation and Backwards Compatibility
-
+
+Parallel mode first appears.
+
 
-
-
-  Links
-
+Variadic template implementations of items in <tuple> and
+    <functional>. 
+
 
-
-Migrating to gcc-4.1, by Dan Kegel.
+
Default what implementations give more elaborate
+    exception strings for bad_cast,
+    bad_typeid, bad_exception, and
+    bad_alloc.
 
 
 
-Building the whole Debian archive with GCC 4.1: a summary, by Martin Michlmayr
+PCH binary files no longer installed. Instead, the source files are installed. 
 
 
 
-Migration guide for GCC-3.2
+Namespace pb_ds moved to __gnu_pb_ds.
 
 
 
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 @@
+
+
+
+
+
+   
+   
+   
+   
+   Backwards Compatibility
+
+
+
+
+
+
+Backwards Compatibility
+
+
+   The latest version of this document is always available at
+   
+   http://gcc.gnu.org/onlinedocs/libstdc++/17_intro/backwards_compatibility.html.
+
+
+
+   To the libstdc++ homepage.
+
+
+
+
+
+  First.
+
+
+ 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.
+
+
+Known Issues include many of the limitations of its immediate ancestor. 
+
+Portability notes and known implementation limitations are as follows.
+
+No ios_base
+
+ At least some older implementations don't have std::ios_base, so you should use std::ios::badbit, std::ios::failbit and std::ios::eofbit and std::ios::goodbit.
+
+
+No cout in ostream.h, no cin in istream.h
+
+
+	In earlier versions of the standard,
+	<fstream.h>,
+	<ostream.h>
+	and <istream.h>
+	used to define
+	cout, cin and so on. ISO C++ specifies that one needs to include
+	<iostream>
+	explicitly to get the required definitions.
+ 
+ Some include adjustment may be required.
+
+
+This project is no longer maintained or supported, and the sources
+archived.  The code is considered replaced and rewritten.
+
+
+
+
+  Second.
+
+ 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.
+
+
+ The STL portions of this library are based on SGI/HP STL release 3.11.
+
+
+Portability notes and known implementation limitations are as follows.
+
+Namespace std:: not supported
+
+
+      Some care is required to support C++ compiler and or library
+      implementation that do not have the standard library in
+      namespace std.
+    
+
+   The following sections list some possible solutions to support compilers
+   that cannot ignore std::-qualified names.
+ 
+
+ 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 std::, as
+      the compilers use -fno-honor-std (ignore
+      std::, :: = std::) by default. That
+      is, the responsibility for enabling or disabling
+      std:: is on the user; the maintainer does not have
+      to care about it. This probably applies to some other compilers
+      as well.
+    
+
+Second, experiment with a variety of pre-processor tricks.
+
+ By defining std as a macro, fully-qualified namespace calls become global. Volia. 
+	      
++#ifdef WICKEDLY_OLD_COMPILER
+# define std
+#endif
+
+(thanks to Juergen Heinzl who posted this solution on gnu.gcc.help)
+
+Another pre-processor based approach is to define a
+macro NAMESPACE_STD, 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 HAVE_NAMESPACE_STD, then using that to
+set a value for the NAMESPACE_STD macro.  At that point,
+one is able to use NAMESPACE_STD::string, which will
+evaluate to std::string or
+::string (ie, in the global namespace on systems that do
+not put string in std::). 
+
++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 
+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  
+                  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
+])
+
+
+Illegal iterator usage
+
+      The following illustrate implementation-allowed illegal iterator
+      use, and then correct use.  
+
+
+ you cannot do
+      ostream::operator<<(iterator) to print the
+      address of the iterator => use operator<<
+      &*iterator instead
+	  
+you cannot clear an iterator's reference
+	    (iterator = 0) => use
+	    iterator = iterator_type();
+	  
+
+if (iterator) won't work any
+	    more => use if (iterator != iterator_type())
+	    
+
+
+isspace from <cctype> is a macro
+
+
+ Glibc 2.0.x and 2.1.x define <ctype.h>
+functionality as macros (isspace, isalpha etc.).    
+
+
+
+This implementations of libstdc++, however, keep these functions as
+macros, and so it is not back-portable to use fully qualified
+names. For example:
+
+
+ 
+#include <cctype> 
+int main() { std::isspace('X'); } 
+ 
+
+Results in something like this:
+
+
+ 
+std:: (__ctype_b[(int) ( ( 'X' ) )] & (unsigned short int) _ISspace ) ; 
+
+
+
+ A solution is to modify a header-file so that the compiler tells
+<ctype.h> to define functions instead of macros:
+
+
++// This keeps isalnum, et al from being propagated as macros. 
+#if __linux__
+# define __NO_CTYPE 1
+#endif
+
+
+Then, include <ctype.h>
+
+
+
+Another problem arises if you put a using namespace std;
+declaration at the top, and include <ctype.h>. This
+will result in ambiguities between the definitions in the global
+namespace (<ctype.h>) and the definitions in namespace
+std:: (<cctype>).    
+
+
+No vector::at, deque::at, string::at
+
+
+      One solution is to add an autoconf-test for this:
+
++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)])
+
+
+
+If you are using other (non-GNU) compilers it might be a good idea
+to check for string::at separately.
+
+
+No std::char_traits<char>::eof
+
+
+Use some kind of autoconf test, plus this:
+      
+ 
+#ifdef HAVE_CHAR_TRAITS
+#define CPP_EOF std::char_traits<char>::eof()
+#else
+#define CPP_EOF EOF
+#endif
+
+
+No string::clear
+
+
+      There are two functions for deleting the contents of a string:
+      clear and erase (the latter
+      returns the string).
+
+      
++void 
+clear() { _M_mutate(0, this->size(), 0); }
+
++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()); 
+}
+
+
+
+      Unfortunately, ut clear is not
+      implemented in this version, so you should use
+      erase (which is probably faster than
+      operator=(charT*)).
+
+
+Removal of ostream::form and
+istream::scan extensions
+
+ These are no longer supported. Please use
+   
+    stringstreams instead.	
+
+
+No basic_stringbuf, basic_stringstream
+
+
+Although the ISO standard 
+i/ostringstream-classes are provided, (<sstream>), for compatibility with older implementations the pre-ISO i/ostrstream (<strstream>) interface is also provided, with these caveats:
+
+
+      
+ strstream is considered to be
+	    deprecated
+	  
+ strstream is limited to
+	    char
+	  
+ with ostringstream you don't
+	    have to take care of terminating the string or freeing its
+	    memory
+	  
+ istringstream can be re-filled
+	    (clear(); str(input);)
+	  
+
+
+      You can then use output-stringstreams like this:
+
+       
++#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
+
+
+
+      Input-stringstreams can be used similarly:
+
+      
+ 
+std::string input;
+...
+#ifdef HAVE_SSTREAM
+std::istringstream iss(input);
+#else
+std::istrstream iss(input.c_str());
+#endif
+
+int i;
+iss >> i; 
+
+
+ One (the only?) restriction is that an istrstream cannot be re-filled:
+
+      
++std::istringstream iss(numerator);
+iss >> m_num;
+// this is not possible with istrstream
+iss.clear();
+iss.str(denominator);
+iss >> m_den;
+ 
+ 
+
+If you don't care about speed, you can put these conversions in
+      a template-function:
+      
++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;
+}
+
+
+ Another example of using stringstreams is in this howto.
+
+
+ There is additional information in the libstdc++-v2 info files, in
+particular "info iostream".
+
+
+Little or no wide character support
+
+No templatized iostreams
+
+Thread safety issues
+
+This project is no longer maintained or supported, and the sources
+archived.  The code is considered replaced and rewritten.
+
+
+
+
+
+  Third.
+
+ The third generation GNU C++ library is called libstdc++, or
+libstdc++-v3.
+
+
+      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.
+      
+
+      A more formal description of the V3 goals can be found in the
+         official design document.
+      
+
+Portability notes and known implementation limitations are as follows.
+
+Pre-ISO headers moved to backwards or removed
+
+ The pre-ISO C++ headers
+      (iostream.h, defalloc.h etc.) are
+      available, unlike previous libstdc++ versions, but inclusion
+      generates a warning that you are using deprecated headers.
+
+
+    This compatibility layer is constructed by including the
+    standard C++ headers, and injecting any items in
+    std:: into the global namespace.
+   
+   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 item
+      [27.4].
+   
+
+ Some include adjustment may be required. What follows is an
+autoconf test that defines PRE_STDCXX_HEADERS when they
+exist.
+
++# 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
+])
+
+
+Porting between pre-ISO headers and ISO headers is simple: headers
+like <vector.h> can be replaced with <vector> and a using
+directive using namespace std; can be put at the global
+scope. This should be enough to get this code compiling, assuming the
+other usage is correct.
+
+
+Extension headers hash_map, hash_set moved to ext or backwards
+
+ Header files hash_map and hash_set moved
+to ext/hash_map and ext/hash_set,
+respectively. At the same time, all types in these files are enclosed
+in namespace __gnu_cxx. Later versions move deprecate
+these files, and suggest using TR1's unordered_map
+and unordered_set instead.
+
+
+The following autoconf tests check for working HP/SGI hash containers.
+
+
++# 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 ], [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
+])
+
+
++# 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 ], [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
+])
+
+
+
+
+No ios::nocreate/ios::noreplace.
+
+
+ The existence of ios::nocreate 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.
+
+
+For output streams, "nocreate" is probably the default,
+unless you specify std::ios::trunc ? 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 app, ate
+and trunc (except for app ?).
+
+
+
+
+No stream::attach(int fd)
+
+
+
+      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.
+      
+
+
+      For a portable solution (among systems which use
+      filedescriptors), you need to implement a subclass of
+      std::streambuf (or
+      std::basic_streambuf<..>) which opens a file
+      given a descriptor, and then pass an instance of this to the
+      stream-constructor. 
+    
+
+
+      An extension is available that implements this.
+      <ext/stdio_filebuf.h> contains a derived class called
+      __gnu_cxx::stdio_filebuf.
+      This class can be constructed from a C FILE* or a file
+      descriptor, and provides the fd() function.
+    
+
+
+ For another example of this, refer to
+      fdstream example 
+      by Nicolai Josuttis.
+
+
+
+Support for C++98 dialect.
+
+
+Check for complete library coverage of the C++1998/2003 standard.
+
+
++
+# 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
+])
+
+
+
+
+Support for C++TR1 dialect.
+
+
+Check for library coverage of the TR1 standard.
+
+
++
+# 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
+])
+
+
+An alternative is to check just for specific TR1 includes, such as <unordered_map> and <unordered_set>.
+
+
++# 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
+])
+
+
++# 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
+])
+
+
+
+
+
+Support for C++0x dialect.
+
+
+Check for baseline language coverage in the compiler for the C++0xstandard.
+
+
++# 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
+])
+
+
+
+Check for library coverage of the C++0xstandard.
+
+
++
+# 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
+])
+
+
+As is the case for TR1 support, these autoconf macros can be made for a finer-grained, per-header-file check. For <unordered_map>
+
+
++
+# 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
+])
+
+
++# 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
+])
+
+
+
+
+Container iterator_type is not necessarily container value_type*
+
+
+
+
+
+  Fourth, and future
+
+
+
+
+  Links
+
+
+
+Migrating to gcc-4.1, by Dan Kegel.
+
+
+
+Building the whole Debian archive with GCC 4.1: a summary, by Martin Michlmayr
+
+
+
+Migration guide for GCC-3.2
+
+
+
+
+
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 @@
 
 Contents
 
-   Header Files
-   Implementation specific behavior
+   Header Files
+   Namespaces
    Macros
-   Multithreading
+   Implementation specific behavior
+   Multithreading
 
 
 
 
 
 
-Header Files
-   The C++ standard specifies 50 header files that must be
+
Header Files
+   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 #include's a certain header, the
-      contents of that header, as defined by the Standard, become
+      only rule is that when one #include's a header, the
+      contents of that header become
       available, no matter how.
    
 
-C++98/03 include files:
+
That said, in practice files are used.
+
+ 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).
+
+Two dialects of standard headers are supported, corresponding to
+the 1998 standard as updated for 2003, and the draft of the upcoming
+200x standard.
+
+
+C++98/03 include files. These are available in the default compilation mode, ie -std=c++98 or -std=gnu++98. 
 
--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
-
 
-C++0x include files:
+

+
+
+
+
+
+
+
+C++98 Library Headers<algorithm> <iomanip> <list> <ostream> <streambuf>
<bitset> <ios> <locale> <queue> <string>
<complex> <iosfwd> <map> <set> <typeinfo>
<deque> <iostream> <memory> <sstream> <utility>
<exception> <istream> <new> <stack> <valarray>
<fstream> <iterator> <numeric> <stdexcept> <vector>
<functional> <limits>
+
+
+
+
+
+
+
+
+C++98 Headers for C Library Facilities<cassert> <ciso646> <csetjmp> <cstdio> <ctime>
<cctype> <climits> <csignal> <cstdlib> <cwchar>
<cerrno> <clocale> <cstdarg> <cstring> <cwctype>
<cfloat> <cmath> <cstddef>
+
+C++0x include files. These are only available in C++0x compilation mode, ie -std=c++0x or -std=gnu++0x. 
 
+
+
+
+
+
+
+
+
+
+
+C++0x Library Headers<algorithm> <iomanip> <locale> <regex> <tuple>
<array> <ios> <map> <set> <typeinfo>
<bitset> <iosfwd> <memory> <sstream> <type_traits>
<complex> <iostream> <new> <stack> <unordered_map>
<deque> <istream> <numeric> <stdexcept> <unordered_set>
<exception> <iterator> <ostream> <streambuf> <utility>
<fstream> <limits> <queue> <string> <valarray>
<functional> <list> <random> <system_error> <vector>
+
+
+
+
+
+
+
+
+
+C++0x Headers for C Library Facilities<cassert> <cfloat> <cmath> <cstddef> <ctgmath>
<ccomplex> <cinttypes> <csetjmp> <cstdint> <ctime>
<cctype> <ciso646> <csignal> <cstdio> <cuchar>
<cerrno> <climits> <cstdarg> <cstdlib> <cwchar>
<cfenv> <clocale> <cstdbool> <cstring> <cwctype>
+
+
+In addition, TR1 includes as:
+
+
+
+
+
+
+TR1 Library Headers<tr1/array> <tr1/memory> <tr1/regex> <tr1/type_traits> <tr1/unordered_set>
<tr1/complex> <tr1/random> <tr1/tuple> <tr1/unordered_map> <tr1/utility>
<tr1/functional>
+
+
+
+
+
+
+
+TR1 Headers for C Library Facilities<tr1/cmath> <tr1/cfloat> <tr1/cstdarg> <tr1/cstdio> <tr1/ctime>
<tr1/ccomplex> <tr1/cinttypes> <tr1/cstdbool> <tr1/cstdlib> <tr1/cwchar>
<tr1/cfenv> <tr1/climits> <tr1/cstdint> <tr1/ctgmath> <tr1/cwctype> 
+
+Also included are files for the C++ ABI interface:
+
+
+
+C++ ABI Headers<cxxabi.h> <cxxabi_forced.h>
+
+And a large variety of extensions.
+
+
+
+
+
+
+
+
+
+Extension Headers<ext/algorithm> <ext/debug_allocator.h> <ext/mt_allocator.h> <ext/pod_char_traits.h> <ext/stdio_sync_filebuf.h>
<ext/array_allocator.h> <ext/enc_filebuf.h> <ext/new_allocator.h> <ext/pool_allocator.h> <ext/throw_allocator.h>
<ext/atomicity.h> <ext/functional> <ext/numeric> <ext/rb_tree> <ext/typelist.h> 
<ext/bitmap_allocator.h> <ext/iterator> <ext/numeric_traits.h> <ext/rope> <ext/type_traits.h>
<ext/codecvt_specializations.h> <ext/malloc_allocator.h> <ext/pb_ds/assoc_container.h> <ext/slist> <ext/vstring.h>
<ext/concurrence.h> <ext/memory> <ext/pb_ds/priority_queue.h> <ext/stdio_filebuf.h>
+
+
+
+
+
+
+Extension Debug Headers<debug/bitset> <debug/list> <debug/set> <debug/unordered_map> <debug/vector>
<debug/deque> <debug/map> <debug/string> <debug/unordered_set>
+
+
+
+
+
+Extension Parallel Headers<parallel/algorithm> <parallel/numeric>
+
+
+Recipes for mixing headers
+
+ A few simple rules.
+
+
+First, mixing different dialects of the standard headers is not
+possible. It's an all-or-nothing affair. Thus, code like
+
+
 -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>
 
 
-In addition, TR1 includes as:
+
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.
+
+
+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 __gnu_cxx::vstring, or to use the
+debug-mode versions of std::unordered_map, one must use
+the std=gnu++0x compiler flag. (Or std=c++0x, of course.)
 
+
+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:
+
+
 -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>
 
 
+ Several parts of C++0x diverge quite substantially from TR1 predecessors.
+
+
+
 
-Headers and namespace std::
+The C Headers and namespace std
 
-	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
-	<math.h>, you
-	should use <cmath>. In some cases this has
-	the advantage that the C++-header is more standardized than
-	the C-header (i.e. <ctime> (almost)
-	corresponds to either <time.h> or <sys/time.h>).
-
-	The standard specifies that if you include the C-style header
-	(<math.h> in
-	this case), the symbols will be available both in the global
-	namespace and in namespace std:: (but
-	libstdc++ does not yet have fully compliant headers) On the
-	other hand, if you include only the new header (i.e. <cmath>), the symbols
-	will only be defined in namespace std::
-	(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 std:: (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.
       
 
-FIXME: this is no longer accurate.
-
 
-	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 
-	  www.cantrip.org.
-      
+Usage of C++-style headers is recommended, as then
+C-linkage names can be disambiguated by explicit qualification, such
+as by std::abort. 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 std::sin has overloads for all the builtin
+floating-point types. This means that std::sin can be
+used uniformly, instead of a combination
+of std::sinf, std::sin,
+and std::sinl.
+
+
+
+Precompiled Headers
+
+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.
+
+
+
+
+stdc++.h
+Includes all standard headers. Actual content varies depending on
+language dialect.
+
+
+
+stdtr1c++.h
+Includes all of <stdc++.h>, and adds all the TR1 headers.
+
+
+
+extc++.h
+Includes all of <stdtr1c++.h>, and adds all the Extension headers.
+
+
+
+How to construct a .gch file from one of these base header files.
+
+First, find the include directory for the compiler. One way to do
+this is:
+
++g++ -v hello.cc
+
+#include <...> search starts here:
+ /mnt/share/bld/H-x86-gcc.20071201/include/c++/4.3.0
+...
+End of search list.
+
+
+
+Then, create a precompiled header file with the same flags that
+will be used to compile other projects.
+
++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
+
+
+The resulting file will be quite large: the current size is around
+thirty megabytes. 
+
+How to use the resulting file.
+
++g++ -I. -include stdc++.h  -H -g -O2 hello.cc 
+
+
+Verification that the PCH file is being used is easy:
+
++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
+
+
+The exclamation point to the left of the stdc++.h.gch listing means that the generated PCH file was used, and thus the 
+
+
+ Detailed information about creating precompiled header files can be found in the GCC documentation.
+
+
 
 
-Namespace std::
+Namespaces
+
+
+ There are three main namespaces.
+
+
+
+std
+The ISO C++ standards specify that "all library entities are defined
+within namespace std." This includes namepaces nested
+within namespace std, such as namespace
+std::tr1.
+
+
+abi
+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.
+
+
+
+__gnu_
+Indicating one of several GNU extensions. Choices
+include __gnu_cxx, __gnu_debug, __gnu_parallel,
+and __gnu_pbds.
+
+
+
+ A complete list of implementation namespaces (including namespace contents) is available in the generated source documentation. 
+
+
+
+
+Namespace std::
 
 
       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 for each library symbol
 (i.e. std::string, std::cout) 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.)

<algorithm>	<iomanip>	<list>	<ostream>	<streambuf>
<bitset>	<ios>	<locale>	<queue>	<string>
<complex>	<iosfwd>	<map>	<set>	<typeinfo>
<deque>	<iostream>	<memory>	<sstream>	<utility>
<exception>	<istream>	<new>	<stack>	<valarray>
<fstream>	<iterator>	<numeric>	<stdexcept>	<vector>
<functional>	<limits>

<cassert>	<ciso646>	<csetjmp>	<cstdio>	<ctime>
<cctype>	<climits>	<csignal>	<cstdlib>	<cwchar>
<cerrno>	<clocale>	<cstdarg>	<cstring>	<cwctype>
<cfloat>	<cmath>	<cstddef>

<tr1/array>	<tr1/memory>	<tr1/regex>	<tr1/type_traits>	<tr1/unordered_set>
<tr1/complex>	<tr1/random>	<tr1/tuple>	<tr1/unordered_map>	<tr1/utility>
<tr1/functional>

<tr1/cmath>	<tr1/cfloat>	<tr1/cstdarg>	<tr1/cstdio>	<tr1/ctime>
<tr1/ccomplex>	<tr1/cinttypes>	<tr1/cstdbool>	<tr1/cstdlib>	<tr1/cwchar>
<tr1/cfenv>	<tr1/climits>	<tr1/cstdint>	<tr1/ctgmath>	<tr1/cwctype>

<ext/algorithm>	<ext/debug_allocator.h>	<ext/mt_allocator.h>	<ext/pod_char_traits.h>	<ext/stdio_sync_filebuf.h>
<ext/array_allocator.h>	<ext/enc_filebuf.h>	<ext/new_allocator.h>	<ext/pool_allocator.h>	<ext/throw_allocator.h>
<ext/atomicity.h>	<ext/functional>	<ext/numeric>	<ext/rb_tree>	<ext/typelist.h>
<ext/bitmap_allocator.h>	<ext/iterator>	<ext/numeric_traits.h>	<ext/rope>	<ext/type_traits.h>
<ext/codecvt_specializations.h>	<ext/malloc_allocator.h>	<ext/pb_ds/assoc_container.h>	<ext/slist>	<ext/vstring.h>
<ext/concurrence.h>	<ext/memory>	<ext/pb_ds/priority_queue.h>	<ext/stdio_filebuf.h>

<debug/bitset>	<debug/list>	<debug/set>	<debug/unordered_map>	<debug/vector>
<debug/deque>	<debug/map>	<debug/string>	<debug/unordered_set>

- First. + API Evolution, Deprecation, and History of User Visible Changes

+ 3.0 +

No ios_base

No cout in ostream.h, no cin in istream.h

- Second. + 3.1

Namespace std:: not supported.

Illegal iterator usage.

isspace from <cctype> is a macro -

+ 3.2 +

+ 3.3 +

+ 3.4 +

No vector::at, deque::at, string::at

No std::char_traits<char>::eof

No string::clear

Removal of ostream::form and -istream::scan extensions.

No basic_stringbuf, basic_stringstream

Little or no wide character support

No templatized iostreams

Thread safety issues.

- Third. + 4.0

Pre-ISO headers moved to backwards

Extension headers hash_map, hash_set moved to ext

-No ios::nocreate/ios::noreplace. -

+ 4.1 +

-No stream::attach(int fd). -

-container iterator types are not necessarily container value_type* -

+ 4.2 +

+ 4.3 +

- Fourth, and future -

- Deprecation and Backwards Compatibility -

- Links -

+ First. +

No ios_base

No cout in ostream.h, no cin in istream.h

+ Second. +

Namespace std:: not supported

Illegal iterator usage

isspace from <cctype> is a macro +

No vector::at, deque::at, string::at

No std::char_traits<char>::eof

No string::clear

Removal of ostream::form and +istream::scan extensions

No basic_stringbuf, basic_stringstream

Little or no wide character support

No templatized iostreams

Thread safety issues

+ Third. +

Pre-ISO headers moved to backwards or removed

Extension headers hash_map, hash_set moved to ext or backwards

+No ios::nocreate/ios::noreplace. +

+No stream::attach(int fd) +

+Support for C++98 dialect. +

+Support for C++TR1 dialect. +

+Support for C++0x dialect. +

+Container iterator_type is not necessarily container value_type* +

+ Fourth, and future +

+ Links +

Contents

+ Atomics Interface +

+ Pthread Interface +

+ Concurrence Interface +

+ Details on builtin atomic support and library fallbacks +

No `ios_base`

No `cout` in `ostream.h`, no `cin` in `istream.h`

Namespace `std::` not supported.

`isspace` from `<cctype>` is a macro -

No `vector::at`, `deque::at`, `string::at`

No `std::char_traits<char>::eof`

No `string::clear`

Removal of `ostream::form` and -`istream::scan` extensions.

No `basic_stringbuf`, `basic_stringstream`

-No `ios::nocreate/ios::noreplace`. -

-No `stream::attach(int fd)`. -

No `ios_base`

No `cout` in `ostream.h`, no `cin` in `istream.h`

Namespace `std::` not supported

`isspace` from `<cctype>` is a macro +

No `vector::at`, `deque::at`, `string::at`

No `std::char_traits<char>::eof`

No `string::clear`

Removal of `ostream::form` and +`istream::scan` extensions

No `basic_stringbuf`, `basic_stringstream`

+No `ios::nocreate/ios::noreplace`. +

+No `stream::attach(int fd)` +