l4/pkg/libstdc++-v3/contrib/libstdc++-v3-4.1.0/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://libsigc.sourceforge.net">
 284                   libsigc++</ulink></entry>
 285               <entry>conservative-impl</entry>
 286             </row>
 287           </tbody>
 288         </tgroup>
 289       </table>
 290
 291       <table><title>Notations for categories</title>
 292         <tgroup cols = "2">
 293           <tbody>
 294             <row>
 295               <entry>usual</entry>
 296               <entry>mostly fully qualified names and some
 297                 using-declarations (but not in headers)</entry>
 298             </row>
 299             <row>
 300               <entry>none</entry> <entry>no namespace std at all</entry>
 301             </row>
 302             <row>
 303               <entry>conservative-impl</entry>
 304               <entry>wrap all
 305                 namespace-handling in macros to support compilers without
 306                 namespace-support (no libstdc++ used in headers)</entry>
 307             </row>
 308           </tbody>
 309         </tgroup>
 310       </table>
 311
 312       <para>
 313         As you can see, this currently lacks an example of a project
 314         which uses libstdc++-symbols in headers in a back-portable way
 315         (except for Gtk--: see the <link linkend="sec-gtkmm-hack"
 316           endterm="sec-gtkmm-hack.title">section on the gtkmm-hack</link>).
 317       </para>
 318     </section>
 319   </section> <!-- end of namespace-section -->
 320
 321   <section id = "sec-nocreate" label = "2">
 322     <title id="sec-nocreate.title">there is no ios::nocreate/ios::noreplace
 323       in ISO 14882</title>
 324     <para>
 325       I have seen <command>ios::nocreate</command> being used for
 326       input-streams, most probably because the author thought it would be
 327       more correct to specify nocreate "explicitly".  So you can simply
 328       leave it out for input-streams.
 329     </para>
 330     <para>
 331       For output streams, "nocreate" is probably the default, unless you
 332       specify <command>std::ios::trunc</command> ? To be safe, you can open
 333       the file for reading, check if it has been opened, and then decide
 334       whether you want to create/replace or not. To my knowledge, even
 335       older implementations support <command>app</command>,
 336       <command>ate</command> and <command>trunc</command> (except for
 337       <command>app</command> ?).
 338     </para>
 339   </section>
 340
 341   <section id = "sec-stream::attach" label = "3">
 342     <title id="sec-stream::attach.title"><command>stream::attach(int
 343         fd)</command> is not in the standard any more</title>
 344     <para>
 345       Phil Edwards <email>pedwards@disaster.jaj.com</email> writes:
 346       It was considered and rejected.  Not all environments use file
 347       descriptors.  Of those that do, not all of them use integers to represent
 348       them.
 349     </para>
 350     <para>
 351       When using libstdc++-v3, you can use
 352       <funcsynopsis>
 353         <funcsynopsisinfo format="linespecific">
 354           #include &lt;fstream&gt;
 355         </funcsynopsisinfo>
 356         <funcprototype>
 357           <funcdef>
 358             <function>basic_filebuf&lt;...&gt;::basic_filebuf&lt;...&gt;
 359             </function>
 360           </funcdef>
 361           <paramdef>__c_file_type* <parameter>file</parameter></paramdef>
 362           <paramdef>ios_base::open_mode <parameter>mode</parameter></paramdef>
 363           <paramdef>int <parameter>size</parameter></paramdef>
 364         </funcprototype>
 365       </funcsynopsis>
 366       but the the signature of this constructor has changed often, and
 367       it might change again. For the current state of this, check
 368       <ulink url="../ext/howto.html">the howto for extensions</ulink>.
 369     </para>
 370     <para>
 371       For a portable solution (among systems which use
 372       filedescriptors), you need to implement a subclass of
 373       <command>std::streambuf</command> (or
 374       <command>std::basic_streambuf&lt;..&gt;</command>) which opens a file
 375       given a descriptor, and then pass an instance of this to the
 376       stream-constructor.  For an example of this, refer to
 377       <ulink url="http://www.josuttis.com/cppcode/fdstream.html">fdstream example</ulink>
 378       by Nicolai Josuttis.
 379     </para>
 380   </section>
 381
 382   <section id = "sec-headers" label = "4">
 383     <title id="sec-headers.title">The new headers</title>
 384     <para>
 385       All new headers can be seen in this <ulink url="headers_cc.txt">
 386         source-code</ulink>.
 387     </para>
 388     <para>
 389       The old C++-headers (iostream.h etc.) are available, but gcc generates
 390       a warning that you are using deprecated headers.
 391     </para>
 392
 393     <section id = "sec-cheaders" label = "4.1">
 394       <title id="sec-cheaders.title">New headers replacing C-headers</title>
 395       <para>
 396         You should not use the C-headers (except for system-level
 397         headers) from C++ programs. Instead, you should use a set of
 398         headers that are named by prepending 'c' and, as usual,
 399         omitting the extension (.h). For example, instead of using
 400         <filename class="headerfile">&lt;math.h&gt;</filename>, you
 401         should use <filename class =
 402           "headerfile">&lt;cmath&gt;</filename>. In some cases this has
 403         the advantage that the C++-header is more standardized than
 404         the C-header (i.e. <filename
 405           class="headerfile">&lt;ctime&gt;</filename> (almost)
 406         corresponds to either <filename class =
 407           "headerfile">&lt;time.h&gt;</filename> or <filename class =
 408           "headerfile">&lt;sys/time.h&gt;</filename>).
 409
 410         The standard specifies that if you include the C-style header
 411         (<filename class = "headerfile">&lt;math.h&gt;</filename> in
 412         this case), the symbols will be available both in the global
 413         namespace and in namespace <command>std::</command> (but
 414         libstdc++ does not yet have fully compliant headers) On the
 415         other hand, if you include only the new header (i.e. <filename
 416           class = "headerfile">&lt;cmath&gt;</filename>), the symbols
 417         will only be defined in namespace <command>std::</command>
 418         (and macros will be converted to inline-functions).
 419       </para>
 420       <para>
 421         For more information on this, and for information on how the
 422         GNU C++ implementation might reuse ("shadow") the C
 423         library-functions, have a look at <ulink
 424           url="http://www.cantrip.org/cheaders.html">
 425           www.cantrip.org</ulink>.
 426       </para>
 427     </section>
 428
 429     <section id = "sec-fstream-header" label = "4.2">
 430       <title id="sec-fstream-header.title">
 431         <filename class="headerfile">&lt;fstream&gt;</filename> does
 432         not define <command>std::cout</command>,
 433         <command>std::cin</command> etc.</title>
 434       <para>
 435         In earlier versions of the standard,
 436         <filename class="headerfile">&lt;fstream.h&gt;</filename>,
 437         <filename class="headerfile">&lt;ostream.h&gt;</filename>
 438         and <filename class="headerfile">&lt;istream.h&gt;</filename>
 439         used to define
 440         <command>cout</command>, <command>cin</command> and so on. Because
 441         of the templatized iostreams in libstdc++-v3, you need to include
 442         <filename class = "headerfile">&lt;iostream&gt;</filename>
 443         explicitly to define these.
 444       </para>
 445     </section>
 446   </section>
 447
 448   <section id = "sec-iterators" label = "5">
 449     <title id="sec-iterators.title">Iterators</title>
 450     <para>
 451       The following are not proper uses of iterators, but may be working
 452       fixes for existing uses of iterators.
 453       <itemizedlist>
 454         <listitem><para>you cannot do
 455             <command>ostream::operator&lt;&lt;(iterator)</command> to
 456             print the address of the iterator =&gt; use
 457             <command>operator&lt;&lt; &amp;*iterator</command> instead ?
 458           </para>
 459         </listitem>
 460         <listitem><para>you cannot clear an iterator's reference
 461             (<command>iterator = 0</command>) =&gt; use
 462             <command>iterator = iterator_type();</command> ?
 463           </para>
 464         </listitem>
 465         <listitem><para><command>if (iterator)</command> won't work any
 466             more => use <command>if (iterator != iterator_type())</command>
 467             ?</para>
 468         </listitem>
 469       </itemizedlist>
 470     </para>
 471   </section>
 472
 473   <section id = "sec-macros" label = "6">
 474     <title id="sec-macros.title">
 475       Libc-macros (i.e. <command>isspace</command> from
 476       <filename class = "headerfile">&lt;cctype&gt;</filename>)</title>
 477     <para>
 478       Glibc 2.0.x and 2.1.x define the
 479       <filename class="headerfile">&lt;ctype.h&gt;</filename>
 480       -functionality as macros (isspace, isalpha etc.). Libstdc++-v3
 481       "shadows" these macros as described in the <link
 482         linkend="sec-cheaders" endterm="sec-cheaders.title">section about
 483         c-headers</link>.
 484     </para>
 485     <para>
 486       Older implementations of libstdc++ (g++-2 for egcs 1.x and g++-3
 487       for gcc 2.95.x), however, keep these functions as macros, and so it
 488       is not back-portable to use fully qualified names. For example:
 489       <programlisting>
 490         #include &lt;cctype&gt;
 491         int main() { std::isspace('X'); }
 492       </programlisting>
 493       will result in something like this (unless using g++-v3):
 494       <programlisting>
 495         std:: (__ctype_b[(int) ( ( 'X' ) )] &amp; (unsigned short int)
 496         _ISspace )  ;
 497       </programlisting>
 498     </para>
 499     <para>
 500       One solution I can think of is to test for -v3 using
 501       autoconf-macros, and define macros for each of the C-functions
 502       (maybe that is possible with one "wrapper" macro as well ?).
 503     </para>
 504     <para>
 505       Another solution which would fix g++ is to tell the user to modify a
 506       header-file so that g++-2 (egcs 1.x) and g++-3 (gcc 2.95.x) define a
 507       macro which tells <filename
 508         class="headerfile">&lt;ctype.h&gt;</filename> to define functions
 509       instead of macros:
 510       <programlisting>
 511         // This keeps isalnum, et al from being propagated as macros.
 512         #if __linux__
 513         #define __NO_CTYPE 1
 514         #endif
 515
 516         [ now include &lt;ctype.h&gt; ]
 517       </programlisting>
 518     </para>
 519     <para>
 520       Another problem arises if you put a <command>using namespace
 521         std;</command> declaration at the top, and include <filename class
 522         = "headerfile">&lt;ctype.h&gt;</filename>. This will result in
 523       ambiguities between the definitions in the global namespace
 524       (<filename class = "headerfile">&lt;ctype.h&gt;</filename>) and the
 525       definitions in namespace <command>std::</command>
 526       (<command>&lt;cctype&gt;</command>).
 527     </para>
 528     <para>
 529       The solution to this problem was posted to the libstdc++-v3
 530       mailing-list:
 531       Benjamin Kosnik <email>bkoz@redhat.com</email> writes:
 532       <quote>
 533         --enable-cshadow-headers is currently broken. As a result, shadow
 534         headers are not being searched....
 535       </quote>
 536       This is now outdated, but gcc 3.0 still does not have fully
 537       compliant "shadow headers".
 538     </para>
 539   </section>
 540
 541   <section id="sec-stream-state" label="7">
 542     <title id="sec-stream-state.title">State of streams</title>
 543     <para>
 544       At least some older implementations don't have
 545       <command>std::ios_base</command>, so you should use
 546       <command>std::ios::badbit</command>, <command>std::ios::failbit</command>
 547       and <command>std::ios::eofbit</command> and
 548       <command>std::ios::goodbit</command>.
 549     </para>
 550   </section>
 551
 552   <section id="sec-vector-at" label="8">
 553     <title>vector::at is missing (i.e. gcc 2.95.x)</title>
 554     <para>
 555       One solution is to add an autoconf-test for this:
 556       <programlisting>
 557         AC_MSG_CHECKING(for container::at)
 558         AC_TRY_COMPILE(
 559         [
 560         #include &lt;vector&gt;
 561         #include &lt;deque&gt;
 562         #include &lt;string&gt;
 563
 564         using namespace std;
 565         ],
 566         [
 567         deque&lt;int&gt; test_deque(3);
 568         test_deque.at(2);
 569         vector&lt;int&gt; test_vector(2);
 570         test_vector.at(1);
 571         string test_string("test_string");
 572         test_string.at(3);
 573         ],
 574         [AC_MSG_RESULT(yes)
 575         AC_DEFINE(HAVE_CONTAINER_AT)],
 576         [AC_MSG_RESULT(no)])
 577       </programlisting>
 578       If you are using other (non-GNU) compilers it might be a good idea
 579       to check for <command>string::at</command> separately.
 580     </para>
 581   </section>
 582
 583   <section id="sec-eof" label="9">
 584     <title>Using std::char_traits&lt;char&gt;::eof()</title>
 585     <para>
 586       <programlisting>
 587         #ifdef HAVE_CHAR_TRAITS
 588         #define CPP_EOF std::char_traits&lt;char&gt;::eof()
 589         #else
 590         #define CPP_EOF EOF
 591         #endif
 592       </programlisting>
 593     </para>
 594   </section>
 595
 596   <section id="sec-string-clear" label="10">
 597     <title>Using string::clear()/string::erase()</title>
 598     <para>
 599       There are two functions for deleting the contents of a string:
 600       <command>clear</command> and <command>erase</command> (the latter
 601       returns the string).
 602       <programlisting>
 603         void
 604         clear() { _M_mutate(0, this->size(), 0); }
 605       </programlisting>
 606       <programlisting>
 607         basic_string&amp;
 608         erase(size_type __pos = 0, size_type __n = npos)
 609         {
 610         return this->replace(_M_check(__pos), _M_fold(__pos, __n),
 611         _M_data(), _M_data());
 612         }
 613       </programlisting>
 614       The implementation of <command>erase</command> seems to be more
 615       complicated (from libstdc++-v3), but <command>clear</command> is not
 616       implemented in gcc 2.95.x's libstdc++, so you should use
 617       <command>erase</command> (which is probably faster than
 618       <command>operator=(charT*)</command>).
 619     </para>
 620   </section>
 621
 622   <section id="sec-scan-form" label="11">
 623     <title>GNU Extensions ostream::form and istream::scan</title>
 624     <para>
 625       These     are not supported any more - use
 626       <link     linkend="sec-stringstream" endterm="sec-stringstream.title">
 627         stringstreams</link> instead.
 628     </para>
 629   </section>
 630
 631   <section id="sec-stringstream" label="12">
 632     <title>Using stringstreams</title>
 633     <para>
 634       Libstdc++-v3 provides the new
 635       <command>i/ostringstream</command>-classes, (<filename
 636         class="headerfile">&lt;sstream&gt;</filename>), but for compatibility
 637       with older implementations you still have to use
 638       <command>i/ostrstream</command> (<filename
 639         class="headerfile">&lt;strstream&gt;</filename>):
 640       <programlisting>
 641         #ifdef HAVE_SSTREAM
 642         #include &lt;sstream&gt;
 643         #else
 644         #include &lt;strstream&gt;
 645         #endif
 646       </programlisting>
 647       <itemizedlist>
 648         <listitem><para> <command>strstream</command> is considered to be
 649             deprecated
 650           </para>
 651         </listitem>
 652         <listitem><para> <command>strstream</command> is limited to
 653             <command>char</command>
 654           </para>
 655         </listitem>
 656         <listitem><para> with <command>ostringstream</command> you don't
 657             have to take care of terminating the string or freeing its
 658             memory
 659           </para>
 660         </listitem>
 661         <listitem><para> <command>istringstream</command> can be re-filled
 662             (clear(); str(input);)
 663           </para>
 664         </listitem>
 665       </itemizedlist>
 666     </para>
 667     <para>
 668       You can then use output-stringstreams like this:
 669       <programlisting>
 670         #ifdef HAVE_SSTREAM
 671         std::ostringstream oss;
 672         #else
 673         std::ostrstream oss;
 674         #endif
 675         oss &lt;&lt; "Name=" &lt;&lt; m_name &lt;&lt; ", number=" &lt;&lt; m_number &lt;&lt; std::endl;
 676         ...
 677         #ifndef HAVE_SSTREAM
 678         oss &lt;&lt; std::ends; // terminate the char*-string
 679         #endif
 680         // str() returns char* for ostrstream and a string for ostringstream
 681         // this also causes ostrstream to think that the buffer's memory
 682         // is yours
 683         m_label.set_text(oss.str());
 684         #ifndef HAVE_SSTREAM
 685         // let the ostrstream take care of freeing the memory
 686         oss.freeze(false);
 687         #endif
 688       </programlisting>
 689     </para>
 690     <para>
 691       Input-stringstreams can be used similarly:
 692       <programlisting>
 693         std::string input;
 694         ...
 695         #ifdef HAVE_SSTREAM
 696         std::istringstream iss(input);
 697         #else
 698         std::istrstream iss(input.c_str());
 699         #endif
 700         int i;
 701         iss >> i;
 702       </programlisting>
 703       One (the only?) restriction is that an istrstream cannot be re-filled:
 704       <programlisting>
 705         std::istringstream iss(numerator);
 706         iss >> m_num;
 707         // this is not possible with istrstream
 708         iss.clear();
 709         iss.str(denominator);
 710         iss >> m_den;
 711       </programlisting>
 712       If you don't care about speed, you can put these conversions in
 713       a template-function:
 714       <programlisting>
 715         template &lt;class X&gt;
 716         void fromString(const string&amp; input, X&amp; any)
 717         {
 718         #ifdef HAVE_SSTREAM
 719         std::istringstream iss(input);
 720         #else
 721         std::istrstream iss(input.c_str());
 722         #endif
 723         X temp;
 724         iss >> temp;
 725         if (iss.fail())
 726         throw runtime_error(..)
 727         any = temp;
 728         }
 729       </programlisting>
 730       Another example of using stringstreams is in <ulink
 731         url="../21_strings/howto.html">this howto</ulink>.
 732     </para>
 733     <para>
 734       I have read the Josuttis book on Standard C++, so some information
 735       comes from there. Additionally, there is information in
 736       "info iostream", which covers the old implementation that gcc 2.95.x
 737       uses.
 738     </para>
 739   </section>
 740
 741   <section id = "sec-about" label="13">
 742     <title id="sec-about.title">About...</title>
 743     <para>
 744       Please send any experience, additions, corrections or questions to
 745       <ulink url = "mailto:fnatter@gmx.net">fnatter@gmx.net</ulink> or for
 746       discussion to the libstdc++-v3-mailing-list.
 747     </para>
 748   </section>
 749
 750 </article>
 751
 752   <!-- this is now obsolete, since the nwalsh-stylesheet generates an index
 753 <para>
 754 <itemizedlist>
 755 <listitem><para>
 756 <link linkend = "sec-nsstd" endterm = "sec-nsstd.title"/>
 757 </para></listitem>
 758 <listitem><para>
 759 <link linkend = "sec-nocreate" endterm = "sec-nocreate.title"/>
 760 </para></listitem>
 761 <listitem><para>
 762 <link linkend = "sec-stream::attach"
 763   endterm = "sec-stream::attach.title"/>
 764 </para></listitem>
 765 <listitem><para>
 766 <link linkend = "sec-headers" endterm = "sec-headers.title"/>
 767 </para></listitem>
 768 <listitem><para>
 769 <link linkend = "sec-iterators" endterm = "sec-iterators.title"/>
 770 </para></listitem>
 771 <listitem><para>
 772 <link linkend = "sec-macros" endterm = "sec-macros.title"/>
 773 </para></listitem>
 774 <listitem><para>
 775 <link linkend = "sec-about" endterm = "sec-about.title"/>
 776 </para></listitem>
 777 </itemizedlist>
 778 </para>
 779   -->
 780
 781 <!--
 782 Local Variables:
 783 compile-command: "xsltproc -o porting-howto.html docbook-xslt/docbook/html/docbook.xsl porting-howto.xml"
 784 End:
 785 -->