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 <bvector> 67 <hash_map> 68 <hash_set> 69 <rope> 70 <slist> 71 <tree> 72 </pre> 73 <p>are all here; <code><bvector></code> exposes the old bit_vector 74 class that was used before specialization of vector<bool> was 75 available (it's actually a typedef for the specialization now). 76 <code><hash_map></code> and <code><hash_set></code> 77 are discussed further below. <code><rope></code> is the SGI 78 specialization for large strings ("rope," "large 79 strings," get it? love those SGI folks). 80 <code><slist></code> is a singly-linked list, for when the 81 doubly-linked <code>list<></code> is too much space overhead, and 82 <code><tree></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 "normal" 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>"Why wasn't a hash 114 table included in the Standard in the first #!$@ place?"</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 "Readings" 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>"Noconv" 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<< 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 "copying stream state" 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&</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>> 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>> and getline() for string<> 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<>::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<<</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#169">169</a>: 362 <em>Bad efficiency of overflow() mandated</em> 363 </dt> 364 <dd>Grow efficiently the internal array object. 365 </dd> 366 367 <dt><a href="lwg-defects.html#171">171</a>: 368 <em>Strange seekpos() semantics due to joint position</em> 369 </dt> 370 <dd>Quite complex to summarize... 371 </dd> 372 373 <dt><a href="lwg-defects.html#181">181</a>: 374 <em>make_pair() unintended behavior</em> 375 </dt> 376 <dd>This function used to take its arguments as reference-to-const, now 377 it copies them (pass by value). 378 </dd> 379 380 <dt><a href="lwg-defects.html#195">195</a>: 381 <em>Should basic_istream::sentry's constructor ever set eofbit?</em> 382 </dt> 383 <dd>Yes, it can, specifically if EOF is reached while skipping whitespace. 384 </dd> 385 386 <dt><a href="lwg-defects.html#211">211</a>: 387 <em>operator>>(istream&, string&) doesn't set failbit</em> 388 </dt> 389 <dd>If nothing is extracted into the string, <code>op>></code> now 390 sets <code>failbit</code> (which can cause an exception, etc., etc.). 391 </dd> 392 393 <dt><a href="lwg-defects.html#214">214</a>: 394 <em>set::find() missing const overload</em> 395 </dt> 396 <dd>Both <code>set</code> and <code>multiset</code> were missing 397 overloaded find, lower_bound, upper_bound, and equal_range functions 398 for const instances. 399 </dd> 400 401 <dt><a href="lwg-defects.html#231">231</a>: 402 <em>Precision in iostream?</em> 403 </dt> 404 <dd>For conversion from a floating-point type, <code>str.precision()</code> 405 is specified in the conversion specification. 406 </dd> 407 408 <dt><a href="lwg-active.html#233">233</a>: 409 <em>Insertion hints in associative containers</em> 410 </dt> 411 <dd>Implement N1780, first check before then check after, insert as close 412 to hint as possible. 413 </dd> 414 415 <dt><a href="lwg-defects.html#235">235</a>: 416 <em>No specification of default ctor for reverse_iterator</em> 417 </dt> 418 <dd>The declaration of <code>reverse_iterator</code> lists a default constructor. 419 However, no specification is given what this constructor should do. 420 </dd> 421 422 <dt><a href="lwg-defects.html#241">241</a>: 423 <em>Does unique_copy() require CopyConstructible and Assignable?</em> 424 </dt> 425 <dd>Add an helper for forward_iterator/output_iterator, fix the existing 426 one for input_iterator/output_iterator not to rely on Assignability. 427 </dd> 428 429 <dt><a href="lwg-defects.html#243">243</a>: 430 <em>get and getline when sentry reports failure</em> 431 </dt> 432 <dd>Store a null character only if the character array has a non-zero size. 433 </dd> 434 435 <dt><a href="lwg-defects.html#251">251</a>: 436 <em>basic_stringbuf missing allocator_type</em> 437 </dt> 438 <dd>This nested typedef was originally not specified. 439 </dd> 440 441 <dt><a href="lwg-defects.html#253">253</a>: 442 <em>valarray helper functions are almost entirely useless</em> 443 </dt> 444 <dd>Make the copy constructor and copy-assignment operator declarations 445 public in gslice_array, indirect_array, mask_array, slice_array; provide 446 definitions. 447 </dd> 448 449 <dt><a href="lwg-defects.html#265">265</a>: 450 <em>std::pair::pair() effects overly restrictive</em> 451 </dt> 452 <dd>The default ctor would build its members from copies of temporaries; 453 now it simply uses their respective default ctors. 454 </dd> 455 456 <dt><a href="lwg-defects.html#266">266</a>: 457 <em>bad_exception::~bad_exception() missing Effects clause</em> 458 </dt> 459 <dd>The <code>bad_</code>* classes no longer have destructors (they 460 are trivial), since no description of them was ever given. 461 </dd> 462 463 <dt><a href="lwg-defects.html#271">271</a>: 464 <em>basic_iostream missing typedefs</em> 465 </dt> 466 <dd>The typedefs it inherits from its base classes can't be used, since 467 (for example) <code>basic_iostream<T>::traits_type</code> is ambiguous. 468 </dd> 469 470 <dt><a href="lwg-defects.html#275">275</a>: 471 <em>Wrong type in num_get::get() overloads</em> 472 </dt> 473 <dd>Similar to 118. 474 </dd> 475 476 <dt><a href="lwg-defects.html#280">280</a>: 477 <em>Comparison of reverse_iterator to const reverse_iterator</em> 478 </dt> 479 <dd>Add global functions with two template parameters. 480 (NB: not added for now a templated assignment operator) 481 </dd> 482 483 <dt><a href="lwg-defects.html#292">292</a>: 484 <em>Effects of a.copyfmt (a)</em> 485 </dt> 486 <dd>If <code>(this == &rhs)</code> do nothing. 487 </dd> 488 489 <dt><a href="lwg-defects.html#300">300</a>: 490 <em>List::merge() specification incomplete</em> 491 </dt> 492 <dd>If <code>(this == &x)</code> do nothing. 493 </dd> 494 495 <dt><a href="lwg-defects.html#303">303</a>: 496 <em>Bitset input operator underspecified</em> 497 </dt> 498 <dd>Basically, compare the input character to <code>is.widen(0)</code> 499 and <code>is.widen(1)</code>. 500 </dd> 501 502 <dt><a href="lwg-defects.html#305">305</a>: 503 <em>Default behavior of codecvt<wchar_t, char, mbstate_t>::length()</em> 504 </dt> 505 <dd>Do not specify what <code>codecvt<wchar_t, char, mbstate_t>::do_length</code> 506 must return. 507 </dd> 508 509 <dt><a href="lwg-defects.html#328">328</a>: 510 <em>Bad sprintf format modifier in money_put<>::do_put()</em> 511 </dt> 512 <dd>Change the format string to "%.0Lf". 513 </dd> 514 515 <dt><a href="lwg-defects.html#365">365</a>: 516 <em>Lack of const-qualification in clause 27</em> 517 </dt> 518 <dd>Add const overloads of <code>is_open</code>. 519 </dd> 520 521 <dt><a href="lwg-defects.html#389">389</a>: 522 <em>Const overload of valarray::operator[] returns by value</em> 523 </dt> 524 <dd>Change it to return a <code>const T&</code>. 525 </dd> 526 527 <dt><a href="lwg-defects.html#402">402</a>: 528 <em>Wrong new expression in [some_]allocator::construct</em> 529 </dt> 530 <dd>Replace "new" with "::new". 531 </dd> 532 533 <dt><a href="lwg-defects.html#409">409</a>: 534 <em>Closing an fstream should clear the error state</em> 535 </dt> 536 <dd>Have <code>open</code> clear the error flags. 537 </dd> 538 539 <dt><a href="lwg-active.html#431">431</a>: 540 <em>Swapping containers with unequal allocators</em> 541 </dt> 542 <dd>Implement Option 3, as per N1599. 543 </dd> 544 545 <dt><a href="lwg-defects.html#432">432</a>: 546 <em>432. stringbuf::overflow() makes only one write position 547 available</em> 548 </dt> 549 <dd>Implement the resolution, beyond DR 169. 550 </dd> 551 552 <dt><a href="lwg-defects.html#434">434</a>: 553 <em>bitset::to_string() hard to use</em> 554 </dt> 555 <dd>Add three overloads, taking fewer template arguments. 556 </dd> 557 558 <dt><a href="lwg-defects.html#453">453</a>: 559 <em>basic_stringbuf::seekoff need not always fail for an empty stream</em> 560 </dt> 561 <dd>Don't fail if the next pointer is null and newoff is zero. 562 </dd> 563 564 <dt><a href="lwg-defects.html#455">455</a>: 565 <em>cerr::tie() and wcerr::tie() are overspecified</em> 566 </dt> 567 <dd>Initialize cerr tied to cout and wcerr tied to wcout. 568 </dd> 569 570 <dt><a href="lwg-defects.html#464">464</a>: 571 <em>Suggestion for new member functions in standard containers</em> 572 </dt> 573 <dd>Add <code>data()</code> to <code>std::vector</code> and 574 <code>at(const key_type&)</code> to <code>std::map</code>. 575 </dd> 576 577 <dt><a href="lwg-defects.html#508">508</a>: 578 <em>Bad parameters for ranlux64_base_01</em> 579 </dt> 580 <dd>Fix the parameters. 581 </dd> 582 583 <dt><a href="lwg-closed.html#512">512</a>: 584 <em>Seeding subtract_with_carry_01 from a single unsigned long</em> 585 </dt> 586 <dd>Construct a <code>linear_congruential</code> engine and seed with it. 587 </dd> 588 589 <dt><a href="lwg-defects.html#538">538</a>: 590 <em>241 again: Does unique_copy() require CopyConstructible 591 and Assignable?</em> 592 </dt> 593 <dd>In case of input_iterator/output_iterator rely on Assignability of 594 input_iterator' value_type. 595 </dd> 596 597 <dt><a href="lwg-active.html#586">586</a>: 598 <em>string inserter not a formatted function</em> 599 </dt> 600 <dd>Change it to be a formatted output function (i.e. catch exceptions). 601 </dd> 602<!-- 603 <dt><a href="lwg-defects.html#"></a>: 604 <em></em> 605 </dt> 606 <dd> 607 </dd> 608 609--> 610 </dl> 611 <p>Return <a href="#top">to top of page</a> or 612 <a href="../faq/index.html">to the FAQ</a>. 613 </p> 614 615 616<!-- ####################################################### --> 617 618<hr /> 619<p class="fineprint"><em> 620See <a href="../17_intro/license.html">license.html</a> for copying conditions. 621Comments and suggestions are welcome, and may be sent to 622<a href="mailto:libstdc++@gcc.gnu.org">the libstdc++ mailing list</a>. 623</em></p> 624 625 626</body> 627</html> 628