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 <ulink url="XXX">access
52 these headers properly</ulink>.
58 <!-- Chapter 01 : Compile Time Checks -->
59 <chapter id="manual.ext.compile_checks" xreflabel="Compile Time Checks">
60 <?dbhtml filename="ext_compile_checks.html"?>
61 <title>Compile Time Checks</title>
63 Also known as concept checking.
65 <para>In 1999, SGI added <emphasis>concept checkers</emphasis> to their implementation
66 of the STL: code which checked the template parameters of
67 instantiated pieces of the STL, in order to insure that the parameters
68 being used met the requirements of the standard. For example,
69 the Standard requires that types passed as template parameters to
70 <code>vector</code> be <quote>Assignable</quote> (which means what you think
71 it means). The checking was done during compilation, and none of
72 the code was executed at runtime.
74 <para>Unfortunately, the size of the compiler files grew significantly
75 as a result. The checking code itself was cumbersome. And bugs
76 were found in it on more than one occasion.
78 <para>The primary author of the checking code, Jeremy Siek, had already
79 started work on a replacement implementation. The new code has been
80 formally reviewed and accepted into
81 <ulink url="http://www.boost.org/libs/concept_check/concept_check.htm">the
82 Boost libraries</ulink>, and we are pleased to incorporate it into the
85 <para>The new version imposes a much smaller space overhead on the generated
86 object file. The checks are also cleaner and easier to read and
89 <para>They are off by default for all versions of GCC from 3.0 to 3.4 (the
90 latest release at the time of writing).
91 They can be enabled at configure time with
92 <ulink url="../configopts.html"><literal>--enable-concept-checks</literal></ulink>.
93 You can enable them on a per-translation-unit basis with
94 <code>#define _GLIBCXX_CONCEPT_CHECKS</code> for GCC 3.4 and higher
95 (or with <code>#define _GLIBCPP_CONCEPT_CHECKS</code> for versions
99 <para>Please note that the upcoming C++ standard has first-class
100 support for template parameter constraints based on concepts in the core
101 language. This will obviate the need for the library-simulated concept
102 checking described above.
107 <!-- Chapter 02 : Debug Mode -->
108 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
109 parse="xml" href="debug_mode.xml">
112 <!-- Chapter 03 : Parallel Mode -->
113 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
114 parse="xml" href="parallel_mode.xml">
117 <!-- Chapter 04 : Allocators -->
118 <chapter id="manual.ext.allocator" xreflabel="Allocators">
119 <?dbhtml filename="ext_allocators.html"?>
120 <title>Allocators</title>
122 <!-- Section 01 : __mt_alloc -->
123 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
124 parse="xml" href="mt_allocator.xml">
127 <!-- Section 02 : bitmap_allocator -->
128 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
129 parse="xml" href="bitmap_allocator.xml">
134 <!-- Chapter 05 : Containers -->
135 <chapter id="manual.ext.containers" xreflabel="Containers">
136 <?dbhtml filename="ext_containers.html"?>
137 <title>Containers</title>
140 <sect1 id="manual.ext.containers.pbds" xreflabel="Policy Based Data Structures">
141 <title>Policy Based Data Structures</title>
144 url="http://gcc.gnu.org/onlinedocs/libstdc++/ext/pb_ds/index.html">More details here</ulink>.
148 <sect1 id="manual.ext.containers.sgi" xreflabel="SGI ext">
149 <title>HP/SGI</title>
153 <para>A few extensions and nods to backwards-compatibility have been made with
154 containers. Those dealing with older SGI-style allocators are dealt with
155 elsewhere. The remaining ones all deal with bits:
157 <para>The old pre-standard <code>bit_vector</code> class is present for
158 backwards compatibility. It is simply a typedef for the
159 <code>vector<bool></code> specialization.
161 <para>The <code>bitset</code> class has a number of extensions, described in the
162 rest of this item. First, we'll mention that this implementation of
163 <code>bitset<N></code> is specialized for cases where N number of
164 bits will fit into a single word of storage. If your choice of N is
165 within that range (<=32 on i686-pc-linux-gnu, for example), then all
166 of the operations will be faster.
169 versions of single-bit test, set, reset, and flip member functions which
170 do no range-checking. If we call them member functions of an instantiation
171 of "bitset<N>," then their names and signatures are:
174 bitset<N>& _Unchecked_set (size_t pos);
175 bitset<N>& _Unchecked_set (size_t pos, int val);
176 bitset<N>& _Unchecked_reset (size_t pos);
177 bitset<N>& _Unchecked_flip (size_t pos);
178 bool _Unchecked_test (size_t pos);
180 <para>Note that these may in fact be removed in the future, although we have
181 no present plans to do so (and there doesn't seem to be any immediate
184 <para>The semantics of member function <code>operator[]</code> are not specified
185 in the C++ standard. A long-standing defect report calls for sensible
186 obvious semantics, which are already implemented here: <code>op[]</code>
187 on a const bitset returns a bool, and for a non-const bitset returns a
188 <code>reference</code> (a nested type). However, this implementation does
189 no range-checking on the index argument, which is in keeping with other
190 containers' <code>op[]</code> requirements. The defect report's proposed
191 resolution calls for range-checking to be done. We'll just wait and see...
193 <para>Finally, two additional searching functions have been added. They return
194 the index of the first "on" bit, and the index of the first
195 "on" bit that is after <code>prev</code>, respectively:
198 size_t _Find_first() const;
199 size_t _Find_next (size_t prev) const;</programlisting>
200 <para>The same caveat given for the _Unchecked_* functions applies here also.
205 <sect1 id="manual.ext.containers.deprecated_sgi" xreflabel="SGI ext dep">
206 <title>Deprecated HP/SGI</title>
209 The SGI hashing classes <classname>hash_set</classname> and
210 <classname>hash_set</classname> have been deprecated by the
211 unordered_set, unordered_multiset, unordered_map,
212 unordered_multimap containers in TR1 and the upcoming C++0x, and
213 may be removed in future releases.
216 <para>The SGI headers</para>
225 <code><hash_map></code> and <code><hash_set></code>
226 are deprecated but available as backwards-compatible extensions,
227 as discussed further below. <code><rope></code> is the
228 SGI specialization for large strings ("rope,"
229 "large strings," get it? Love that geeky humor.)
230 <code><slist></code> is a singly-linked list, for when the
231 doubly-linked <code>list<></code> is too much space
232 overhead, and <code><rb_tree></code> exposes the red-black
233 tree classes used in the implementation of the standard maps and
236 <para>Each of the associative containers map, multimap, set, and multiset
237 have a counterpart which uses a
238 <ulink url="http://www.sgi.com/tech/stl/HashFunction.html">hashing
239 function</ulink> to do the arranging, instead of a strict weak ordering
240 function. The classes take as one of their template parameters a
241 function object that will return the hash value; by default, an
243 <ulink url="http://www.sgi.com/tech/stl/hash.html">hash</ulink>.
244 You should specialize this functor for your class, or define your own,
245 before trying to use one of the hashing classes.
247 <para>The hashing classes support all the usual associative container
248 functions, as well as some extra constructors specifying the number
251 <para>Why would you want to use a hashing class instead of the
252 <quote>normal</quote>implementations? Matt Austern writes:
256 <emphasis>[W]ith a well chosen hash function, hash tables
257 generally provide much better average-case performance than
258 binary search trees, and much worse worst-case performance. So
259 if your implementation has hash_map, if you don't mind using
260 nonstandard components, and if you aren't scared about the
261 possibility of pathological cases, you'll probably get better
262 performance from hash_map.
270 <!-- Chapter 06 : Utilities -->
271 <chapter id="manual.ext.util" xreflabel="Utilities">
272 <?dbhtml filename="ext_utilities.html"?>
273 <title>Utilities</title>
275 The <functional> header contains many additional functors
276 and helper functions, extending section 20.3. They are
277 implemented in the file stl_function.h:
281 <para><code>identity_element</code> for addition and multiplication. *
285 <para>The functor <code>identity</code>, whose <code>operator()</code>
286 returns the argument unchanged. *
290 <para>Composition functors <code>unary_function</code> and
291 <code>binary_function</code>, and their helpers <code>compose1</code>
292 and <code>compose2</code>. *
296 <para><code>select1st</code> and <code>select2nd</code>, to strip pairs. *
299 <listitem><para><code>project1st</code> and <code>project2nd</code>. * </para></listitem>
300 <listitem><para>A set of functors/functions which always return the same result. They
301 are <code>constant_void_fun</code>, <code>constant_binary_fun</code>,
302 <code>constant_unary_fun</code>, <code>constant0</code>,
303 <code>constant1</code>, and <code>constant2</code>. * </para></listitem>
304 <listitem><para>The class <code>subtractive_rng</code>. * </para></listitem>
305 <listitem><para>mem_fun adaptor helpers <code>mem_fun1</code> and
306 <code>mem_fun1_ref</code> are provided for backwards compatibility. </para></listitem>
309 20.4.1 can use several different allocators; they are described on the
310 main extensions page.
313 20.4.3 is extended with a special version of
314 <code>get_temporary_buffer</code> taking a second argument. The
315 argument is a pointer, which is ignored, but can be used to specify
316 the template type (instead of using explicit function template
317 arguments like the standard version does). That is, in addition to
320 get_temporary_buffer<int>(5);
328 get_temporary_buffer(5, (int*)0);
331 A class <code>temporary_buffer</code> is given in stl_tempbuf.h. *
334 The specialized algorithms of section 20.4.4 are extended with
335 <code>uninitialized_copy_n</code>. *
340 <!-- Chapter 07 : Algorithms -->
341 <chapter id="manual.ext.algorithms" xreflabel="Algorithms">
342 <?dbhtml filename="ext_algorithms.html"?>
343 <title>Algorithms</title>
344 <para>25.1.6 (count, count_if) is extended with two more versions of count
345 and count_if. The standard versions return their results. The
346 additional signatures return void, but take a final parameter by
347 reference to which they assign their results, e.g.,
350 void count (first, last, value, n);</programlisting>
351 <para>25.2 (mutating algorithms) is extended with two families of signatures,
352 random_sample and random_sample_n.
354 <para>25.2.1 (copy) is extended with
357 copy_n (_InputIter first, _Size count, _OutputIter result);</programlisting>
358 <para>which copies the first 'count' elements at 'first' into 'result'.
360 <para>25.3 (sorting 'n' heaps 'n' stuff) is extended with some helper
361 predicates. Look in the doxygen-generated pages for notes on these.
364 <listitem><para><code>is_heap</code> tests whether or not a range is a heap.</para></listitem>
365 <listitem><para><code>is_sorted</code> tests whether or not a range is sorted in
366 nondescending order.</para></listitem>
368 <para>25.3.8 (lexicographical_compare) is extended with
371 lexicographical_compare_3way(_InputIter1 first1, _InputIter1 last1,
372 _InputIter2 first2, _InputIter2 last2)</programlisting>
373 <para>which does... what?
378 <!-- Chapter 08 : Numerics -->
379 <chapter id="manual.ext.numerics" xreflabel="Numerics">
380 <?dbhtml filename="ext_numerics.html"?>
381 <title>Numerics</title>
382 <para>26.4, the generalized numeric operations such as accumulate, are extended
383 with the following functions:
387 power (x, n, moniod_operation);</programlisting>
388 <para>Returns, in FORTRAN syntax, "x ** n" where n>=0. In the
389 case of n == 0, returns the <ulink url="#ch20">identity element</ulink> for the
390 monoid operation. The two-argument signature uses multiplication (for
391 a true "power" implementation), but addition is supported as well.
392 The operation functor must be associative.
394 <para>The <code>iota</code> function wins the award for Extension With the
395 Coolest Name. It "assigns sequentially increasing values to a range.
396 That is, it assigns value to *first, value + 1 to *(first + 1) and so
397 on." Quoted from SGI documentation.
400 void iota(_ForwardIter first, _ForwardIter last, _Tp value);</programlisting>
403 <!-- Chapter 09 : Iterators -->
404 <chapter id="manual.ext.iterators" xreflabel="Iterators">
405 <?dbhtml filename="ext_iterators.html"?>
406 <title>Iterators</title>
407 <para>24.3.2 describes <code>struct iterator</code>, which didn't exist in the
408 original HP STL implementation (the language wasn't rich enough at the
409 time). For backwards compatibility, base classes are provided which
410 declare the same nested typedefs:
413 <listitem><para>input_iterator</para></listitem>
414 <listitem><para>output_iterator</para></listitem>
415 <listitem><para>forward_iterator</para></listitem>
416 <listitem><para>bidirectional_iterator</para></listitem>
417 <listitem><para>random_access_iterator</para></listitem>
419 <para>24.3.4 describes iterator operation <code>distance</code>, which takes
420 two iterators and returns a result. It is extended by another signature
421 which takes two iterators and a reference to a result. The result is
422 modified, and the function returns nothing.
427 <!-- Chapter 08 : IO -->
428 <chapter id="manual.ext.io" xreflabel="IO">
429 <?dbhtml filename="ext_io.html"?>
430 <title>Input and Output</title>
433 Extensions allowing <code>filebuf</code>s to be constructed from
434 "C" types like FILE*s and file descriptors.
437 <sect1 id="manual.ext.io.filebuf_derived" xreflabel="Derived filebufs">
438 <title>Derived filebufs</title>
440 <para>The v2 library included non-standard extensions to construct
441 <code>std::filebuf</code>s from C stdio types such as
442 <code>FILE*</code>s and POSIX file descriptors.
443 Today the recommended way to use stdio types with libstdc++
444 IOStreams is via the <code>stdio_filebuf</code> class (see below),
445 but earlier releases provided slightly different mechanisms.
448 <listitem><para>3.0.x <code>filebuf</code>s have another ctor with this signature:
449 <code>basic_filebuf(__c_file_type*, ios_base::openmode, int_type);
451 This comes in very handy in a number of places, such as
452 attaching Unix sockets, pipes, and anything else which uses file
453 descriptors, into the IOStream buffering classes. The three
454 arguments are as follows:
456 <listitem><para><code>__c_file_type* F </code>
457 // the __c_file_type typedef usually boils down to stdio's FILE
459 <listitem><para><code>ios_base::openmode M </code>
460 // same as all the other uses of openmode
462 <listitem><para><code>int_type B </code>
463 // buffer size, defaults to BUFSIZ if not specified
466 For those wanting to use file descriptors instead of FILE*'s, I
467 invite you to contemplate the mysteries of C's <code>fdopen()</code>.
469 <listitem><para>In library snapshot 3.0.95 and later, <code>filebuf</code>s bring
470 back an old extension: the <code>fd()</code> member function. The
471 integer returned from this function can be used for whatever file
472 descriptors can be used for on your platform. Naturally, the
473 library cannot track what you do on your own with a file descriptor,
474 so if you perform any I/O directly, don't expect the library to be
477 <listitem><para>Beginning with 3.1, the extra <code>filebuf</code> constructor and
478 the <code>fd()</code> function were removed from the standard
479 filebuf. Instead, <code><ext/stdio_filebuf.h></code> contains
480 a derived class called
481 <ulink url="http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/a00063.html"><code>__gnu_cxx::stdio_filebuf</code></ulink>.
482 This class can be constructed from a C <code>FILE*</code> or a file
483 descriptor, and provides the <code>fd()</code> function.
486 <para>If you want to access a <code>filebuf</code>'s file descriptor to
487 implement file locking (e.g. using the <code>fcntl()</code> system
488 call) then you might be interested in Henry Suter's
489 <ulink url="http://suter.home.cern.ch/suter/RWLock.html">RWLock</ulink>
498 <!-- Chapter 09 : Demangling -->
499 <chapter id="manual.ext.demangle" xreflabel="Demangling">
500 <?dbhtml filename="ext_demangling.html"?>
501 <title>Demangling</title>
503 Transforming C++ ABI identifiers (like RTTI symbols) into the
504 original C++ source identifiers is called
505 <quote>demangling.</quote>
508 If you have read the <ulink
509 url="http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/namespaceabi.html">source
510 documentation for <code>namespace abi</code></ulink> then you are
511 aware of the cross-vendor C++ ABI in use by GCC. One of the
512 exposed functions is used for demangling,
513 <code>abi::__cxa_demangle</code>.
516 In programs like <command>c++filt</command>, the linker, and other tools
517 have the ability to decode C++ ABI names, and now so can you.
520 (The function itself might use different demanglers, but that's the
521 whole point of abstract interfaces. If we change the implementation,
525 Probably the only times you'll be interested in demangling at runtime
526 are when you're seeing <code>typeid</code> strings in RTTI, or when
527 you're handling the runtime-support exception classes. For example:
530 #include <exception>
531 #include <iostream>
532 #include <cxxabi.h>
536 template <typename T, int N>
545 // exception classes not in <stdexcept>, thrown by the implementation
546 // instead of the user
547 std::bad_exception e;
548 realname = abi::__cxa_demangle(e.what(), 0, 0, &status);
549 std::cout << e.what() << "\t=> " << realname << "\t: " << status << '\n';
554 bar<empty,17> u;
555 const std::type_info &ti = typeid(u);
557 realname = abi::__cxa_demangle(ti.name(), 0, 0, &status);
558 std::cout << ti.name() << "\t=> " << realname << "\t: " << status << '\n';
570 St13bad_exception => std::bad_exception : 0
571 3barI5emptyLi17EE => bar<empty, 17> : 0
576 The demangler interface is described in the source documentation
577 linked to above. It is actually written in C, so you don't need to
578 be writing C++ in order to demangle C++. (That also means we have to
579 use crummy memory management facilities, so don't forget to free()
580 the returned char array.)
584 <!-- Chapter 10 : Concurrency -->
585 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
586 parse="xml" href="concurrency.xml">