2 <!DOCTYPE part PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3 "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"
6 <part id="manual.ext" xreflabel="Extensions">
7 <?dbhtml filename="extensions.html"?>
22 <indexterm><primary>Extensions</primary></indexterm>
28 Here we will make an attempt at describing the non-Standard extensions to
29 the library. Some of these are from SGI's STL, some of these are GNU's,
30 and some just seemed to appear on the doorstep.
32 <para><emphasis>Before</emphasis> you leap in and use any of these
33 extensions, be aware of two things:
38 Non-Standard means exactly that.
41 The behavior, and the very
42 existence, of these extensions may change with little or no
43 warning. (Ideally, the really good ones will appear in the next
44 revision of C++.) Also, other platforms, other compilers, other
45 versions of g++ or libstdc++ may not recognize these names, or
46 treat them differently, or...
51 You should know how to access these headers properly.
57 <!-- Chapter 01 : Compile Time Checks -->
58 <chapter id="manual.ext.compile_checks" xreflabel="Compile Time Checks">
59 <?dbhtml filename="ext_compile_checks.html"?>
60 <title>Compile Time Checks</title>
62 Also known as concept checking.
64 <para>In 1999, SGI added <emphasis>concept checkers</emphasis> to their implementation
65 of the STL: code which checked the template parameters of
66 instantiated pieces of the STL, in order to insure that the parameters
67 being used met the requirements of the standard. For example,
68 the Standard requires that types passed as template parameters to
69 <code>vector</code> be <quote>Assignable</quote> (which means what you think
70 it means). The checking was done during compilation, and none of
71 the code was executed at runtime.
73 <para>Unfortunately, the size of the compiler files grew significantly
74 as a result. The checking code itself was cumbersome. And bugs
75 were found in it on more than one occasion.
77 <para>The primary author of the checking code, Jeremy Siek, had already
78 started work on a replacement implementation. The new code has been
79 formally reviewed and accepted into
80 <ulink url="http://www.boost.org/libs/concept_check/concept_check.htm">the
81 Boost libraries</ulink>, and we are pleased to incorporate it into the
84 <para>The new version imposes a much smaller space overhead on the generated
85 object file. The checks are also cleaner and easier to read and
88 <para>They are off by default for all versions of GCC from 3.0 to 3.4 (the
89 latest release at the time of writing).
90 They can be enabled at configure time with
91 <link linkend="manual.intro.setup.configure"><literal>--enable-concept-checks</literal></link>.
92 You can enable them on a per-translation-unit basis with
93 <code>#define _GLIBCXX_CONCEPT_CHECKS</code> for GCC 3.4 and higher
94 (or with <code>#define _GLIBCPP_CONCEPT_CHECKS</code> for versions
98 <para>Please note that the upcoming C++ standard has first-class
99 support for template parameter constraints based on concepts in the core
100 language. This will obviate the need for the library-simulated concept
101 checking described above.
106 <!-- Chapter 02 : Debug Mode -->
107 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
108 parse="xml" href="debug_mode.xml">
111 <!-- Chapter 03 : Parallel Mode -->
112 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
113 parse="xml" href="parallel_mode.xml">
116 <!-- Chapter 04 : Allocators -->
117 <chapter id="manual.ext.allocator" xreflabel="Allocators">
118 <?dbhtml filename="ext_allocators.html"?>
119 <title>Allocators</title>
121 <!-- Section 01 : __mt_alloc -->
122 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
123 parse="xml" href="mt_allocator.xml">
126 <!-- Section 02 : bitmap_allocator -->
127 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
128 parse="xml" href="bitmap_allocator.xml">
133 <!-- Chapter 05 : Containers -->
134 <chapter id="manual.ext.containers" xreflabel="Containers">
135 <?dbhtml filename="ext_containers.html"?>
136 <title>Containers</title>
139 <sect1 id="manual.ext.containers.pbds" xreflabel="Policy Based Data Structures">
140 <title>Policy Based Data Structures</title>
143 url="http://gcc.gnu.org/onlinedocs/libstdc++/ext/pb_ds/index.html">More details here</ulink>.
147 <sect1 id="manual.ext.containers.sgi" xreflabel="SGI ext">
148 <title>HP/SGI</title>
152 <para>A few extensions and nods to backwards-compatibility have been made with
153 containers. Those dealing with older SGI-style allocators are dealt with
154 elsewhere. The remaining ones all deal with bits:
156 <para>The old pre-standard <code>bit_vector</code> class is present for
157 backwards compatibility. It is simply a typedef for the
158 <code>vector<bool></code> specialization.
160 <para>The <code>bitset</code> class has a number of extensions, described in the
161 rest of this item. First, we'll mention that this implementation of
162 <code>bitset<N></code> is specialized for cases where N number of
163 bits will fit into a single word of storage. If your choice of N is
164 within that range (<=32 on i686-pc-linux-gnu, for example), then all
165 of the operations will be faster.
168 versions of single-bit test, set, reset, and flip member functions which
169 do no range-checking. If we call them member functions of an instantiation
170 of "bitset<N>," then their names and signatures are:
173 bitset<N>& _Unchecked_set (size_t pos);
174 bitset<N>& _Unchecked_set (size_t pos, int val);
175 bitset<N>& _Unchecked_reset (size_t pos);
176 bitset<N>& _Unchecked_flip (size_t pos);
177 bool _Unchecked_test (size_t pos);
179 <para>Note that these may in fact be removed in the future, although we have
180 no present plans to do so (and there doesn't seem to be any immediate
183 <para>The semantics of member function <code>operator[]</code> are not specified
184 in the C++ standard. A long-standing defect report calls for sensible
185 obvious semantics, which are already implemented here: <code>op[]</code>
186 on a const bitset returns a bool, and for a non-const bitset returns a
187 <code>reference</code> (a nested type). However, this implementation does
188 no range-checking on the index argument, which is in keeping with other
189 containers' <code>op[]</code> requirements. The defect report's proposed
190 resolution calls for range-checking to be done. We'll just wait and see...
192 <para>Finally, two additional searching functions have been added. They return
193 the index of the first "on" bit, and the index of the first
194 "on" bit that is after <code>prev</code>, respectively:
197 size_t _Find_first() const;
198 size_t _Find_next (size_t prev) const;</programlisting>
199 <para>The same caveat given for the _Unchecked_* functions applies here also.
204 <sect1 id="manual.ext.containers.deprecated_sgi" xreflabel="SGI ext dep">
205 <title>Deprecated HP/SGI</title>
208 The SGI hashing classes <classname>hash_set</classname> and
209 <classname>hash_set</classname> have been deprecated by the
210 unordered_set, unordered_multiset, unordered_map,
211 unordered_multimap containers in TR1 and the upcoming C++0x, and
212 may be removed in future releases.
215 <para>The SGI headers</para>
224 <code><hash_map></code> and <code><hash_set></code>
225 are deprecated but available as backwards-compatible extensions,
226 as discussed further below. <code><rope></code> is the
227 SGI specialization for large strings ("rope,"
228 "large strings," get it? Love that geeky humor.)
229 <code><slist></code> is a singly-linked list, for when the
230 doubly-linked <code>list<></code> is too much space
231 overhead, and <code><rb_tree></code> exposes the red-black
232 tree classes used in the implementation of the standard maps and
235 <para>Each of the associative containers map, multimap, set, and multiset
236 have a counterpart which uses a
237 <ulink url="http://www.sgi.com/tech/stl/HashFunction.html">hashing
238 function</ulink> to do the arranging, instead of a strict weak ordering
239 function. The classes take as one of their template parameters a
240 function object that will return the hash value; by default, an
242 <ulink url="http://www.sgi.com/tech/stl/hash.html">hash</ulink>.
243 You should specialize this functor for your class, or define your own,
244 before trying to use one of the hashing classes.
246 <para>The hashing classes support all the usual associative container
247 functions, as well as some extra constructors specifying the number
250 <para>Why would you want to use a hashing class instead of the
251 <quote>normal</quote>implementations? Matt Austern writes:
255 <emphasis>[W]ith a well chosen hash function, hash tables
256 generally provide much better average-case performance than
257 binary search trees, and much worse worst-case performance. So
258 if your implementation has hash_map, if you don't mind using
259 nonstandard components, and if you aren't scared about the
260 possibility of pathological cases, you'll probably get better
261 performance from hash_map.
269 <!-- Chapter 06 : Utilities -->
270 <chapter id="manual.ext.util" xreflabel="Utilities">
271 <?dbhtml filename="ext_utilities.html"?>
272 <title>Utilities</title>
274 The <functional> header contains many additional functors
275 and helper functions, extending section 20.3. They are
276 implemented in the file stl_function.h:
280 <para><code>identity_element</code> for addition and multiplication. *
284 <para>The functor <code>identity</code>, whose <code>operator()</code>
285 returns the argument unchanged. *
289 <para>Composition functors <code>unary_function</code> and
290 <code>binary_function</code>, and their helpers <code>compose1</code>
291 and <code>compose2</code>. *
295 <para><code>select1st</code> and <code>select2nd</code>, to strip pairs. *
298 <listitem><para><code>project1st</code> and <code>project2nd</code>. * </para></listitem>
299 <listitem><para>A set of functors/functions which always return the same result. They
300 are <code>constant_void_fun</code>, <code>constant_binary_fun</code>,
301 <code>constant_unary_fun</code>, <code>constant0</code>,
302 <code>constant1</code>, and <code>constant2</code>. * </para></listitem>
303 <listitem><para>The class <code>subtractive_rng</code>. * </para></listitem>
304 <listitem><para>mem_fun adaptor helpers <code>mem_fun1</code> and
305 <code>mem_fun1_ref</code> are provided for backwards compatibility. </para></listitem>
308 20.4.1 can use several different allocators; they are described on the
309 main extensions page.
312 20.4.3 is extended with a special version of
313 <code>get_temporary_buffer</code> taking a second argument. The
314 argument is a pointer, which is ignored, but can be used to specify
315 the template type (instead of using explicit function template
316 arguments like the standard version does). That is, in addition to
319 get_temporary_buffer<int>(5);
327 get_temporary_buffer(5, (int*)0);
330 A class <code>temporary_buffer</code> is given in stl_tempbuf.h. *
333 The specialized algorithms of section 20.4.4 are extended with
334 <code>uninitialized_copy_n</code>. *
339 <!-- Chapter 07 : Algorithms -->
340 <chapter id="manual.ext.algorithms" xreflabel="Algorithms">
341 <?dbhtml filename="ext_algorithms.html"?>
342 <title>Algorithms</title>
343 <para>25.1.6 (count, count_if) is extended with two more versions of count
344 and count_if. The standard versions return their results. The
345 additional signatures return void, but take a final parameter by
346 reference to which they assign their results, e.g.,
349 void count (first, last, value, n);</programlisting>
350 <para>25.2 (mutating algorithms) is extended with two families of signatures,
351 random_sample and random_sample_n.
353 <para>25.2.1 (copy) is extended with
356 copy_n (_InputIter first, _Size count, _OutputIter result);</programlisting>
357 <para>which copies the first 'count' elements at 'first' into 'result'.
359 <para>25.3 (sorting 'n' heaps 'n' stuff) is extended with some helper
360 predicates. Look in the doxygen-generated pages for notes on these.
363 <listitem><para><code>is_heap</code> tests whether or not a range is a heap.</para></listitem>
364 <listitem><para><code>is_sorted</code> tests whether or not a range is sorted in
365 nondescending order.</para></listitem>
367 <para>25.3.8 (lexicographical_compare) is extended with
370 lexicographical_compare_3way(_InputIter1 first1, _InputIter1 last1,
371 _InputIter2 first2, _InputIter2 last2)</programlisting>
372 <para>which does... what?
377 <!-- Chapter 08 : Numerics -->
378 <chapter id="manual.ext.numerics" xreflabel="Numerics">
379 <?dbhtml filename="ext_numerics.html"?>
380 <title>Numerics</title>
381 <para>26.4, the generalized numeric operations such as accumulate, are extended
382 with the following functions:
386 power (x, n, moniod_operation);</programlisting>
387 <para>Returns, in FORTRAN syntax, "x ** n" where n>=0. In the
388 case of n == 0, 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.
393 <para>The <code>iota</code> function wins the award for Extension With the
394 Coolest Name. It "assigns sequentially increasing values to a range.
395 That is, it assigns value to *first, value + 1 to *(first + 1) and so
396 on." Quoted from SGI documentation.
399 void iota(_ForwardIter first, _ForwardIter last, _Tp value);</programlisting>
402 <!-- Chapter 09 : Iterators -->
403 <chapter id="manual.ext.iterators" xreflabel="Iterators">
404 <?dbhtml filename="ext_iterators.html"?>
405 <title>Iterators</title>
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:
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>
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.
426 <!-- Chapter 08 : IO -->
427 <chapter id="manual.ext.io" xreflabel="IO">
428 <?dbhtml filename="ext_io.html"?>
429 <title>Input and Output</title>
432 Extensions allowing <code>filebuf</code>s to be constructed from
433 "C" types like FILE*s and file descriptors.
436 <sect1 id="manual.ext.io.filebuf_derived" xreflabel="Derived filebufs">
437 <title>Derived filebufs</title>
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.
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);
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:
455 <listitem><para><code>__c_file_type* F </code>
456 // the __c_file_type typedef usually boils down to stdio's FILE
458 <listitem><para><code>ios_base::openmode M </code>
459 // same as all the other uses of openmode
461 <listitem><para><code>int_type B </code>
462 // buffer size, defaults to BUFSIZ if not specified
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>.
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
476 <listitem><para>Beginning with 3.1, the extra <code>filebuf</code> constructor and
477 the <code>fd()</code> function were removed from the standard
478 filebuf. Instead, <code><ext/stdio_filebuf.h></code> contains
479 a derived class called
480 <ulink url="http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/a00063.html"><code>__gnu_cxx::stdio_filebuf</code></ulink>.
481 This class can be constructed from a C <code>FILE*</code> or a file
482 descriptor, and provides the <code>fd()</code> function.
485 <para>If you want to access a <code>filebuf</code>'s file descriptor to
486 implement file locking (e.g. using the <code>fcntl()</code> system
487 call) then you might be interested in Henry Suter's RWLock class.
488 <!-- url="http://suter.home.cern.ch/suter/RWLock.html" -->
496 <!-- Chapter 09 : Demangling -->
497 <chapter id="manual.ext.demangle" xreflabel="Demangling">
498 <?dbhtml filename="ext_demangling.html"?>
499 <title>Demangling</title>
501 Transforming C++ ABI identifiers (like RTTI symbols) into the
502 original C++ source identifiers is called
503 <quote>demangling.</quote>
506 If you have read the <ulink
507 url="http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/namespaceabi.html">source
508 documentation for <code>namespace abi</code></ulink> then you are
509 aware of the cross-vendor C++ ABI in use by GCC. One of the
510 exposed functions is used for demangling,
511 <code>abi::__cxa_demangle</code>.
514 In programs like <command>c++filt</command>, the linker, and other tools
515 have the ability to decode C++ ABI names, and now so can you.
518 (The function itself might use different demanglers, but that's the
519 whole point of abstract interfaces. If we change the implementation,
523 Probably the only times you'll be interested in demangling at runtime
524 are when you're seeing <code>typeid</code> strings in RTTI, or when
525 you're handling the runtime-support exception classes. For example:
528 #include <exception>
529 #include <iostream>
530 #include <cxxabi.h>
534 template <typename T, int N>
543 // exception classes not in <stdexcept>, thrown by the implementation
544 // instead of the user
545 std::bad_exception e;
546 realname = abi::__cxa_demangle(e.what(), 0, 0, &status);
547 std::cout << e.what() << "\t=> " << realname << "\t: " << status << '\n';
552 bar<empty,17> u;
553 const std::type_info &ti = typeid(u);
555 realname = abi::__cxa_demangle(ti.name(), 0, 0, &status);
556 std::cout << ti.name() << "\t=> " << realname << "\t: " << status << '\n';
568 St13bad_exception => std::bad_exception : 0
569 3barI5emptyLi17EE => bar<empty, 17> : 0
574 The demangler interface is described in the source documentation
575 linked to above. It is actually written in C, so you don't need to
576 be writing C++ in order to demangle C++. (That also means we have to
577 use crummy memory management facilities, so don't forget to free()
578 the returned char array.)
582 <!-- Chapter 10 : Concurrency -->
583 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
584 parse="xml" href="concurrency.xml">