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