libstdc++-v3/docs/html/17_intro/porting-howto.xml

   1 <?xml version="1.0" encoding="ISO-8859-1"?>
   2
   3 <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1//EN"
   4                          "http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd">
   5
   6 <?xml-stylesheet type="text/xsl" href="docbook-xslt/docbook/html/docbook.xsl"?>
   7
   8 <!--
   9   This is written using docbook 4.1 xml. HTML is generated using
  10   the xslt-stylesheets from http://www.nwalsh.com.
  11
  12   xsltproc is an xslt-processor included in libxslt:
  13   (http://xmlsoft.org/XSLT/ or here:
  14   ftp://ftp.gnome.org/pub/GNOME/unstable/sources/libxslt/)
  15   (it requires libxml2: http://xmlsoft.org
  16         or here: ftp://ftp.gnome.org/pub/GNOME/stable/sources/libxml/)
  17
  18   You can find the latest version of this document here:
  19   http://gcc.gnu.org/onlinedocs/libstdc++/17_intro/porting-howto(.html|.xml)
  20 -->
  21
  22 <!-- TODO:
  23 o remove //@label: use automatic numbering
  24 o make this work: <link linkend="sec-gtkmm-hack" endterm="sec-gtkmm-hack.title"/>.
  25 o clean up the section-numbering
  26 -->
  27
  28 <article class = "whitepaper" id = "libstdc++-porting-howto" lang = "en">
  29   <articleinfo>
  30     <title>Libstdc++-porting-howto</title>
  31     <author>
  32       <firstname>Felix</firstname>
  33       <surname>Natter</surname>
  34     </author>
  35     <address>
  36       <email>fnatter@gmx.net</email>
  37     </address>
  38     <revhistory>
  39       <revision>
  40         <revnumber>0.5</revnumber>
  41         <date>Thu Jun  1 13:06:50 2000</date>
  42         <authorinitials>fnatter</authorinitials>
  43         <revremark>First docbook-version.</revremark>
  44       </revision>
  45       <revision>
  46         <revnumber>0.8</revnumber>
  47         <date>Sun Jul 30 20:28:40 2000</date>
  48         <authorinitials>fnatter</authorinitials>
  49         <revremark>First released version using docbook-xml
  50           + second upload to libstdc++-page.
  51         </revremark>
  52       </revision>
  53       <revision>
  54         <revnumber>0.9</revnumber>
  55         <date>Wed Sep  6 02:59:32 2000</date>
  56         <authorinitials>fnatter</authorinitials>
  57         <revremark>5 new sections.</revremark>
  58       </revision>
  59       <revision>
  60         <revnumber>0.9.1</revnumber>
  61         <date>Sat Sep 23 14:20:15 2000</date>
  62         <authorinitials>fnatter</authorinitials>
  63         <revremark>added information about why file-descriptors are not in the
  64           standard</revremark>
  65       </revision>
  66       <revision>
  67         <revnumber>0.9.2</revnumber>
  68         <date>Tue Jun  5 20:07:49 2001</date>
  69         <authorinitials>fnatter</authorinitials>
  70         <revremark>
  71           a fix, added hint on increased portability of C-shadow-headers,
  72           added autoconf-test HAVE_CONTAINER_AT
  73         </revremark>
  74       </revision>
  75       <revision>
  76         <revnumber>0.9.3</revnumber>
  77         <date>Fri Jun 29 16:15:56 2001</date>
  78         <authorinitials>fnatter</authorinitials>
  79         <revremark>
  80           changed signature of nonstandard filebuf-constructor and
  81           update the section on filebuf::attach to point to ../ext/howto.html,
  82           added link to ../21/strings/howto.html
  83           in sec-stringstream, changed &lt;link&gt;-tags to have content
  84           (so that these links work),
  85           replace "user-space" by "global namespace"
  86           add note about gcc 3.0 and shadow-headers
  87           add section about ostream::form and istream::scan
  88           sec-vector-at: remove hint to modify headers
  89           fix spelling error in sec-stringstream
  90         </revremark>
  91       </revision>
  92       <revision>
  93         <revnumber>0.9.4</revnumber>
  94         <date>Mon Nov  5 17:01:04 2001</date>
  95         <authorinitials>fnatter</authorinitials>
  96         <revremark>
  97           rewrite section 1.1.3 because of gnu.gcc.help-post by
  98           Juergen Heinzl
  99         </revremark>
 100       </revision>
 101     </revhistory>
 102     <legalnotice><title>Legal Notice</title>
 103       <para>
 104         This document can be distributed under the FDL
 105         (<ulink url = "http://www.gnu.org">www.gnu.org</ulink>)
 106       </para>
 107     </legalnotice>
 108
 109     <pubdate>Tue Jun  5 20:07:49 2001</pubdate>
 110     <abstract>
 111       <para>
 112         Some notes on porting applications from libstdc++-2.90 (or earlier
 113         versions) to libstdc++-v3. Not speaking in terms of the GNU libstdc++
 114         implementations, this means porting from earlier versions of the
 115         C++-Standard to ISO 14882.
 116       </para>
 117     </abstract>
 118   </articleinfo>
 119
 120   <para>
 121     In the following, when I say portable, I will refer to "portable among ISO
 122     14882-implementations". On the other hand, if I say "backportable" or
 123     "conservative", I am talking about "compiles with older
 124     libstdc++-implementations".
 125   </para>
 126
 127   <section id="sec-nsstd" label="1"><title>Namespace std::</title>
 128     <para>
 129       The latest C++-standard (ISO-14882) requires that the standard
 130       C++-library is defined in namespace std::. Thus, in order to use
 131       classes from the standard C++-library, you can do one of three
 132       things:
 133       <itemizedlist>
 134
 135         <listitem><para>wrap your code in <command>namespace std {
 136               ... }</command> =&gt; This is not an option because only symbols
 137             from the standard c++-library are defined in namespace std::.
 138           </para></listitem>
 139
 140         <listitem><para>put a kind of
 141             <emphasis>using-declaration</emphasis> in your source (either
 142             <command>using namespace std;</command> or i.e. <command>using
 143               std::string;</command>) =&gt; works well for source-files, but
 144             cannot be used in header-files.
 145           </para></listitem>
 146
 147         <listitem><para>use a <emphasis>fully qualified name</emphasis> for
 148             each libstdc++-symbol (i.e. <command>std::string</command>,
 149             <command>std::cout</command>) =&gt; can always be used
 150           </para></listitem>
 151       </itemizedlist>
 152     </para>
 153
 154     <para>
 155       Because there are many compilers which still use an implementation
 156       that does not have the standard C++-library in namespace
 157       <command>std::</command>, some care is required to support these as
 158       well.
 159     </para>
 160
 161     <para>
 162       Namespace back-portability-issues are generally not a problem with
 163       g++, because versions of g++ that do not have libstdc++ in
 164       <command>std::</command> use <command>-fno-honor-std</command>
 165       (ignore <command>std::</command>, <command>:: = std::</command>) by
 166       default. That is, the responsibility for enabling or disabling
 167       <command>std::</command> is on the user; the maintainer does not have
 168       to care about it. This probably applies to some other compilers as
 169       well.
 170     </para>
 171     <para>
 172       The following sections list some possible solutions to support compilers
 173       that cannot ignore std::.
 174     </para>
 175
 176     <section id = "sec-gtkmm-hack" label = "1.1">
 177       <title id="sec-gtkmm-hack.title">Using <emphasis>namespace
 178           composition</emphasis> if the project uses a separate
 179         namespace</title>
 180       <para>
 181         <ulink url = "http://gtkmm.sourceforge.net">Gtk--</ulink> defines
 182         most of its classes in namespace Gtk::. Thus, it was possible to
 183         adapt Gtk-- to namespace std:: by using a C++-feature called
 184         <emphasis>namespace composition</emphasis>. This is what happens if
 185         you put a <emphasis>using</emphasis>-declaration into a
 186         namespace-definition: the imported symbol(s) gets imported into the
 187         currently active namespace(s). For example:
 188         <programlisting>
 189           namespace Gtk {
 190           using std::string;
 191           class Window { ... }
 192           }
 193         </programlisting>
 194         In this example, <command>std::string</command> gets imported into
 195         namespace Gtk::.  The result is that you don't have to use
 196         <command>std::string</command> in this header, but still
 197         <command>std::string</command> does not get imported into
 198         the global namespace (::) unless the user does
 199         <command>using namespace Gtk;</command> (which is not recommended
 200         practice for Gtk--, so it is not a problem).  Additionally, the
 201         <command>using</command>-declarations are wrapped in macros that
 202         are set based on autoconf-tests to either "" or i.e. <command>using
 203           std::string;</command> (depending on whether the system has
 204         libstdc++ in <command>std::</command> or not).  (ideas from
 205         <email>llewelly@dbritsch.dsl.xmission.com</email>, Karl Nelson
 206         <email>kenelson@ece.ucdavis.edu</email>)
 207       </para>
 208     </section>
 209
 210     <section id = "sec-emptyns" label = "1.2">
 211       <title id="sec-emptyns.title">Defining an empty namespace std</title>
 212       <para>
 213         By defining an (empty) namespace <command>std::</command> before
 214         using it, you avoid getting errors on systems where no part of the
 215         library is in namespace std:
 216         <programlisting>
 217           namespace std { }
 218           using namespace std;
 219         </programlisting>
 220       </para>
 221     </section>
 222
 223     <section id = "sec-avoidfqn" label = "1.3">
 224       <title id="sec-avoidfqn.title">Avoid to use fully qualified names
 225         (i.e. std::string)</title>
 226       <para>
 227         If some compilers complain about <command>using
 228           std::string;</command>, and if the "hack" for gtk-- mentioned above
 229         does not work, then I see two solutions:
 230
 231         <itemizedlist>
 232           <listitem><para>
 233               Define <command>std::</command> as a macro if the compiler
 234               doesn't know about <command>std::</command>.
 235               <programlisting>
 236                 #ifdef OLD_COMPILER
 237                 #define std
 238                 #endif
 239               </programlisting>
 240               (thanks to Juergen Heinzl who posted this solution on
 241               gnu.gcc.help)
 242             </para></listitem>
 243
 244           <listitem><para>
 245               Define a macro <symbol>NS_STD</symbol>, which is defined to
 246               either "" or "std"
 247               based on an autoconf-test. Then you should be able to use
 248               <command>NS_STD::string</command>, which will evaluate to
 249               <command>::string</command> ("string in the global namespace") on
 250               systems that do not put string in std::.  (This is untested)
 251             </para></listitem>
 252         </itemizedlist>
 253
 254       </para>
 255     </section>
 256
 257     <section id = "sec-osprojects" label = "1.4">
 258       <title id="sec-osprojects.title">How some open-source-projects deal
 259         with this</title>
 260       <para>
 261         This information was gathered around May 2000. It may not be correct
 262         by the time you read this.
 263       </para>
 264       <table><title>Namespace std:: in Open-Source programs</title>
 265         <tgroup cols = "2">
 266           <tbody>
 267             <row>
 268               <entry><ulink url = "http://www.clanlib.org">clanlib</ulink>
 269               </entry>
 270               <entry>usual</entry>
 271             </row>
 272             <row>
 273               <entry><ulink url = "http://pingus.seul.org">pingus</ulink>
 274               </entry>
 275               <entry>usual</entry>
 276             </row>
 277             <row>
 278               <entry><ulink url = "http://www.mozilla.org">mozilla</ulink>
 279               </entry>
 280               <entry>usual</entry>
 281             </row>
 282             <row>
 283               <entry><ulink url = "http://www.mnemonic.org">mnemonic</ulink>
 284               </entry> <entry>none</entry>
 285             </row>
 286             <row>
 287               <entry><ulink url = "http://libsigc.sourceforge.net">
 288                   libsigc++</ulink></entry>
 289               <entry>conservative-impl</entry>
 290             </row>
 291           </tbody>
 292         </tgroup>
 293       </table>
 294
 295       <table><title>Notations for categories</title>
 296         <tgroup cols = "2">
 297           <tbody>
 298             <row>
 299               <entry>usual</entry>
 300               <entry>mostly fully qualified names and some
 301                 using-declarations (but not in headers)</entry>
 302             </row>
 303             <row>
 304               <entry>none</entry> <entry>no namespace std at all</entry>
 305             </row>
 306             <row>
 307               <entry>conservative-impl</entry>
 308               <entry>wrap all
 309                 namespace-handling in macros to support compilers without
 310                 namespace-support (no libstdc++ used in headers)</entry>
 311             </row>
 312           </tbody>
 313         </tgroup>
 314       </table>
 315
 316       <para>
 317         As you can see, this currently lacks an example of a project
 318         which uses libstdc++-symbols in headers in a back-portable way
 319         (except for Gtk--: see the <link linkend="sec-gtkmm-hack"
 320           endterm="sec-gtkmm-hack.title">section on the gtkmm-hack</link>).
 321       </para>
 322     </section>
 323   </section> <!-- end of namespace-section -->
 324
 325   <section id = "sec-nocreate" label = "2">
 326     <title id="sec-nocreate.title">there is no ios::nocreate/ios::noreplace
 327       in ISO 14882</title>
 328     <para>
 329       I have seen <command>ios::nocreate</command> being used for
 330       input-streams, most probably because the author thought it would be
 331       more correct to specify nocreate "explicitly".  So you can simply
 332       leave it out for input-streams.
 333     </para>
 334     <para>
 335       For output streams, "nocreate" is probably the default, unless you
 336       specify <command>std::ios::trunc</command> ? To be safe, you can open
 337       the file for reading, check if it has been opened, and then decide
 338       whether you want to create/replace or not. To my knowledge, even
 339       older implementations support <command>app</command>,
 340       <command>ate</command> and <command>trunc</command> (except for
 341       <command>app</command> ?).
 342     </para>
 343   </section>
 344
 345   <section id = "sec-stream::attach" label = "3">
 346     <title id="sec-stream::attach.title"><command>stream::attach(int
 347         fd)</command> is not in the standard any more</title>
 348     <para>
 349       Phil Edwards <email>pedwards@disaster.jaj.com</email> writes:
 350       It was considered and rejected.  Not all environments use file
 351       descriptors.  Of those that do, not all of them use integers to represent
 352       them.
 353     </para>
 354     <para>
 355       When using libstdc++-v3, you can use
 356       <funcsynopsis>
 357         <funcsynopsisinfo format="linespecific">
 358           #include &lt;fstream&gt;
 359         </funcsynopsisinfo>
 360         <funcprototype>
 361           <funcdef>
 362             <function>basic_filebuf&lt;...&gt;::basic_filebuf&lt;...&gt;
 363             </function>
 364           </funcdef>
 365           <paramdef>__c_file_type* <parameter>file</parameter></paramdef>
 366           <paramdef>ios_base::open_mode <parameter>mode</parameter></paramdef>
 367           <paramdef>int <parameter>size</parameter></paramdef>
 368         </funcprototype>
 369       </funcsynopsis>
 370       but the the signature of this constructor has changed often, and
 371       it might change again. For the current state of this, check
 372       <ulink url="../ext/howto.html">the howto for extensions</ulink>.
 373     </para>
 374     <para>
 375       For a portable solution (among systems which use
 376       filedescriptors), you need to implement a subclass of
 377       <command>std::streambuf</command> (or
 378       <command>std::basic_streambuf&lt;..&gt;</command>) which opens a file
 379       given a descriptor, and then pass an instance of this to the
 380       stream-constructor.  For an example of this, refer to
 381       <ulink url="http://www.josuttis.com/cppcode/fdstream.html">fdstream example</ulink>
 382       by Nicolai Josuttis.
 383     </para>
 384   </section>
 385
 386   <section id = "sec-headers" label = "4">
 387     <title id="sec-headers.title">The new headers</title>
 388     <para>
 389       All new headers can be seen in this <ulink url="headers_cc.txt">
 390         source-code</ulink>.
 391     </para>
 392     <para>
 393       The old C++-headers (iostream.h etc.) are available, but gcc generates
 394       a warning that you are using deprecated headers.
 395     </para>
 396
 397     <section id = "sec-cheaders" label = "4.1">
 398       <title id="sec-cheaders.title">New headers replacing C-headers</title>
 399       <para>
 400         You should not use the C-headers (except for system-level
 401         headers) from C++ programs. Instead, you should use a set of
 402         headers that are named by prepending 'c' and, as usual,
 403         omitting the extension (.h). For example, instead of using
 404         <filename class="headerfile">&lt;math.h&gt;</filename>, you
 405         should use <filename class =
 406           "headerfile">&lt;cmath&gt;</filename>. In some cases this has
 407         the advantage that the C++-header is more standardized than
 408         the C-header (i.e. <filename
 409           class="headerfile">&lt;ctime&gt;</filename> (almost)
 410         corresponds to either <filename class =
 411           "headerfile">&lt;time.h&gt;</filename> or <filename class =
 412           "headerfile">&lt;sys/time.h&gt;</filename>).
 413
 414         The standard specifies that if you include the C-style header
 415         (<filename class = "headerfile">&lt;math.h&gt;</filename> in
 416         this case), the symbols will be available both in the global
 417         namespace and in namespace <command>std::</command> (but
 418         libstdc++ does not yet have fully compliant headers) On the
 419         other hand, if you include only the new header (i.e. <filename
 420           class = "headerfile">&lt;cmath&gt;</filename>), the symbols
 421         will only be defined in namespace <command>std::</command>
 422         (and macros will be converted to inline-functions).
 423       </para>
 424       <para>
 425         For more information on this, and for information on how the
 426         GNU C++ implementation might reuse ("shadow") the C
 427         library-functions, have a look at <ulink
 428           url="http://www.cantrip.org/cheaders.html">
 429           www.cantrip.org</ulink>.
 430       </para>
 431     </section>
 432
 433     <section id = "sec-fstream-header" label = "4.2">
 434       <title id="sec-fstream-header.title">
 435         <filename class="headerfile">&lt;fstream&gt;</filename> does
 436         not define <command>std::cout</command>,
 437         <command>std::cin</command> etc.</title>
 438       <para>
 439         In earlier versions of the standard,
 440         <filename class="headerfile">&lt;fstream.h&gt;</filename>,
 441         <filename class="headerfile">&lt;ostream.h&gt;</filename>
 442         and <filename class="headerfile">&lt;istream.h&gt;</filename>
 443         used to define
 444         <command>cout</command>, <command>cin</command> and so on. Because
 445         of the templatized iostreams in libstdc++-v3, you need to include
 446         <filename class = "headerfile">&lt;iostream&gt;</filename>
 447         explicitly to define these.
 448       </para>
 449     </section>
 450   </section>
 451
 452   <section id = "sec-iterators" label = "5">
 453     <title id="sec-iterators.title">Iterators</title>
 454     <para>
 455       The following are not proper uses of iterators, but may be working
 456       fixes for existing uses of iterators.
 457       <itemizedlist>
 458         <listitem><para>you cannot do
 459             <command>ostream::operator&lt;&lt;(iterator)</command> to
 460             print the address of the iterator =&gt; use
 461             <command>operator&lt;&lt; &amp;*iterator</command> instead ?
 462           </para>
 463         </listitem>
 464         <listitem><para>you cannot clear an iterator's reference
 465             (<command>iterator = 0</command>) =&gt; use
 466             <command>iterator = iterator_type();</command> ?
 467           </para>
 468         </listitem>
 469         <listitem><para><command>if (iterator)</command> won't work any
 470             more => use <command>if (iterator != iterator_type())</command>
 471             ?</para>
 472         </listitem>
 473       </itemizedlist>
 474     </para>
 475   </section>
 476
 477   <section id = "sec-macros" label = "6">
 478     <title id="sec-macros.title">
 479       Libc-macros (i.e. <command>isspace</command> from
 480       <filename class = "headerfile">&lt;cctype&gt;</filename>)</title>
 481     <para>
 482       Glibc 2.0.x and 2.1.x define the
 483       <filename class="headerfile">&lt;ctype.h&gt;</filename>
 484       -functionality as macros (isspace, isalpha etc.). Libstdc++-v3
 485       "shadows" these macros as described in the <link
 486         linkend="sec-cheaders" endterm="sec-cheaders.title">section about
 487         c-headers</link>.
 488     </para>
 489     <para>
 490       Older implementations of libstdc++ (g++-2 for egcs 1.x and g++-3
 491       for gcc 2.95.x), however, keep these functions as macros, and so it
 492       is not back-portable to use fully qualified names. For example:
 493       <programlisting>
 494         #include &lt;cctype&gt;
 495         int main() { std::isspace('X'); }
 496       </programlisting>
 497       will result in something like this (unless using g++-v3):
 498       <programlisting>
 499         std:: (__ctype_b[(int) ( ( 'X' ) )] &amp; (unsigned short int)
 500         _ISspace )  ;
 501       </programlisting>
 502     </para>
 503     <para>
 504       One solution I can think of is to test for -v3 using
 505       autoconf-macros, and define macros for each of the C-functions
 506       (maybe that is possible with one "wrapper" macro as well ?).
 507     </para>
 508     <para>
 509       Another solution which would fix g++ is to tell the user to modify a
 510       header-file so that g++-2 (egcs 1.x) and g++-3 (gcc 2.95.x) define a
 511       macro which tells <filename
 512         class="headerfile">&lt;ctype.h&gt;</filename> to define functions
 513       instead of macros:
 514       <programlisting>
 515         // This keeps isalnum, et al from being propagated as macros.
 516         #if __linux__
 517         #define __NO_CTYPE 1
 518         #endif
 519
 520         [ now include &lt;ctype.h&gt; ]
 521       </programlisting>
 522     </para>
 523     <para>
 524       Another problem arises if you put a <command>using namespace
 525         std;</command> declaration at the top, and include <filename class
 526         = "headerfile">&lt;ctype.h&gt;</filename>. This will result in
 527       ambiguities between the definitions in the global namespace
 528       (<filename class = "headerfile">&lt;ctype.h&gt;</filename>) and the
 529       definitions in namespace <command>std::</command>
 530       (<command>&lt;cctype&gt;</command>).
 531     </para>
 532     <para>
 533       The solution to this problem was posted to the libstdc++-v3
 534       mailing-list:
 535       Benjamin Kosnik <email>bkoz@redhat.com</email> writes:
 536       <quote>
 537         --enable-cshadow-headers is currently broken. As a result, shadow
 538         headers are not being searched....
 539       </quote>
 540       This is now outdated, but gcc 3.0 still does not have fully
 541       compliant "shadow headers".
 542     </para>
 543   </section>
 544
 545   <section id="sec-stream-state" label="7">
 546     <title id="sec-stream-state.title">State of streams</title>
 547     <para>
 548       At least some older implementations don't have
 549       <command>std::ios_base</command>, so you should use
 550       <command>std::ios::badbit</command>, <command>std::ios::failbit</command>
 551       and <command>std::ios::eofbit</command> and
 552       <command>std::ios::goodbit</command>.
 553     </para>
 554   </section>
 555
 556   <section id="sec-vector-at" label="8">
 557     <title>vector::at is missing (i.e. gcc 2.95.x)</title>
 558     <para>
 559       One solution is to add an autoconf-test for this:
 560       <programlisting>
 561         AC_MSG_CHECKING(for container::at)
 562         AC_TRY_COMPILE(
 563         [
 564         #include &lt;vector&gt;
 565         #include &lt;deque&gt;
 566         #include &lt;string&gt;
 567
 568         using namespace std;
 569         ],
 570         [
 571         deque&lt;int&gt; test_deque(3);
 572         test_deque.at(2);
 573         vector&lt;int&gt; test_vector(2);
 574         test_vector.at(1);
 575         string test_string("test_string");
 576         test_string.at(3);
 577         ],
 578         [AC_MSG_RESULT(yes)
 579         AC_DEFINE(HAVE_CONTAINER_AT)],
 580         [AC_MSG_RESULT(no)])
 581       </programlisting>
 582       If you are using other (non-GNU) compilers it might be a good idea
 583       to check for <command>string::at</command> separately.
 584     </para>
 585   </section>
 586
 587   <section id="sec-eof" label="9">
 588     <title>Using std::char_traits&lt;char&gt;::eof()</title>
 589     <para>
 590       <programlisting>
 591         #ifdef HAVE_CHAR_TRAITS
 592         #define CPP_EOF std::char_traits&lt;char&gt;::eof()
 593         #else
 594         #define CPP_EOF EOF
 595         #endif
 596       </programlisting>
 597     </para>
 598   </section>
 599
 600   <section id="sec-string-clear" label="10">
 601     <title>Using string::clear()/string::erase()</title>
 602     <para>
 603       There are two functions for deleting the contents of a string:
 604       <command>clear</command> and <command>erase</command> (the latter
 605       returns the string).
 606       <programlisting>
 607         void
 608         clear() { _M_mutate(0, this->size(), 0); }
 609       </programlisting>
 610       <programlisting>
 611         basic_string&amp;
 612         erase(size_type __pos = 0, size_type __n = npos)
 613         {
 614         return this->replace(_M_check(__pos), _M_fold(__pos, __n),
 615         _M_data(), _M_data());
 616         }
 617       </programlisting>
 618       The implementation of <command>erase</command> seems to be more
 619       complicated (from libstdc++-v3), but <command>clear</command> is not
 620       implemented in gcc 2.95.x's libstdc++, so you should use
 621       <command>erase</command> (which is probably faster than
 622       <command>operator=(charT*)</command>).
 623     </para>
 624   </section>
 625
 626   <section id="sec-scan-form" label="11">
 627     <title>GNU Extensions ostream::form and istream::scan</title>
 628     <para>
 629       These     are not supported any more - use
 630       <link     linkend="sec-stringstream" endterm="sec-stringstream.title">
 631         stringstreams</link> instead.
 632     </para>
 633   </section>
 634
 635   <section id="sec-stringstream" label="12">
 636     <title>Using stringstreams</title>
 637     <para>
 638       Libstdc++-v3 provides the new
 639       <command>i/ostringstream</command>-classes, (<filename
 640         class="headerfile">&lt;sstream&gt;</filename>), but for compatibility
 641       with older implementations you still have to use
 642       <command>i/ostrstream</command> (<filename
 643         class="headerfile">&lt;strstream&gt;</filename>):
 644       <programlisting>
 645         #ifdef HAVE_SSTREAM
 646         #include &lt;sstream&gt;
 647         #else
 648         #include &lt;strstream&gt;
 649         #endif
 650       </programlisting>
 651       <itemizedlist>
 652         <listitem><para> <command>strstream</command> is considered to be
 653             deprecated
 654           </para>
 655         </listitem>
 656         <listitem><para> <command>strstream</command> is limited to
 657             <command>char</command>
 658           </para>
 659         </listitem>
 660         <listitem><para> with <command>ostringstream</command> you don't
 661             have to take care of terminating the string or freeing its
 662             memory
 663           </para>
 664         </listitem>
 665         <listitem><para> <command>istringstream</command> can be re-filled
 666             (clear(); str(input);)
 667           </para>
 668         </listitem>
 669       </itemizedlist>
 670     </para>
 671     <para>
 672       You can then use output-stringstreams like this:
 673       <programlisting>
 674         #ifdef HAVE_SSTREAM
 675         std::ostringstream oss;
 676         #else
 677         std::ostrstream oss;
 678         #endif
 679         oss &lt;&lt; "Name=" &lt;&lt; m_name &lt;&lt; ", number=" &lt;&lt; m_number &lt;&lt; std::endl;
 680         ...
 681         #ifndef HAVE_SSTREAM
 682         oss &lt;&lt; std::ends; // terminate the char*-string
 683         #endif
 684         // str() returns char* for ostrstream and a string for ostringstream
 685         // this also causes ostrstream to think that the buffer's memory
 686         // is yours
 687         m_label.set_text(oss.str());
 688         #ifndef HAVE_SSTREAM
 689         // let the ostrstream take care of freeing the memory
 690         oss.freeze(false);
 691         #endif
 692       </programlisting>
 693     </para>
 694     <para>
 695       Input-stringstreams can be used similarly:
 696       <programlisting>
 697         std::string input;
 698         ...
 699         #ifdef HAVE_SSTREAM
 700         std::istringstream iss(input);
 701         #else
 702         std::istrstream iss(input.c_str());
 703         #endif
 704         int i;
 705         iss >> i;
 706       </programlisting>
 707       One (the only?) restriction is that an istrstream cannot be re-filled:
 708       <programlisting>
 709         std::istringstream iss(numerator);
 710         iss >> m_num;
 711         // this is not possible with istrstream
 712         iss.clear();
 713         iss.str(denominator);
 714         iss >> m_den;
 715       </programlisting>
 716       If you don't care about speed, you can put these conversions in
 717       a template-function:
 718       <programlisting>
 719         template &lt;class X&gt;
 720         void fromString(const string&amp; input, X&amp; any)
 721         {
 722         #ifdef HAVE_SSTREAM
 723         std::istringstream iss(input);
 724         #else
 725         std::istrstream iss(input.c_str());
 726         #endif
 727         X temp;
 728         iss >> temp;
 729         if (iss.fail())
 730         throw runtime_error(..)
 731         any = temp;
 732         }
 733       </programlisting>
 734       Another example of using stringstreams is in <ulink
 735         url="../21_strings/howto.html">this howto</ulink>.
 736     </para>
 737     <para>
 738       I have read the Josuttis book on Standard C++, so some information
 739       comes from there. Additionally, there is information in
 740       "info iostream", which covers the old implementation that gcc 2.95.x
 741       uses.
 742     </para>
 743   </section>
 744
 745   <section id = "sec-about" label="13">
 746     <title id="sec-about.title">About...</title>
 747     <para>
 748       Please send any experience, additions, corrections or questions to
 749       <ulink url = "mailto:fnatter@gmx.net">fnatter@gmx.net</ulink> or for
 750       discussion to the libstdc++-v3-mailing-list.
 751     </para>
 752   </section>
 753
 754 </article>
 755
 756   <!-- this is now obsolete, since the nwalsh-stylesheet generates an index
 757 <para>
 758 <itemizedlist>
 759 <listitem><para>
 760 <link linkend = "sec-nsstd" endterm = "sec-nsstd.title"/>
 761 </para></listitem>
 762 <listitem><para>
 763 <link linkend = "sec-nocreate" endterm = "sec-nocreate.title"/>
 764 </para></listitem>
 765 <listitem><para>
 766 <link linkend = "sec-stream::attach"
 767   endterm = "sec-stream::attach.title"/>
 768 </para></listitem>
 769 <listitem><para>
 770 <link linkend = "sec-headers" endterm = "sec-headers.title"/>
 771 </para></listitem>
 772 <listitem><para>
 773 <link linkend = "sec-iterators" endterm = "sec-iterators.title"/>
 774 </para></listitem>
 775 <listitem><para>
 776 <link linkend = "sec-macros" endterm = "sec-macros.title"/>
 777 </para></listitem>
 778 <listitem><para>
 779 <link linkend = "sec-about" endterm = "sec-about.title"/>
 780 </para></listitem>
 781 </itemizedlist>
 782 </para>
 783   -->
 784
 785 <!--
 786 Local Variables:
 787 compile-command: "xsltproc -o porting-howto.html docbook-xslt/docbook/html/docbook.xsl porting-howto.xml"
 788 End:
 789 -->