gcc/libstdc++-v3/doc/html/manual/backwards.html
Benjamin Kosnik 49d60f14c0 authors.xml: Update.
2009-10-14  Benjamin Kosnik  <bkoz@redhat.com>

	* doc/xml/authors.xml: Update.
	* doc/xml/manual/intro.xml: Move test section...
	* doc/xml/manual/appendix_porting.xml: ...here.
	* doc/xml/manual/diagnostics.xml: Edit.
	* doc/xml/manual/using.xml: Break out exception section.
	* doc/xml/manual/using_exceptions.xml: New.
	* doc/html: Regenerate.

From-SVN: r152797
2009-10-15 02:51:30 +00:00

933 lines
42 KiB
HTML
Raw Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!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"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Backwards Compatibility</title><meta name="generator" content="DocBook XSL Stylesheets V1.74.3" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; backwards&#10; " /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="appendix_porting.html" title="Appendix B.  Porting and Maintenance" /><link rel="prev" href="api.html" title="API Evolution and Deprecation History" /><link rel="next" href="appendix_free.html" title="Appendix C.  Free Software Needs Free Documentation" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Backwards Compatibility</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="api.html">Prev</a> </td><th width="60%" align="center">Appendix B. 
Porting and Maintenance
</th><td width="20%" align="right"> <a accesskey="n" href="appendix_free.html">Next</a></td></tr></table><hr /></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="manual.appendix.porting.backwards"></a>Backwards Compatibility</h2></div></div></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="backwards.first"></a>First</h3></div></div></div><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>Some background: libg++ was designed and created when there was no
ISO standard to provide guidance. Classes like linked lists are now
provided for by <code class="classname">list&lt;T&gt;</code> and do not need to be
created by <code class="function">genclass</code>. (For that matter, templates exist
now and are well-supported, whereas genclass (mostly) predates them.)
</p><p>There are other classes in libg++ that are not specified in the
ISO Standard (e.g., statistical analysis). While there are a lot of
really useful things that are used by a lot of people, the Standards
Committee couldn't include everything, and so a lot of those
<span class="quote">obvious</span>” classes didn't get included.
</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><div class="sect3" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="id744149"></a>No <code class="code">ios_base</code></h4></div></div></div><p> At least some older implementations don't have <code class="code">std::ios_base</code>, so you should use <code class="code">std::ios::badbit</code>, <code class="code">std::ios::failbit</code> and <code class="code">std::ios::eofbit</code> and <code class="code">std::ios::goodbit</code>.
</p></div><div class="sect3" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="id744181"></a>No <code class="code">cout</code> in <code class="code">ostream.h</code>, no <code class="code">cin</code> in <code class="code">istream.h</code></h4></div></div></div><p>
In earlier versions of the standard,
<code class="filename">fstream.h</code>,
<code class="filename">ostream.h</code>
and <code class="filename">istream.h</code>
used to define
<code class="code">cout</code>, <code class="code">cin</code> and so on. ISO C++ specifies that one needs to include
<code class="filename">iostream</code>
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. For the desperate,
the <a class="ulink" href="http://gcc.gnu.org/extensions.html" target="_top">GCC extensions
page</a> describes where to find the last libg++ source. The code is
considered replaced and rewritten.
</p></div></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="backwards.second"></a>Second</h3></div></div></div><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>
This project is no longer maintained or supported, and the sources
archived. The code is considered replaced and rewritten.
</p><p>
Portability notes and known implementation limitations are as follows.
</p><div class="sect3" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="id744279"></a>Namespace <code class="code">std::</code> not supported</h4></div></div></div><p>
Some care is required to support C++ compiler and or library
implementation that do not have the standard library in
<code class="code">namespace std</code>.
</p><p>
The following sections list some possible solutions to support compilers
that cannot ignore <code class="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 class="code">std::</code>, as the
compilers use <code class="code">-fno-honor-std</code> (ignore
<code class="code">std::</code>, <code class="code">:: = std::</code>) by default. That is,
the responsibility for enabling or disabling <code class="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 class="code">std</code> as a macro, fully-qualified namespace
calls become global. Volia.
</p><pre class="programlisting">
#ifdef WICKEDLY_OLD_COMPILER
# define std
#endif
</pre><p>
Thanks to Juergen Heinzl who posted this solution on gnu.gcc.help.
</p><p>
Another pre-processor based approach is to define a macro
<code class="code">NAMESPACE_STD</code>, which is defined to either
<span class="quote"> </span>” or “<span class="quote">std</span>” 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 class="code">HAVE_NAMESPACE_STD</code>,
then using that to set a value for the <code class="code">NAMESPACE_STD</code>
macro. At that point, one is able to use
<code class="code">NAMESPACE_STD::string</code>, which will evaluate to
<code class="code">std::string</code> or <code class="code">::string</code> (i.e., in the
global namespace on systems that do not put <code class="code">string</code> in
<code class="code">std::</code>).
</p><pre class="programlisting">
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 &lt;luc@spaceroots.org&gt;
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 &lt;iostream&gt;
std::istream&amp; 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></div><div class="sect3" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="id673182"></a>Illegal iterator usage</h4></div></div></div><p>
The following illustrate implementation-allowed illegal iterator
use, and then correct use.
</p><div class="itemizedlist"><ul type="disc"><li><p>
you cannot do <code class="code">ostream::operator&lt;&lt;(iterator)</code>
to print the address of the iterator =&gt; use
<code class="code">operator&lt;&lt; &amp;*iterator</code> instead
</p></li><li><p>
you cannot clear an iterator's reference (<code class="code">iterator =
0</code>) =&gt; use <code class="code">iterator = iterator_type();</code>
</p></li><li><p>
<code class="code">if (iterator)</code> won't work any more =&gt; use
<code class="code">if (iterator != iterator_type())</code>
</p></li></ul></div></div><div class="sect3" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="id673243"></a><code class="code">isspace</code> from <code class="filename">cctype</code> is a macro
</h4></div></div></div><p>
Glibc 2.0.x and 2.1.x define <code class="filename">ctype.h</code> 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 class="programlisting">
#include &lt;cctype&gt;
int main() { std::isspace('X'); }
</pre><p>
Results in something like this:
</p><pre class="programlisting">
std:: (__ctype_b[(int) ( ( 'X' ) )] &amp; (unsigned short int) _ISspace ) ;
</pre><p>
A solution is to modify a header-file so that the compiler tells
<code class="filename">ctype.h</code> to define functions
instead of macros:
</p><pre class="programlisting">
// This keeps isalnum, et al from being propagated as macros.
#if __linux__
# define __NO_CTYPE 1
#endif
</pre><p>
Then, include <code class="filename">ctype.h</code>
</p><p>
Another problem arises if you put a <code class="code">using namespace
std;</code> declaration at the top, and include <code class="filename">ctype.h</code>. This will result in
ambiguities between the definitions in the global namespace
(<code class="filename">ctype.h</code>) and the
definitions in namespace <code class="code">std::</code>
(<code class="code">&lt;cctype&gt;</code>).
</p></div><div class="sect3" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="id586519"></a>No <code class="code">vector::at</code>, <code class="code">deque::at</code>, <code class="code">string::at</code></h4></div></div></div><p>
One solution is to add an autoconf-test for this:
</p><pre class="programlisting">
AC_MSG_CHECKING(for container::at)
AC_TRY_COMPILE(
[
#include &lt;vector&gt;
#include &lt;deque&gt;
#include &lt;string&gt;
using namespace std;
],
[
deque&lt;int&gt; test_deque(3);
test_deque.at(2);
vector&lt;int&gt; test_vector(2);
test_vector.at(1);
string test_string(“<span class="quote">test_string</span>”);
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 class="code">string::at</code> separately.
</p></div><div class="sect3" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="id586557"></a>No <code class="code">std::char_traits&lt;char&gt;::eof</code></h4></div></div></div><p>
Use some kind of autoconf test, plus this:
</p><pre class="programlisting">
#ifdef HAVE_CHAR_TRAITS
#define CPP_EOF std::char_traits&lt;char&gt;::eof()
#else
#define CPP_EOF EOF
#endif
</pre></div><div class="sect3" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="id586575"></a>No <code class="code">string::clear</code></h4></div></div></div><p>
There are two functions for deleting the contents of a string:
<code class="code">clear</code> and <code class="code">erase</code> (the latter returns the
string).
</p><pre class="programlisting">
void
clear() { _M_mutate(0, this-&gt;size(), 0); }
</pre><pre class="programlisting">
basic_string&amp;
erase(size_type __pos = 0, size_type __n = npos)
{
return this-&gt;replace(_M_check(__pos), _M_fold(__pos, __n),
_M_data(), _M_data());
}
</pre><p>
Unfortunately, <code class="code">clear</code> is not implemented in this
version, so you should use <code class="code">erase</code> (which is probably
faster than <code class="code">operator=(charT*)</code>).
</p></div><div class="sect3" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="id586620"></a>
Removal of <code class="code">ostream::form</code> and <code class="code">istream::scan</code>
extensions
</h4></div></div></div><p>
These are no longer supported. Please use stringstreams instead.
</p></div><div class="sect3" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="id586640"></a>No <code class="code">basic_stringbuf</code>, <code class="code">basic_stringstream</code></h4></div></div></div><p>
Although the ISO standard <code class="code">i/ostringstream</code>-classes are
provided, (<code class="filename">sstream</code>), for
compatibility with older implementations the pre-ISO
<code class="code">i/ostrstream</code> (<code class="filename">strstream</code>) interface is also provided,
with these caveats:
</p><div class="itemizedlist"><ul type="disc"><li><p>
<code class="code">strstream</code> is considered to be deprecated
</p></li><li><p>
<code class="code">strstream</code> is limited to <code class="code">char</code>
</p></li><li><p>
with <code class="code">ostringstream</code> you don't have to take care of
terminating the string or freeing its memory
</p></li><li><p>
<code class="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 class="programlisting">
#ifdef HAVE_SSTREAM
# include &lt;sstream&gt;
#else
# include &lt;strstream&gt;
#endif
#ifdef HAVE_SSTREAM
std::ostringstream oss;
#else
std::ostrstream oss;
#endif
oss &lt;&lt;<span class="quote">Name=</span>&lt;&lt; m_name &lt;&lt;<span class="quote">, number=</span>&lt;&lt; m_number &lt;&lt; std::endl;
...
#ifndef HAVE_SSTREAM
oss &lt;&lt; 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 class="programlisting">
std::string input;
...
#ifdef HAVE_SSTREAM
std::istringstream iss(input);
#else
std::istrstream iss(input.c_str());
#endif
int i;
iss &gt;&gt; i;
</pre><p> One (the only?) restriction is that an istrstream cannot be re-filled:
</p><pre class="programlisting">
std::istringstream iss(numerator);
iss &gt;&gt; m_num;
// this is not possible with istrstream
iss.clear();
iss.str(denominator);
iss &gt;&gt; m_den;
</pre><p>
If you don't care about speed, you can put these conversions in
a template-function:
</p><pre class="programlisting">
template &lt;class X&gt;
void fromString(const string&amp; input, X&amp; any)
{
#ifdef HAVE_SSTREAM
std::istringstream iss(input);
#else
std::istrstream iss(input.c_str());
#endif
X temp;
iss &gt;&gt; temp;
if (iss.fail())
throw runtime_error(..)
any = temp;
}
</pre><p>
Another example of using stringstreams is in <a class="link" href="bk01pt05ch13s05.html" title="Shrink to Fit">this howto</a>.
</p><p> There is additional information in the libstdc++-v2 info files, in
particular “<span class="quote">info iostream</span>”.
</p></div><div class="sect3" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="id659623"></a>Little or no wide character support</h4></div></div></div><p>
Classes <code class="classname">wstring</code> and
<code class="classname">char_traits&lt;wchar_t&gt;</code> are
not supported.
</p></div><div class="sect3" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="id659642"></a>No templatized iostreams</h4></div></div></div><p>
Classes <code class="classname">wfilebuf</code> and
<code class="classname">wstringstream</code> are not supported.
</p></div><div class="sect3" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="id659661"></a>Thread safety issues</h4></div></div></div><p>
Earlier GCC releases had a somewhat different approach to
threading configuration and proper compilation. Before GCC 3.0,
configuration of the threading model was dictated by compiler
command-line options and macros (both of which were somewhat
thread-implementation and port-specific). There were no
guarantees related to being able to link code compiled with one
set of options and macro setting with another set.
</p><p>
For GCC 3.0, configuration of the threading model used with
libraries and user-code is performed when GCC is configured and
built using the --enable-threads and --disable-threads options.
The ABI is stable for symbol name-mangling and limited functional
compatibility exists between code compiled under different
threading models.
</p><p>
The libstdc++ library has been designed so that it can be used in
multithreaded applications (with libstdc++-v2 this was only true
of the STL parts.) The first problem is finding a
<span class="emphasis"><em>fast</em></span> method of implementation portable to
all platforms. Due to historical reasons, some of the library is
written against per-CPU-architecture spinlocks and other parts
against the gthr.h abstraction layer which is provided by gcc. A
minor problem that pops up every so often is different
interpretations of what "thread-safe" means for a
library (not a general program). We currently use the <a class="ulink" href="http://www.sgi.com/tech/stl/thread_safety.html" target="_top">same
definition that SGI</a> uses for their STL subset. However,
the exception for read-only containers only applies to the STL
components. This definition is widely-used and something similar
will be used in the next version of the C++ standard library.
</p><p>
Here is a small link farm to threads (no pun) in the mail
archives that discuss the threading problem. Each link is to the
first relevant message in the thread; from there you can use
"Thread Next" to move down the thread. This farm is in
latest-to-oldest order.
</p><div class="itemizedlist"><ul type="disc"><li><p>
Our threading expert Loren gives a breakdown of <a class="ulink" href="http://gcc.gnu.org/ml/libstdc++/2001-10/msg00024.html" target="_top">the
six situations involving threads</a> for the 3.0
release series.
</p></li><li><p>
<a class="ulink" href="http://gcc.gnu.org/ml/libstdc++/2001-05/msg00384.html" target="_top">
This message</a> inspired a recent updating of issues with
threading and the SGI STL library. It also contains some
example POSIX-multithreaded STL code.
</p></li></ul></div><p>
(A large selection of links to older messages has been removed;
many of the messages from 1999 were lost in a disk crash, and the
few people with access to the backup tapes have been too swamped
with work to restore them. Many of the points have been
superseded anyhow.)
</p></div></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="backwards.third"></a>Third</h3></div></div></div><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 class="link" href="source_design_notes.html" title="Design Notes">design document</a>.
</p><p>Portability notes and known implementation limitations are as follows.</p><div class="sect3" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="id659778"></a>Pre-ISO headers moved to backwards or removed</h4></div></div></div><p> The pre-ISO C++ headers
(<code class="code">iostream.h</code>, <code class="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 class="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 class="ulink" href="http://www.parashift.com/c++-faq-lite/coding-standards.html#faq-27.4" target="_top">item
[27.4]</a>.
</p><p> Some include adjustment may be required. What follows is an
autoconf test that defines <code class="code">PRE_STDCXX_HEADERS</code> when they
exist.</p><pre class="programlisting">
# 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 &lt;new.h&gt;
#include &lt;iterator.h&gt;
#include &lt;alloc.h&gt;
#include &lt;set.h&gt;
#include &lt;hashtable.h&gt;
#include &lt;hash_set.h&gt;
#include &lt;fstream.h&gt;
#include &lt;tempbuf.h&gt;
#include &lt;istream.h&gt;
#include &lt;bvector.h&gt;
#include &lt;stack.h&gt;
#include &lt;rope.h&gt;
#include &lt;complex.h&gt;
#include &lt;ostream.h&gt;
#include &lt;heap.h&gt;
#include &lt;iostream.h&gt;
#include &lt;function.h&gt;
#include &lt;multimap.h&gt;
#include &lt;pair.h&gt;
#include &lt;stream.h&gt;
#include &lt;iomanip.h&gt;
#include &lt;slist.h&gt;
#include &lt;tree.h&gt;
#include &lt;vector.h&gt;
#include &lt;deque.h&gt;
#include &lt;multiset.h&gt;
#include &lt;list.h&gt;
#include &lt;map.h&gt;
#include &lt;algobase.h&gt;
#include &lt;hash_map.h&gt;
#include &lt;algo.h&gt;
#include &lt;queue.h&gt;
#include &lt;streambuf.h&gt;
],,
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 <code class="filename">vector.h</code> can be replaced with <code class="filename">vector</code> and a using
directive <code class="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></div><div class="sect3" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="id674389"></a>Extension headers hash_map, hash_set moved to ext or backwards</h4></div></div></div><p>At this time most of the features of the SGI STL extension have been
replaced by standardized libraries.
In particular, the unordered_map and unordered_set containers of TR1
are suitable replacement for the non-standard hash_map and hash_set
containers in the SGI STL.
</p><p> Header files <code class="filename">hash_map</code> and <code class="filename">hash_set</code> moved
to <code class="filename">ext/hash_map</code> and <code class="filename">ext/hash_set</code>,
respectively. At the same time, all types in these files are enclosed
in <code class="code">namespace __gnu_cxx</code>. Later versions move deprecate
these files, and suggest using TR1's <code class="filename">unordered_map</code>
and <code class="filename">unordered_set</code> instead.
</p><p>The extensions are no longer in the global or <code class="code">std</code>
namespaces, instead they are declared in the <code class="code">__gnu_cxx</code>
namespace. For maximum portability, consider defining a namespace
alias to use to talk about extensions, e.g.:
</p><pre class="programlisting">
#ifdef __GNUC__
#if __GNUC__ &lt; 3
#include &lt;hash_map.h&gt;
namespace extension { using ::hash_map; }; // inherit globals
#else
#include &lt;backward/hash_map&gt;
#if __GNUC__ == 3 &amp;&amp; __GNUC_MINOR__ == 0
namespace extension = std; // GCC 3.0
#else
namespace extension = ::__gnu_cxx; // GCC 3.1 and later
#endif
#endif
#else // ... there are other compilers, right?
namespace extension = std;
#endif
extension::hash_map&lt;int,int&gt; my_map;
</pre><p>This is a bit cleaner than defining typedefs for all the
instantiations you might need.
</p><p>The following autoconf tests check for working HP/SGI hash containers.
</p><pre class="programlisting">
# 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 &lt;ext/hash_map&gt;], [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 class="programlisting">
# 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 &lt;ext/hash_set&gt;], [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></div><div class="sect3" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="id674492"></a>No <code class="code">ios::nocreate/ios::noreplace</code>.
</h4></div></div></div><p> The existence of <code class="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, “<span class="quote">nocreate</span>” is probably the default,
unless you specify <code class="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 class="code">app</code>, <code class="code">ate</code>
and <code class="code">trunc</code> (except for <code class="code">app</code> ?).
</p></div><div class="sect3" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="id674539"></a>
No <code class="code">stream::attach(int fd)</code>
</h4></div></div></div><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
file descriptors), you need to implement a subclass of
<code class="code">std::streambuf</code> (or
<code class="code">std::basic_streambuf&lt;..&gt;</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 class="filename">ext/stdio_filebuf.h</code> contains a derived class called
<a class="ulink" href="http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/a00063.html" target="_top"><code class="code">__gnu_cxx::stdio_filebuf</code></a>.
This class can be constructed from a C <code class="code">FILE*</code> or a file
descriptor, and provides the <code class="code">fd()</code> function.
</p><p>
For another example of this, refer to
<a class="ulink" href="http://www.josuttis.com/cppcode/fdstream.html" target="_top">fdstream example</a>
by Nicolai Josuttis.
</p></div><div class="sect3" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="id674603"></a>
Support for C++98 dialect.
</h4></div></div></div><p>Check for complete library coverage of the C++1998/2003 standard.
</p><pre class="programlisting">
# 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 &lt;cassert&gt;
#include &lt;cctype&gt;
#include &lt;cerrno&gt;
#include &lt;cfloat&gt;
#include &lt;ciso646&gt;
#include &lt;climits&gt;
#include &lt;clocale&gt;
#include &lt;cmath&gt;
#include &lt;csetjmp&gt;
#include &lt;csignal&gt;
#include &lt;cstdarg&gt;
#include &lt;cstddef&gt;
#include &lt;cstdio&gt;
#include &lt;cstdlib&gt;
#include &lt;cstring&gt;
#include &lt;ctime&gt;
#include &lt;algorithm&gt;
#include &lt;bitset&gt;
#include &lt;complex&gt;
#include &lt;deque&gt;
#include &lt;exception&gt;
#include &lt;fstream&gt;
#include &lt;functional&gt;
#include &lt;iomanip&gt;
#include &lt;ios&gt;
#include &lt;iosfwd&gt;
#include &lt;iostream&gt;
#include &lt;istream&gt;
#include &lt;iterator&gt;
#include &lt;limits&gt;
#include &lt;list&gt;
#include &lt;locale&gt;
#include &lt;map&gt;
#include &lt;memory&gt;
#include &lt;new&gt;
#include &lt;numeric&gt;
#include &lt;ostream&gt;
#include &lt;queue&gt;
#include &lt;set&gt;
#include &lt;sstream&gt;
#include &lt;stack&gt;
#include &lt;stdexcept&gt;
#include &lt;streambuf&gt;
#include &lt;string&gt;
#include &lt;typeinfo&gt;
#include &lt;utility&gt;
#include &lt;valarray&gt;
#include &lt;vector&gt;
],,
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></div><div class="sect3" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="id674631"></a>
Support for C++TR1 dialect.
</h4></div></div></div><p>Check for library coverage of the TR1 standard.
</p><pre class="programlisting">
# 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 &lt;tr1/array&gt;
#include &lt;tr1/ccomplex&gt;
#include &lt;tr1/cctype&gt;
#include &lt;tr1/cfenv&gt;
#include &lt;tr1/cfloat&gt;
#include &lt;tr1/cinttypes&gt;
#include &lt;tr1/climits&gt;
#include &lt;tr1/cmath&gt;
#include &lt;tr1/complex&gt;
#include &lt;tr1/cstdarg&gt;
#include &lt;tr1/cstdbool&gt;
#include &lt;tr1/cstdint&gt;
#include &lt;tr1/cstdio&gt;
#include &lt;tr1/cstdlib&gt;
#include &lt;tr1/ctgmath&gt;
#include &lt;tr1/ctime&gt;
#include &lt;tr1/cwchar&gt;
#include &lt;tr1/cwctype&gt;
#include &lt;tr1/functional&gt;
#include &lt;tr1/memory&gt;
#include &lt;tr1/random&gt;
#include &lt;tr1/regex&gt;
#include &lt;tr1/tuple&gt;
#include &lt;tr1/type_traits&gt;
#include &lt;tr1/unordered_set&gt;
#include &lt;tr1/unordered_map&gt;
#include &lt;tr1/utility&gt;
],,
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 &lt;unordered_map&gt; and &lt;unordered_set&gt;.
</p><pre class="programlisting">
# 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 &lt;tr1/unordered_map&gt;], [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 class="programlisting">
# 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 &lt;tr1/unordered_set&gt;], [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></div><div class="sect3" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="id675096"></a>
Support for C++0x dialect.
</h4></div></div></div><p>Check for baseline language coverage in the compiler for the C++0xstandard.
</p><pre class="programlisting">
# 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 &lt;typename T&gt;
struct check
{
static_assert(sizeof(int) &lt;= sizeof(T), "not big enough");
};
typedef check&lt;check&lt;bool&gt;&gt; right_angle_brackets;
int a;
decltype(a) b;
typedef check&lt;int&gt; check_type;
check_type c;
check_type&amp;&amp; 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 &lt;typename T&gt;
struct check
{
static_assert(sizeof(int) &lt;= sizeof(T), "not big enough");
};
typedef check&lt;check&lt;bool&gt;&gt; right_angle_brackets;
int a;
decltype(a) b;
typedef check&lt;int&gt; check_type;
check_type c;
check_type&amp;&amp; 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 &lt;typename T&gt;
struct check
{
static_assert(sizeof(int) &lt;= sizeof(T), "not big enough");
};
typedef check&lt;check&lt;bool&gt;&gt; right_angle_brackets;
int a;
decltype(a) b;
typedef check&lt;int&gt; check_type;
check_type c;
check_type&amp;&amp; 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 class="programlisting">
# 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 &lt;cassert&gt;
#include &lt;ccomplex&gt;
#include &lt;cctype&gt;
#include &lt;cerrno&gt;
#include &lt;cfenv&gt;
#include &lt;cfloat&gt;
#include &lt;cinttypes&gt;
#include &lt;ciso646&gt;
#include &lt;climits&gt;
#include &lt;clocale&gt;
#include &lt;cmath&gt;
#include &lt;csetjmp&gt;
#include &lt;csignal&gt;
#include &lt;cstdarg&gt;
#include &lt;cstdbool&gt;
#include &lt;cstddef&gt;
#include &lt;cstdint&gt;
#include &lt;cstdio&gt;
#include &lt;cstdlib&gt;
#include &lt;cstring&gt;
#include &lt;ctgmath&gt;
#include &lt;ctime&gt;
#include &lt;cwchar&gt;
#include &lt;cwctype&gt;
#include &lt;algorithm&gt;
#include &lt;array&gt;
#include &lt;bitset&gt;
#include &lt;complex&gt;
#include &lt;deque&gt;
#include &lt;exception&gt;
#include &lt;fstream&gt;
#include &lt;functional&gt;
#include &lt;iomanip&gt;
#include &lt;ios&gt;
#include &lt;iosfwd&gt;
#include &lt;iostream&gt;
#include &lt;istream&gt;
#include &lt;iterator&gt;
#include &lt;limits&gt;
#include &lt;list&gt;
#include &lt;locale&gt;
#include &lt;map&gt;
#include &lt;memory&gt;
#include &lt;new&gt;
#include &lt;numeric&gt;
#include &lt;ostream&gt;
#include &lt;queue&gt;
#include &lt;random&gt;
#include &lt;regex&gt;
#include &lt;set&gt;
#include &lt;sstream&gt;
#include &lt;stack&gt;
#include &lt;stdexcept&gt;
#include &lt;streambuf&gt;
#include &lt;string&gt;
#include &lt;tuple&gt;
#include &lt;typeinfo&gt;
#include &lt;type_traits&gt;
#include &lt;unordered_map&gt;
#include &lt;unordered_set&gt;
#include &lt;utility&gt;
#include &lt;valarray&gt;
#include &lt;vector&gt;
],,
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 &lt;unordered_map&gt;
</p><pre class="programlisting">
# 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 &lt;unordered_map&gt;], [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 class="programlisting">
# 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 &lt;unordered_set&gt;], [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></div><div class="sect3" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="id675173"></a>
Container::iterator_type is not necessarily Container::value_type*
</h4></div></div></div><p>
This is a change in behavior from the previous version. Now, most
<span class="type">iterator_type</span> typedefs in container classes are POD
objects, not <span class="type">value_type</span> pointers.
</p></div></div><div class="bibliography"><div class="titlepage"><div><div><h3 class="title"><a id="backwards.biblio"></a>Bibliography</h3></div></div></div><div class="biblioentry"><a id="id675202"></a><p>[<abbr class="abbrev">
kegel41
</abbr>] <span class="title"><i>
Migrating to GCC 4.1
</i>. </span><span class="author"><span class="firstname">Dan</span> <span class="surname">Kegel</span>. </span><span class="biblioid">
<a class="ulink" href="http://www.kegel.com/gcc/gcc4.html" target="_top">
</a>
. </span></p></div><div class="biblioentry"><a id="id675235"></a><p>[<abbr class="abbrev">
kegel41
</abbr>] <span class="title"><i>
Building the Whole Debian Archive with GCC 4.1: A Summary
</i>. </span><span class="author"><span class="firstname">Martin</span> <span class="surname">Michlmayr</span>. </span><span class="biblioid">
<a class="ulink" href="http://lists.debian.org/debian-gcc/2006/03/msg00405.html" target="_top">
</a>
. </span></p></div><div class="biblioentry"><a id="id675268"></a><p>[<abbr class="abbrev">
lbl32
</abbr>] <span class="title"><i>
Migration guide for GCC-3.2
</i>. </span><span class="biblioid">
<a class="ulink" href="http://annwm.lbl.gov/~leggett/Atlas/gcc-3.2.html" target="_top">
</a>
. </span></p></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="api.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="appendix_porting.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="appendix_free.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">API Evolution and Deprecation History </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Appendix C. 
Free Software Needs Free Documentation
</td></tr></table></div></body></html>