1 <part xmlns="http://docbook.org/ns/docbook" version="5.0"
2 xml:id="manual.ext" xreflabel="Extensions">
3 <?dbhtml filename="extensions.html"?>
7 <indexterm><primary>Extensions</primary></indexterm>
20 <preface><info><title/></info>
22 Here we will make an attempt at describing the non-Standard
23 extensions to the library. Some of these are from older versions of
24 standard library components, namely SGI's STL, and some of these are
27 <para><emphasis>Before</emphasis> you leap in and use any of these
28 extensions, be aware of two things:
30 <orderedlist inheritnum="ignore" continuation="restarts">
33 Non-Standard means exactly that.
36 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...
46 You should know how to access these headers properly.
52 <!-- Chapter 01 : Compile Time Checks -->
53 <chapter xml:id="manual.ext.compile_checks" xreflabel="Compile Time Checks"><info><title>Compile Time Checks</title></info>
54 <?dbhtml filename="ext_compile_checks.html"?>
57 Also known as concept checking.
59 <para>In 1999, SGI added <emphasis>concept checkers</emphasis> to their implementation
60 of the STL: code which checked the template parameters of
61 instantiated pieces of the STL, in order to insure that the parameters
62 being used met the requirements of the standard. For example,
63 the Standard requires that types passed as template parameters to
64 <code>vector</code> be <quote>Assignable</quote> (which means what you think
65 it means). The checking was done during compilation, and none of
66 the code was executed at runtime.
68 <para>Unfortunately, the size of the compiler files grew significantly
69 as a result. The checking code itself was cumbersome. And bugs
70 were found in it on more than one occasion.
72 <para>The primary author of the checking code, Jeremy Siek, had already
73 started work on a replacement implementation. The new code has been
74 formally reviewed and accepted into
75 <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.boost.org/libs/concept_check/concept_check.htm">the
76 Boost libraries</link>, and we are pleased to incorporate it into the
79 <para>The new version imposes a much smaller space overhead on the generated
80 object file. The checks are also cleaner and easier to read and
83 <para>They are off by default for all versions of GCC from 3.0 to 3.4 (the
84 latest release at the time of writing).
85 They can be enabled at configure time with
86 <link linkend="manual.intro.setup.configure"><literal>--enable-concept-checks</literal></link>.
87 You can enable them on a per-translation-unit basis with
88 <code>#define _GLIBCXX_CONCEPT_CHECKS</code> for GCC 3.4 and higher
89 (or with <code>#define _GLIBCPP_CONCEPT_CHECKS</code> for versions
93 <para>Please note that the upcoming C++ standard has first-class
94 support for template parameter constraints based on concepts in the core
95 language. This will obviate the need for the library-simulated concept
96 checking described above.
101 <!-- Chapter 02 : Debug Mode -->
102 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="xml"
103 href="debug_mode.xml">
106 <!-- Chapter 03 : Parallel Mode -->
107 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="xml"
108 href="parallel_mode.xml">
111 <!-- Chapter 04 : Profile Mode -->
112 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="xml"
113 href="profile_mode.xml">
119 <!-- Chapter 05 : __mt_alloc -->
120 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="xml"
121 href="mt_allocator.xml">
124 <!-- Chapter 06 : bitmap_allocator -->
125 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="xml"
126 href="bitmap_allocator.xml">
130 <!-- Chapter 07 : Policy-Based Data Structures -->
131 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="xml"
132 href="policy_data_structures.xml">
135 <!-- Chapter 08 : HP/SGI -->
136 <chapter xml:id="manual.ext.containers" xreflabel="Containers">
137 <info><title>HP/SGI Extensions</title></info>
138 <?dbhtml filename="ext_containers.html"?>
140 <section xml:id="manual.ext.containers.sgi" xreflabel="SGI ext">
141 <info><title>Backwards Compatibility</title></info>
143 <para>A few extensions and nods to backwards-compatibility have
144 been made with containers. Those dealing with older SGI-style
145 allocators are dealt with elsewhere. The remaining ones all deal
148 <para>The old pre-standard <code>bit_vector</code> class is
149 present for backwards compatibility. It is simply a typedef for
150 the <code>vector<bool></code> specialization.
153 <para>The <code>bitset</code> class has a number of extensions, described in the
154 rest of this item. First, we'll mention that this implementation of
155 <code>bitset<N></code> is specialized for cases where N number of
156 bits will fit into a single word of storage. If your choice of N is
157 within that range (<=32 on i686-pc-linux-gnu, for example), then all
158 of the operations will be faster.
161 versions of single-bit test, set, reset, and flip member functions which
162 do no range-checking. If we call them member functions of an instantiation
163 of "bitset<N>," then their names and signatures are:
166 bitset<N>& _Unchecked_set (size_t pos);
167 bitset<N>& _Unchecked_set (size_t pos, int val);
168 bitset<N>& _Unchecked_reset (size_t pos);
169 bitset<N>& _Unchecked_flip (size_t pos);
170 bool _Unchecked_test (size_t pos);
172 <para>Note that these may in fact be removed in the future, although we have
173 no present plans to do so (and there doesn't seem to be any immediate
176 <para>The semantics of member function <code>operator[]</code> are not specified
177 in the C++ standard. A long-standing defect report calls for sensible
178 obvious semantics, which are already implemented here: <code>op[]</code>
179 on a const bitset returns a bool, and for a non-const bitset returns a
180 <code>reference</code> (a nested type). However, this implementation does
181 no range-checking on the index argument, which is in keeping with other
182 containers' <code>op[]</code> requirements. The defect report's proposed
183 resolution calls for range-checking to be done. We'll just wait and see...
185 <para>Finally, two additional searching functions have been added. They return
186 the index of the first "on" bit, and the index of the first
187 "on" bit that is after <code>prev</code>, respectively:
190 size_t _Find_first() const;
191 size_t _Find_next (size_t prev) const;</programlisting>
192 <para>The same caveat given for the _Unchecked_* functions applies here also.
197 <section xml:id="manual.ext.containers.deprecated_sgi" xreflabel="SGI ext dep"><info><title>Deprecated</title></info>
201 The SGI hashing classes <classname>hash_set</classname> and
202 <classname>hash_set</classname> have been deprecated by the
203 unordered_set, unordered_multiset, unordered_map,
204 unordered_multimap containers in TR1 and C++11, and
205 may be removed in future releases.
208 <para>The SGI headers</para>
217 <code><hash_map></code> and <code><hash_set></code>
218 are deprecated but available as backwards-compatible extensions,
219 as discussed further below. <code><rope></code> is the
220 SGI specialization for large strings ("rope,"
221 "large strings," get it? Love that geeky humor.)
222 <code><slist></code> is a singly-linked list, for when the
223 doubly-linked <code>list<></code> is too much space
224 overhead, and <code><rb_tree></code> exposes the red-black
225 tree classes used in the implementation of the standard maps and
228 <para>Each of the associative containers map, multimap, set, and multiset
229 have a counterpart which uses a
230 <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.sgi.com/tech/stl/HashFunction.html">hashing
231 function</link> to do the arranging, instead of a strict weak ordering
232 function. The classes take as one of their template parameters a
233 function object that will return the hash value; by default, an
235 <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.sgi.com/tech/stl/hash.html">hash</link>.
236 You should specialize this functor for your class, or define your own,
237 before trying to use one of the hashing classes.
239 <para>The hashing classes support all the usual associative container
240 functions, as well as some extra constructors specifying the number
243 <para>Why would you want to use a hashing class instead of the
244 <quote>normal</quote>implementations? Matt Austern writes:
248 <emphasis>[W]ith a well chosen hash function, hash tables
249 generally provide much better average-case performance than
250 binary search trees, and much worse worst-case performance. So
251 if your implementation has hash_map, if you don't mind using
252 nonstandard components, and if you aren't scared about the
253 possibility of pathological cases, you'll probably get better
254 performance from hash_map.
262 <!-- Chapter 09 : Utilities -->
263 <chapter xml:id="manual.ext.util" xreflabel="Utilities"><info><title>Utilities</title></info>
264 <?dbhtml filename="ext_utilities.html"?>
267 The <functional> header contains many additional functors
268 and helper functions, extending section 20.3. They are
269 implemented in the file stl_function.h:
273 <para><code>identity_element</code> for addition and multiplication. *
277 <para>The functor <code>identity</code>, whose <code>operator()</code>
278 returns the argument unchanged. *
282 <para>Composition functors <code>unary_function</code> and
283 <code>binary_function</code>, and their helpers <code>compose1</code>
284 and <code>compose2</code>. *
288 <para><code>select1st</code> and <code>select2nd</code>, to strip pairs. *
291 <listitem><para><code>project1st</code> and <code>project2nd</code>. * </para></listitem>
292 <listitem><para>A set of functors/functions which always return the same result. They
293 are <code>constant_void_fun</code>, <code>constant_binary_fun</code>,
294 <code>constant_unary_fun</code>, <code>constant0</code>,
295 <code>constant1</code>, and <code>constant2</code>. * </para></listitem>
296 <listitem><para>The class <code>subtractive_rng</code>. * </para></listitem>
297 <listitem><para>mem_fun adaptor helpers <code>mem_fun1</code> and
298 <code>mem_fun1_ref</code> are provided for backwards compatibility. </para></listitem>
301 20.4.1 can use several different allocators; they are described on the
302 main extensions page.
305 20.4.3 is extended with a special version of
306 <code>get_temporary_buffer</code> taking a second argument. The
307 argument is a pointer, which is ignored, but can be used to specify
308 the template type (instead of using explicit function template
309 arguments like the standard version does). That is, in addition to
312 get_temporary_buffer<int>(5);
320 get_temporary_buffer(5, (int*)0);
323 A class <code>temporary_buffer</code> is given in stl_tempbuf.h. *
326 The specialized algorithms of section 20.4.4 are extended with
327 <code>uninitialized_copy_n</code>. *
332 <!-- Chapter 10 : Algorithms -->
333 <chapter xml:id="manual.ext.algorithms" xreflabel="Algorithms"><info><title>Algorithms</title></info>
334 <?dbhtml filename="ext_algorithms.html"?>
336 <para>25.1.6 (count, count_if) is extended with two more versions of count
337 and count_if. The standard versions return their results. The
338 additional signatures return void, but take a final parameter by
339 reference to which they assign their results, e.g.,
342 void count (first, last, value, n);</programlisting>
343 <para>25.2 (mutating algorithms) is extended with two families of signatures,
344 random_sample and random_sample_n.
346 <para>25.2.1 (copy) is extended with
349 copy_n (_InputIter first, _Size count, _OutputIter result);</programlisting>
350 <para>which copies the first 'count' elements at 'first' into 'result'.
352 <para>25.3 (sorting 'n' heaps 'n' stuff) is extended with some helper
353 predicates. Look in the doxygen-generated pages for notes on these.
356 <listitem><para><code>is_heap</code> tests whether or not a range is a heap.</para></listitem>
357 <listitem><para><code>is_sorted</code> tests whether or not a range is sorted in
358 nondescending order.</para></listitem>
360 <para>25.3.8 (lexicographical_compare) is extended with
363 lexicographical_compare_3way(_InputIter1 first1, _InputIter1 last1,
364 _InputIter2 first2, _InputIter2 last2)</programlisting>
365 <para>which does... what?
370 <!-- Chapter 11 : Numerics -->
371 <chapter xml:id="manual.ext.numerics" xreflabel="Numerics"><info><title>Numerics</title></info>
372 <?dbhtml filename="ext_numerics.html"?>
374 <para>26.4, the generalized numeric operations such as accumulate, are extended
375 with the following functions:
379 power (x, n, moniod_operation);</programlisting>
380 <para>Returns, in FORTRAN syntax, "x ** n" where n>=0. In the
381 case of n == 0, returns the identity element for the
382 monoid operation. The two-argument signature uses multiplication (for
383 a true "power" implementation), but addition is supported as well.
384 The operation functor must be associative.
386 <para>The <code>iota</code> function wins the award for Extension With the
387 Coolest Name. It "assigns sequentially increasing values to a range.
388 That is, it assigns value to *first, value + 1 to *(first + 1) and so
389 on." Quoted from SGI documentation.
392 void iota(_ForwardIter first, _ForwardIter last, _Tp value);</programlisting>
395 <!-- Chapter 12 : Iterators -->
396 <chapter xml:id="manual.ext.iterators" xreflabel="Iterators"><info><title>Iterators</title></info>
397 <?dbhtml filename="ext_iterators.html"?>
399 <para>24.3.2 describes <code>struct iterator</code>, which didn't exist in the
400 original HP STL implementation (the language wasn't rich enough at the
401 time). For backwards compatibility, base classes are provided which
402 declare the same nested typedefs:
405 <listitem><para>input_iterator</para></listitem>
406 <listitem><para>output_iterator</para></listitem>
407 <listitem><para>forward_iterator</para></listitem>
408 <listitem><para>bidirectional_iterator</para></listitem>
409 <listitem><para>random_access_iterator</para></listitem>
411 <para>24.3.4 describes iterator operation <code>distance</code>, which takes
412 two iterators and returns a result. It is extended by another signature
413 which takes two iterators and a reference to a result. The result is
414 modified, and the function returns nothing.
419 <!-- Chapter 13 : IO -->
420 <chapter xml:id="manual.ext.io" xreflabel="IO"><info><title>Input and Output</title></info>
421 <?dbhtml filename="ext_io.html"?>
425 Extensions allowing <code>filebuf</code>s to be constructed from
426 "C" types like FILE*s and file descriptors.
429 <section xml:id="manual.ext.io.filebuf_derived" xreflabel="Derived filebufs"><info><title>Derived filebufs</title></info>
432 <para>The v2 library included non-standard extensions to construct
433 <code>std::filebuf</code>s from C stdio types such as
434 <code>FILE*</code>s and POSIX file descriptors.
435 Today the recommended way to use stdio types with libstdc++
436 IOStreams is via the <code>stdio_filebuf</code> class (see below),
437 but earlier releases provided slightly different mechanisms.
440 <listitem><para>3.0.x <code>filebuf</code>s have another ctor with this signature:
441 <code>basic_filebuf(__c_file_type*, ios_base::openmode, int_type);
443 This comes in very handy in a number of places, such as
444 attaching Unix sockets, pipes, and anything else which uses file
445 descriptors, into the IOStream buffering classes. The three
446 arguments are as follows:
448 <listitem><para><code>__c_file_type* F </code>
449 // the __c_file_type typedef usually boils down to stdio's FILE
451 <listitem><para><code>ios_base::openmode M </code>
452 // same as all the other uses of openmode
454 <listitem><para><code>int_type B </code>
455 // buffer size, defaults to BUFSIZ if not specified
458 For those wanting to use file descriptors instead of FILE*'s, I
459 invite you to contemplate the mysteries of C's <code>fdopen()</code>.
461 <listitem><para>In library snapshot 3.0.95 and later, <code>filebuf</code>s bring
462 back an old extension: the <code>fd()</code> member function. The
463 integer returned from this function can be used for whatever file
464 descriptors can be used for on your platform. Naturally, the
465 library cannot track what you do on your own with a file descriptor,
466 so if you perform any I/O directly, don't expect the library to be
469 <listitem><para>Beginning with 3.1, the extra <code>filebuf</code> constructor and
470 the <code>fd()</code> function were removed from the standard
471 filebuf. Instead, <code><ext/stdio_filebuf.h></code> contains
472 a derived class called
473 <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>.
474 This class can be constructed from a C <code>FILE*</code> or a file
475 descriptor, and provides the <code>fd()</code> function.
478 <para>If you want to access a <code>filebuf</code>'s file descriptor to
479 implement file locking (e.g. using the <code>fcntl()</code> system
480 call) then you might be interested in Henry Suter's RWLock class.
481 <!-- url="http://suter.home.cern.ch/suter/RWLock.html" -->
489 <!-- Chapter 14 : Demangling -->
490 <chapter xml:id="manual.ext.demangle" xreflabel="Demangling"><info><title>Demangling</title></info>
491 <?dbhtml filename="ext_demangling.html"?>
494 Transforming C++ ABI identifiers (like RTTI symbols) into the
495 original C++ source identifiers is called
496 <quote>demangling.</quote>
499 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
500 documentation for <code>namespace abi</code></link> then you are
501 aware of the cross-vendor C++ ABI in use by GCC. One of the
502 exposed functions is used for demangling,
503 <code>abi::__cxa_demangle</code>.
506 In programs like <command>c++filt</command>, the linker, and other tools
507 have the ability to decode C++ ABI names, and now so can you.
510 (The function itself might use different demanglers, but that's the
511 whole point of abstract interfaces. If we change the implementation,
515 Probably the only times you'll be interested in demangling at runtime
516 are when you're seeing <code>typeid</code> strings in RTTI, or when
517 you're handling the runtime-support exception classes. For example:
520 #include <exception>
521 #include <iostream>
522 #include <cxxabi.h>
526 template <typename T, int N>
535 // exception classes not in <stdexcept>, thrown by the implementation
536 // instead of the user
537 std::bad_exception e;
538 realname = abi::__cxa_demangle(e.what(), 0, 0, &status);
539 std::cout << e.what() << "\t=> " << realname << "\t: " << status << '\n';
544 bar<empty,17> u;
545 const std::type_info &ti = typeid(u);
547 realname = abi::__cxa_demangle(ti.name(), 0, 0, &status);
548 std::cout << ti.name() << "\t=> " << realname << "\t: " << status << '\n';
560 St13bad_exception => std::bad_exception : 0
561 3barI5emptyLi17EE => bar<empty, 17> : 0
566 The demangler interface is described in the source documentation
567 linked to above. It is actually written in C, so you don't need to
568 be writing C++ in order to demangle C++. (That also means we have to
569 use crummy memory management facilities, so don't forget to free()
570 the returned char array.)
574 <!-- Chapter 15 : Concurrency -->
575 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="xml" href="concurrency_extensions.xml">