--- /dev/null
+<?xml version='1.0'?>
+<!DOCTYPE part PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+ "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"
+[ ]>
+
+<part id="manual.ext" xreflabel="Extensions">
+<?dbhtml filename="extensions.html"?>
+
+<partinfo>
+ <keywordset>
+ <keyword>
+ ISO C++
+ </keyword>
+ <keyword>
+ library
+ </keyword>
+ </keywordset>
+</partinfo>
+
+<title>
+ Extensions
+ <indexterm><primary>Extensions</primary></indexterm>
+</title>
+
+<preface>
+ <title></title>
+<para>
+ Here we will make an attempt at describing the non-Standard extensions to
+ the library. Some of these are from SGI's STL, some of these are GNU's,
+ and some just seemed to appear on the doorstep.
+</para>
+<para><emphasis>Before</emphasis> you leap in and use any of these
+extensions, be aware of two things:
+</para>
+<orderedlist>
+ <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 <ulink url="XXX">access
+ these headers properly</ulink>.
+ </para>
+ </listitem>
+</orderedlist>
+</preface>
+
+<!-- Chapter 01 : Compile Time Checks -->
+<chapter id="manual.ext.compile_checks" xreflabel="Compile Time Checks">
+<?dbhtml filename="ext_compile_checks.html"?>
+ <title>Compile Time Checks</title>
+ <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
+ <ulink url="http://www.boost.org/libs/concept_check/concept_check.htm">the
+ Boost libraries</ulink>, 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
+ <ulink url="../configopts.html"><literal>--enable-concept-checks</literal></ulink>.
+ You can enable them on a per-translation-unit basis with
+ <code>#define _GLIBCXX_CONCEPT_CHECKS</code> 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 upcoming C++ standard has first-class
+ support for template parameter constraints based on concepts in the core
+ language. This will obviate the need for the library-simulated concept
+ checking described above.
+ </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>
+
+<!-- Chapter 04 : Allocators -->
+<chapter id="manual.ext.allocator" xreflabel="Allocators">
+<?dbhtml filename="ext_allocators.html"?>
+ <title>Allocators</title>
+
+ <!-- Section 01 : __mt_alloc -->
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+ parse="xml" href="mt_allocator.xml">
+ </xi:include>
+
+ <!-- Section 02 : bitmap_allocator -->
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+ parse="xml" href="bitmap_allocator.xml">
+ </xi:include>
+
+</chapter>
+
+<!-- Chapter 05 : Containers -->
+<chapter id="manual.ext.containers" xreflabel="Containers">
+<?dbhtml filename="ext_containers.html"?>
+ <title>Containers</title>
+ <para>
+ </para>
+ <sect1 id="manual.ext.containers.pbds" xreflabel="Policy Based Data Structures">
+ <title>Policy Based Data Structures</title>
+ <para>
+ <ulink
+ url="http://gcc.gnu.org/onlinedocs/libstdc++/ext/pb_ds/index.html">More details here</ulink>.
+ </para>
+ </sect1>
+
+ <sect1 id="manual.ext.containers.sgi" xreflabel="SGI ext">
+ <title>HP/SGI</title>
+ <para>
+ </para>
+
+<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 "bitset<N>," 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 semantics of member function <code>operator[]</code> are not specified
+ in the C++ standard. A long-standing defect report calls for sensible
+ obvious semantics, which are already implemented here: <code>op[]</code>
+ on a const bitset returns a bool, and for a non-const bitset returns a
+ <code>reference</code> (a nested type). However, this implementation does
+ no range-checking on the index argument, which is in keeping with other
+ containers' <code>op[]</code> requirements. The defect report's proposed
+ resolution calls for range-checking to be done. We'll just wait and see...
+</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>
+ </sect1>
+
+
+ <sect1 id="manual.ext.containers.deprecated_sgi" xreflabel="SGI ext dep">
+ <title>Deprecated HP/SGI</title>
+
+ <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 the upcoming C++0x, 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;
+ <code><hash_map></code> and <code><hash_set></code>
+ are deprecated but available as backwards-compatible extensions,
+ as discussed further below. <code><rope></code> is the
+ SGI specialization for large strings ("rope,"
+ "large strings," get it? Love that geeky humor.)
+ <code><slist></code> is a singly-linked list, for when the
+ doubly-linked <code>list<></code> is too much space
+ overhead, and <code><rb_tree></code> 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
+ <ulink url="http://www.sgi.com/tech/stl/HashFunction.html">hashing
+ function</ulink> 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
+ <ulink url="http://www.sgi.com/tech/stl/hash.html">hash</ulink>.
+ 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>
+
+ </sect1>
+</chapter>
+
+<!-- Chapter 06 : Utilities -->
+<chapter id="manual.ext.util" xreflabel="Utilities">
+<?dbhtml filename="ext_utilities.html"?>
+ <title>Utilities</title>
+ <para>
+ The <functional> 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 07 : Algorithms -->
+<chapter id="manual.ext.algorithms" xreflabel="Algorithms">
+<?dbhtml filename="ext_algorithms.html"?>
+ <title>Algorithms</title>
+<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 08 : Numerics -->
+<chapter id="manual.ext.numerics" xreflabel="Numerics">
+<?dbhtml filename="ext_numerics.html"?>
+ <title>Numerics</title>
+<para>26.4, the generalized numeric operations such as accumulate, are extended
+ with the following functions:
+</para>
+ <programlisting>
+ power (x, n);
+ power (x, n, moniod_operation);</programlisting>
+<para>Returns, in FORTRAN syntax, "x ** n" where n>=0. In the
+ case of n == 0, returns the <ulink url="#ch20">identity element</ulink> 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. It "assigns sequentially increasing values to a range.
+ That is, it assigns value to *first, value + 1 to *(first + 1) and so
+ on." Quoted from SGI documentation.
+</para>
+ <programlisting>
+ void iota(_ForwardIter first, _ForwardIter last, _Tp value);</programlisting>
+</chapter>
+
+<!-- Chapter 09 : Iterators -->
+<chapter id="manual.ext.iterators" xreflabel="Iterators">
+<?dbhtml filename="ext_iterators.html"?>
+ <title>Iterators</title>
+<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 08 : IO -->
+<chapter id="manual.ext.io" xreflabel="IO">
+<?dbhtml filename="ext_io.html"?>
+ <title>Input and Output</title>
+
+ <para>
+ Extensions allowing <code>filebuf</code>s to be constructed from
+ "C" types like FILE*s and file descriptors.
+ </para>
+
+ <sect1 id="manual.ext.io.filebuf_derived" xreflabel="Derived filebufs">
+ <title>Derived filebufs</title>
+
+ <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 <code>filebuf</code> constructor and
+ the <code>fd()</code> function were removed from the standard
+ filebuf. Instead, <code><ext/stdio_filebuf.h></code> contains
+ a derived class called
+ <ulink url="http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/class____gnu__cxx_1_1stdio__filebuf.html"><code>__gnu_cxx::stdio_filebuf</code></ulink>.
+ 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>
+ <para>If you want to access a <code>filebuf</code>'s file descriptor to
+ implement file locking (e.g. using the <code>fcntl()</code> system
+ call) then you might be interested in Henry Suter's
+ <ulink url="http://suter.home.cern.ch/suter/RWLock.html">RWLock</ulink>
+ class.
+ </para>
+
+ <para>
+ </para>
+ </sect1>
+</chapter>
+
+<!-- Chapter 09 : Demangling -->
+<chapter id="manual.ext.demangle" xreflabel="Demangling">
+<?dbhtml filename="ext_demangling.html"?>
+ <title>Demangling</title>
+ <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 <ulink
+ url="http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/namespaceabi.html">source
+ documentation for <code>namespace abi</code></ulink> 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 10 : Concurrency -->
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+ parse="xml" href="concurrency.xml">
+</xi:include>
+
+</part>
projects / msp430-gcc.git / blobdiff