diff options
| author | Felix Natter <fnatter@gmx.net> | 2000-08-07 19:29:19 +0000 |
|---|---|---|
| committer | Phil Edwards <pme@gcc.gnu.org> | 2000-08-07 19:29:19 +0000 |
| commit | 320f95489d1a822d0b67fa63aa5691d70cd3ae0d (patch) | |
| tree | 8087e1fc7b8fd94118772322cff24d8bfc1f2ee9 | |
| parent | 10120687102bd8cff1cfb26bb904b6246f36f4df (diff) | |
| download | gcc-320f95489d1a822d0b67fa63aa5691d70cd3ae0d.zip gcc-320f95489d1a822d0b67fa63aa5691d70cd3ae0d.tar.gz gcc-320f95489d1a822d0b67fa63aa5691d70cd3ae0d.tar.bz2 | |
porting-howto.html: New version.
2000-08-07 Felix Natter <fnatter@gmx.net>
* docs/17_intro/porting-howto.html: New version.
From-SVN: r35555
| -rw-r--r-- | libstdc++-v3/ChangeLog | 4 | ||||
| -rw-r--r-- | libstdc++-v3/docs/17_intro/porting-howto.html | 799 |
2 files changed, 508 insertions, 295 deletions
diff --git a/libstdc++-v3/ChangeLog b/libstdc++-v3/ChangeLog index 427d3cc..df0e50a 100644 --- a/libstdc++-v3/ChangeLog +++ b/libstdc++-v3/ChangeLog @@ -1,3 +1,7 @@ +2000-08-07 Felix Natter <fnatter@gmx.net> + + * docs/17_intro/porting-howto.html: New version. + 2000-08-03 Mark Mitchell <mark@codesourcery.com> * bits/locale_facets.h (ctype::ctype): Don't name unused diff --git a/libstdc++-v3/docs/17_intro/porting-howto.html b/libstdc++-v3/docs/17_intro/porting-howto.html index 4d4c254..4e6422e 100644 --- a/libstdc++-v3/docs/17_intro/porting-howto.html +++ b/libstdc++-v3/docs/17_intro/porting-howto.html @@ -1,305 +1,514 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> - <html> - <head> <title>Libstdc++-porting-howto</title> + <meta content="DocBook XSL Stylesheets V1.16" name="generator"> </head> - - <body> - - <h1>Porting to libstdc++-v3</h1> - - <center> - <li><a href = "#std">Namespaces std</a> - <li><a href = "#nocreate">File-flags: <tt>ios::nocreate</tt> and - <tt>ios::noreplace</tt></a> - <li><a href = "#headers">The new headers</a> - <li><a href = "#iterators">Iterator-changes</a> - <li><a href = "#macros">Libc-macros</a> - <li><a href = "#about">Comments, suggestions, corrections, questions...</a> - </center> - - <p> -In the following, when I say portable, I will refer to "portable among ISO -14882-implementations". On the other hand, if I say "backportable" or -"conservative", I am talking about "compiles with older -libstdc++-implementations". -</p> - - <a name = "std"> - <h2>Namespace std::</h2> - </a> - <p> -The latest C++-standard (ISO-14882) requires that the standard C++-library -is defined in namespace std::. Thus, to use classes from the standard c++ -library, you can do one of three things: - <ul> - <li>wrap your code in <tt>namespace std { ... }</tt> => This is not an - option because only symbols from the standard c++-library are defined in - namespace std::. - - <li>put a kind of <dfn>using-declaration</dfn> in your source (either - <tt>using namespace std;</tt> or i.e. <tt>using std::string;</tt>) - => works well for source-files, but cannot be used in header-files - - <li>use a <dfn>fully qualified name</dfn> for each libstdc++-symbol - (i.e. <tt>std::string</tt>, <tt>std::cout</tt>) => can always be used - </ul> -</p> - <p> -Because there are many compilers which still use an implementation that -does not have the standard C++-library in namespace <tt>std::</tt>, some -care is required to support these as well. -</p> - <p> -Namespace back-portability-issues are generally not a problem with g++, -because versions of g++ that do not have libstdc++ in <tt>std::</tt> use -<tt>-fno-honor-std</tt> (ignore <tt>std::</tt>, <tt>:: = std::</tt>) by -default. That is, the responsibility for enabling or disabling -<tt>std::</tt> is on the user; the maintainer does not have to care about it. -This probably applies to some other compilers as well. -</p> - <p> -The following sections list some possible solutions to support compilers -that cannot ignore std::. -</p> - <a name = "gtkmm"> - <h3>Using <dfn>namespace composition</dfn> if the project uses a separate - namespace</h3> - </a> - - <p> -<a href = "http://gtkmm.sourcforge.net">Gtk--</a> defines most of its -classes in namespace Gtk::. Thus, it was possible to adapt Gtk-- to -namespace std:: by using a C++-feature called <dfn>namespace -composition</dfn>. This is what happens if you put a -<dfn>using</dfn>-declaration into a namespace-definition: the imported -symbol(s) gets imported into the currently active namespace(s). For example: -<pre> -namespace Gtk { - using std::string; - class Window { ... } -} -</pre> -In this example, <tt>std::string</tt> gets imported into namespace Gtk::. -The result is that you don't have to use <tt>std::string</tt> in this -header, but still <tt>std::string</tt> does not get imported into -user-space (the global namespace ::) unless the user does <tt>using -namespace Gtk;</tt> (which is not recommended practice for Gtk--, so it is -not a problem). Additionally, the <tt>using</tt>-declarations are wrapped -in macros that are set based on autoconf-tests to either "" or -i.e. <tt>using std::string;</tt> (depending on whether the system has -libstdc++ in <tt>std::</tt> or not). -(ideas from llewelly@dbritsch.dsl.xmission.com, -Karl Nelson <kenelson@ece.ucdavis.edu>) -</p> - - <h3>Defining an empty namespace std</h3> - <p> -By defining an (empty) namespace <tt>std::</tt> before using it, you can -avoid getting errors on systems where no part of the library is in -namespace std: -<pre> -namespace std { } -using namespace std; -</pre> -</p> - <h3>Avoid to use fully qualified names (i.e. std::string)</h3> - <p> -If some compilers complain about <tt>using std::string;</tt>, and if the -"hack" for gtk-- mentioned above does not work, then it might be a good idea -to define a macro <tt>NS_STD</tt>, which is defined to either "" or "std" -based on an autoconf-test. Then you should be able to use -<tt>NS_STD::string</tt>, which will evaluate to <tt>::string</tt> ("string -in the global namespace") on systems that do not put string in std::. -(This is untested) -</p> - - <h3>How some open-source-projects deal with this</h3> - <p> - -<table> - <tr><td><a href = "http://www.clanlib.org">clanlib</a></td> <td>usual</td> - </tr> - <tr><td><a href = "http://pingus.seul.org">pingus</a></td> <td>usual</td> - </tr> - <tr><td><a href = "http://www.mozilla.org">mozilla</a></td> <td>usual</td> - </tr> - <tr><td><a href = "http://www.mnemonic.org">mnemonic</a></td> <td>none</td> - </tr> - <tr><td><a href = "http://libsigc.sourceforge.net">libsigc++</a></td> - <td>conservative-impl</td> - </tr> -</table> - -<table> - <caption>Notations for categories</caption> - <tr> - <td>usual</td> <td>mostly fully qualified names and some - using-declarations (but not in headers)</td> - </tr> - <tr> - <td>none</td> <td>no namespace std at all</td> - </tr> - <tr> - <td>conservative-impl</td> <td>wrap all namespace-handling in macros to - support compilers without namespace-support (no libstdc++ used in - headers)</td> - </tr> -</table> -As you can see, this currently lacks an example of a project which uses -libstdc++-symbols in headers in a back-portable way -(except for the <a href = "#gtkmm">Gtk-- "hack"</a>). -</p> - <a name = "nocreate"> - <h2>there is no ios::nocreate/ios::noreplace in ISO 14882</h2> - </a> - <p> -I have seen <tt>ios::nocreate</tt> being used for input-streams, most -probably because the authors thought it would be more correct to specify -nocreate "explicitly". So you can simply leave it out for -input-streams. -</p> -<p> -For output streams, "nocreate" is probably the default, unless you specify -<tt>std::ios::trunc</tt> ? 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 -<tt>app</tt>, <tt>ate</tt> and <tt>trunc</tt> (except for <tt>app</tt> ?). -</p> - <a name = "attach"> - <h2><tt>stream::attach(int fd)</tt> is not in the standard any more</h2> - </a> - <p> -With libstdc++-v3, you can use -<pre> -basic_filebuf(int __fd, const char*__name, ios_base::openmode __mode) -</pre> -For a portable solution (if there is one), you need to implement -a subclass of <tt>streambuf</tt> which opens a file given a descriptor, -and then pass an instance of this to the stream-constructor (from the -Josuttis-book). -</p> - <a name = "headers"> - <h2>The new headers</h2> - </a> - <p> -The new headers can be seen in this -<a href = "../../testsuite/17_intro/headers.cc">source file</a>. -</p> - <p> -I think it is a problem for libstdc++-v3 to add links or wrappers for the -old headers, because the implementation has changed, and the -header-name-changes indicate this. It might be preferable to use the new -headers and tell users of old compilers that they should create links -(which is what they will have to do sometime anyway). -</p> - - <a name = "cheaders"> - <h3>New headers replacing C-headers</h3> - </a> - <p> -You should not use the C-headers (except for system-level headers) from C++ -programs. Instead, you should use a set of headers that are named by -prepending 'c' and, as usual, ommiting the extension (.h). For example, -instead of using <tt><math.h></tt>, you should use -<tt><cmath></tt>. The standard specifies that if you include the -C-style header (<tt><math.h></tt> in this case), the symbols will be -available both in the global namespace and in namespace <tt>std::</tt> -(libstdc++-v3, version 2.90.8 currently puts them in <tt>std::</tt> only) -On the other hand, if you include only the new header -(i.e. <tt><cmath></tt>), the symbols will only be defined in -namespace <tt>std::</tt> (and macros will be converted to -inline-functions). -</p> + <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> + <div class="article" id="libstdporting"> + <div class="titlepage"> + <h1 class="title"> + <a name="libstdporting">Libstdc++-porting-howto</a> + </h1> + <h3 class="author">Felix Natter</h3> <p> -For more information on this, and for information on how the GNU C++ -implementation reuses ("shadows") the C library-functions, have -a look at <a href = "http://www.cantrip.org/cheaders.html">www.cantrip.org</a>. -</p> - - <h3><tt><fstream></tt> does not define <tt>std::cout</tt>, - <tt>std::cin</tt> etc.</h3> + This document can be distributed under the FDL + (<a href="http://www.gnu.org">www.gnu.org</a>) + </p> + <p class="pubdate">what kind of a date ? I don't drink !</p> + <div class="revhistory"> + <table width="100%" border="1"> + <tr> + <th colspan="3" valign="top" align="left"><b>Revision History</b></th> + </tr> + <tr> + <td align="left">Revision 0.5</td><td align="left">Thu Jun 1 13:06:50 2000</td><td align="left">fnatter</td> + </tr> + <tr> + <td colspan="3" align="left">First docbook-version.</td> + </tr> + <tr> + <td align="left">Revision 0.8</td><td align="left">Sun Jul 30 20:28:40 2000</td><td align="left">fnatter</td> + </tr> + <tr> + <td colspan="3" align="left">First released version using docbook-xml + + second upload to libstdc++-page. + </td> + </tr> + </table> + </div> + <div class="abstract"> + <p> + <a name="N2672"></a><b>Abstract</b> + </p> + <p> + Some notes on porting applications from libstdc++-2.90 (or earlier + versions) to libstdc++-v3. Not speaking in terms of the GNU libstdc++ + implementations, this means porting from earlier versions of the + C++-Standard to ISO 14882. + </p> + </div> + <hr> + </div> + <div class="toc"> <p> -In previous versions of the standard, <tt><fstream.h></tt>, -<tt><ostream.h></tt> and <tt><istream.h></tt> used to define -<tt>cout</tt>, <tt>cin</tt> and so on. Because of the templatized iostreams -in libstdc++-v3, you need to include <tt><iostream></tt> explicitly -to define these. -</p> - - <a name = "iterators"> - <h2>Iterators</h2> - </a> - <p> -The following are not proper uses of iterators, but may be working fixes -for existing uses of iterators. - <ul> - <li>you cannot do <tt>ostream::operator<<(iterator)</tt> to print the - address of the iterator => use <tt><< &*iterator</tt> instead ? - <li>you cannot clear an iterator's reference (<tt>iterator = 0</tt>) - => use <tt>iterator = iterator_type();</tt> ? - <li><tt>if (iterator)</tt> won't work any more - => use <tt>if (iterator != iterator_type())</tt> ? - </ul> -</p> - - <a name = "macros"> - <h2>Libc-macros (i.e. <tt>isspace</tt> from <tt><cctype></tt>)</h2> - </a> - <p> -Glibc 2.0.x and 2.1.x define the <tt><ctype.h></tt>-functionality -as macros (isspace, isalpha etc.). Libstdc++-v3 "shadows" these macros -as described in the <a href = "#cheaders">section on C-headers</a>. -</p> + <b>Table of Contents</b> + </p> + <dl> + <dt>1. <a href="#sec-nsstd">Namespace std::</a> + </dt> + <dd> + <dl> + <dt>1.1.1. <a href="#sec-gtkmm-hack">Using <i>namespace + composition</i> if the project uses a separate + namespace</a> + </dt> + <dt>1.1.2. <a href="#sec-emptyns">Defining an empty namespace std</a> + </dt> + <dt>1.1.3. <a href="#sec-avoidfqn">Avoid to use fully qualified names + (i.e. std::string)</a> + </dt> + <dt>1.1.4. <a href="#sec-osprojects">How some open-source-projects deal + with this</a> + </dt> + </dl> + </dd> + <dt>2. <a href="#sec-nocreate">there is no ios::nocreate/ios::noreplace + in ISO 14882</a> + </dt> + <dt>3. <a href="#sec-stream::attach"><b>stream::attach(int + fd)</b> is not in the standard any more</a> + </dt> + <dt>4. <a href="#sec-headers">The new headers</a> + </dt> + <dd> + <dl> + <dt>4.4.1. <a href="#sec-cheaders">New headers replacing C-headers</a> + </dt> + <dt>4.4.2. <a href="#sec-fstream-header"> + <tt><fstream></tt> does + not define <b>std::cout</b>, + <b>std::cin</b> etc.</a> + </dt> + </dl> + </dd> + <dt>5. <a href="#sec-iterators">Iterators</a> + </dt> + <dt>6. <a href="#sec-macros"> + Libc-macros (i.e. <b>isspace</b> from + <tt><cctype></tt>)</a> + </dt> + <dt>7. <a href="#sec-about">About...</a> + </dt> + </dl> + </div> <p> -Older implementations of libstdc++ (g++-2 for egcs 1.x and g++-3 for -gcc 2.95.2), however, keep these functions as macros, and so it is not -back-portable to use fully qualified names. For example: -<pre> -#include <cctype> -int main() { std::isspace('X'); } -</pre> -will result in something like this (unless using g++-v3): -<pre> -std:: (__ctype_b[(int) ( ( 'X' ) )] & (unsigned short int) _ISspace ) ; -</pre> -Another problem arises if you put a <tt>using namespace std;</tt> -declaration at the top, and include <tt><ctype.h></tt>. This will -result in ambiguities between the definitions in the global namespace -(<tt><ctype.h></tt>) and the definitions in namespace <tt>std::</tt> -(<tt><cctype></tt>). -</p> - <p> -One solution I can think of is to test for -v3 using autoconf-macros, and -define macros for each of the C-functions (maybe that is possible with one -"wrapper" macro as well ?). -</p> - <p> -Another solution which would fix g++ is to tell the user to modify -a header-file so that g++-2 (egcs 1.x) and g++-3 (gcc 2.95.2) -enable a macro which tells <ctype.h> to define functions instead of -macros: -<pre> -// This keeps isanum, et al from being propagated as macros. -#if __linux__ -#define __NO_CTYPE 1 -#endif - -[ now include <ctype.h> ] -</pre> -</p> + In the following, when I say portable, I will refer to "portable among ISO + 14882-implementations". On the other hand, if I say "backportable" or + "conservative", I am talking about "compiles with older + libstdc++-implementations". + </p> + <div class="section" id="sec-nsstd"> + <h2 class="title" style="clear: all"> + <a name="sec-nsstd"><b>1. Namespace std::</b></a> + </h2> + <p> + The latest C++-standard (ISO-14882) requires that the standard + C++-library is defined in namespace std::. Thus, in order to use + classes from the standard C++-library, you can do one of three + things: + <div class="itemizedlist"> + <ul> + <li> + <a name="N2696"></a> + <p>wrap your code in <b>namespace std { + ... }</b> => This is not an option because only symbols + from the standard c++-library are defined in namespace std::. + </p> + </li> + <li> + <a name="N2705"></a> + <p>put a kind of + <i>using-declaration</i> in your source (either + <b>using namespace std;</b> or i.e. <b>using + std::string;</b>) => works well for source-files, but + cannot be used in header-files. + </p> + </li> + <li> + <a name="N2720"></a> + <p>use a <i>fully qualified name</i> for + each libstdc++-symbol (i.e. <b>std::string</b>, + <b>std::cout</b>) => can always be used + </p> + </li> + </ul> + </div> + </p> + <p> + Because there are many compilers which still use an implementation + that does not have the standard C++-library in namespace + <b>std::</b>, some care is required to support these as + well. + </p> + <p> + Namespace back-portability-issues are generally not a problem with + g++, because versions of g++ that do not have libstdc++ in + <b>std::</b> use <b>-fno-honor-std</b> + (ignore <b>std::</b>, <b>:: = std::</b>) by + default. That is, the responsibility for enabling or disabling + <b>std::</b> is on the user; the maintainer does not have + to care about it. This probably applies to some other compilers as + well. + </p> + <p> + The following sections list some possible solutions to support compilers + that cannot ignore std::. + </p> + <div class="section" id="sec-gtkmm-hack"> + <h3 class="title"> + <a name="sec-gtkmm-hack"><b>1.1.1. Using <i>namespace + composition</i> if the project uses a separate + namespace</b></a> + </h3> + <p> + <a href="http://gtkmm.sourceforge.net">Gtk--</a> defines + most of its classes in namespace Gtk::. Thus, it was possible to + adapt Gtk-- to namespace std:: by using a C++-feature called + <i>namespace composition</i>. This is what happens if + you put a <i>using</i>-declaration into a + namespace-definition: the imported symbol(s) gets imported into the + currently active namespace(s). For example: + <pre class="programlisting"> + namespace Gtk { + using std::string; + class Window { ... } + } + </pre> + In this example, <b>std::string</b> gets imported into + namespace Gtk::. The result is that you don't have to use + <b>std::string</b> in this header, but still + <b>std::string</b> does not get imported into + user-space (the global namespace ::) unless the user does + <b>using namespace Gtk;</b> (which is not recommended + practice for Gtk--, so it is not a problem). Additionally, the + <b>using</b>-declarations are wrapped in macros that + are set based on autoconf-tests to either "" or i.e. <b>using + std::string;</b> (depending on whether the system has + libstdc++ in <b>std::</b> or not). (ideas from + <tt><<a href="mailto:llewelly@dbritsch.dsl.xmission.com">llewelly@dbritsch.dsl.xmission.com</a>></tt>, Karl Nelson + <tt><<a href="mailto:kenelson@ece.ucdavis.edu">kenelson@ece.ucdavis.edu</a>></tt>) + </p> + </div> + <div class="section" id="sec-emptyns"> + <h3 class="title"> + <a name="sec-emptyns"><b>1.1.2. Defining an empty namespace std</b></a> + </h3> + <p> + By defining an (empty) namespace <b>std::</b> before + using it, you avoid getting errors on systems where no part of the + library is in namespace std: + <pre class="programlisting"> + namespace std { } + using namespace std; + </pre> + </p> + </div> + <div class="section" id="sec-avoidfqn"> + <h3 class="title"> + <a name="sec-avoidfqn"><b>1.1.3. Avoid to use fully qualified names + (i.e. std::string)</b></a> + </h3> + <p> + If some compilers complain about <b>using + std::string;</b>, and if the "hack" for gtk-- mentioned above + does not work, then it might be a good idea to define a macro + NS_STD, which is defined to either "" or "std" + based on an autoconf-test. Then you should be able to use + <b>NS_STD::string</b>, which will evaluate to + <b>::string</b> ("string in the global namespace") on + systems that do not put string in std::. (This is untested) + </p> + </div> + <div class="section" id="sec-osprojects"> + <h3 class="title"> + <a name="sec-osprojects"><b>1.1.4. How some open-source-projects deal + with this</b></a> + </h3> + <p> + This information was gathered around May 2000. It may not be correct + by the time you read this. + </p> + <div class="table"> + <p> + <a name="N2885"></a><b>Table 1. Namespace std:: in Open-Source programs</b> + </p> + <table border="1"> + <colgroup> + <col> + <col> + </colgroup> + <tbody> + <tr> + <td><a href="http://www.clanlib.org">clanlib</a></td><td>usual</td> + </tr> + <tr> + <td><a href="http://pingus.seul.org">pingus</a></td><td>usual</td> + </tr> + <tr> + <td><a href="http://www.mozilla.org">mozilla</a></td><td>usual</td> + </tr> + <tr> + <td><a href="http://www.mnemonic.org">mnemonic</a></td><td>none</td> + </tr> + <tr> + <td><a href="http://libsigc.sourceforge.net"> + libsigc++</a></td><td>conservative-impl</td> + </tr> + </tbody> + </table> + </div> + <div class="table"> + <p> + <a name="N2962"></a><b>Table 2. Notations for categories</b> + </p> + <table border="1"> + <colgroup> + <col> + <col> + </colgroup> + <tbody> + <tr> + <td>usual</td><td>mostly fully qualified names and some + using-declarations (but not in headers)</td> + </tr> + <tr> + <td>none</td><td>no namespace std at all</td> + </tr> + <tr> + <td>conservative-impl</td><td>wrap all + namespace-handling in macros to support compilers without + namespace-support (no libstdc++ used in headers)</td> + </tr> + </tbody> + </table> + </div> + <p> + As you can see, this currently lacks an example of a project which + uses libstdc++-symbols in headers in a back-portable way (except + for Gtk--: see the <a href="#sec-gtkmm-hack">section on the Gtk-- hack + </a>). + </p> + </div> + </div> + <div class="section" id="sec-nocreate"> + <h2 class="title" style="clear: all"> + <a name="sec-nocreate"><b>2. there is no ios::nocreate/ios::noreplace + in ISO 14882</b></a> + </h2> + <p> + I have seen <b>ios::nocreate</b> being used for input-streams, + most probably because the authors thought it would be more correct + to specify nocreate "explicitly". So you can simply leave it out + for input-streams. + </p> + <p> + For output streams, "nocreate" is probably the default, unless you + specify <b>std::ios::trunc</b> ? 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 <b>app</b>, + <b>ate</b> and <b>trunc</b> (except for + <b>app</b> ?). + </p> + </div> + <div class="section" id="sec-stream::attach"> + <h2 class="title" style="clear: all"> + <a name="sec-stream::attach"><b>3. <b>stream::attach(int + fd)</b> is not in the standard any more</b></a> + </h2> + <p> + When using libstdc++-v3, you can use + <div id="N3066" class="funcsynopsis"> + <p> + </p> + <a name="N3066"></a> + <pre class="funcsynopsisinfo"> + #include <fstream> + </pre> + <p> + <code><code class="funcdef">int <b class="fsfunc">basic_filebuf</b></code>(<var class="pdparam">__fd</var>, <var class="pdparam">__name</var>, <var class="pdparam">__mode</var>);<br>int <var class="pdparam">__fd</var>;<br>const char* <var class="pdparam">__name</var>;<br>ios_base::openmode <var class="pdparam">__mode</var>;</code> + </p> + <p> + </p> + </div> + For a portable solution (if there is one), you need to implement a + subclass of <b>streambuf</b> which opens a file given a + descriptor, and then pass an instance of this to the + stream-constructor (from the Josuttis-book). + </p> + </div> + <div class="section" id="sec-headers"> + <h2 class="title" style="clear: all"> + <a name="sec-headers"><b>4. The new headers</b></a> + </h2> + <p> + All new headers can be seen in this <a href="../../testsuite/17_intro/headers.cc">source-code</a>. + </p> + <p> + I think it is a problem for libstdc++-v3 to add links or wrappers + for the old headers, because the implementation has changed, and + the header name-changes indicate this. It might be preferable to + use the new headers and tell users of old compilers that they + should create links (which is what they will have to do sometime + anyway). + </p> + <div class="section" id="sec-cheaders"> + <h3 class="title"> + <a name="sec-cheaders"><b>4.4.1. New headers replacing C-headers</b></a> + </h3> + <p> + You should not use the C-headers (except for system-level headers) + from C++ programs. Instead, you should use a set of headers that + are named by prepending 'c' and, as usual, ommiting the extension + (.h). For example, instead of using <tt><math.h></tt>, you should use <tt><cmath></tt>. The standard + specifies that if you include the C-style header (<tt><math.h></tt> in this case), the symbols + will be available both in the global namespace and in namespace + <b>std::</b> (libstdc++-v3, version 2.90.8 currently + puts them in <b>std::</b> only) On the other hand, if + you include only the new header (i.e. <tt><pcmath></tt>), the symbols will only be + defined in namespace <b>std::</b> (and macros will be + converted to inline-functions). + </p> + <p> + For more information on this, and for information on how the GNU + C++ implementation reuses ("shadows") the C library-functions, have + a look at <a href="http://www.cantrip.org/cheaders.html"> + www.cantrip.org</a>. + </p> + </div> + <div class="section" id="sec-fstream-header"> + <h3 class="title"> + <a name="sec-fstream-header"><b>4.4.2. + <tt><fstream></tt> does + not define <b>std::cout</b>, + <b>std::cin</b> etc.</b></a> + </h3> + <p> + In previous versions of the standard, <tt><fstream.h></tt>, <tt><ostream.h></tt> and <tt><istream.h></tt> used to define + <b>cout</b>, <b>cin</b> and so on. Because + of the templatized iostreams in libstdc++-v3, you need to include + <tt><iostream></tt> + explicitly to define these. + </p> + </div> + </div> + <div class="section" id="sec-iterators"> + <h2 class="title" style="clear: all"> + <a name="sec-iterators"><b>5. Iterators</b></a> + </h2> + <p> + The following are not proper uses of iterators, but may be working + fixes for existing uses of iterators. + <div class="itemizedlist"> + <ul> + <li> + <a name="N3266"></a> + <p>you cannot do + <b>ostream::operator<<(iterator)</b> to + print the address of the iterator => use + <b>operator<< &*iterator</b> instead ? + </p> + </li> + <li> + <a name="N3287"></a> + <p>you cannot clear an iterator's reference + (<b>iterator = 0</b>) => use + <b>iterator = iterator_type();</b> ? + </p> + </li> + <li> + <a name="N3300"></a> + <p> + <b>if (iterator)</b> won't work any + more => use <b>if (iterator != iterator_type())</b> + ?</p> + </li> + </ul> + </div> + </p> + </div> + <div class="section" id="sec-macros"> + <h2 class="title" style="clear: all"> + <a name="sec-macros"><b>6. + Libc-macros (i.e. <b>isspace</b> from + <tt><cctype></tt>)</b></a> + </h2> + <p> + Glibc 2.0.x and 2.1.x define the <tt><ctype.h></tt> -functionality as + macros (isspace, isalpha etc.). Libstdc++-v3 "shadows" these macros + as described in the <a href="#sec-cheaders">section on C-headers</a>. + </p> + <p> + Older implementations of libstdc++ (g++-2 for egcs 1.x and g++-3 + for gcc 2.95.2), however, keep these functions as macros, and so it + is not back-portable to use fully qualified names. For example: + <pre class="programlisting"> + #include <cctype> + int main() { std::isspace('X'); } + </pre> + will result in something like this (unless using g++-v3): + <pre class="programlisting"> + std:: (__ctype_b[(int) ( ( 'X' ) )] & (unsigned short int) + _ISspace ) ; + </pre> + </p> + <p> + One solution I can think of is to test for -v3 using + autoconf-macros, and define macros for each of the C-functions + (maybe that is possible with one "wrapper" macro as well ?). + </p> + <p> + Another solution which would fix g++ is to tell the user to modify a + header-file so that g++-2 (egcs 1.x) and g++-3 (gcc 2.95.2) define a + macro which tells <tt><ctype.h></tt> to define functions + instead of macros: + <pre class="programlisting"> + // This keeps isalnum, et al from being propagated as macros. + #if __linux__ + #define __NO_CTYPE 1 + #endif - <a name = "about"> - <h2>About...</h2> - </a> - <p> -Please send any experience, additions, corrections or questions to <a href -= "mailto:fnatter@gmx.net">fnatter@gmx.net</a> or for discussion to the -libstdc++-v3-mailing-list. -</p> - + [ now include <ctype.h> ] + </pre> + </p> + <p> + Another problem arises if you put a <b>using namespace + std;</b> declaration at the top, and include <tt><ctype.h></tt>. This will result in + ambiguities between the definitions in the global namespace + (<tt><ctype.h></tt>) and the + definitions in namespace <b>std::</b> + (<b><cctype></b>). + </p> + <p> + The solution to this problem was posted to the libstdc++-v3 + mailing-list: + Benjamin Kosnik <tt><<a href="mailto:bkoz@redhat.com">bkoz@redhat.com</a>></tt> writes: + " + --enable-cshadow-headers is currently broken. As a result, shadow + headers are not being searched.... + " + </p> + </div> + <div class="section" id="sec-about"> + <h2 class="title" style="clear: all"> + <a name="sec-about"><b>7. About...</b></a> + </h2> + <p> + Please send any experience, additions, corrections or questions to + <a href="mailto:fnatter@gmx.net">fnatter@gmx.net</a> or for + discussion to the libstdc++-v3-mailing-list. + </p> + </div> + </div> </body> - </html> |