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

   1 <html>
   2   <head>
   3     <title>Libstdc++-porting-howto</title>
   4     <meta content="DocBook XSL Stylesheets V1.16" name="generator">
   5   </head>
   6   <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
   7     <div class="article" id="libstdporting">
   8       <div class="titlepage">
   9         <h1 class="title">
  10           <a name="libstdporting">Libstdc++-porting-howto</a>
  11         </h1>
  12         <h3 class="author">Felix Natter</h3>
  13         <p>
  14                 This document can be distributed under the FDL
  15                 (<a href="http://www.gnu.org">www.gnu.org</a>)
  16           </p>
  17         <p class="pubdate">what kind of a date ? I don't drink !</p>
  18         <div class="revhistory">
  19           <table width="100%" border="1">
  20             <tr>
  21               <th colspan="3" valign="top" align="left"><b>Revision History</b></th>
  22             </tr>
  23             <tr>
  24               <td align="left">Revision 0.5</td><td align="left">Thu Jun  1 13:06:50 2000</td><td align="left">fnatter</td>
  25             </tr>
  26             <tr>
  27               <td colspan="3" align="left">First docbook-version.</td>
  28             </tr>
  29             <tr>
  30               <td align="left">Revision 0.8</td><td align="left">Sun Jul 30 20:28:40 2000</td><td align="left">fnatter</td>
  31             </tr>
  32             <tr>
  33               <td colspan="3" align="left">First released version using docbook-xml
  34                   + second upload to libstdc++-page.
  35                 </td>
  36             </tr>
  37             <tr>
  38               <td align="left">Revision 0.9</td><td align="left">Wed Sep  6 02:59:32 2000</td><td align="left">fnatter</td>
  39             </tr>
  40             <tr>
  41               <td colspan="3" align="left">5 new sections.</td>
  42             </tr>
  43           </table>
  44         </div>
  45         <div class="abstract">
  46           <p>
  47             <a name="N2688"></a><b>Abstract</b>
  48           </p>
  49           <p>
  50                 Some notes on porting applications from libstdc++-2.90 (or earlier
  51                 versions) to libstdc++-v3. Not speaking in terms of the GNU libstdc++
  52                 implementations, this means porting from earlier versions of the
  53                 C++-Standard to ISO 14882.
  54           </p>
  55         </div>
  56         <hr>
  57       </div>
  58       <div class="toc">
  59         <p>
  60           <b>Table of Contents</b>
  61         </p>
  62         <dl>
  63           <dt>1. <a href="#sec-nsstd">Namespace std::</a>
  64           </dt>
  65           <dd>
  66             <dl>
  67               <dt>1.1.1. <a href="#sec-gtkmm-hack">Using <i>namespace
  68                 composition</i> if the project uses a separate
  69                 namespace</a>
  70               </dt>
  71               <dt>1.1.2. <a href="#sec-emptyns">Defining an empty namespace std</a>
  72               </dt>
  73               <dt>1.1.3. <a href="#sec-avoidfqn">Avoid to use fully qualified names
  74           (i.e. std::string)</a>
  75               </dt>
  76               <dt>1.1.4. <a href="#sec-osprojects">How some open-source-projects deal
  77           with this</a>
  78               </dt>
  79             </dl>
  80           </dd>
  81           <dt>2. <a href="#sec-nocreate">there is no ios::nocreate/ios::noreplace
  82           in ISO 14882</a>
  83           </dt>
  84           <dt>3. <a href="#sec-stream::attach"><b>stream::attach(int
  85           fd)</b> is not in the standard any more</a>
  86           </dt>
  87           <dt>4. <a href="#sec-headers">The new headers</a>
  88           </dt>
  89           <dd>
  90             <dl>
  91               <dt>4.4.1. <a href="#sec-cheaders">New headers replacing C-headers</a>
  92               </dt>
  93               <dt>4.4.2. <a href="#sec-fstream-header">
  94                 <tt>&lt;fstream&gt;</tt> does
  95                 not define <b>std::cout</b>,
  96                 <b>std::cin</b> etc.</a>
  97               </dt>
  98             </dl>
  99           </dd>
 100           <dt>5. <a href="#sec-iterators">Iterators</a>
 101           </dt>
 102           <dt>6. <a href="#sec-macros">
 103           Libc-macros (i.e. <b>isspace</b> from
 104           <tt>&lt;cctype&gt;</tt>)</a>
 105           </dt>
 106           <dt>7. <a href="#sec-stream-state">
 107           State of streams
 108         </a>
 109           </dt>
 110           <dt>8. <a href="#sec-vector-at">vector::at is missing (i.e. gcc 2.95.2)</a>
 111           </dt>
 112           <dt>9. <a href="#sec-eof">Using std::char_traits&lt;char&gt;::eof()</a>
 113           </dt>
 114           <dt>10. <a href="#sec-string-clear">Using string::clear()/string::erase()</a>
 115           </dt>
 116           <dt>11. <a href="#sec-stringstream">Using stringstream's</a>
 117           </dt>
 118           <dt>12. <a href="#sec-about">About...</a>
 119           </dt>
 120         </dl>
 121       </div>
 122       <p>
 123         In the following, when I say portable, I will refer to "portable among ISO
 124         14882-implementations". On the other hand, if I say "backportable" or
 125         "conservative", I am talking about "compiles with older
 126         libstdc++-implementations".
 127   </p>
 128       <div class="section" id="sec-nsstd">
 129         <h2 class="title" style="clear: all">
 130           <a name="sec-nsstd"><b>1. Namespace std::</b></a>
 131         </h2>
 132         <p>
 133           The latest C++-standard (ISO-14882) requires that the standard
 134           C++-library is defined in namespace std::. Thus, in order to use
 135           classes from the standard C++-library, you can do one of three
 136           things:
 137           <div class="itemizedlist">
 138             <ul>
 139               <li>
 140                 <a name="N2712"></a>
 141                 <p>wrap your code in <b>namespace std {
 142                           ... }</b> =&gt; This is not an option because only symbols
 143                         from the standard c++-library are defined in namespace std::.
 144                   </p>
 145               </li>
 146               <li>
 147                 <a name="N2721"></a>
 148                 <p>put a kind of
 149                         <i>using-declaration</i> in your source (either
 150                         <b>using namespace std;</b> or i.e. <b>using
 151                           std::string;</b>) =&gt; works well for source-files, but
 152                         cannot be used in header-files.
 153                   </p>
 154               </li>
 155               <li>
 156                 <a name="N2736"></a>
 157                 <p>use a <i>fully qualified name</i> for
 158                         each libstdc++-symbol (i.e. <b>std::string</b>,
 159                         <b>std::cout</b>) =&gt; can always be used
 160                   </p>
 161               </li>
 162             </ul>
 163           </div>
 164         </p>
 165         <p>
 166           Because there are many compilers which still use an implementation
 167           that does not have the standard C++-library in namespace
 168           <b>std::</b>, some care is required to support these as
 169           well.
 170         </p>
 171         <p>
 172           Namespace back-portability-issues are generally not a problem with
 173           g++, because versions of g++ that do not have libstdc++ in
 174           <b>std::</b> use <b>-fno-honor-std</b>
 175           (ignore <b>std::</b>, <b>:: = std::</b>) by
 176           default. That is, the responsibility for enabling or disabling
 177           <b>std::</b> is on the user; the maintainer does not have
 178           to care about it. This probably applies to some other compilers as
 179           well.
 180         </p>
 181         <p>
 182           The following sections list some possible solutions to support compilers
 183           that cannot ignore std::.
 184         </p>
 185         <div class="section" id="sec-gtkmm-hack">
 186           <h3 class="title">
 187             <a name="sec-gtkmm-hack"><b>1.1.1. Using <i>namespace
 188                 composition</i> if the project uses a separate
 189                 namespace</b></a>
 190           </h3>
 191           <p>
 192                 <a href="http://gtkmm.sourceforge.net">Gtk--</a> defines
 193                 most of its classes in namespace Gtk::. Thus, it was possible to
 194                 adapt Gtk-- to namespace std:: by using a C++-feature called
 195                 <i>namespace composition</i>. This is what happens if
 196                 you put a <i>using</i>-declaration into a
 197                 namespace-definition: the imported symbol(s) gets imported into the
 198                 currently active namespace(s). For example:
 199                 <pre class="programlisting">
 200                   namespace Gtk {
 201                   using std::string;
 202                   class Window { ... }
 203                   }
 204                 </pre>
 205                 In this example, <b>std::string</b> gets imported into
 206                 namespace Gtk::.  The result is that you don't have to use
 207                 <b>std::string</b> in this header, but still
 208                 <b>std::string</b> does not get imported into
 209                 user-space (the global namespace ::) unless the user does
 210                 <b>using namespace Gtk;</b> (which is not recommended
 211                 practice for Gtk--, so it is not a problem).  Additionally, the
 212                 <b>using</b>-declarations are wrapped in macros that
 213                 are set based on autoconf-tests to either "" or i.e. <b>using
 214                   std::string;</b> (depending on whether the system has
 215                 libstdc++ in <b>std::</b> or not).  (ideas from
 216                 <tt>&lt;<a href="mailto:llewelly@dbritsch.dsl.xmission.com">llewelly@dbritsch.dsl.xmission.com</a>&gt;</tt>, Karl Nelson
 217                 <tt>&lt;<a href="mailto:kenelson@ece.ucdavis.edu">kenelson@ece.ucdavis.edu</a>&gt;</tt>)
 218           </p>
 219         </div>
 220         <div class="section" id="sec-emptyns">
 221           <h3 class="title">
 222             <a name="sec-emptyns"><b>1.1.2. Defining an empty namespace std</b></a>
 223           </h3>
 224           <p>
 225                 By defining an (empty) namespace <b>std::</b> before
 226                 using it, you avoid getting errors on systems where no part of the
 227                 library is in namespace std:
 228                 <pre class="programlisting">
 229                   namespace std { }
 230                   using namespace std;
 231                 </pre>
 232           </p>
 233         </div>
 234         <div class="section" id="sec-avoidfqn">
 235           <h3 class="title">
 236             <a name="sec-avoidfqn"><b>1.1.3. Avoid to use fully qualified names
 237           (i.e. std::string)</b></a>
 238           </h3>
 239           <p>
 240                 If some compilers complain about <b>using
 241                   std::string;</b>, and if the "hack" for gtk-- mentioned above
 242                 does not work, then it might be a good idea to define a macro
 243                 NS_STD, which is defined to either "" or "std"
 244                 based on an autoconf-test. Then you should be able to use
 245                 <b>NS_STD::string</b>, which will evaluate to
 246                 <b>::string</b> ("string in the global namespace") on
 247                 systems that do not put string in std::.  (This is untested)
 248           </p>
 249         </div>
 250         <div class="section" id="sec-osprojects">
 251           <h3 class="title">
 252             <a name="sec-osprojects"><b>1.1.4. How some open-source-projects deal
 253           with this</b></a>
 254           </h3>
 255           <p>
 256                 This information was gathered around May 2000. It may not be correct
 257                 by the time you read this.
 258           </p>
 259           <div class="table">
 260             <p>
 261               <a name="N2901"></a><b>Table 1. Namespace std:: in Open-Source programs</b>
 262             </p>
 263             <table border="1">
 264               <colgroup>
 265                 <col>
 266                 <col>
 267               </colgroup>
 268               <tbody>
 269                 <tr>
 270                   <td><a href="http://www.clanlib.org">clanlib</a></td><td>usual</td>
 271                 </tr>
 272                 <tr>
 273                   <td><a href="http://pingus.seul.org">pingus</a></td><td>usual</td>
 274                 </tr>
 275                 <tr>
 276                   <td><a href="http://www.mozilla.org">mozilla</a></td><td>usual</td>
 277                 </tr>
 278                 <tr>
 279                   <td><a href="http://www.mnemonic.org">mnemonic</a></td><td>none</td>
 280                 </tr>
 281                 <tr>
 282                   <td><a href="http://libsigc.sourceforge.net">
 283                                   libsigc++</a></td><td>conservative-impl</td>
 284                 </tr>
 285               </tbody>
 286             </table>
 287           </div>
 288           <div class="table">
 289             <p>
 290               <a name="N2978"></a><b>Table 2. Notations for categories</b>
 291             </p>
 292             <table border="1">
 293               <colgroup>
 294                 <col>
 295                 <col>
 296               </colgroup>
 297               <tbody>
 298                 <tr>
 299                   <td>usual</td><td>mostly fully qualified names and some
 300                                 using-declarations (but not in headers)</td>
 301                 </tr>
 302                 <tr>
 303                   <td>none</td><td>no namespace std at all</td>
 304                 </tr>
 305                 <tr>
 306                   <td>conservative-impl</td><td>wrap all
 307                                 namespace-handling in macros to support compilers without
 308                                 namespace-support (no libstdc++ used in headers)</td>
 309                 </tr>
 310               </tbody>
 311             </table>
 312           </div>
 313           <p>
 314                 As you can see, this currently lacks an example of a project which
 315                 uses libstdc++-symbols in headers in a back-portable way (except
 316                 for Gtk--: see the <a href="#"></a>).
 317           </p>
 318         </div>
 319       </div>
 320       <div class="section" id="sec-nocreate">
 321         <h2 class="title" style="clear: all">
 322           <a name="sec-nocreate"><b>2. there is no ios::nocreate/ios::noreplace
 323           in ISO 14882</b></a>
 324         </h2>
 325         <p>
 326           I have seen <b>ios::nocreate</b> being used for input-streams,
 327           most probably because the authors thought it would be more correct
 328           to specify nocreate "explicitly".  So you can simply leave it out
 329           for input-streams.
 330         </p>
 331         <p>
 332           For output streams, "nocreate" is probably the default, unless you
 333           specify <b>std::ios::trunc</b> ? To be safe, you can open
 334           the file for reading, check if it has been opened, and then decide
 335           whether you want to create/replace or not. To my knowledge, even
 336           older implementations support <b>app</b>,
 337           <b>ate</b> and <b>trunc</b> (except for
 338           <b>app</b> ?).
 339         </p>
 340       </div>
 341       <div class="section" id="sec-stream::attach">
 342         <h2 class="title" style="clear: all">
 343           <a name="sec-stream::attach"><b>3. <b>stream::attach(int
 344           fd)</b> is not in the standard any more</b></a>
 345         </h2>
 346         <p>
 347           When using libstdc++-v3, you can use
 348           <div id="N3082" class="funcsynopsis">
 349             <p>
 350             </p>
 351             <a name="N3082"></a>
 352             <pre class="funcsynopsisinfo">
 353                   #include &lt;fstream&gt;
 354                 </pre>
 355             <p>
 356               <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>
 357             </p>
 358             <p>
 359             </p>
 360           </div>
 361           For a portable solution (if there is one), you need to implement a
 362           subclass of <b>streambuf</b> which opens a file given a
 363           descriptor, and then pass an instance of this to the
 364           stream-constructor (from the Josuttis-book).
 365         </p>
 366       </div>
 367       <div class="section" id="sec-headers">
 368         <h2 class="title" style="clear: all">
 369           <a name="sec-headers"><b>4. The new headers</b></a>
 370         </h2>
 371         <p>
 372           All new headers can be seen in this <a href="../../testsuite/17_intro/headers.cc">source-code</a>.
 373         </p>
 374         <p>
 375           I think it is a problem for libstdc++-v3 to add links or wrappers
 376           for the old headers, because the implementation has changed, and
 377           the header name-changes indicate this. It might be preferable to
 378           use the new headers and tell users of old compilers that they
 379           should create links (which is what they will have to do sometime
 380           anyway).
 381         </p>
 382         <div class="section" id="sec-cheaders">
 383           <h3 class="title">
 384             <a name="sec-cheaders"><b>4.4.1. New headers replacing C-headers</b></a>
 385           </h3>
 386           <p>
 387                 You should not use the C-headers (except for system-level headers)
 388                 from C++ programs. Instead, you should use a set of headers that
 389                 are named by prepending 'c' and, as usual, ommiting the extension
 390                 (.h). For example, instead of using <tt>&lt;math.h&gt;</tt>, you should use <tt>&lt;cmath&gt;</tt>. The standard
 391                 specifies that if you include the C-style header (<tt>&lt;math.h&gt;</tt> in this case), the symbols
 392                 will be available both in the global namespace and in namespace
 393                 <b>std::</b> (libstdc++-v3, version 2.90.8 currently
 394                 puts them in <b>std::</b> only) On the other hand, if
 395                 you include only the new header (i.e. <tt>&lt;pcmath&gt;</tt>), the symbols will only be
 396                 defined in namespace <b>std::</b> (and macros will be
 397                 converted to inline-functions).
 398           </p>
 399           <p>
 400                 For more information on this, and for information on how the GNU
 401                 C++ implementation reuses ("shadows") the C library-functions, have
 402                 a look at <a href="http://www.cantrip.org/cheaders.html">
 403                   www.cantrip.org</a>.
 404           </p>
 405         </div>
 406         <div class="section" id="sec-fstream-header">
 407           <h3 class="title">
 408             <a name="sec-fstream-header"><b>4.4.2.
 409                 <tt>&lt;fstream&gt;</tt> does
 410                 not define <b>std::cout</b>,
 411                 <b>std::cin</b> etc.</b></a>
 412           </h3>
 413           <p>
 414                 In previous versions of the standard, <tt>&lt;fstream.h&gt;</tt>, <tt>&lt;ostream.h&gt;</tt> and <tt>&lt;istream.h&gt;</tt> used to define
 415                 <b>cout</b>, <b>cin</b> and so on. Because
 416                 of the templatized iostreams in libstdc++-v3, you need to include
 417                 <tt>&lt;iostream&gt;</tt>
 418                 explicitly to define these.
 419           </p>
 420         </div>
 421       </div>
 422       <div class="section" id="sec-iterators">
 423         <h2 class="title" style="clear: all">
 424           <a name="sec-iterators"><b>5. Iterators</b></a>
 425         </h2>
 426         <p>
 427           The following are not proper uses of iterators, but may be working
 428           fixes for existing uses of iterators.
 429           <div class="itemizedlist">
 430             <ul>
 431               <li>
 432                 <a name="N3282"></a>
 433                 <p>you cannot do
 434                         <b>ostream::operator&lt;&lt;(iterator)</b> to
 435                         print the address of the iterator =&gt; use
 436                         <b>operator&lt;&lt; &amp;*iterator</b> instead ?
 437                   </p>
 438               </li>
 439               <li>
 440                 <a name="N3303"></a>
 441                 <p>you cannot clear an iterator's reference
 442                         (<b>iterator = 0</b>) =&gt; use
 443                         <b>iterator = iterator_type();</b> ?
 444                   </p>
 445               </li>
 446               <li>
 447                 <a name="N3316"></a>
 448                 <p>
 449                   <b>if (iterator)</b> won't work any
 450                         more =&gt; use <b>if (iterator != iterator_type())</b>
 451                         ?</p>
 452               </li>
 453             </ul>
 454           </div>
 455         </p>
 456       </div>
 457       <div class="section" id="sec-macros">
 458         <h2 class="title" style="clear: all">
 459           <a name="sec-macros"><b>6.
 460           Libc-macros (i.e. <b>isspace</b> from
 461           <tt>&lt;cctype&gt;</tt>)</b></a>
 462         </h2>
 463         <p>
 464           Glibc 2.0.x and 2.1.x define the <tt>&lt;ctype.h&gt;</tt> -functionality as
 465           macros (isspace, isalpha etc.). Libstdc++-v3 "shadows" these macros
 466           as described in the <a href="#"></a>.
 467         </p>
 468         <p>
 469           Older implementations of libstdc++ (g++-2 for egcs 1.x and g++-3
 470           for gcc 2.95.2), however, keep these functions as macros, and so it
 471           is not back-portable to use fully qualified names. For example:
 472           <pre class="programlisting">
 473                 #include &lt;cctype&gt;
 474                 int main() { std::isspace('X'); }
 475           </pre>
 476           will result in something like this (unless using g++-v3):
 477           <pre class="programlisting">
 478                 std:: (__ctype_b[(int) ( ( 'X' ) )] &amp; (unsigned short int)
 479                 _ISspace )  ;
 480           </pre>
 481           </p>
 482         <p>
 483           One solution I can think of is to test for -v3 using
 484           autoconf-macros, and define macros for each of the C-functions
 485           (maybe that is possible with one "wrapper" macro as well ?).
 486         </p>
 487         <p>
 488           Another solution which would fix g++ is to tell the user to modify a
 489           header-file so that g++-2 (egcs 1.x) and g++-3 (gcc 2.95.2) define a
 490           macro which tells <tt>&lt;ctype.h&gt;</tt> to define functions
 491           instead of macros:
 492           <pre class="programlisting">
 493                 // This keeps isalnum, et al from being propagated as macros.
 494                 #if __linux__
 495                 #define __NO_CTYPE 1
 496                 #endif
 497
 498                 [ now include &lt;ctype.h&gt; ]
 499           </pre>
 500         </p>
 501         <p>
 502           Another problem arises if you put a <b>using namespace
 503                 std;</b> declaration at the top, and include <tt>&lt;ctype.h&gt;</tt>. This will result in
 504                 ambiguities between the definitions in the global namespace
 505                 (<tt>&lt;ctype.h&gt;</tt>) and the
 506                 definitions in namespace <b>std::</b>
 507                 (<b>&lt;cctype&gt;</b>).
 508         </p>
 509         <p>
 510           The solution to this problem was posted to the libstdc++-v3
 511           mailing-list:
 512           Benjamin Kosnik <tt>&lt;<a href="mailto:bkoz@redhat.com">bkoz@redhat.com</a>&gt;</tt> writes:
 513           "
 514                 --enable-cshadow-headers is currently broken. As a result, shadow
 515                 headers are not being searched....
 516           "
 517         </p>
 518       </div>
 519       <div class="section" id="sec-stream-state">
 520         <h2 class="title" style="clear: all">
 521           <a name="sec-stream-state"><b>7.
 522           State of streams
 523         </b></a>
 524         </h2>
 525         <p>
 526           At least some older implementations don't have
 527           <b>std::ios_base</b>, so you should use
 528           <b>std::ios::badbit</b>, <b>std::ios::failbit</b>
 529           and <b>std::ios::eofbit</b> and
 530           <b>std::ios::goodbit</b>.
 531         </p>
 532       </div>
 533       <div class="section" id="sec-vector-at">
 534         <h2 class="title" style="clear: all">
 535           <a name="sec-vector-at"><b>8. vector::at is missing (i.e. gcc 2.95.2)</b></a>
 536         </h2>
 537         <p>
 538           For my use, I added it to
 539           <tt>prefix/include/g++-3/stl_vector.h</tt>:
 540           <pre class="programlisting">
 541   reference operator[](size_type __n) { return *(begin() + __n); }
 542   reference at(size_type __n) {
 543     if (begin() + __n &gt;= end())
 544       throw out_of_range("vector::at");
 545     return *(begin() + __n);
 546   }
 547   const_reference operator[](size_type __n) const { return *(begin() + __n); }
 548   const_reference at(size_type __n) const {
 549     if (begin() + __n &gt;= end())
 550       throw out_of_range("vector::at");
 551     return *(begin() + __n);
 552   }
 553           </pre>
 554         </p>
 555       </div>
 556       <div class="section" id="sec-eof">
 557         <h2 class="title" style="clear: all">
 558           <a name="sec-eof"><b>9. Using std::char_traits&lt;char&gt;::eof()</b></a>
 559         </h2>
 560         <p>
 561           <pre class="programlisting">
 562                 #ifdef HAVE_CHAR_TRAITS
 563                 #define CPP_EOF std::char_traits&lt;char&gt;::eof()
 564                 #else
 565                 #define CPP_EOF EOF
 566                 #endif
 567           </pre>
 568         </p>
 569       </div>
 570       <div class="section" id="sec-string-clear">
 571         <h2 class="title" style="clear: all">
 572           <a name="sec-string-clear"><b>10. Using string::clear()/string::erase()</b></a>
 573         </h2>
 574         <p>
 575           There are two functions for deleting the contents of a string:
 576           <b>clear</b> and <b>erase</b> (the latter
 577           returns the string).
 578           <pre class="programlisting">
 579                 void
 580                 clear() { _M_mutate(0, this-&gt;size(), 0); }
 581           </pre>
 582           <pre class="programlisting">
 583       basic_string&amp;
 584       erase(size_type __pos = 0, size_type __n = npos)
 585       {
 586                 return this-&gt;replace(_M_check(__pos), _M_fold(__pos, __n),
 587                              _M_data(), _M_data());
 588       }
 589           </pre>
 590           The implementation of <b>erase</b> seems to be more
 591           complicated (from libstdc++-v3), but <b>clear</b> is not
 592           implemented in gcc 2.95.2's libstdc++, so you should use
 593           <b>erase</b> (which is probably faster than
 594           <b>operator=(charT*)</b>).
 595         </p>
 596       </div>
 597       <div class="section" id="sec-stringstream">
 598         <h2 class="title" style="clear: all">
 599           <a name="sec-stringstream"><b>11. Using stringstream's</b></a>
 600         </h2>
 601         <p>
 602           Libstdc++-v3 includes the new
 603           <b>i/ostringstream</b>-classes, (<tt>&lt;sstream&gt;</tt>), but with older
 604           implementations you still have to use <b>i/ostrstream</b>
 605           (<tt>&lt;strstream&gt;</tt>):
 606           <pre class="programlisting">
 607                 #ifdef HAVE_SSTREAM
 608                 #include &lt;sstream&gt;
 609                 #else
 610                 #include &lt;strstream&gt;
 611                 #endif
 612           </pre>
 613           <div class="itemizedlist">
 614             <ul>
 615               <li>
 616                 <a name="N3595"></a>
 617                 <p> <b>strstream</b> is considered to be
 618                         deprecated
 619                   </p>
 620               </li>
 621               <li>
 622                 <a name="N3603"></a>
 623                 <p> <b>strstream</b> is limited to
 624                         <b>char</b>
 625                   </p>
 626               </li>
 627               <li>
 628                 <a name="N3614"></a>
 629                 <p> with <b>ostringstream</b> you don't
 630                         have to take care of terminating the string or freeing its
 631                         memory
 632                   </p>
 633               </li>
 634               <li>
 635                 <a name="N3622"></a>
 636                 <p> <b>istringstream</b> can be re-filled
 637                         (clear(); str(input);)
 638                   </p>
 639               </li>
 640             </ul>
 641           </div>
 642         </p>
 643         <p>
 644           You can then use output-stringstreams like this:
 645           <pre class="programlisting">
 646                 #ifdef HAVE_SSTREAM
 647                 std::ostringstream oss;
 648                 #else
 649                 std::ostrstream oss;
 650                 #endif
 651                 oss &lt;&lt; "Name=" &lt;&lt; m_name &lt;&lt; ", number=" &lt;&lt; m_number &lt;&lt; std::endl;
 652                 ...
 653                 #ifndef HAVE_SSTREAM
 654                 oss &lt;&lt; std::ends; // terminate the char*-string
 655                 #endif
 656                 // str() returns char* for ostrstream and a string for ostringstream
 657                 // this also causes ostrstream to think that the buffer's memory
 658                 // is yours
 659                 m_label.set_text(oss.str());
 660                 #ifndef HAVE_SSTREAM
 661                 // let the ostrstream take care of freeing the memory
 662                 oss.freeze(false);
 663                 #endif
 664           </pre>
 665         </p>
 666         <p>
 667           Input-stringstreams can be used similarly:
 668           <pre class="programlisting">
 669                 std::string input;
 670                 ...
 671                 #ifdef HAVE_SSTREAM
 672                 std::istringstream iss(input);
 673                 #else
 674                 std::istrstream iss(input.c_str());
 675                 #endif
 676                 int i;
 677                 iss &gt;&gt; i;
 678           </pre>
 679           One (the only?) restriction is that an istrstream cannot be re-filled:
 680           <pre class="programlisting">
 681                 std::istringstream iss(numerator);
 682                 iss &gt;&gt; m_num;
 683                 // this is not possible with istrstream
 684                 iss.clear();
 685                 iss.str(denominator);
 686                 iss &gt;&gt; m_den;
 687           </pre>
 688           If you don't care about speed, you can put these conversions in
 689           a template-function:
 690           <pre class="programlisting">
 691                 template &lt;class X&gt;
 692                 void fromString(const string&amp; input, X&amp; any)
 693                 {
 694                 #ifdef HAVE_SSTREAM
 695                 std::istringstream iss(input);
 696                 #else
 697                 std::istrstream iss(input.c_str());
 698                 #endif
 699                 X temp;
 700                 iss &gt;&gt; temp;
 701                 if (iss.fail())
 702                    throw runtime_error(..)
 703                 any = temp;
 704                 }
 705           </pre>
 706         </p>
 707         <p>
 708           I have read the Josuttis book on Standard C++, so some information
 709           comes from there. Additionally, there is information in
 710           "info iostream", which covers the old implementation that gcc 2.95.2
 711           uses.
 712         </p>
 713       </div>
 714       <div class="section" id="sec-about">
 715         <h2 class="title" style="clear: all">
 716           <a name="sec-about"><b>12. About...</b></a>
 717         </h2>
 718         <p>
 719           Please send any experience, additions, corrections or questions to
 720           <a href="mailto:fnatter@gmx.net">fnatter@gmx.net</a> or for
 721           discussion to the libstdc++-v3-mailing-list.
 722         </p>
 723       </div>
 724     </div>
 725   </body>
 726 </html>