libstdc++-v3/docs/html/ext/howto.html

   1 <?xml version="1.0" encoding="ISO-8859-1"?>
   2 <!DOCTYPE html
   3           PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
   4           "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   5
   6 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
   7 <head>
   8    <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
   9    <meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)" />
  10    <meta name="KEYWORDS" content="HOWTO, libstdc++, GCC, g++, libg++, STL" />
  11    <meta name="DESCRIPTION" content="Notes for the libstdc++ extensions." />
  12    <meta name="GENERATOR" content="vi and eight fingers" />
  13    <title>libstdc++-v3 HOWTO:  Extensions</title>
  14 <link rel="StyleSheet" href="../lib3styles.css" type="text/css" />
  15 <link rel="Start" href="../documentation.html" type="text/html"
  16   title="GNU C++ Standard Library" />
  17 <link rel="Prev" href="../27_io/howto.html" type="text/html"
  18   title="Input/Output" />
  19 <link rel="Bookmark" href="sgiexts.html" type="text/html"
  20   title="SGI extensions" />
  21 <link rel="Bookmark" href="mt_allocator.html" type="text/html"
  22   title="__mt_alloc" />
  23 <link rel="Copyright" href="../17_intro/license.html" type="text/html" />
  24 </head>
  25 <body>
  26
  27 <h1 class="centered"><a name="top">Extensions</a></h1>
  28
  29 <p>Here we will make an attempt at describing the non-Standard extensions to
  30    the library.  Some of these are from SGI's STL, some of these are GNU's,
  31    and some just seemed to appear on the doorstep.
  32 </p>
  33 <p><strong>Before you leap in and use these</strong>, be aware of two things:
  34 </p>
  35 <ol>
  36    <li>Non-Standard means exactly that.  The behavior, and the very
  37        existence, of these extensions may change with little or no
  38        warning.  (Ideally, the really good ones will appear in the next
  39        revision of C++.)  Also, other platforms, other compilers, other
  40        versions of g++ or libstdc++-v3 may not recognize these names, or
  41        treat them differently, or... </li>
  42    <li>You should know how to <a href="../faq/index.html#5_4">access
  43        these headers properly</a>. </li>
  44 </ol>
  45
  46
  47 <!-- ####################################################### -->
  48 <hr />
  49 <h1>Contents</h1>
  50 <ul>
  51    <li><a href="#1">Ropes and trees and hashes, oh my!</a></li>
  52    <li><a href="#2">Added members and types</a></li>
  53    <li><a href="mt_allocator.html"><code>__mt_alloc</code> </a></li>
  54    <li><a href="#4">Compile-time checks</a></li>
  55    <li><a href="#5">LWG Issues</a></li>
  56    <li><a href="../18_support/howto.html#6">Demangling</a></li>
  57 </ul>
  58
  59 <hr />
  60
  61 <!-- ####################################################### -->
  62
  63 <h2><a name="1">Ropes and trees and hashes, oh my!</a></h2>
  64    <p>The SGI headers</p>
  65    <pre>
  66      &lt;bvector&gt;
  67      &lt;hash_map&gt;
  68      &lt;hash_set&gt;
  69      &lt;rope&gt;
  70      &lt;slist&gt;
  71      &lt;tree&gt;
  72    </pre>
  73    <p>are all here; <code>&lt;bvector&gt;</code> exposes the old bit_vector
  74       class that was used before specialization of vector&lt;bool&gt; was
  75       available (it's actually a typedef for the specialization now).
  76       <code>&lt;hash_map&gt;</code> and <code>&lt;hash_set&gt;</code>
  77       are discussed further below.  <code>&lt;rope&gt;</code> is the SGI
  78       specialization for large strings (&quot;rope,&quot; &quot;large
  79       strings,&quot; get it?  love those SGI folks).
  80       <code>&lt;slist&gt;</code> is a singly-linked list, for when the
  81       doubly-linked <code>list&lt;&gt;</code> is too much space overhead, and
  82       <code>&lt;tree&gt;</code> exposes the red-black tree classes used in the
  83       implementation of the standard maps and sets.
  84    </p>
  85    <p>Okay, about those hashing classes...  I'm going to foist most of the
  86       work off onto SGI's own site.
  87    </p>
  88    <p>Each of the associative containers map, multimap, set, and multiset
  89       have a counterpart which uses a
  90       <a href="http://www.sgi.com/tech/stl/HashFunction.html">hashing
  91       function</a> to do the arranging, instead of a strict weak ordering
  92       function.  The classes take as one of their template parameters a
  93       function object that will return the hash value; by default, an
  94       instantiation of
  95       <a href="http://www.sgi.com/tech/stl/hash.html">hash</a>.
  96       You should specialize this functor for your class, or define your own,
  97       before trying to use one of the hashing classes.
  98    </p>
  99    <p>The hashing classes support all the usual associative container
 100       functions, as well as some extra constructors specifying the number
 101       of buckets, etc.
 102    </p>
 103    <p>Why would you want to use a hashing class instead of the
 104       &quot;normal&quot; implementations?  Matt Austern writes:
 105    </p>
 106    <blockquote><em>[W]ith a well chosen hash function, hash tables
 107    generally provide much better average-case performance than binary
 108    search trees, and much worse worst-case performance.  So if your
 109    implementation has hash_map, if you don't mind using nonstandard
 110    components, and if you aren't scared about the possibility of
 111    pathological cases, you'll probably get better performance from
 112    hash_map.</em></blockquote>
 113    <p>(Side note:  for those of you wondering, <strong>&quot;Why wasn't a hash
 114       table included in the Standard in the first #!$@ place?&quot;</strong>
 115       I'll give a quick answer:  it was proposed, but too late and in too
 116       unorganized a fashion.  Some sort of hashing will undoubtedly be
 117       included in a future Standard.)
 118    </p>
 119    <p>Return <a href="#top">to top of page</a> or
 120       <a href="../faq/index.html">to the FAQ</a>.
 121    </p>
 122
 123 <hr />
 124 <h2><a name="2">Added members and types</a></h2>
 125    <p>Some of the classes in the Standard Library have additional
 126       publicly-available members, and some classes are themselves not in
 127       the standard.  Of those, some are intended purely for the implementors,
 128       for example, additional typedefs.  Those won't be described here
 129       (or anywhere else).
 130    </p>
 131    <ul>
 132      <li>The extensions added by SGI are so numerous that they have
 133          <a href="sgiexts.html">their own page</a>.  Since the SGI STL is no
 134          longer actively maintained, we will try and keep this code working
 135          ourselves.</li>
 136      <li>Extensions allowing <code>filebuf</code>s to be constructed from
 137          stdio types are described in the
 138          <a href="../27_io/howto.html#11">chapter 27 notes</a>.</li>
 139    </ul>
 140    <p>Return <a href="#top">to top of page</a> or
 141       <a href="../faq/index.html">to the FAQ</a>.
 142    </p>
 143
 144 <hr />
 145 <h2><a name="4">Compile-time checks</a></h2>
 146    <p>Currently libstdc++-v3 uses the concept checkers from the Boost
 147       library to perform <a href="../19_diagnostics/howto.html#3">optional
 148       compile-time checking</a> of template instantiations of the standard
 149       containers.  They are described in the linked-to page.
 150    </p>
 151    <p>Return <a href="#top">to top of page</a> or
 152       <a href="../faq/index.html">to the FAQ</a>.
 153    </p>
 154
 155 <hr />
 156 <h2><a name="5">LWG Issues</a></h2>
 157    <p>Everybody's got issues.  Even the C++ Standard Library.
 158    </p>
 159    <p>The Library Working Group, or LWG, is the ISO subcommittee responsible
 160       for making changes to the library.  They periodically publish an
 161       Issues List containing problems and possible solutions.  As they reach
 162       a consensus on proposed solutions, we often incorporate the solution
 163       into libstdc++-v3.
 164    </p>
 165    <p>Here are the issues which have resulted in code changes to the library.
 166       The links are to the specific defect reports from a <strong>partial
 167       copy</strong> of the Issues List.  You can read the full version online
 168       at the <a href="http://www.open-std.org/jtc1/sc22/wg21/">ISO C++
 169       Committee homepage</a>, linked to on the
 170       <a href="http://gcc.gnu.org/readings.html">GCC &quot;Readings&quot;
 171       page</a>.  If
 172       you spend a lot of time reading the issues, we recommend downloading
 173       the ZIP file and reading them locally.
 174    </p>
 175    <p>(NB:  <strong>partial copy</strong> means that not all links within
 176       the lwg-*.html pages will work.
 177       Specifically, links to defect reports that have not been accorded full
 178       DR status will probably break.  Rather than trying to mirror the
 179       entire issues list on our overworked web server, we recommend you go
 180       to the LWG homepage instead.)
 181    </p>
 182    <p>
 183       If a DR is not listed here, we may simply not have gotten to it yet;
 184       feel free to submit a patch.  Search the include/bits and src
 185       directories for appearances of _GLIBCXX_RESOLVE_LIB_DEFECTS for
 186       examples of style.  Note that we usually do not make changes to the code
 187       until an issue has reached <a href="lwg-active.html#DR">DR</a> status.
 188    </p>
 189    <dl>
 190     <dt><a href="lwg-defects.html#5">5</a>:
 191         <em>string::compare specification questionable</em>
 192     </dt>
 193     <dd>This should be two overloaded functions rather than a single function.
 194     </dd>
 195
 196     <dt><a href="lwg-defects.html#17">17</a>:
 197         <em>Bad bool parsing</em>
 198     </dt>
 199     <dd>Apparently extracting Boolean values was messed up...
 200     </dd>
 201
 202     <dt><a href="lwg-defects.html#19">19</a>:
 203         <em>&quot;Noconv&quot; definition too vague</em>
 204     </dt>
 205     <dd>If <code>codecvt::do_in</code> returns <code>noconv</code> there are
 206         no changes to the values in <code>[to, to_limit)</code>.
 207     </dd>
 208
 209     <dt><a href="lwg-defects.html#22">22</a>:
 210         <em>Member open vs flags</em>
 211     </dt>
 212     <dd>Re-opening a file stream does <em>not</em> clear the state flags.
 213     </dd>
 214
 215     <dt><a href="lwg-defects.html#25">25</a>:
 216         <em>String operator&lt;&lt; uses width() value wrong</em>
 217     </dt>
 218     <dd>Padding issues.
 219     </dd>
 220
 221     <dt><a href="lwg-defects.html#48">48</a>:
 222         <em>Use of non-existent exception constructor</em>
 223     </dt>
 224     <dd>An instance of <code>ios_base::failure</code> is constructed instead.
 225     </dd>
 226
 227     <dt><a href="lwg-defects.html#49">49</a>:
 228         <em>Underspecification of ios_base::sync_with_stdio</em>
 229     </dt>
 230     <dd>The return type is the <em>previous</em> state of synchronization.
 231     </dd>
 232
 233     <dt><a href="lwg-defects.html#50">50</a>:
 234         <em>Copy constructor and assignment operator of ios_base</em>
 235     </dt>
 236     <dd>These members functions are declared <code>private</code> and are
 237         thus inaccessible.  Specifying the correct semantics of
 238         &quot;copying stream state&quot; was deemed too complicated.
 239     </dd>
 240
 241     <dt><a href="lwg-defects.html#60">60</a>:
 242         <em>What is a formatted input function?</em>
 243     </dt>
 244     <dd>This DR made many widespread changes to <code>basic_istream</code>
 245         and <code>basic_ostream</code> all of which have been implemented.
 246     </dd>
 247
 248     <dt><a href="lwg-defects.html#63">63</a>:
 249         <em>Exception-handling policy for unformatted output</em>
 250     </dt>
 251     <dd>Make the policy consistent with that of formatted input, unformatted
 252         input, and formatted output.
 253     </dd>
 254
 255     <dt><a href="lwg-defects.html#68">68</a>:
 256         <em>Extractors for char* should store null at end</em>
 257     </dt>
 258     <dd>And they do now.  An editing glitch in the last item in the list of
 259         [27.6.1.2.3]/7.
 260     </dd>
 261
 262     <dt><a href="lwg-defects.html#74">74</a>:
 263         <em>Garbled text for codecvt::do_max_length</em>
 264     </dt>
 265     <dd>The text of the standard was gibberish.  Typos gone rampant.
 266     </dd>
 267
 268     <dt><a href="lwg-defects.html#75">75</a>:
 269         <em>Contradiction in codecvt::length's argument types</em>
 270     </dt>
 271     <dd>Change the first parameter to <code>stateT&amp;</code> and implement
 272         the new effects paragraph.
 273     </dd>
 274
 275     <dt><a href="lwg-defects.html#83">83</a>:
 276         <em>string::npos vs. string::max_size()</em>
 277     </dt>
 278     <dd>Safety checks on the size of the string should test against
 279         <code>max_size()</code> rather than <code>npos</code>.
 280     </dd>
 281
 282     <dt><a href="lwg-defects.html#90">90</a>:
 283         <em>Incorrect description of operator&gt;&gt; for strings</em>
 284     </dt>
 285     <dd>The effect contain <code>isspace(c,getloc())</code> which must be
 286         replaced by <code>isspace(c,is.getloc())</code>.
 287     </dd>
 288
 289     <dt><a href="lwg-defects.html#91">91</a>:
 290         <em>Description of operator&gt;&gt; and getline() for string&lt;&gt;
 291             might cause endless loop</em>
 292     </dt>
 293     <dd>They behave as a formatted input function and as an unformatted
 294         input function, respectively (except that <code>getline</code> is
 295         not required to set <code>gcount</code>).
 296     </dd>
 297
 298     <dt><a href="lwg-defects.html#103">103</a>:
 299         <em>set::iterator is required to be modifiable, but this allows
 300             modification of keys.</em>
 301     </dt>
 302     <dd>For associative containers where the value type is the same as
 303         the key type, both <code>iterator</code> and <code>const_iterator
 304         </code> are constant iterators.
 305     </dd>
 306
 307     <dt><a href="lwg-defects.html#109">109</a>:
 308         <em>Missing binders for non-const sequence elements</em>
 309     </dt>
 310     <dd>The <code>binder1st</code> and <code>binder2nd</code> didn't have an
 311         <code>operator()</code> taking a non-const parameter.
 312     </dd>
 313
 314     <dt><a href="lwg-defects.html#110">110</a>:
 315         <em>istreambuf_iterator::equal not const</em>
 316     </dt>
 317     <dd>This was not a const member function.  Note that the DR says to
 318         replace the function with a const one; we have instead provided an
 319         overloaded version with identical contents.
 320     </dd>
 321
 322     <dt><a href="lwg-defects.html#117">117</a>:
 323         <em>basic_ostream uses nonexistent num_put member functions</em>
 324     </dt>
 325     <dd><code>num_put::put()</code> was overloaded on the wrong types.
 326     </dd>
 327
 328     <dt><a href="lwg-defects.html#118">118</a>:
 329         <em>basic_istream uses nonexistent num_get member functions</em>
 330     </dt>
 331     <dd>Same as 117, but for <code>num_get::get()</code>.
 332     </dd>
 333
 334     <dt><a href="lwg-defects.html#129">129</a>:
 335         <em>Need error indication from seekp() and seekg()</em>
 336     </dt>
 337     <dd>These functions set <code>failbit</code> on error now.
 338     </dd>
 339
 340     <dt><a href="lwg-defects.html#136">136</a>:
 341         <em>seekp, seekg setting wrong streams?</em>
 342     </dt>
 343     <dd><code>seekp</code> should only set the output stream, and
 344         <code>seekg</code> should only set the input stream.
 345     </dd>
 346
 347 <!--<dt><a href="lwg-defects.html#159">159</a>:
 348         <em>Strange use of underflow()</em>
 349     </dt>
 350     <dd>In fstream.tcc, the basic_filebuf&lt;&gt;::showmanyc() function
 351         should probably not be calling <code>underflow()</code>.
 352     </dd> -->
 353
 354     <dt><a href="lwg-defects.html#167">167</a>:
 355         <em>Improper use of traits_type::length()</em>
 356     </dt>
 357     <dd><code>op&lt;&lt;</code> with a <code>const char*</code> was
 358         calculating an incorrect number of characters to write.
 359     </dd>
 360
 361     <dt><a href="lwg-defects.html#171">171</a>:
 362         <em>Strange seekpos() semantics due to joint position</em>
 363     </dt>
 364     <dd>Quite complex to summarize...
 365     </dd>
 366
 367     <dt><a href="lwg-defects.html#181">181</a>:
 368         <em>make_pair() unintended behavior</em>
 369     </dt>
 370     <dd>This function used to take its arguments as reference-to-const, now
 371         it copies them (pass by value).
 372     </dd>
 373
 374     <dt><a href="lwg-defects.html#195">195</a>:
 375         <em>Should basic_istream::sentry's constructor ever set eofbit?</em>
 376     </dt>
 377     <dd>Yes, it can, specifically if EOF is reached while skipping whitespace.
 378     </dd>
 379
 380     <dt><a href="lwg-defects.html#211">211</a>:
 381         <em>operator&gt;&gt;(istream&amp;, string&amp;) doesn't set failbit</em>
 382     </dt>
 383     <dd>If nothing is extracted into the string, <code>op&gt;&gt;</code> now
 384         sets <code>failbit</code> (which can cause an exception, etc, etc).
 385     </dd>
 386
 387     <dt><a href="lwg-defects.html#214">214</a>:
 388         <em>set::find() missing const overload</em>
 389     </dt>
 390     <dd>Both <code>set</code> and <code>multiset</code> were missing
 391         overloaded find, lower_bound, upper_bound, and equal_range functions
 392         for const instances.
 393     </dd>
 394
 395     <dt><a href="lwg-defects.html#231">231</a>:
 396         <em>Precision in iostream?</em>
 397     </dt>
 398     <dd>For conversion from a floating-point type, <code>str.precision()</code>
 399         is specified in the conversion specification.
 400     </dd>
 401
 402     <dt><a href="lwg-defects.html#235">235</a>:
 403         <em>No specification of default ctor for reverse_iterator</em>
 404     </dt>
 405     <dd>The declaration of <code>reverse_iterator</code> lists a default constructor.
 406         However, no specification is given what this constructor should do.
 407     </dd>
 408
 409     <dt><a href="lwg-defects.html#243">243</a>:
 410         <em>get and getline when sentry reports failure</em>
 411     </dt>
 412     <dd>Store a null character only if the character array has a non-zero size.
 413     </dd>
 414
 415     <dt><a href="lwg-defects.html#251">251</a>:
 416         <em>basic_stringbuf missing allocator_type</em>
 417     </dt>
 418     <dd>This nested typedef was originally not specified.
 419     </dd>
 420
 421     <dt><a href="lwg-defects.html#253">253</a>:
 422         <em>valarray helper functions are almost entirely useless</em>
 423     </dt>
 424     <dd>Make the copy constructor and copy-assignment operator declarations
 425         public in gslice_array, indirect_array, mask_array, slice_array; provide
 426         definitions.
 427     </dd>
 428
 429     <dt><a href="lwg-defects.html#265">265</a>:
 430         <em>std::pair::pair() effects overly restrictive</em>
 431     </dt>
 432     <dd>The default ctor would build its members from copies of temporaries;
 433         now it simply uses their respective default ctors.
 434     </dd>
 435
 436     <dt><a href="lwg-defects.html#266">266</a>:
 437         <em>bad_exception::~bad_exception() missing Effects clause</em>
 438     </dt>
 439     <dd>The <code>bad_</code>* classes no longer have destructors (they
 440         are trivial), since no description of them was ever given.
 441     </dd>
 442
 443     <dt><a href="lwg-defects.html#271">271</a>:
 444         <em>basic_iostream missing typedefs</em>
 445     </dt>
 446     <dd>The typedefs it inherits from its base classes can't be used, since
 447         (for example) <code>basic_iostream&lt;T&gt;::traits_type</code> is ambiguous.
 448     </dd>
 449
 450     <dt><a href="lwg-defects.html#275">275</a>:
 451         <em>Wrong type in num_get::get() overloads</em>
 452     </dt>
 453     <dd>Similar to 118.
 454     </dd>
 455
 456     <dt><a href="lwg-defects.html#292">292</a>:
 457         <em>Effects of a.copyfmt (a)</em>
 458     </dt>
 459     <dd>If <code>(this == &amp;rhs)</code> do nothing.
 460     </dd>
 461
 462     <dt><a href="lwg-defects.html#300">300</a>:
 463         <em>List::merge() specification incomplete</em>
 464     </dt>
 465     <dd>If <code>(this == &amp;x)</code> do nothing.
 466     </dd>
 467
 468     <dt><a href="lwg-defects.html#303">303</a>:
 469         <em>Bitset input operator underspecified</em>
 470     </dt>
 471     <dd>Basically, compare the input character to <code>is.widen(0)</code>
 472         and <code>is.widen(1)</code>.
 473     </dd>
 474
 475     <dt><a href="lwg-defects.html#305">305</a>:
 476         <em>Default behavior of codecvt&lt;wchar_t, char, mbstate_t&gt;::length()</em>
 477     </dt>
 478     <dd>Do not specify what <code>codecvt&lt;wchar_t, char, mbstate_t&gt;::do_length</code>
 479         must return.
 480     </dd>
 481
 482     <dt><a href="lwg-defects.html#328">328</a>:
 483         <em>Bad sprintf format modifier in money_put&lt;&gt;::do_put()</em>
 484     </dt>
 485     <dd>Change the format string to &quot;%.0Lf&quot;.
 486     </dd>
 487
 488     <dt><a href="lwg-defects.html#365">365</a>:
 489         <em>Lack of const-qualification in clause 27</em>
 490     </dt>
 491     <dd>Add const overloads of <code>is_open</code>.
 492     </dd>
 493
 494     <dt><a href="lwg-defects.html#389">389</a>:
 495         <em>Const overload of valarray::operator[] returns by value</em>
 496     </dt>
 497     <dd>Change it to return a <code>const T&amp;</code>.
 498     </dd>
 499
 500     <dt><a href="lwg-defects.html#402">402</a>:
 501         <em>Wrong new expression in [some_]allocator::construct</em>
 502     </dt>
 503     <dd>Replace &quot;new&quot; with &quot;::new&quot;.
 504     </dd>
 505
 506     <dt><a href="lwg-active.html#434">434</a>:
 507         <em>bitset::to_string() hard to use</em>
 508     </dt>
 509     <dd>Add three overloads, taking fewer template arguments.
 510     </dd>
 511
 512     <dt><a href="lwg-active.html#453">453</a>:
 513         <em>basic_stringbuf::seekoff need not always fail for an empty stream</em>
 514     </dt>
 515     <dd>Don't fail if the next pointer is null and newoff is zero.
 516     </dd>
 517 <!--
 518     <dt><a href="lwg-defects.html#"></a>:
 519         <em></em>
 520     </dt>
 521     <dd>
 522     </dd>
 523
 524 -->
 525    </dl>
 526    <p>Return <a href="#top">to top of page</a> or
 527       <a href="../faq/index.html">to the FAQ</a>.
 528    </p>
 529
 530
 531 <!-- ####################################################### -->
 532
 533 <hr />
 534 <p class="fineprint"><em>
 535 See <a href="../17_intro/license.html">license.html</a> for copying conditions.
 536 Comments and suggestions are welcome, and may be sent to
 537 <a href="mailto:libstdc++@gcc.gnu.org">the libstdc++ mailing list</a>.
 538 </em></p>
 539
 540
 541 </body>
 542 </html>