1<part xmlns="http://docbook.org/ns/docbook" version="5.0" 2 xml:id="manual.ext" xreflabel="Extensions"> 3<?dbhtml filename="extensions.html"?> 4 5<info><title> 6 Extensions 7 <indexterm><primary>Extensions</primary></indexterm> 8</title> 9 <keywordset> 10 <keyword>ISO C++</keyword> 11 <keyword>library</keyword> 12 </keywordset> 13</info> 14 15 16<preface><info><title/></info> 17<?dbhtml filename="ext_preface.html"?> 18<para> 19 Here we will make an attempt at describing the non-Standard 20 extensions to the library. Some of these are from older versions of 21 standard library components, namely SGI's STL, and some of these are 22 GNU's. 23</para> 24<para><emphasis>Before</emphasis> you leap in and use any of these 25extensions, be aware of two things: 26</para> 27<orderedlist inheritnum="ignore" continuation="restarts"> 28 <listitem> 29 <para> 30 Non-Standard means exactly that. 31 </para> 32 <para> 33 The behavior, and the very 34 existence, of these extensions may change with little or no 35 warning. (Ideally, the really good ones will appear in the next 36 revision of C++.) Also, other platforms, other compilers, other 37 versions of g++ or libstdc++ may not recognize these names, or 38 treat them differently, or... 39 </para> 40 </listitem> 41 <listitem> 42 <para> 43 You should know how to access these headers properly. 44 </para> 45 </listitem> 46</orderedlist> 47</preface> 48 49<!-- Chapter 01 : Compile Time Checks --> 50<chapter xml:id="manual.ext.compile_checks" xreflabel="Compile Time Checks"><info><title>Compile Time Checks</title></info> 51<?dbhtml filename="ext_compile_checks.html"?> 52 53 <para> 54 Also known as concept checking. 55 </para> 56 <para>In 1999, SGI added <emphasis>concept checkers</emphasis> to their implementation 57 of the STL: code which checked the template parameters of 58 instantiated pieces of the STL, in order to insure that the parameters 59 being used met the requirements of the standard. For example, 60 the Standard requires that types passed as template parameters to 61 <code>vector</code> be <quote>Assignable</quote> (which means what you think 62 it means). The checking was done during compilation, and none of 63 the code was executed at runtime. 64 </para> 65 <para>Unfortunately, the size of the compiler files grew significantly 66 as a result. The checking code itself was cumbersome. And bugs 67 were found in it on more than one occasion. 68 </para> 69 <para>The primary author of the checking code, Jeremy Siek, had already 70 started work on a replacement implementation. The new code has been 71 formally reviewed and accepted into 72 <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.boost.org/libs/concept_check/concept_check.htm">the 73 Boost libraries</link>, and we are pleased to incorporate it into the 74 GNU C++ library. 75 </para> 76 <para>The new version imposes a much smaller space overhead on the generated 77 object file. The checks are also cleaner and easier to read and 78 understand. 79 </para> 80 <para>They are off by default for all versions of GCC from 3.0 to 3.4 (the 81 latest release at the time of writing). 82 They can be enabled at configure time with 83 <link linkend="manual.intro.setup.configure"><literal>--enable-concept-checks</literal></link>. 84 You can enable them on a per-translation-unit basis with 85 <code>#define _GLIBCXX_CONCEPT_CHECKS</code> for GCC 3.4 and higher 86 (or with <code>#define _GLIBCPP_CONCEPT_CHECKS</code> for versions 87 3.1, 3.2 and 3.3). 88 </para> 89 90 <para>Please note that the upcoming C++ standard has first-class 91 support for template parameter constraints based on concepts in the core 92 language. This will obviate the need for the library-simulated concept 93 checking described above. 94 </para> 95 96</chapter> 97 98<!-- Chapter 02 : Debug Mode --> 99<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="xml" 100 href="debug_mode.xml"> 101</xi:include> 102 103<!-- Chapter 03 : Parallel Mode --> 104<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="xml" 105 href="parallel_mode.xml"> 106</xi:include> 107 108<!-- Chapter 04 : Profile Mode --> 109<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="xml" 110 href="profile_mode.xml"> 111</xi:include> 112 113 114<!-- XXX --> 115<!-- Allocators --> 116<!-- Chapter 05 : __mt_alloc --> 117<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="xml" 118 href="mt_allocator.xml"> 119</xi:include> 120 121<!-- Chapter 06 : bitmap_allocator --> 122<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="xml" 123 href="bitmap_allocator.xml"> 124</xi:include> 125 126<!-- Containers --> 127<!-- Chapter 07 : Policy-Based Data Structures --> 128<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="xml" 129 href="policy_data_structures.xml"> 130</xi:include> 131 132<!-- Chapter 08 : HP/SGI --> 133<chapter xml:id="manual.ext.containers" xreflabel="Containers"> 134 <info><title>HP/SGI Extensions</title></info> 135<?dbhtml filename="ext_containers.html"?> 136 137 <section xml:id="manual.ext.containers.sgi" xreflabel="SGI ext"> 138 <info><title>Backwards Compatibility</title></info> 139 140 <para>A few extensions and nods to backwards-compatibility have 141 been made with containers. Those dealing with older SGI-style 142 allocators are dealt with elsewhere. The remaining ones all deal 143 with bits: 144 </para> 145 <para>The old pre-standard <code>bit_vector</code> class is 146 present for backwards compatibility. It is simply a typedef for 147 the <code>vector<bool></code> specialization. 148 </para> 149 150<para>The <code>bitset</code> class has a number of extensions, described in the 151 rest of this item. First, we'll mention that this implementation of 152 <code>bitset<N></code> is specialized for cases where N number of 153 bits will fit into a single word of storage. If your choice of N is 154 within that range (<=32 on i686-pc-linux-gnu, for example), then all 155 of the operations will be faster. 156</para> 157<para>There are 158 versions of single-bit test, set, reset, and flip member functions which 159 do no range-checking. If we call them member functions of an instantiation 160 of <code>bitset<N></code>, then their names and signatures are: 161</para> 162 <programlisting> 163 bitset<N>& _Unchecked_set (size_t pos); 164 bitset<N>& _Unchecked_set (size_t pos, int val); 165 bitset<N>& _Unchecked_reset (size_t pos); 166 bitset<N>& _Unchecked_flip (size_t pos); 167 bool _Unchecked_test (size_t pos); 168 </programlisting> 169 <para>Note that these may in fact be removed in the future, although we have 170 no present plans to do so (and there doesn't seem to be any immediate 171 reason to). 172</para> 173<para>The member function <code>operator[]</code> on a const bitset returns 174 a bool, and for a non-const bitset returns a <code>reference</code> (a 175 nested type). No range-checking is done on the index argument, in keeping 176 with other containers' <code>operator[]</code> requirements. 177</para> 178<para>Finally, two additional searching functions have been added. They return 179 the index of the first "on" bit, and the index of the first 180 "on" bit that is after <code>prev</code>, respectively: 181</para> 182 <programlisting> 183 size_t _Find_first() const; 184 size_t _Find_next (size_t prev) const;</programlisting> 185<para>The same caveat given for the _Unchecked_* functions applies here also. 186</para> 187 </section> 188 189 190 <section xml:id="manual.ext.containers.deprecated_sgi" xreflabel="SGI ext dep"><info><title>Deprecated</title></info> 191 <?dbhtml filename="ext_sgi.html"?> 192 193 194 <para> 195 The SGI hashing classes <classname>hash_set</classname> and 196 <classname>hash_set</classname> have been deprecated by the 197 unordered_set, unordered_multiset, unordered_map, 198 unordered_multimap containers in TR1 and C++11, and 199 may be removed in future releases. 200 </para> 201 202 <para>The SGI headers</para> 203 <programlisting> 204 <hash_map> 205 <hash_set> 206 <rope> 207 <slist> 208 <rb_tree> 209 </programlisting> 210 <para>are all here; 211 <filename class="headerfile"><backwards/hash_map></filename> and 212 <filename class="headerfile"><backwards/hash_set></filename> 213 are deprecated but available as backwards-compatible extensions, 214 as discussed further below. 215 <filename class="headerfile"><ext/rope></filename> is the SGI 216 specialization for large strings ("rope," "large strings," get it? Love 217 that geeky humor.) 218 <filename class="headerfile"><ext/slist></filename> (superseded in 219 C++11 by <filename class="headerfile"><forward_list></filename>) 220 is a singly-linked list, for when the doubly-linked <code>list<></code> 221 is too much space overhead, and 222 <filename class="headerfile"><ext/rb_tree></filename> exposes the 223 red-black tree classes used in the implementation of the standard maps 224 and sets. 225 </para> 226 <para>Each of the associative containers map, multimap, set, and multiset 227 have a counterpart which uses a 228 <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.sgi.com/tech/stl/HashFunction.html">hashing 229 function</link> to do the arranging, instead of a strict weak ordering 230 function. The classes take as one of their template parameters a 231 function object that will return the hash value; by default, an 232 instantiation of 233 <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.sgi.com/tech/stl/hash.html">hash</link>. 234 You should specialize this functor for your class, or define your own, 235 before trying to use one of the hashing classes. 236 </para> 237 <para>The hashing classes support all the usual associative container 238 functions, as well as some extra constructors specifying the number 239 of buckets, etc. 240 </para> 241 <para>Why would you want to use a hashing class instead of the 242 <quote>normal</quote>implementations? Matt Austern writes: 243 </para> 244 <blockquote> 245 <para> 246 <emphasis>[W]ith a well chosen hash function, hash tables 247 generally provide much better average-case performance than 248 binary search trees, and much worse worst-case performance. So 249 if your implementation has hash_map, if you don't mind using 250 nonstandard components, and if you aren't scared about the 251 possibility of pathological cases, you'll probably get better 252 performance from hash_map. 253 </emphasis> 254 </para> 255 </blockquote> 256 257 <para> 258 The deprecated hash tables are superseded by the standard unordered 259 associative containers defined in the ISO C++ 2011 standard in the 260 headers <filename class="headerfile"><unordered_map></filename> 261 and <filename class="headerfile"><unordered_set></filename>. 262 </para> 263 264 </section> 265</chapter> 266 267<!-- Chapter 09 : Utilities --> 268<chapter xml:id="manual.ext.util" xreflabel="Utilities"><info><title>Utilities</title></info> 269<?dbhtml filename="ext_utilities.html"?> 270 271 <para> 272 The <filename class="headerfile"><functional></filename> header 273 contains many additional functors 274 and helper functions, extending section 20.3. They are 275 implemented in the file stl_function.h: 276 </para> 277 <itemizedlist> 278 <listitem> 279 <para><code>identity_element</code> for addition and multiplication. 280 </para> 281 </listitem> 282 <listitem> 283 <para>The functor <code>identity</code>, whose <code>operator()</code> 284 returns the argument unchanged. 285 </para> 286 </listitem> 287 <listitem> 288 <para>Composition functors <code>unary_function</code> and 289 <code>binary_function</code>, and their helpers <code>compose1</code> 290 and <code>compose2</code>. 291 </para> 292 </listitem> 293 <listitem> 294 <para><code>select1st</code> and <code>select2nd</code>, to strip pairs. 295 </para> 296 </listitem> 297 <listitem><para><code>project1st</code> and <code>project2nd</code>. </para></listitem> 298 <listitem><para>A set of functors/functions which always return the same result. They 299 are <code>constant_void_fun</code>, <code>constant_binary_fun</code>, 300 <code>constant_unary_fun</code>, <code>constant0</code>, 301 <code>constant1</code>, and <code>constant2</code>. </para></listitem> 302 <listitem><para>The class <code>subtractive_rng</code>. </para></listitem> 303 <listitem><para>mem_fun adaptor helpers <code>mem_fun1</code> and 304 <code>mem_fun1_ref</code> are provided for backwards compatibility. </para></listitem> 305</itemizedlist> 306<para> 307 20.4.1 can use several different allocators; they are described on the 308 main extensions page. 309</para> 310<para> 311 20.4.3 is extended with a special version of 312 <code>get_temporary_buffer</code> taking a second argument. The 313 argument is a pointer, which is ignored, but can be used to specify 314 the template type (instead of using explicit function template 315 arguments like the standard version does). That is, in addition to 316</para> 317<programlisting> 318get_temporary_buffer<int>(5); 319</programlisting> 320 321<para> 322you can also use 323</para> 324 325<programlisting> 326get_temporary_buffer(5, (int*)0); 327</programlisting> 328<para> 329 A class <code>temporary_buffer</code> is given in stl_tempbuf.h. 330</para> 331<para> 332 The specialized algorithms of section 20.4.4 are extended with 333 <code>uninitialized_copy_n</code>. 334</para> 335 336</chapter> 337 338<!-- Chapter 10 : Algorithms --> 339<chapter xml:id="manual.ext.algorithms" xreflabel="Algorithms"><info><title>Algorithms</title></info> 340<?dbhtml filename="ext_algorithms.html"?> 341 342<para>25.1.6 (count, count_if) is extended with two more versions of count 343 and count_if. The standard versions return their results. The 344 additional signatures return void, but take a final parameter by 345 reference to which they assign their results, e.g., 346</para> 347 <programlisting> 348 void count (first, last, value, n);</programlisting> 349<para>25.2 (mutating algorithms) is extended with two families of signatures, 350 random_sample and random_sample_n. 351</para> 352<para>25.2.1 (copy) is extended with 353</para> 354 <programlisting> 355 copy_n (_InputIter first, _Size count, _OutputIter result);</programlisting> 356<para>which copies the first 'count' elements at 'first' into 'result'. 357</para> 358<para>25.3 (sorting 'n' heaps 'n' stuff) is extended with some helper 359 predicates. Look in the doxygen-generated pages for notes on these. 360</para> 361 <itemizedlist> 362 <listitem><para><code>is_heap</code> tests whether or not a range is a heap.</para></listitem> 363 <listitem><para><code>is_sorted</code> tests whether or not a range is sorted in 364 nondescending order.</para></listitem> 365 </itemizedlist> 366<para>25.3.8 (lexicographical_compare) is extended with 367</para> 368 <programlisting> 369 lexicographical_compare_3way(_InputIter1 first1, _InputIter1 last1, 370 _InputIter2 first2, _InputIter2 last2)</programlisting> 371<para>which does... what? 372</para> 373 374</chapter> 375 376<!-- Chapter 11 : Numerics --> 377<chapter xml:id="manual.ext.numerics" xreflabel="Numerics"><info><title>Numerics</title></info> 378<?dbhtml filename="ext_numerics.html"?> 379 380<para>26.4, the generalized numeric operations such as <code>accumulate</code>, 381 are extended with the following functions: 382</para> 383 <programlisting> 384 power (x, n); 385 power (x, n, monoid_operation);</programlisting> 386<para>Returns, in FORTRAN syntax, "<code>x ** n</code>" where 387 <code>n >= 0</code>. In the 388 case of <code>n == 0</code>, returns the identity element for the 389 monoid operation. The two-argument signature uses multiplication (for 390 a true "power" implementation), but addition is supported as well. 391 The operation functor must be associative. 392</para> 393<para>The <code>iota</code> function wins the award for Extension With the 394 Coolest Name (the name comes from Ken Iverson's APL language.) As 395 described in the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.sgi.com/tech/stl/iota.html">SGI 396 documentation</link>, it "assigns sequentially increasing values to a range. 397 That is, it assigns <code>value</code> to <code>*first</code>, 398 <code>value + 1</code> to<code> *(first + 1)</code> and so on." 399</para> 400 <programlisting> 401 void iota(_ForwardIter first, _ForwardIter last, _Tp value);</programlisting> 402<para>The <code>iota</code> function is included in the ISO C++ 2011 standard. 403</para> 404</chapter> 405 406<!-- Chapter 12 : Iterators --> 407<chapter xml:id="manual.ext.iterators" xreflabel="Iterators"><info><title>Iterators</title></info> 408<?dbhtml filename="ext_iterators.html"?> 409 410<para>24.3.2 describes <code>struct iterator</code>, which didn't exist in the 411 original HP STL implementation (the language wasn't rich enough at the 412 time). For backwards compatibility, base classes are provided which 413 declare the same nested typedefs: 414</para> 415 <itemizedlist> 416 <listitem><para>input_iterator</para></listitem> 417 <listitem><para>output_iterator</para></listitem> 418 <listitem><para>forward_iterator</para></listitem> 419 <listitem><para>bidirectional_iterator</para></listitem> 420 <listitem><para>random_access_iterator</para></listitem> 421 </itemizedlist> 422<para>24.3.4 describes iterator operation <code>distance</code>, which takes 423 two iterators and returns a result. It is extended by another signature 424 which takes two iterators and a reference to a result. The result is 425 modified, and the function returns nothing. 426</para> 427 428</chapter> 429 430<!-- Chapter 13 : IO --> 431<chapter xml:id="manual.ext.io" xreflabel="IO"><info><title>Input and Output</title></info> 432<?dbhtml filename="ext_io.html"?> 433 434 435 <para> 436 Extensions allowing <code>filebuf</code>s to be constructed from 437 "C" types like FILE*s and file descriptors. 438 </para> 439 440 <section xml:id="manual.ext.io.filebuf_derived" xreflabel="Derived filebufs"><info><title>Derived filebufs</title></info> 441 442 443 <para>The v2 library included non-standard extensions to construct 444 <code>std::filebuf</code>s from C stdio types such as 445 <code>FILE*</code>s and POSIX file descriptors. 446 Today the recommended way to use stdio types with libstdc++ 447 IOStreams is via the <code>stdio_filebuf</code> class (see below), 448 but earlier releases provided slightly different mechanisms. 449 </para> 450 <itemizedlist> 451 <listitem><para>3.0.x <code>filebuf</code>s have another ctor with this signature: 452 <code>basic_filebuf(__c_file_type*, ios_base::openmode, int_type); 453 </code> 454 This comes in very handy in a number of places, such as 455 attaching Unix sockets, pipes, and anything else which uses file 456 descriptors, into the IOStream buffering classes. The three 457 arguments are as follows: 458 <itemizedlist> 459 <listitem><para><code>__c_file_type* F </code> 460 // the __c_file_type typedef usually boils down to stdio's FILE 461 </para></listitem> 462 <listitem><para><code>ios_base::openmode M </code> 463 // same as all the other uses of openmode 464 </para></listitem> 465 <listitem><para><code>int_type B </code> 466 // buffer size, defaults to BUFSIZ if not specified 467 </para></listitem> 468 </itemizedlist> 469 For those wanting to use file descriptors instead of FILE*'s, I 470 invite you to contemplate the mysteries of C's <code>fdopen()</code>. 471 </para></listitem> 472 <listitem><para>In library snapshot 3.0.95 and later, <code>filebuf</code>s bring 473 back an old extension: the <code>fd()</code> member function. The 474 integer returned from this function can be used for whatever file 475 descriptors can be used for on your platform. Naturally, the 476 library cannot track what you do on your own with a file descriptor, 477 so if you perform any I/O directly, don't expect the library to be 478 aware of it. 479 </para></listitem> 480 <listitem><para>Beginning with 3.1, the extra <code>filebuf</code> constructor and 481 the <code>fd()</code> function were removed from the standard 482 filebuf. Instead, <code><ext/stdio_filebuf.h></code> contains 483 a derived class called 484 <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/a00074.html"><code>__gnu_cxx::stdio_filebuf</code></link>. 485 This class can be constructed from a C <code>FILE*</code> or a file 486 descriptor, and provides the <code>fd()</code> function. 487 </para></listitem> 488 </itemizedlist> 489 490 </section> 491</chapter> 492 493<!-- Chapter 14 : Demangling --> 494<chapter xml:id="manual.ext.demangle" xreflabel="Demangling"><info><title>Demangling</title></info> 495<?dbhtml filename="ext_demangling.html"?> 496 497 <para> 498 Transforming C++ ABI identifiers (like RTTI symbols) into the 499 original C++ source identifiers is called 500 <quote>demangling.</quote> 501 </para> 502 <para> 503 If you have read the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/a01115.html">source 504 documentation for <code>namespace abi</code></link> then you are 505 aware of the cross-vendor C++ ABI in use by GCC. One of the 506 exposed functions is used for demangling, 507 <code>abi::__cxa_demangle</code>. 508 </para> 509 <para> 510 In programs like <command>c++filt</command>, the linker, and other tools 511 have the ability to decode C++ ABI names, and now so can you. 512 </para> 513 <para> 514 (The function itself might use different demanglers, but that's the 515 whole point of abstract interfaces. If we change the implementation, 516 you won't notice.) 517 </para> 518 <para> 519 Probably the only times you'll be interested in demangling at runtime 520 are when you're seeing <code>typeid</code> strings in RTTI, or when 521 you're handling the runtime-support exception classes. For example: 522 </para> 523 <programlisting> 524#include <exception> 525#include <iostream> 526#include <cxxabi.h> 527 528struct empty { }; 529 530template <typename T, int N> 531 struct bar { }; 532 533 534int main() 535{ 536 int status; 537 char *realname; 538 539 // exception classes not in <stdexcept>, thrown by the implementation 540 // instead of the user 541 std::bad_exception e; 542 realname = abi::__cxa_demangle(e.what(), 0, 0, &status); 543 std::cout << e.what() << "\t=> " << realname << "\t: " << status << '\n'; 544 free(realname); 545 546 547 // typeid 548 bar<empty,17> u; 549 const std::type_info &ti = typeid(u); 550 551 realname = abi::__cxa_demangle(ti.name(), 0, 0, &status); 552 std::cout << ti.name() << "\t=> " << realname << "\t: " << status << '\n'; 553 free(realname); 554 555 return 0; 556} 557 </programlisting> 558 <para> 559 This prints 560 </para> 561 562 <screen> 563 <computeroutput> 564 St13bad_exception => std::bad_exception : 0 565 3barI5emptyLi17EE => bar<empty, 17> : 0 566 </computeroutput> 567 </screen> 568 569 <para> 570 The demangler interface is described in the source documentation 571 linked to above. It is actually written in C, so you don't need to 572 be writing C++ in order to demangle C++. (That also means we have to 573 use crummy memory management facilities, so don't forget to free() 574 the returned char array.) 575 </para> 576</chapter> 577 578<!-- Chapter 15 : Concurrency --> 579<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="xml" href="concurrency_extensions.xml"> 580</xi:include> 581 582</part> 583