Mercurial > hg > CbC > CbC_gcc
view libstdc++-v3/doc/xml/manual/extensions.xml @ 120:f93fa5091070
fix conv1.c
author | mir3636 |
---|---|
date | Thu, 08 Mar 2018 14:53:42 +0900 |
parents | 04ced10e8804 |
children | 84e7813d76e9 |
line wrap: on
line source
<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> <!-- Chapter 04 : Profile Mode --> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="xml" href="profile_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="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="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="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 <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 <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/a00074.html"><code>__gnu_cxx::stdio_filebuf</code></link>. 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>