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