| <part xmlns="http://docbook.org/ns/docbook" version="5.0" |
| xml:id="manual.ext" xreflabel="Extensions"> |
| <?dbhtml filename="extensions.html"?> |
| |
| <info><title> |
| Extensions |
| <indexterm><primary>Extensions</primary></indexterm> |
| </title> |
| <keywordset> |
| <keyword>ISO C++</keyword> |
| <keyword>library</keyword> |
| </keywordset> |
| </info> |
| |
| |
| <preface xml:id="manual.ext.preface"><info><title/></info> |
| <?dbhtml filename="ext_preface.html"?> |
| <para> |
| Here we will make an attempt at describing the non-Standard |
| extensions to the library. Some of these are from older versions of |
| standard library components, namely SGI's STL, and some of these are |
| GNU's. |
| </para> |
| <para><emphasis>Before</emphasis> you leap in and use any of these |
| extensions, be aware of two things: |
| </para> |
| <orderedlist inheritnum="ignore" continuation="restarts"> |
| <listitem> |
| <para> |
| Non-Standard means exactly that. |
| </para> |
| <para> |
| The behavior, and the very |
| existence, of these extensions may change with little or no |
| warning. (Ideally, the really good ones will appear in the next |
| revision of C++.) Also, other platforms, other compilers, other |
| versions of g++ or libstdc++ may not recognize these names, or |
| treat them differently, or... |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| You should know how to access these headers properly. |
| </para> |
| </listitem> |
| </orderedlist> |
| </preface> |
| |
| <!-- Chapter 01 : Compile Time Checks --> |
| <chapter xml:id="manual.ext.compile_checks" xreflabel="Compile Time Checks"><info><title>Compile Time Checks</title></info> |
| <?dbhtml filename="ext_compile_checks.html"?> |
| |
| <para> |
| Also known as concept checking. |
| </para> |
| <para>In 1999, SGI added <emphasis>concept checkers</emphasis> to their implementation |
| of the STL: code which checked the template parameters of |
| instantiated pieces of the STL, in order to insure that the parameters |
| being used met the requirements of the standard. For example, |
| the Standard requires that types passed as template parameters to |
| <code>vector</code> be <quote>Assignable</quote> (which means what you think |
| it means). The checking was done during compilation, and none of |
| the code was executed at runtime. |
| </para> |
| <para>Unfortunately, the size of the compiler files grew significantly |
| as a result. The checking code itself was cumbersome. And bugs |
| were found in it on more than one occasion. |
| </para> |
| <para>The primary author of the checking code, Jeremy Siek, had already |
| started work on a replacement implementation. The new code has been |
| formally reviewed and accepted into |
| <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.boost.org/libs/concept_check/concept_check.htm">the |
| Boost libraries</link>, and we are pleased to incorporate it into the |
| GNU C++ library. |
| </para> |
| <para>The new version imposes a much smaller space overhead on the generated |
| object file. The checks are also cleaner and easier to read and |
| understand. |
| </para> |
| <para>They are off by default for all versions of GCC from 3.0 to 3.4 (the |
| latest release at the time of writing). |
| They can be enabled at configure time with |
| <link linkend="manual.intro.setup.configure"><literal>--enable-concept-checks</literal></link>. |
| You can enable them on a per-translation-unit basis with |
| <link linkend="manual.intro.using.macros"><code>#define |
| _GLIBCXX_CONCEPT_CHECKS</code></link> for GCC 3.4 and higher |
| (or with <code>#define _GLIBCPP_CONCEPT_CHECKS</code> for versions |
| 3.1, 3.2 and 3.3). |
| </para> |
| |
| <para>Please note that the concept checks only validate the requirements |
| of the old C++03 standard. C++11 was expected to have first-class |
| support for template parameter constraints based on concepts in the core |
| language. This would have obviated the need for the library-simulated concept |
| checking described above, but was not part of C++11. |
| </para> |
| |
| </chapter> |
| |
| <!-- Chapter 02 : Debug Mode --> |
| <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="xml" |
| href="debug_mode.xml"> |
| </xi:include> |
| |
| <!-- Chapter 03 : Parallel Mode --> |
| <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="xml" |
| href="parallel_mode.xml"> |
| </xi:include> |
| |
| <!-- XXX --> |
| <!-- Allocators --> |
| <!-- Chapter 05 : __mt_alloc --> |
| <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="xml" |
| href="mt_allocator.xml"> |
| </xi:include> |
| |
| <!-- Chapter 06 : bitmap_allocator --> |
| <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="xml" |
| href="bitmap_allocator.xml"> |
| </xi:include> |
| |
| <!-- Containers --> |
| <!-- Chapter 07 : Policy-Based Data Structures --> |
| <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="xml" |
| href="policy_data_structures.xml"> |
| </xi:include> |
| |
| <!-- Chapter 08 : HP/SGI --> |
| <chapter xml:id="manual.ext.containers" xreflabel="Containers"> |
| <info><title>HP/SGI Extensions</title></info> |
| <?dbhtml filename="ext_containers.html"?> |
| |
| <section xml:id="manual.ext.containers.sgi" xreflabel="SGI ext"> |
| <info><title>Backwards Compatibility</title></info> |
| |
| <para>A few extensions and nods to backwards-compatibility have |
| been made with containers. Those dealing with older SGI-style |
| allocators are dealt with elsewhere. The remaining ones all deal |
| with bits: |
| </para> |
| <para>The old pre-standard <code>bit_vector</code> class is |
| present for backwards compatibility. It is simply a typedef for |
| the <code>vector<bool></code> specialization. |
| </para> |
| |
| <para>The <code>bitset</code> class has a number of extensions, described in the |
| rest of this item. First, we'll mention that this implementation of |
| <code>bitset<N></code> is specialized for cases where N number of |
| bits will fit into a single word of storage. If your choice of N is |
| within that range (<=32 on i686-pc-linux-gnu, for example), then all |
| of the operations will be faster. |
| </para> |
| <para>There are |
| versions of single-bit test, set, reset, and flip member functions which |
| do no range-checking. If we call them member functions of an instantiation |
| of <code>bitset<N></code>, then their names and signatures are: |
| </para> |
| <programlisting> |
| bitset<N>& _Unchecked_set (size_t pos); |
| bitset<N>& _Unchecked_set (size_t pos, int val); |
| bitset<N>& _Unchecked_reset (size_t pos); |
| bitset<N>& _Unchecked_flip (size_t pos); |
| bool _Unchecked_test (size_t pos); |
| </programlisting> |
| <para>Note that these may in fact be removed in the future, although we have |
| no present plans to do so (and there doesn't seem to be any immediate |
| reason to). |
| </para> |
| <para>The member function <code>operator[]</code> on a const bitset returns |
| a bool, and for a non-const bitset returns a <code>reference</code> (a |
| nested type). No range-checking is done on the index argument, in keeping |
| with other containers' <code>operator[]</code> requirements. |
| </para> |
| <para>Finally, two additional searching functions have been added. They return |
| the index of the first "on" bit, and the index of the first |
| "on" bit that is after <code>prev</code>, respectively: |
| </para> |
| <programlisting> |
| size_t _Find_first() const; |
| size_t _Find_next (size_t prev) const;</programlisting> |
| <para>The same caveat given for the _Unchecked_* functions applies here also. |
| </para> |
| </section> |
| |
| |
| <section xml:id="manual.ext.containers.deprecated_sgi" xreflabel="SGI ext dep"><info><title>Deprecated</title></info> |
| <?dbhtml filename="ext_sgi.html"?> |
| |
| |
| <para> |
| The SGI hashing classes <classname>hash_set</classname> and |
| <classname>hash_set</classname> have been deprecated by the |
| unordered_set, unordered_multiset, unordered_map, |
| unordered_multimap containers in TR1 and C++11, and |
| may be removed in future releases. |
| </para> |
| |
| <para>The SGI headers</para> |
| <programlisting> |
| <hash_map> |
| <hash_set> |
| <rope> |
| <slist> |
| <rb_tree> |
| </programlisting> |
| <para>are all here; |
| <filename class="headerfile"><backwards/hash_map></filename> and |
| <filename class="headerfile"><backwards/hash_set></filename> |
| are deprecated but available as backwards-compatible extensions, |
| as discussed further below. |
| <filename class="headerfile"><ext/rope></filename> is the SGI |
| specialization for large strings ("rope," "large strings," get it? Love |
| that geeky humor.) |
| <filename class="headerfile"><ext/slist></filename> (superseded in |
| C++11 by <filename class="headerfile"><forward_list></filename>) |
| is a singly-linked list, for when the doubly-linked <code>list<></code> |
| is too much space overhead, and |
| <filename class="headerfile"><ext/rb_tree></filename> exposes the |
| red-black tree classes used in the implementation of the standard maps |
| and sets. |
| </para> |
| <para>Each of the associative containers map, multimap, set, and multiset |
| have a counterpart which uses a |
| <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 |
| function</link> to do the arranging, instead of a strict weak ordering |
| function. The classes take as one of their template parameters a |
| function object that will return the hash value; by default, an |
| instantiation of |
| <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>. |
| You should specialize this functor for your class, or define your own, |
| before trying to use one of the hashing classes. |
| </para> |
| <para>The hashing classes support all the usual associative container |
| functions, as well as some extra constructors specifying the number |
| of buckets, etc. |
| </para> |
| <para>Why would you want to use a hashing class instead of the |
| <quote>normal</quote>implementations? Matt Austern writes: |
| </para> |
| <blockquote> |
| <para> |
| <emphasis>[W]ith a well chosen hash function, hash tables |
| generally provide much better average-case performance than |
| binary search trees, and much worse worst-case performance. So |
| if your implementation has hash_map, if you don't mind using |
| nonstandard components, and if you aren't scared about the |
| possibility of pathological cases, you'll probably get better |
| performance from hash_map. |
| </emphasis> |
| </para> |
| </blockquote> |
| |
| <para> |
| The deprecated hash tables are superseded by the standard unordered |
| associative containers defined in the ISO C++ 2011 standard in the |
| headers <filename class="headerfile"><unordered_map></filename> |
| and <filename class="headerfile"><unordered_set></filename>. |
| </para> |
| |
| </section> |
| </chapter> |
| |
| <!-- Chapter 09 : Utilities --> |
| <chapter xml:id="manual.ext.util" xreflabel="Utilities"><info><title>Utilities</title></info> |
| <?dbhtml filename="ext_utilities.html"?> |
| |
| <para> |
| The <filename class="headerfile"><functional></filename> header |
| contains many additional functors |
| and helper functions, extending section 20.3. They are |
| implemented in the file stl_function.h: |
| </para> |
| <itemizedlist> |
| <listitem> |
| <para><code>identity_element</code> for addition and multiplication. |
| </para> |
| </listitem> |
| <listitem> |
| <para>The functor <code>identity</code>, whose <code>operator()</code> |
| returns the argument unchanged. |
| </para> |
| </listitem> |
| <listitem> |
| <para>Composition functors <code>unary_function</code> and |
| <code>binary_function</code>, and their helpers <code>compose1</code> |
| and <code>compose2</code>. |
| </para> |
| </listitem> |
| <listitem> |
| <para><code>select1st</code> and <code>select2nd</code>, to strip pairs. |
| </para> |
| </listitem> |
| <listitem><para><code>project1st</code> and <code>project2nd</code>. </para></listitem> |
| <listitem><para>A set of functors/functions which always return the same result. They |
| are <code>constant_void_fun</code>, <code>constant_binary_fun</code>, |
| <code>constant_unary_fun</code>, <code>constant0</code>, |
| <code>constant1</code>, and <code>constant2</code>. </para></listitem> |
| <listitem><para>The class <code>subtractive_rng</code>. </para></listitem> |
| <listitem><para>mem_fun adaptor helpers <code>mem_fun1</code> and |
| <code>mem_fun1_ref</code> are provided for backwards compatibility. </para></listitem> |
| </itemizedlist> |
| <para> |
| 20.4.1 can use several different allocators; they are described on the |
| main extensions page. |
| </para> |
| <para> |
| 20.4.3 is extended with a special version of |
| <code>get_temporary_buffer</code> taking a second argument. The |
| argument is a pointer, which is ignored, but can be used to specify |
| the template type (instead of using explicit function template |
| arguments like the standard version does). That is, in addition to |
| </para> |
| <programlisting> |
| get_temporary_buffer<int>(5); |
| </programlisting> |
| |
| <para> |
| you can also use |
| </para> |
| |
| <programlisting> |
| get_temporary_buffer(5, (int*)0); |
| </programlisting> |
| <para> |
| A class <code>temporary_buffer</code> is given in stl_tempbuf.h. |
| </para> |
| <para> |
| The specialized algorithms of section 20.4.4 are extended with |
| <code>uninitialized_copy_n</code>. |
| </para> |
| |
| </chapter> |
| |
| <!-- Chapter 10 : Algorithms --> |
| <chapter xml:id="manual.ext.algorithms" xreflabel="Algorithms"><info><title>Algorithms</title></info> |
| <?dbhtml filename="ext_algorithms.html"?> |
| |
| <para>25.1.6 (count, count_if) is extended with two more versions of count |
| and count_if. The standard versions return their results. The |
| additional signatures return void, but take a final parameter by |
| reference to which they assign their results, e.g., |
| </para> |
| <programlisting> |
| void count (first, last, value, n);</programlisting> |
| <para>25.2 (mutating algorithms) is extended with two families of signatures, |
| random_sample and random_sample_n. |
| </para> |
| <para>25.2.1 (copy) is extended with |
| </para> |
| <programlisting> |
| copy_n (_InputIter first, _Size count, _OutputIter result);</programlisting> |
| <para>which copies the first 'count' elements at 'first' into 'result'. |
| </para> |
| <para>25.3 (sorting 'n' heaps 'n' stuff) is extended with some helper |
| predicates. Look in the doxygen-generated pages for notes on these. |
| </para> |
| <itemizedlist> |
| <listitem><para><code>is_heap</code> tests whether or not a range is a heap.</para></listitem> |
| <listitem><para><code>is_sorted</code> tests whether or not a range is sorted in |
| nondescending order.</para></listitem> |
| </itemizedlist> |
| <para>25.3.8 (lexicographical_compare) is extended with |
| </para> |
| <programlisting> |
| lexicographical_compare_3way(_InputIter1 first1, _InputIter1 last1, |
| _InputIter2 first2, _InputIter2 last2)</programlisting> |
| <para>which does... what? |
| </para> |
| |
| </chapter> |
| |
| <!-- Chapter 11 : Numerics --> |
| <chapter xml:id="manual.ext.numerics" xreflabel="Numerics"><info><title>Numerics</title></info> |
| <?dbhtml filename="ext_numerics.html"?> |
| |
| <para>26.4, the generalized numeric operations such as <code>accumulate</code>, |
| are extended with the following functions: |
| </para> |
| <programlisting> |
| power (x, n); |
| power (x, n, monoid_operation);</programlisting> |
| <para>Returns, in FORTRAN syntax, "<code>x ** n</code>" where |
| <code>n >= 0</code>. In the |
| case of <code>n == 0</code>, returns the identity element for the |
| monoid operation. The two-argument signature uses multiplication (for |
| a true "power" implementation), but addition is supported as well. |
| The operation functor must be associative. |
| </para> |
| <para>The <code>iota</code> function wins the award for Extension With the |
| Coolest Name (the name comes from Ken Iverson's APL language.) As |
| 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 |
| documentation</link>, it "assigns sequentially increasing values to a range. |
| That is, it assigns <code>value</code> to <code>*first</code>, |
| <code>value + 1</code> to<code> *(first + 1)</code> and so on." |
| </para> |
| <programlisting> |
| void iota(_ForwardIter first, _ForwardIter last, _Tp value);</programlisting> |
| <para>The <code>iota</code> function is included in the ISO C++ 2011 standard. |
| </para> |
| </chapter> |
| |
| <!-- Chapter 12 : Iterators --> |
| <chapter xml:id="manual.ext.iterators" xreflabel="Iterators"><info><title>Iterators</title></info> |
| <?dbhtml filename="ext_iterators.html"?> |
| |
| <para>24.3.2 describes <code>struct iterator</code>, which didn't exist in the |
| original HP STL implementation (the language wasn't rich enough at the |
| time). For backwards compatibility, base classes are provided which |
| declare the same nested typedefs: |
| </para> |
| <itemizedlist> |
| <listitem><para>input_iterator</para></listitem> |
| <listitem><para>output_iterator</para></listitem> |
| <listitem><para>forward_iterator</para></listitem> |
| <listitem><para>bidirectional_iterator</para></listitem> |
| <listitem><para>random_access_iterator</para></listitem> |
| </itemizedlist> |
| <para>24.3.4 describes iterator operation <code>distance</code>, which takes |
| two iterators and returns a result. It is extended by another signature |
| which takes two iterators and a reference to a result. The result is |
| modified, and the function returns nothing. |
| </para> |
| |
| </chapter> |
| |
| <!-- Chapter 13 : IO --> |
| <chapter xml:id="manual.ext.io" xreflabel="IO"><info><title>Input and Output</title></info> |
| <?dbhtml filename="ext_io.html"?> |
| |
| |
| <para> |
| Extensions allowing <code>filebuf</code>s to be constructed from |
| "C" types like FILE*s and file descriptors. |
| </para> |
| |
| <section xml:id="manual.ext.io.filebuf_derived" xreflabel="Derived filebufs"><info><title>Derived filebufs</title></info> |
| |
| |
| <para>The v2 library included non-standard extensions to construct |
| <code>std::filebuf</code>s from C stdio types such as |
| <code>FILE*</code>s and POSIX file descriptors. |
| Today the recommended way to use stdio types with libstdc++ |
| IOStreams is via the <code>stdio_filebuf</code> class (see below), |
| but earlier releases provided slightly different mechanisms. |
| </para> |
| <itemizedlist> |
| <listitem><para>3.0.x <code>filebuf</code>s have another ctor with this signature: |
| <code>basic_filebuf(__c_file_type*, ios_base::openmode, int_type); |
| </code> |
| This comes in very handy in a number of places, such as |
| attaching Unix sockets, pipes, and anything else which uses file |
| descriptors, into the IOStream buffering classes. The three |
| arguments are as follows: |
| <itemizedlist> |
| <listitem><para><code>__c_file_type* F </code> |
| // the __c_file_type typedef usually boils down to stdio's FILE |
| </para></listitem> |
| <listitem><para><code>ios_base::openmode M </code> |
| // same as all the other uses of openmode |
| </para></listitem> |
| <listitem><para><code>int_type B </code> |
| // buffer size, defaults to BUFSIZ if not specified |
| </para></listitem> |
| </itemizedlist> |
| For those wanting to use file descriptors instead of FILE*'s, I |
| invite you to contemplate the mysteries of C's <code>fdopen()</code>. |
| </para></listitem> |
| <listitem><para>In library snapshot 3.0.95 and later, <code>filebuf</code>s bring |
| back an old extension: the <code>fd()</code> member function. The |
| integer returned from this function can be used for whatever file |
| descriptors can be used for on your platform. Naturally, the |
| library cannot track what you do on your own with a file descriptor, |
| so if you perform any I/O directly, don't expect the library to be |
| aware of it. |
| </para></listitem> |
| <listitem><para>Beginning with 3.1, the extra |
| <classname>basic_filebuf</classname> constructor and |
| the <code>fd()</code> function were removed from the standard |
| filebuf. Instead, |
| <filename class="headerfile"><ext/stdio_filebuf.h></filename> |
| contains a derived class template called |
| <classname>__gnu_cxx::stdio_filebuf</classname>. |
| This class can be constructed from a C <code>FILE*</code> or a file |
| descriptor, and provides the <code>fd()</code> function. |
| </para></listitem> |
| </itemizedlist> |
| |
| </section> |
| </chapter> |
| |
| <!-- Chapter 14 : Demangling --> |
| <chapter xml:id="manual.ext.demangle" xreflabel="Demangling"><info><title>Demangling</title></info> |
| <?dbhtml filename="ext_demangling.html"?> |
| |
| <para> |
| Transforming C++ ABI identifiers (like RTTI symbols) into the |
| original C++ source identifiers is called |
| <quote>demangling.</quote> |
| </para> |
| <para> |
| 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 |
| documentation for <code>namespace abi</code></link> then you are |
| aware of the cross-vendor C++ ABI in use by GCC. One of the |
| exposed functions is used for demangling, |
| <code>abi::__cxa_demangle</code>. |
| </para> |
| <para> |
| In programs like <command>c++filt</command>, the linker, and other tools |
| have the ability to decode C++ ABI names, and now so can you. |
| </para> |
| <para> |
| (The function itself might use different demanglers, but that's the |
| whole point of abstract interfaces. If we change the implementation, |
| you won't notice.) |
| </para> |
| <para> |
| Probably the only times you'll be interested in demangling at runtime |
| are when you're seeing <code>typeid</code> strings in RTTI, or when |
| you're handling the runtime-support exception classes. For example: |
| </para> |
| <programlisting> |
| #include <exception> |
| #include <iostream> |
| #include <cxxabi.h> |
| |
| struct empty { }; |
| |
| template <typename T, int N> |
| struct bar { }; |
| |
| |
| int main() |
| { |
| int status; |
| char *realname; |
| |
| // exception classes not in <stdexcept>, thrown by the implementation |
| // instead of the user |
| std::bad_exception e; |
| realname = abi::__cxa_demangle(e.what(), 0, 0, &status); |
| std::cout << e.what() << "\t=> " << realname << "\t: " << status << '\n'; |
| free(realname); |
| |
| |
| // typeid |
| bar<empty,17> u; |
| const std::type_info &ti = typeid(u); |
| |
| realname = abi::__cxa_demangle(ti.name(), 0, 0, &status); |
| std::cout << ti.name() << "\t=> " << realname << "\t: " << status << '\n'; |
| free(realname); |
| |
| return 0; |
| } |
| </programlisting> |
| <para> |
| This prints |
| </para> |
| |
| <screen> |
| <computeroutput> |
| St13bad_exception => std::bad_exception : 0 |
| 3barI5emptyLi17EE => bar<empty, 17> : 0 |
| </computeroutput> |
| </screen> |
| |
| <para> |
| The demangler interface is described in the source documentation |
| linked to above. It is actually written in C, so you don't need to |
| be writing C++ in order to demangle C++. (That also means we have to |
| use crummy memory management facilities, so don't forget to free() |
| the returned char array.) |
| </para> |
| </chapter> |
| |
| <!-- Chapter 15 : Concurrency --> |
| <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="xml" href="concurrency_extensions.xml"> |
| </xi:include> |
| |
| </part> |