1 <?xml version="1.0" encoding="ISO-8859-1"?>
3 PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
4 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
6 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
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++ 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"
23 <link rel="Copyright" href="../17_intro/license.html" type="text/html" />
27 <h1 class="centered"><a name="top">Extensions</a></h1>
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.
33 <p><strong>Before you leap in and use these</strong>, be aware of two things:
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++ 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>
47 <!-- ####################################################### -->
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>
61 <!-- ####################################################### -->
63 <h2><a name="1">Ropes and trees and hashes, oh my!</a></h2>
64 <p>The SGI headers</p>
73 <code><hash_map></code> and <code><hash_set></code>
74 are deprecated but available as backwards-compatible extensions,
75 as discussed further below. <code><rope></code> is the
76 SGI specialization for large strings ("rope,"
77 "large strings," get it? Love that geeky humor.)
78 <code><slist></code> is a singly-linked list, for when the
79 doubly-linked <code>list<></code> is too much space
80 overhead, and <code><rb_tree></code> exposes the red-black
81 tree classes used in the implementation of the standard maps and
84 <p>Each of the associative containers map, multimap, set, and multiset
85 have a counterpart which uses a
86 <a href="http://www.sgi.com/tech/stl/HashFunction.html">hashing
87 function</a> to do the arranging, instead of a strict weak ordering
88 function. The classes take as one of their template parameters a
89 function object that will return the hash value; by default, an
91 <a href="http://www.sgi.com/tech/stl/hash.html">hash</a>.
92 You should specialize this functor for your class, or define your own,
93 before trying to use one of the hashing classes.
95 <p>The hashing classes support all the usual associative container
96 functions, as well as some extra constructors specifying the number
99 <p>Why would you want to use a hashing class instead of the
100 "normal" implementations? Matt Austern writes:
102 <blockquote><em>[W]ith a well chosen hash function, hash tables
103 generally provide much better average-case performance than binary
104 search trees, and much worse worst-case performance. So if your
105 implementation has hash_map, if you don't mind using nonstandard
106 components, and if you aren't scared about the possibility of
107 pathological cases, you'll probably get better performance from
108 hash_map.</em></blockquote>
110 <p>Okay, about the SGI hashing classes... these classes have been
111 deprecated by the unordered_set, unordered_multiset, unordered_map,
112 unordered_multimap containers in TR1 and the upcoming C++0x, and
113 may be removed in future releases.
116 <p>Return <a href="#top">to top of page</a> or
117 <a href="../faq/index.html">to the FAQ</a>.
121 <h2><a name="2">Added members and types</a></h2>
122 <p>Some of the classes in the Standard Library have additional
123 publicly-available members, and some classes are themselves not in
124 the standard. Of those, some are intended purely for the implementors,
125 for example, additional typedefs. Those won't be described here
129 <li>The extensions added by SGI are so numerous that they have
130 <a href="sgiexts.html">their own page</a>. Since the SGI STL is no
131 longer actively maintained, we will try and keep this code working
133 <li>Extensions allowing <code>filebuf</code>s to be constructed from
134 stdio types are described in the
135 <a href="../27_io/howto.html#11">chapter 27 notes</a>.</li>
136 <li>The C++ Standard Library Technical Report adds many new features
137 to the library, see <a href="../faq/index.html#5_5">FAQ 5.5</a>.</li>
139 <p>Return <a href="#top">to top of page</a> or
140 <a href="../faq/index.html">to the FAQ</a>.
144 <h2><a name="4">Compile-time checks</a></h2>
145 <p>Currently libstdc++ uses the concept checkers from the Boost
146 library to perform <a href="../19_diagnostics/howto.html#3">optional
147 compile-time checking</a> of template instantiations of the standard
148 containers. They are described in the linked-to page.
150 <p>Return <a href="#top">to top of page</a> or
151 <a href="../faq/index.html">to the FAQ</a>.
155 <h2><a name="5">LWG Issues</a></h2>
156 <p>Everybody's got issues. Even the C++ Standard Library.
158 <p>The Library Working Group, or LWG, is the ISO subcommittee responsible
159 for making changes to the library. They periodically publish an
160 Issues List containing problems and possible solutions. As they reach
161 a consensus on proposed solutions, we often incorporate the solution
164 <p>Here are the issues which have resulted in code changes to the library.
165 The links are to the specific defect reports from a <strong>partial
166 copy</strong> of the Issues List. You can read the full version online
167 at the <a href="http://www.open-std.org/jtc1/sc22/wg21/">ISO C++
168 Committee homepage</a>, linked to on the
169 <a href="http://gcc.gnu.org/readings.html">GCC "Readings"
171 you spend a lot of time reading the issues, we recommend downloading
172 the ZIP file and reading them locally.
174 <p>(NB: <strong>partial copy</strong> means that not all links within
175 the lwg-*.html pages will work.
176 Specifically, links to defect reports that have not been accorded full
177 DR status will probably break. Rather than trying to mirror the
178 entire issues list on our overworked web server, we recommend you go
179 to the LWG homepage instead.)
182 If a DR is not listed here, we may simply not have gotten to it yet;
183 feel free to submit a patch. Search the include/bits and src
184 directories for appearances of _GLIBCXX_RESOLVE_LIB_DEFECTS for
185 examples of style. Note that we usually do not make changes to the code
186 until an issue has reached <a href="lwg-active.html#DR">DR</a> status.
189 <dt><a href="lwg-defects.html#5">5</a>:
190 <em>string::compare specification questionable</em>
192 <dd>This should be two overloaded functions rather than a single function.
195 <dt><a href="lwg-defects.html#17">17</a>:
196 <em>Bad bool parsing</em>
198 <dd>Apparently extracting Boolean values was messed up...
201 <dt><a href="lwg-defects.html#19">19</a>:
202 <em>"Noconv" definition too vague</em>
204 <dd>If <code>codecvt::do_in</code> returns <code>noconv</code> there are
205 no changes to the values in <code>[to, to_limit)</code>.
208 <dt><a href="lwg-defects.html#22">22</a>:
209 <em>Member open vs flags</em>
211 <dd>Re-opening a file stream does <em>not</em> clear the state flags.
214 <dt><a href="lwg-defects.html#25">25</a>:
215 <em>String operator<< uses width() value wrong</em>
220 <dt><a href="lwg-defects.html#48">48</a>:
221 <em>Use of non-existent exception constructor</em>
223 <dd>An instance of <code>ios_base::failure</code> is constructed instead.
226 <dt><a href="lwg-defects.html#49">49</a>:
227 <em>Underspecification of ios_base::sync_with_stdio</em>
229 <dd>The return type is the <em>previous</em> state of synchronization.
232 <dt><a href="lwg-defects.html#50">50</a>:
233 <em>Copy constructor and assignment operator of ios_base</em>
235 <dd>These members functions are declared <code>private</code> and are
236 thus inaccessible. Specifying the correct semantics of
237 "copying stream state" was deemed too complicated.
240 <dt><a href="lwg-defects.html#60">60</a>:
241 <em>What is a formatted input function?</em>
243 <dd>This DR made many widespread changes to <code>basic_istream</code>
244 and <code>basic_ostream</code> all of which have been implemented.
247 <dt><a href="lwg-defects.html#63">63</a>:
248 <em>Exception-handling policy for unformatted output</em>
250 <dd>Make the policy consistent with that of formatted input, unformatted
251 input, and formatted output.
254 <dt><a href="lwg-defects.html#68">68</a>:
255 <em>Extractors for char* should store null at end</em>
257 <dd>And they do now. An editing glitch in the last item in the list of
261 <dt><a href="lwg-defects.html#74">74</a>:
262 <em>Garbled text for codecvt::do_max_length</em>
264 <dd>The text of the standard was gibberish. Typos gone rampant.
267 <dt><a href="lwg-defects.html#75">75</a>:
268 <em>Contradiction in codecvt::length's argument types</em>
270 <dd>Change the first parameter to <code>stateT&</code> and implement
271 the new effects paragraph.
274 <dt><a href="lwg-defects.html#83">83</a>:
275 <em>string::npos vs. string::max_size()</em>
277 <dd>Safety checks on the size of the string should test against
278 <code>max_size()</code> rather than <code>npos</code>.
281 <dt><a href="lwg-defects.html#90">90</a>:
282 <em>Incorrect description of operator>> for strings</em>
284 <dd>The effect contain <code>isspace(c,getloc())</code> which must be
285 replaced by <code>isspace(c,is.getloc())</code>.
288 <dt><a href="lwg-defects.html#91">91</a>:
289 <em>Description of operator>> and getline() for string<>
290 might cause endless loop</em>
292 <dd>They behave as a formatted input function and as an unformatted
293 input function, respectively (except that <code>getline</code> is
294 not required to set <code>gcount</code>).
297 <dt><a href="lwg-defects.html#103">103</a>:
298 <em>set::iterator is required to be modifiable, but this allows
299 modification of keys.</em>
301 <dd>For associative containers where the value type is the same as
302 the key type, both <code>iterator</code> and <code>const_iterator
303 </code> are constant iterators.
306 <dt><a href="lwg-defects.html#109">109</a>:
307 <em>Missing binders for non-const sequence elements</em>
309 <dd>The <code>binder1st</code> and <code>binder2nd</code> didn't have an
310 <code>operator()</code> taking a non-const parameter.
313 <dt><a href="lwg-defects.html#110">110</a>:
314 <em>istreambuf_iterator::equal not const</em>
316 <dd>This was not a const member function. Note that the DR says to
317 replace the function with a const one; we have instead provided an
318 overloaded version with identical contents.
321 <dt><a href="lwg-defects.html#117">117</a>:
322 <em>basic_ostream uses nonexistent num_put member functions</em>
324 <dd><code>num_put::put()</code> was overloaded on the wrong types.
327 <dt><a href="lwg-defects.html#118">118</a>:
328 <em>basic_istream uses nonexistent num_get member functions</em>
330 <dd>Same as 117, but for <code>num_get::get()</code>.
333 <dt><a href="lwg-defects.html#129">129</a>:
334 <em>Need error indication from seekp() and seekg()</em>
336 <dd>These functions set <code>failbit</code> on error now.
339 <dt><a href="lwg-defects.html#136">136</a>:
340 <em>seekp, seekg setting wrong streams?</em>
342 <dd><code>seekp</code> should only set the output stream, and
343 <code>seekg</code> should only set the input stream.
346 <!--<dt><a href="lwg-defects.html#159">159</a>:
347 <em>Strange use of underflow()</em>
349 <dd>In fstream.tcc, the basic_filebuf<>::showmanyc() function
350 should probably not be calling <code>underflow()</code>.
353 <dt><a href="lwg-defects.html#167">167</a>:
354 <em>Improper use of traits_type::length()</em>
356 <dd><code>op<<</code> with a <code>const char*</code> was
357 calculating an incorrect number of characters to write.
360 <dt><a href="lwg-defects.html#169">169</a>:
361 <em>Bad efficiency of overflow() mandated</em>
363 <dd>Grow efficiently the internal array object.
366 <dt><a href="lwg-defects.html#171">171</a>:
367 <em>Strange seekpos() semantics due to joint position</em>
369 <dd>Quite complex to summarize...
372 <dt><a href="lwg-defects.html#181">181</a>:
373 <em>make_pair() unintended behavior</em>
375 <dd>This function used to take its arguments as reference-to-const, now
376 it copies them (pass by value).
379 <dt><a href="lwg-defects.html#195">195</a>:
380 <em>Should basic_istream::sentry's constructor ever set eofbit?</em>
382 <dd>Yes, it can, specifically if EOF is reached while skipping whitespace.
385 <dt><a href="lwg-defects.html#211">211</a>:
386 <em>operator>>(istream&, string&) doesn't set failbit</em>
388 <dd>If nothing is extracted into the string, <code>op>></code> now
389 sets <code>failbit</code> (which can cause an exception, etc., etc.).
392 <dt><a href="lwg-defects.html#214">214</a>:
393 <em>set::find() missing const overload</em>
395 <dd>Both <code>set</code> and <code>multiset</code> were missing
396 overloaded find, lower_bound, upper_bound, and equal_range functions
400 <dt><a href="lwg-defects.html#231">231</a>:
401 <em>Precision in iostream?</em>
403 <dd>For conversion from a floating-point type, <code>str.precision()</code>
404 is specified in the conversion specification.
407 <dt><a href="lwg-active.html#233">233</a>:
408 <em>Insertion hints in associative containers</em>
410 <dd>Implement N1780, first check before then check after, insert as close
414 <dt><a href="lwg-defects.html#235">235</a>:
415 <em>No specification of default ctor for reverse_iterator</em>
417 <dd>The declaration of <code>reverse_iterator</code> lists a default constructor.
418 However, no specification is given what this constructor should do.
421 <dt><a href="lwg-defects.html#241">241</a>:
422 <em>Does unique_copy() require CopyConstructible and Assignable?</em>
424 <dd>Add a helper for forward_iterator/output_iterator, fix the existing
425 one for input_iterator/output_iterator to not rely on Assignability.
428 <dt><a href="lwg-defects.html#243">243</a>:
429 <em>get and getline when sentry reports failure</em>
431 <dd>Store a null character only if the character array has a non-zero size.
434 <dt><a href="lwg-defects.html#251">251</a>:
435 <em>basic_stringbuf missing allocator_type</em>
437 <dd>This nested typedef was originally not specified.
440 <dt><a href="lwg-defects.html#253">253</a>:
441 <em>valarray helper functions are almost entirely useless</em>
443 <dd>Make the copy constructor and copy-assignment operator declarations
444 public in gslice_array, indirect_array, mask_array, slice_array; provide
448 <dt><a href="lwg-defects.html#265">265</a>:
449 <em>std::pair::pair() effects overly restrictive</em>
451 <dd>The default ctor would build its members from copies of temporaries;
452 now it simply uses their respective default ctors.
455 <dt><a href="lwg-defects.html#266">266</a>:
456 <em>bad_exception::~bad_exception() missing Effects clause</em>
458 <dd>The <code>bad_</code>* classes no longer have destructors (they
459 are trivial), since no description of them was ever given.
462 <dt><a href="lwg-defects.html#271">271</a>:
463 <em>basic_iostream missing typedefs</em>
465 <dd>The typedefs it inherits from its base classes can't be used, since
466 (for example) <code>basic_iostream<T>::traits_type</code> is ambiguous.
469 <dt><a href="lwg-defects.html#275">275</a>:
470 <em>Wrong type in num_get::get() overloads</em>
475 <dt><a href="lwg-defects.html#280">280</a>:
476 <em>Comparison of reverse_iterator to const reverse_iterator</em>
478 <dd>Add global functions with two template parameters.
479 (NB: not added for now a templated assignment operator)
482 <dt><a href="lwg-defects.html#292">292</a>:
483 <em>Effects of a.copyfmt (a)</em>
485 <dd>If <code>(this == &rhs)</code> do nothing.
488 <dt><a href="lwg-defects.html#300">300</a>:
489 <em>List::merge() specification incomplete</em>
491 <dd>If <code>(this == &x)</code> do nothing.
494 <dt><a href="lwg-defects.html#303">303</a>:
495 <em>Bitset input operator underspecified</em>
497 <dd>Basically, compare the input character to <code>is.widen(0)</code>
498 and <code>is.widen(1)</code>.
501 <dt><a href="lwg-defects.html#305">305</a>:
502 <em>Default behavior of codecvt<wchar_t, char, mbstate_t>::length()</em>
504 <dd>Do not specify what <code>codecvt<wchar_t, char, mbstate_t>::do_length</code>
508 <dt><a href="lwg-defects.html#328">328</a>:
509 <em>Bad sprintf format modifier in money_put<>::do_put()</em>
511 <dd>Change the format string to "%.0Lf".
514 <dt><a href="lwg-defects.html#365">365</a>:
515 <em>Lack of const-qualification in clause 27</em>
517 <dd>Add const overloads of <code>is_open</code>.
520 <dt><a href="lwg-defects.html#389">389</a>:
521 <em>Const overload of valarray::operator[] returns by value</em>
523 <dd>Change it to return a <code>const T&</code>.
526 <dt><a href="lwg-defects.html#402">402</a>:
527 <em>Wrong new expression in [some_]allocator::construct</em>
529 <dd>Replace "new" with "::new".
532 <dt><a href="lwg-defects.html#409">409</a>:
533 <em>Closing an fstream should clear the error state</em>
535 <dd>Have <code>open</code> clear the error flags.
538 <dt><a href="lwg-active.html#431">431</a>:
539 <em>Swapping containers with unequal allocators</em>
541 <dd>Implement Option 3, as per N1599.
544 <dt><a href="lwg-defects.html#432">432</a>:
545 <em>stringbuf::overflow() makes only one write position
548 <dd>Implement the resolution, beyond DR 169.
551 <dt><a href="lwg-defects.html#434">434</a>:
552 <em>bitset::to_string() hard to use</em>
554 <dd>Add three overloads, taking fewer template arguments.
557 <dt><a href="lwg-defects.html#438">438</a>:
558 <em>Ambiguity in the "do the right thing" clause</em>
560 <dd>Implement the resolution, basically cast less.
563 <dt><a href="lwg-defects.html#453">453</a>:
564 <em>basic_stringbuf::seekoff need not always fail for an empty stream</em>
566 <dd>Don't fail if the next pointer is null and newoff is zero.
569 <dt><a href="lwg-defects.html#455">455</a>:
570 <em>cerr::tie() and wcerr::tie() are overspecified</em>
572 <dd>Initialize cerr tied to cout and wcerr tied to wcout.
575 <dt><a href="lwg-defects.html#464">464</a>:
576 <em>Suggestion for new member functions in standard containers</em>
578 <dd>Add <code>data()</code> to <code>std::vector</code> and
579 <code>at(const key_type&)</code> to <code>std::map</code>.
582 <dt><a href="lwg-defects.html#508">508</a>:
583 <em>Bad parameters for ranlux64_base_01</em>
585 <dd>Fix the parameters.
588 <dt><a href="lwg-closed.html#512">512</a>:
589 <em>Seeding subtract_with_carry_01 from a single unsigned long</em>
591 <dd>Construct a <code>linear_congruential</code> engine and seed with it.
594 <dt><a href="lwg-closed.html#526">526</a>:
595 <em>Is it undefined if a function in the standard changes in
601 <dt><a href="lwg-defects.html#538">538</a>:
602 <em>241 again: Does unique_copy() require CopyConstructible
605 <dd>In case of input_iterator/output_iterator rely on Assignability of
606 input_iterator' value_type.
609 <dt><a href="lwg-defects.html#541">541</a>:
610 <em>shared_ptr template assignment and void</em>
612 <dd>Add an auto_ptr<void> specialization.
615 <dt><a href="lwg-defects.html#543">543</a>:
616 <em>valarray slice default constructor</em>
618 <dd>Follow the straightforward proposed resolution.
621 <dt><a href="lwg-defects.html#586">586</a>:
622 <em>string inserter not a formatted function</em>
624 <dd>Change it to be a formatted output function (i.e. catch exceptions).
627 <dt><a href="lwg-active.html#596">596</a>:
628 <em>27.8.1.3 Table 112 omits "a+" and "a+b" modes</em>
630 <dd>Add the missing modes to fopen_mode.
633 <dt><a href="lwg-defects.html#660">660</a>:
634 <em>Missing bitwise operations</em>
636 <dd>Add the missing operations.
639 <dt><a href="lwg-active.html#693">693</a>:
640 <em>std::bitset::all() missing</em>
642 <dd>Add it, consistently with the discussion.
645 <dt><a href="lwg-active.html#695">695</a>:
646 <em>ctype<char>::classic_table() not accessible</em>
648 <dd>Make the member functions table and classic_table public.
651 <dt><a href="lwg-defects.html#"></a>:
659 <p>Return <a href="#top">to top of page</a> or
660 <a href="../faq/index.html">to the FAQ</a>.
664 <!-- ####################################################### -->
667 <p class="fineprint"><em>
668 See <a href="../17_intro/license.html">license.html</a> for copying conditions.
669 Comments and suggestions are welcome, and may be sent to
670 <a href="mailto:libstdc++@gcc.gnu.org">the libstdc++ mailing list</a>.