diff options
| author | bkoz <bkoz@138bc75d-0d04-0410-961f-82ee72b054a4> | 2008-02-11 00:01:33 +0000 |
|---|---|---|
| committer | bkoz <bkoz@138bc75d-0d04-0410-961f-82ee72b054a4> | 2008-02-11 00:01:33 +0000 |
| commit | 2aad0282e79bee5d49dfd0f76d5c72f6c6912156 (patch) | |
| tree | 9c37bc44363d015d83f53e9ff733daf4affc1973 /libstdc++-v3/doc/xml/manual | |
| parent | 90a6366aaa90e4e3c7bf9af1b57df621241589a0 (diff) | |
| download | ppe42-gcc-2aad0282e79bee5d49dfd0f76d5c72f6c6912156.tar.gz ppe42-gcc-2aad0282e79bee5d49dfd0f76d5c72f6c6912156.zip | |
2008-02-10 Benjamin Kosnik <bkoz@redhat.com>
Convert documentation to DocBook.
* doc/Makefile.am (doc-doxygen-html): Changed to doc-html-doxygen.
(doc-doxygen-man): Changed to doc-man-doxygen.
(doc-performance): Changed to doc-html-performance.
(doc-xml-doxygen): New.
(doc-xml-single): New.
(doc-xml-validate): New.
(doc-html): New.
(doc-html-single): New.
(doc-fo): New.
(doc-pdf): New.
(doc-pdf-fop-xml): New.
(doc-pdf-fop-fo): New.
(doc-pdf-xmlto): New.
(doc-pdf-xmlroff): New.
(doc-pdf-prince): New.
* doc/xml: New directory.
* doc/xml/authors.xml: New.
* doc/xml/images: New directory.
* doc/xml/images/confdeps.png: Add.
* doc/xml/images/confdeps.dot: Add.
* doc/xml/faq.xml: New.
* doc/xml/api.xml: New.
* doc/xml/gnu: New directory.
* doc/xml/gnu/gpl-3.0.xml: New.
* doc/xml/gnu/fdl-1.2.xml: New.
* doc/xml/gnu/gpl-2.0.xml: New.
* doc/xml/manual: New directory.
* doc/xml/manual/mt_allocator.xml: New.
* doc/xml/manual/allocator.xml: New.
* doc/xml/manual/ctype.xml: New.
* doc/xml/manual/numerics.xml: New.
* doc/xml/manual/codecvt.xml: New.
* doc/xml/manual/concurrency.xml: New.
* doc/xml/manual/backwards_compatibility.xml: New.
* doc/xml/manual/intro.xml: New.
* doc/xml/manual/shared_ptr.xml: New.
* doc/xml/manual/abi.xml: New.
* doc/xml/manual/status_cxxtr1.xml: New.
* doc/xml/manual/auto_ptr.xml: New.
* doc/xml/manual/build.xml: New.
* doc/xml/manual/internals.xml: New.
* doc/xml/manual/parallel_mode.xml: New.
* doc/xml/manual/status_cxx1998.xml: New.
* doc/xml/manual/containers.xml: New.
* doc/xml/manual/io.xml: New.
* doc/xml/manual/appendix_porting.xml: New.
* doc/xml/manual/utilities.xml: New.
* doc/xml/manual/bitmap_allocator.xml: New.
* doc/xml/manual/support.xml: New.
* doc/xml/manual/configure.xml: New.
* doc/xml/manual/build_hacking.xml: New.
* doc/xml/manual/evolution.xml: New.
* doc/xml/manual/using.xml: New.
* doc/xml/manual/debug.xml: New.
* doc/xml/manual/localization.xml: New.
* doc/xml/manual/strings.xml: New.
* doc/xml/manual/debug_mode.xml: New.
* doc/xml/manual/locale.xml: New.
* doc/xml/manual/extensions.xml: New.
* doc/xml/manual/appendix_contributing.xml: New.
* doc/xml/manual/messages.xml: New.
* doc/xml/manual/diagnostics.xml: New.
* doc/xml/manual/appendix_free.xml: New.
* doc/xml/manual/algorithms.xml: New.
* doc/xml/manual/iterators.xml: New.
* doc/xml/manual/spine.xml: New.
* doc/xml/manual/test.xml: New.
* doc/xml/manual/status_cxx200x.xml: New.
* doc/xml/spine.xml: New.
* doc/xml/book.txml: New. Template file.
* doc/xml/chapter.txml: Same.
* doc/xml/class.txml: Same.
* doc/doxygen/guide.html: Removed, integrated into other docs.
* doc/doxygen/user.cfg.in: Clean up XML generation.
* doc/doxygen/run_doxygen: Move to..
* scripts/run_doxygen: ...here.
* configure: Regenerate.
* Makefile.in: Regenerate.
* src/Makefile.in: Regenerate.
* doc/Makefile.in: Regenerate.
* po/Makefile.in: Regenerate.
* libmath/Makefile.in: Regenerate.
* include/Makefile.in: Regenerate.
* libsupc++/Makefile.in: Regenerate.
* testsuite/Makefile.in: Regenerate.
* aclocal.m4: Regenerate.
git-svn-id: svn+ssh://gcc.gnu.org/svn/gcc/trunk@132226 138bc75d-0d04-0410-961f-82ee72b054a4
Diffstat (limited to 'libstdc++-v3/doc/xml/manual')
41 files changed, 29885 insertions, 0 deletions
diff --git a/libstdc++-v3/doc/xml/manual/abi.xml b/libstdc++-v3/doc/xml/manual/abi.xml new file mode 100644 index 00000000000..c11da9507db --- /dev/null +++ b/libstdc++-v3/doc/xml/manual/abi.xml @@ -0,0 +1,1130 @@ +<sect1 id="appendix.porting.abi" xreflabel="abi"> +<?dbhtml filename="abi.html"?> + +<sect1info> + <keywordset> + <keyword> + C++ + </keyword> + <keyword> + ABI + </keyword> + <keyword> + version + </keyword> + <keyword> + dynamic + </keyword> + <keyword> + shared + </keyword> + </keywordset> +</sect1info> + +<title>ABI Policy and Guidelines</title> + +<para> +</para> + +<sect2 id="abi.cxx_interface" xreflabel="abi.cxx_interface"> +<title>The C++ Interface</title> + +<para> + C++ applications often dependent on specific language support + routines, say for throwing exceptions, or catching exceptions, and + perhaps also dependent on features in the C++ Standard Library. +</para> + +<para> + The C++ Standard Library has many include files, types defined in + those include files, specific named functions, and other + behavior. The text of these behaviors, as written in source include + files, is called the Application Programing Interface, or API. +</para> + +<para> + Furthermore, C++ source that is compiled into object files is + transformed by the compiler: it arranges objects with specific + alignment and in a particular layout, mangling names according to a + well-defined algorithm, has specific arrangements for the support of + virtual functions, etc. These details are defined as the compiler + Application Binary Interface, or ABI. The GNU C++ compiler uses an + industry-standard C++ ABI starting with version 3. Details can be + found in the <ulink + url="http://www.codesourcery.com/cxx-abi/abi.html"> ABI + specification</ulink>. +</para> + +<para> + The GNU C++ compiler, g++, has a compiler command line option to + switch between various different C++ ABIs. This explicit version + switch is the flag <code>-fabi-version</code>. In addition, some + g++ command line options may change the ABI as a side-effect of + use. Such flags include <code>-fpack-struct</code> and + <code>-fno-exceptions</code>, but include others: see the complete + list in the GCC manual under the heading <ulink url="http://gcc.gnu.org/onlinedocs/gcc/Code-Gen-Options.html#Code%20Gen%20Options">Options + for Code Generation Conventions</ulink>. +</para> + +<para> + The configure options used when building a specific libstdc++ + version may also impact the resulting library ABI. The available + configure options, and their impact on the library ABI, are + documented +<ulink url="http://gcc.gnu.org/onlinedocs/libstdc++/configopts.html"> +here</ulink>. +</para> + +<para> Putting all of these ideas together results in the C++ Standard +library ABI, which is the compilation of a given library API by a +given compiler ABI. In a nutshell: +</para> + +<para> + <quote> + library API + compiler ABI = library ABI + </quote> +</para> + +<para> + The library ABI is mostly of interest for end-users who have + unresolved symbols and are linking dynamically to the C++ Standard + library, and who thus must be careful to compile their application + with a compiler that is compatible with the available C++ Standard + library binary. In this case, compatible is defined with the equation + above: given an application compiled with a given compiler ABI and + library API, it will work correctly with a Standard C++ Library + created with the same constraints. +</para> + +<para> + To use a specific version of the C++ ABI, one must use a + corresponding GNU C++ toolchain (Ie, g++ and libstdc++) that + implements the C++ ABI in question. +</para> + +</sect2> + +<sect2 id="abi.versioning" xreflabel="abi.versioning"> +<title>Versioning</title> + +<para> The C++ interface has evolved throughout the history of the GNU +C++ toolchain. With each release, various details have been changed so +as to give distinct versions to the C++ interface. +</para> + + <sect3 id="abi.versioning.goals" xreflabel="abi.versioning.goals"> + <title>Goals</title> + +<para>Extending existing, stable ABIs. Versioning gives subsequent stable +releases series libraries the ability to add new symbols and add +functionality, all the while retaining backwards compatibility with +the previous releases in the series. Note: the reverse is not true. It +is not possible to take binaries linked with the latest version of a +release series (if symbols have been added) and expect the initial +release of the series to remain link compatible. +</para> + +<para>Allows multiple, incompatible ABIs to coexist at the same time. +</para> + </sect3> + + <sect3 id="abi.versioning.history" xreflabel="abi.versioning.history"> + <title>History</title> + +<para> + How can this complexity be managed? What does C++ versioning mean? + Because library and compiler changes often make binaries compiled + with one version of the GNU tools incompatible with binaries + compiled with other (either newer or older) versions of the same GNU + tools, specific techniques are used to make managing this complexity + easier. +</para> + +<para> + The following techniques are used: +</para> + + <orderedlist> + + <listitem><para>Release versioning on the libgcc_s.so binary. </para> + + <para>This is implemented via file names and the ELF DT_SONAME + mechanism (at least on ELF systems). It is versioned as follows: + </para> + + <itemizedlist> + <listitem><para>gcc-3.0.0: libgcc_s.so.1</para></listitem> + <listitem><para>gcc-3.0.1: libgcc_s.so.1</para></listitem> + <listitem><para>gcc-3.0.2: libgcc_s.so.1</para></listitem> + <listitem><para>gcc-3.0.3: libgcc_s.so.1</para></listitem> + <listitem><para>gcc-3.0.4: libgcc_s.so.1</para></listitem> + <listitem><para>gcc-3.1.0: libgcc_s.so.1</para></listitem> + <listitem><para>gcc-3.1.1: libgcc_s.so.1</para></listitem> + <listitem><para>gcc-3.2.0: libgcc_s.so.1</para></listitem> + <listitem><para>gcc-3.2.1: libgcc_s.so.1</para></listitem> + <listitem><para>gcc-3.2.2: libgcc_s.so.1</para></listitem> + <listitem><para>gcc-3.2.3: libgcc_s.so.1</para></listitem> + <listitem><para>gcc-3.3.0: libgcc_s.so.1</para></listitem> + <listitem><para>gcc-3.3.1: libgcc_s.so.1</para></listitem> + <listitem><para>gcc-3.3.2: libgcc_s.so.1</para></listitem> + <listitem><para>gcc-3.3.3: libgcc_s.so.1</para></listitem> + <listitem><para>gcc-3.4.x, gcc-4.0.x, gcc-4.1.x, gcc-4.2.x: on m68k-linux and + hppa-linux this is either libgcc_s.so.1 (when configuring + <code>--with-sjlj-exceptions</code>) or libgcc_s.so.2. For all + others, this is libgcc_s.so.1. </para> + </listitem> + </itemizedlist> + + </listitem> + + <listitem><para>Symbol versioning on the libgcc_s.so binary.</para> + + <para>It is versioned with the following labels and version + definitions, where the version definition is the maximum for a + particular release. Labels are cumulative. If a particular release + is not listed, it has the same version labels as the preceeding + release.</para> + + <para>This corresponds to the mapfile: gcc/libgcc-std.ver</para> + <itemizedlist> + <listitem><para>gcc-3.0.0: GCC_3.0</para></listitem> + <listitem><para>gcc-3.3.0: GCC_3.3</para></listitem> + <listitem><para>gcc-3.3.1: GCC_3.3.1</para></listitem> + <listitem><para>gcc-3.3.2: GCC_3.3.2</para></listitem> + <listitem><para>gcc-3.3.4: GCC_3.3.4</para></listitem> + <listitem><para>gcc-3.4.0: GCC_3.4</para></listitem> + <listitem><para>gcc-3.4.2: GCC_3.4.2</para></listitem> + <listitem><para>gcc-3.4.4: GCC_3.4.4</para></listitem> + <listitem><para>gcc-4.0.0: GCC_4.0.0</para></listitem> + <listitem><para>gcc-4.1.0: GCC_4.1.0</para></listitem> + <listitem><para>gcc-4.2.0: GCC_4.2.0</para></listitem> + </itemizedlist> + </listitem> + + <listitem><para>Release versioning on the libstdc++.so binary, implemented in the same was as the libgcc_s.so binary, above.</para> + + <para>It is versioned as follows: + </para> + <itemizedlist> + <listitem><para>gcc-3.0.0: libstdc++.so.3.0.0</para></listitem> + <listitem><para>gcc-3.0.1: libstdc++.so.3.0.1</para></listitem> + <listitem><para>gcc-3.0.2: libstdc++.so.3.0.2</para></listitem> + <listitem><para>gcc-3.0.3: libstdc++.so.3.0.2 (Error should be libstdc++.so.3.0.3)</para></listitem> + <listitem><para>gcc-3.0.4: libstdc++.so.3.0.4</para></listitem> + <listitem><para>gcc-3.1.0: libstdc++.so.4.0.0</para></listitem> + <listitem><para>gcc-3.1.1: libstdc++.so.4.0.1</para></listitem> + <listitem><para>gcc-3.2.0: libstdc++.so.5.0.0</para></listitem> + <listitem><para>gcc-3.2.1: libstdc++.so.5.0.1</para></listitem> + <listitem><para>gcc-3.2.2: libstdc++.so.5.0.2</para></listitem> + <listitem><para>gcc-3.2.3: libstdc++.so.5.0.3 (Not strictly required)</para></listitem> + <listitem><para>gcc-3.3.0: libstdc++.so.5.0.4</para></listitem> + <listitem><para>gcc-3.3.1: libstdc++.so.5.0.5</para></listitem> + <listitem><para>gcc-3.3.2: libstdc++.so.5.0.5</para></listitem> + <listitem><para>gcc-3.3.3: libstdc++.so.5.0.5</para></listitem> + <listitem><para>gcc-3.4.0: libstdc++.so.6.0.0</para></listitem> + <listitem><para>gcc-3.4.1: libstdc++.so.6.0.1</para></listitem> + <listitem><para>gcc-3.4.2: libstdc++.so.6.0.2</para></listitem> + <listitem><para>gcc-3.4.3: libstdc++.so.6.0.3</para></listitem> + <listitem><para>gcc-3.4.4: libstdc++.so.6.0.3</para></listitem> + <listitem><para>gcc-3.4.5: libstdc++.so.6.0.3</para></listitem> + <listitem><para>gcc-3.4.6: libstdc++.so.6.0.3</para></listitem> + <listitem><para>gcc-4.0.0: libstdc++.so.6.0.4</para></listitem> + <listitem><para>gcc-4.0.1: libstdc++.so.6.0.5</para></listitem> + <listitem><para>gcc-4.0.2: libstdc++.so.6.0.6</para></listitem> + <listitem><para>gcc-4.0.3: libstdc++.so.6.0.7</para></listitem> + <listitem><para>gcc-4.1.0: libstdc++.so.6.0.7</para></listitem> + <listitem><para>gcc-4.1.1: libstdc++.so.6.0.8</para></listitem> + <listitem><para>gcc-4.1.2: libstdc++.so.6.0.8</para></listitem> + <listitem><para>gcc-4.2.0: libstdc++.so.6.0.9</para></listitem> + </itemizedlist> + </listitem> + + <listitem><para>Symbol versioning on the libstdc++.so binary.</para> + + <para>mapfile: libstdc++/config/linker-map.gnu</para> + <para>It is versioned with the following labels and version + definitions, where the version definition is the maximum for a + particular release. Note, only symbol which are newly introduced + will use the maximum version definition. Thus, for release series + with the same label, but incremented version definitions, the later + release has both versions. (An example of this would be the + gcc-3.2.1 release, which has GLIBCPP_3.2.1 for new symbols and + GLIBCPP_3.2 for symbols that were introduced in the gcc-3.2.0 + release.) If a particular release is not listed, it has the same + version labels as the preceeding release. + </para> + <itemizedlist> + <listitem><para>gcc-3.0.0: (Error, not versioned)</para></listitem> + <listitem><para>gcc-3.0.1: (Error, not versioned)</para></listitem> + <listitem><para>gcc-3.0.2: (Error, not versioned)</para></listitem> + <listitem><para>gcc-3.0.3: (Error, not versioned)</para></listitem> + <listitem><para>gcc-3.0.4: (Error, not versioned)</para></listitem> + <listitem><para>gcc-3.1.0: GLIBCPP_3.1, CXXABI_1</para></listitem> + <listitem><para>gcc-3.1.1: GLIBCPP_3.1, CXXABI_1</para></listitem> + <listitem><para>gcc-3.2.0: GLIBCPP_3.2, CXXABI_1.2</para></listitem> + <listitem><para>gcc-3.2.1: GLIBCPP_3.2.1, CXXABI_1.2</para></listitem> + <listitem><para>gcc-3.2.2: GLIBCPP_3.2.2, CXXABI_1.2</para></listitem> + <listitem><para>gcc-3.2.3: GLIBCPP_3.2.2, CXXABI_1.2</para></listitem> + <listitem><para>gcc-3.3.0: GLIBCPP_3.2.2, CXXABI_1.2.1</para></listitem> + <listitem><para>gcc-3.3.1: GLIBCPP_3.2.3, CXXABI_1.2.1</para></listitem> + <listitem><para>gcc-3.3.2: GLIBCPP_3.2.3, CXXABI_1.2.1</para></listitem> + <listitem><para>gcc-3.3.3: GLIBCPP_3.2.3, CXXABI_1.2.1</para></listitem> + <listitem><para>gcc-3.4.0: GLIBCXX_3.4, CXXABI_1.3</para></listitem> + <listitem><para>gcc-3.4.1: GLIBCXX_3.4.1, CXXABI_1.3</para></listitem> + <listitem><para>gcc-3.4.2: GLIBCXX_3.4.2</para></listitem> + <listitem><para>gcc-3.4.3: GLIBCXX_3.4.3</para></listitem> + <listitem><para>gcc-4.0.0: GLIBCXX_3.4.4, CXXABI_1.3.1</para></listitem> + <listitem><para>gcc-4.0.1: GLIBCXX_3.4.5</para></listitem> + <listitem><para>gcc-4.0.2: GLIBCXX_3.4.6</para></listitem> + <listitem><para>gcc-4.0.3: GLIBCXX_3.4.7</para></listitem> + <listitem><para>gcc-4.1.1: GLIBCXX_3.4.8</para></listitem> + <listitem><para>gcc-4.2.0: GLIBCXX_3.4.9</para></listitem> + </itemizedlist> + </listitem> + + <listitem> + <para>Incremental bumping of a compiler pre-defined macro, + __GXX_ABI_VERSION. This macro is defined as the version of the + compiler v3 ABI, with g++ 3.0.x being version 100. This macro will + be automatically defined whenever g++ is used (the curious can + test this by invoking g++ with the '-v' flag.) + </para> + + <para> + This macro was defined in the file "lang-specs.h" in the gcc/cp directory. + Later versions defined it in "c-common.c" in the gcc directory, and from + G++ 3.4 it is defined in c-cppbuiltin.c and its value determined by the + '-fabi-version' command line option. + </para> + + <para> + It is versioned as follows, where 'n' is given by '-fabi-version=n': + </para> + <itemizedlist> + <listitem><para>gcc-3.0.x: 100</para></listitem> + <listitem><para>gcc-3.1.x: 100 (Error, should be 101)</para></listitem> + <listitem><para>gcc-3.2.x: 102</para></listitem> + <listitem><para>gcc-3.3.x: 102</para></listitem> + <listitem><para>gcc-3.4.x, gcc-4.0.x, gcc-4.1.x, gcc-4.2.x: 102 (when n=1)</para></listitem> + <listitem><para>gcc-3.4.x, gcc-4.0.x, gcc-4.1.x, gcc-4.2.x: 1000 + n (when n>1)</para></listitem> + <listitem><para>gcc-3.4.x, gcc-4.0.x, gcc-4.1.x, gcc-4.2.x: 999999 (when n=0)</para></listitem> + </itemizedlist> + <para></para> + </listitem> + + <listitem> + <para>Changes to the default compiler option for + <code>-fabi-version</code>. + </para> + <para> + It is versioned as follows: + </para> + <itemizedlist> + <listitem><para>gcc-3.0.x: (Error, not versioned) </para></listitem> + <listitem><para>gcc-3.1.x: (Error, not versioned) </para></listitem> + <listitem><para>gcc-3.2.x: <code>-fabi-version=1</code></para></listitem> + <listitem><para>gcc-3.3.x: <code>-fabi-version=1</code></para></listitem> + <listitem><para>gcc-3.4.x, gcc-4.0.x, gcc-4.1.x, gcc-4.2.x: <code>-fabi-version=2</code></para></listitem> + </itemizedlist> + <para></para> + </listitem> + + <listitem> + <para>Incremental bumping of a library pre-defined macro. For releases + before 3.4.0, the macro is __GLIBCPP__. For later releases, it's + __GLIBCXX__. (The libstdc++ project generously changed from CPP to + CXX throughout its source to allow the "C" pre-processor the CPP + macro namespace.) These macros are defined as the date the library + was released, in compressed ISO date format, as an unsigned long. + </para> + + <para> + This macro is defined in the file "c++config" in the + "libstdc++/include/bits" directory. (Up to gcc-4.1.0, it was + changed every night by an automated script. Since gcc-4.1.0, it is + the same value as gcc/DATESTAMP.) + </para> + <para> + It is versioned as follows: + </para> + <itemizedlist> + <listitem><para>gcc-3.0.0: 20010615</para></listitem> + <listitem><para>gcc-3.0.1: 20010819</para></listitem> + <listitem><para>gcc-3.0.2: 20011023</para></listitem> + <listitem><para>gcc-3.0.3: 20011220</para></listitem> + <listitem><para>gcc-3.0.4: 20020220</para></listitem> + <listitem><para>gcc-3.1.0: 20020514</para></listitem> + <listitem><para>gcc-3.1.1: 20020725</para></listitem> + <listitem><para>gcc-3.2.0: 20020814</para></listitem> + <listitem><para>gcc-3.2.1: 20021119</para></listitem> + <listitem><para>gcc-3.2.2: 20030205</para></listitem> + <listitem><para>gcc-3.2.3: 20030422</para></listitem> + <listitem><para>gcc-3.3.0: 20030513</para></listitem> + <listitem><para>gcc-3.3.1: 20030804</para></listitem> + <listitem><para>gcc-3.3.2: 20031016</para></listitem> + <listitem><para>gcc-3.3.3: 20040214</para></listitem> + <listitem><para>gcc-3.4.0: 20040419</para></listitem> + <listitem><para>gcc-3.4.1: 20040701</para></listitem> + <listitem><para>gcc-3.4.2: 20040906</para></listitem> + <listitem><para>gcc-3.4.3: 20041105</para></listitem> + <listitem><para>gcc-3.4.4: 20050519</para></listitem> + <listitem><para>gcc-3.4.5: 20051201</para></listitem> + <listitem><para>gcc-3.4.6: 20060306</para></listitem> + <listitem><para>gcc-4.0.0: 20050421</para></listitem> + <listitem><para>gcc-4.0.1: 20050707</para></listitem> + <listitem><para>gcc-4.0.2: 20050921</para></listitem> + <listitem><para>gcc-4.0.3: 20060309</para></listitem> + <listitem><para>gcc-4.1.0: 20060228</para></listitem> + <listitem><para>gcc-4.1.1: 20060524</para></listitem> + <listitem><para>gcc-4.1.2: 20070214</para></listitem> + <listitem><para>gcc-4.2.0: 20070514</para></listitem> + </itemizedlist> + <para></para> + </listitem> + + <listitem> + <para> + Incremental bumping of a library pre-defined macro, + _GLIBCPP_VERSION. This macro is defined as the released version of + the library, as a string literal. This is only implemented in + gcc-3.1.0 releases and higher, and is deprecated in 3.4 (where it + is called _GLIBCXX_VERSION). + </para> + + <para> + This macro is defined in the file "c++config" in the + "libstdc++/include/bits" directory and is generated + automatically by autoconf as part of the configure-time generation + of config.h. + </para> + + <para> + It is versioned as follows: + </para> + <itemizedlist> + <listitem><para>gcc-3.0.0: "3.0.0"</para></listitem> + <listitem><para>gcc-3.0.1: "3.0.0" (Error, should be "3.0.1")</para></listitem> + <listitem><para>gcc-3.0.2: "3.0.0" (Error, should be "3.0.2")</para></listitem> + <listitem><para>gcc-3.0.3: "3.0.0" (Error, should be "3.0.3")</para></listitem> + <listitem><para>gcc-3.0.4: "3.0.0" (Error, should be "3.0.4")</para></listitem> + <listitem><para>gcc-3.1.0: "3.1.0"</para></listitem> + <listitem><para>gcc-3.1.1: "3.1.1"</para></listitem> + <listitem><para>gcc-3.2.0: "3.2"</para></listitem> + <listitem><para>gcc-3.2.1: "3.2.1"</para></listitem> + <listitem><para>gcc-3.2.2: "3.2.2"</para></listitem> + <listitem><para>gcc-3.2.3: "3.2.3"</para></listitem> + <listitem><para>gcc-3.3.0: "3.3"</para></listitem> + <listitem><para>gcc-3.3.1: "3.3.1"</para></listitem> + <listitem><para>gcc-3.3.2: "3.3.2"</para></listitem> + <listitem><para>gcc-3.3.3: "3.3.3"</para></listitem> + <listitem><para>gcc-3.4.x: "version-unused"</para></listitem> + <listitem><para>gcc-4.0.x: "version-unused"</para></listitem> + <listitem><para>gcc-4.1.x: "version-unused"</para></listitem> + <listitem><para>gcc-4.2.x: "version-unused"</para></listitem> + </itemizedlist> + <para></para> + </listitem> + + <listitem> + <para> + Matching each specific C++ compiler release to a specific set of + C++ include files. This is only implemented in gcc-3.1.1 releases + and higher. + </para> + <para> + All C++ includes are installed in include/c++, then nest in a + directory hierarchy corresponding to the C++ compiler's released + version. This version corresponds to the variable "gcc_version" in + "libstdc++/acinclude.m4," and more details can be found in that + file's macro GLIBCXX_CONFIGURE (GLIBCPP_CONFIGURE before gcc-3.4.0). + </para> + <para> + C++ includes are versioned as follows: + </para> + <itemizedlist> + <listitem><para>gcc-3.0.0: include/g++-v3</para></listitem> + <listitem><para>gcc-3.0.1: include/g++-v3</para></listitem> + <listitem><para>gcc-3.0.2: include/g++-v3</para></listitem> + <listitem><para>gcc-3.0.3: include/g++-v3</para></listitem> + <listitem><para>gcc-3.0.4: include/g++-v3</para></listitem> + <listitem><para>gcc-3.1.0: include/g++-v3</para></listitem> + <listitem><para>gcc-3.1.1: include/c++/3.1.1</para></listitem> + <listitem><para>gcc-3.2.0: include/c++/3.2</para></listitem> + <listitem><para>gcc-3.2.1: include/c++/3.2.1</para></listitem> + <listitem><para>gcc-3.2.2: include/c++/3.2.2</para></listitem> + <listitem><para>gcc-3.2.3: include/c++/3.2.3</para></listitem> + <listitem><para>gcc-3.3.0: include/c++/3.3</para></listitem> + <listitem><para>gcc-3.3.1: include/c++/3.3.1</para></listitem> + <listitem><para>gcc-3.3.2: include/c++/3.3.2</para></listitem> + <listitem><para>gcc-3.3.3: include/c++/3.3.3</para></listitem> + <listitem><para>gcc-3.4.0: include/c++/3.4.0</para></listitem> + <listitem><para>gcc-3.4.1: include/c++/3.4.1</para></listitem> + <listitem><para>gcc-3.4.2: include/c++/3.4.2</para></listitem> + <listitem><para>gcc-3.4.3: include/c++/3.4.3</para></listitem> + <listitem><para>gcc-3.4.4: include/c++/3.4.4</para></listitem> + <listitem><para>gcc-3.4.5: include/c++/3.4.5</para></listitem> + <listitem><para>gcc-3.4.6: include/c++/3.4.6</para></listitem> + <listitem><para>gcc-4.0.0: include/c++/4.0.0</para></listitem> + <listitem><para>gcc-4.0.1: include/c++/4.0.1</para></listitem> + <listitem><para>gcc-4.0.2: include/c++/4.0.2</para></listitem> + <listitem><para>gcc-4.0.3: include/c++/4.0.3</para></listitem> + <listitem><para>gcc-4.1.0: include/c++/4.1.0</para></listitem> + <listitem><para>gcc-4.1.1: include/c++/4.1.1</para></listitem> + <listitem><para>gcc-4.1.2: include/c++/4.1.2</para></listitem> + <listitem><para>gcc-4.2.0: include/c++/4.2.0</para></listitem> + </itemizedlist> + <para></para> + </listitem> + </orderedlist> + +<para> + Taken together, these techniques can accurately specify interface + and implementation changes in the GNU C++ tools themselves. Used + properly, they allow both the GNU C++ tools implementation, and + programs using them, an evolving yet controlled development that + maintains backward compatibility. +</para> + + + </sect3> + + <sect3 id="abi.versioning.prereq" xreflabel="abi.versioning.prereq"> + <title>Prerequisites</title> + <para> + Minimum environment that supports a versioned ABI: A supported + dynamic linker, a GNU linker of sufficient vintage to understand + demangled C++ name globbing (ld), a shared executable compiled + with g++, and shared libraries (libgcc_s, libstdc++) compiled by + a compiler (g++) with a compatible ABI. Phew. + </para> + + <para> + On top of all that, an additional constraint: libstdc++ did not + attempt to version symbols (or age gracefully, really) until + version 3.1.0. + </para> + + <para> + Most modern Linux and BSD versions, particularly ones using + gcc-3.1.x tools and more recent vintages, will meet the + requirements above. + </para> + </sect3> + + <sect3 id="abi.versioning.config" xreflabel="abi.versioning.config"> + <title>Configuring</title> + + <para> + It turns out that most of the configure options that change + default behavior will impact the mangled names of exported + symbols, and thus impact versioning and compatibility. + </para> + + <para> + For more information on configure options, including ABI + impacts, see: + http://gcc.gnu.org/onlinedocs/libstdc++/configopts.html + </para> + + <para> + There is one flag that explicitly deals with symbol versioning: + --enable-symvers. + </para> + + <para> + In particular, libstdc++/acinclude.m4 has a macro called + GLIBCXX_ENABLE_SYMVERS that defaults to yes (or the argument + passed in via --enable-symvers=foo). At that point, the macro + attempts to make sure that all the requirement for symbol + versioning are in place. For more information, please consult + acinclude.m4. + </para> + </sect3> + + <sect3 id="abi.versioning.active" xreflabel="abi.versioning.active"> + <title>Checking Active</title> + + <para> + When the GNU C++ library is being built with symbol versioning + on, you should see the following at configure time for + libstdc++: + </para> + +<screen> +<computeroutput> + checking versioning on shared library symbols... gnu +</computeroutput> +</screen> + +<para> + If you don't see this line in the configure output, or if this line + appears but the last word is 'no', then you are out of luck. +</para> + +<para> + If the compiler is pre-installed, a quick way to test is to compile + the following (or any) simple C++ file and link it to the shared + libstdc++ library: +</para> + +<programlisting> +#include <iostream> + +int main() +{ std::cout << "hello" << std::endl; return 0; } + +%g++ hello.cc -o hello.out + +%ldd hello.out + libstdc++.so.5 => /usr/lib/libstdc++.so.5 (0x00764000) + libm.so.6 => /lib/tls/libm.so.6 (0x004a8000) + libgcc_s.so.1 => /mnt/hd/bld/gcc/gcc/libgcc_s.so.1 (0x40016000) + libc.so.6 => /lib/tls/libc.so.6 (0x0036d000) + /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x00355000) + +%nm hello.out +</programlisting> + +<para> +If you see symbols in the resulting output with "GLIBCXX_3" as part +of the name, then the executable is versioned. Here's an example: +</para> + +<para> + <code>U _ZNSt8ios_base4InitC1Ev@@GLIBCXX_3.4</code> +</para> + + </sect3> +</sect2> + +<sect2 id="abi.changes_allowed" xreflabel="abi.changes_allowed"> +<title>Allowed Changes</title> + +<para> +The following will cause the library minor version number to +increase, say from "libstdc++.so.3.0.4" to "libstdc++.so.3.0.5". +</para> +<orderedlist> + <listitem><para>Adding an exported global or static data member</para></listitem> + <listitem><para>Adding an exported function, static or non-virtual member function</para></listitem> + <listitem><para>Adding an exported symbol or symbols by additional instantiations</para></listitem> +</orderedlist> +<para> +Other allowed changes are possible. +</para> + +</sect2> + +<sect2 id="abi.changes_no" xreflabel="abi.changes_no"> +<title>Prohibited Changes</title> + +<para> +The following non-exhaustive list will cause the library major version +number to increase, say from "libstdc++.so.3.0.4" to +"libstdc++.so.4.0.0". +</para> + +<orderedlist> + <listitem><para>Changes in the gcc/g++ compiler ABI</para></listitem> +<listitem><para>Changing size of an exported symbol</para></listitem> +<listitem><para>Changing alignment of an exported symbol</para></listitem> +<listitem><para>Changing the layout of an exported symbol</para></listitem> +<listitem><para>Changing mangling on an exported symbol</para></listitem> +<listitem><para>Deleting an exported symbol</para></listitem> +<listitem><para>Changing the inheritance properties of a type by adding or removing + base classes</para></listitem> +<listitem><para> + Changing the size, alignment, or layout of types + specified in the C++ standard. These may not necessarily be + instantiated or otherwise exported in the library binary, and + include all the required locale facets, as well as things like + std::basic_streambuf, et al. +</para></listitem> + +<listitem><para> Adding an explicit copy constructor or destructor to a +class that would otherwise have implicit versions. This will change +the way the compiler deals with this class in by-value return +statements or parameters: instead of being passing instances of this +class in registers, the compiler will be forced to use memory. See <ulink url="http://www.codesourcery.com/cxx-abi/abi.html#calls"> this part</ulink> + of the C++ ABI documentation for further details. + </para></listitem> + +</orderedlist> + +</sect2> + + + +<sect2 id="abi.impl" xreflabel="abi.impl"> +<title>Implementation</title> + +<orderedlist> + <listitem> + <para> + Separation of interface and implementation + </para> + <para> + This is accomplished by two techniques that separate the API from + the ABI: forcing undefined references to link against a library + binary for definitions. + </para> + +<variablelist> + <varlistentry> + <term>Include files have declarations, source files have defines</term> + + <listitem> + <para> + For non-templatized types, such as much of <code>class + locale</code>, the appropriate standard C++ include, say + <code>locale</code>, can contain full declarations, while + various source files (say <code> locale.cc, locale_init.cc, + localename.cc</code>) contain definitions. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Extern template on required types</term> + + <listitem> + <para> + For parts of the standard that have an explicit list of + required instantiations, the GNU extension syntax <code> extern + template </code> can be used to control where template + definitions reside. By marking required instantiations as + <code> extern template </code> in include files, and providing + explicit instantiations in the appropriate instantiation files, + non-inlined template functions can be versioned. This technique + is mostly used on parts of the standard that require <code> + char</code> and <code> wchar_t</code> instantiations, and + includes <code> basic_string</code>, the locale facets, and the + types in <code> iostreams</code>. + </para> + </listitem> + </varlistentry> + + </variablelist> + + <para> + In addition, these techniques have the additional benefit that they + reduce binary size, which can increase runtime performance. + </para> + </listitem> + + <listitem> + <para> + Namespaces linking symbol definitions to export mapfiles + </para> + <para> + All symbols in the shared library binary are processed by a + linker script at build time that either allows or disallows + external linkage. Because of this, some symbols, regardless of + normal C/C++ linkage, are not visible. Symbols that are internal + have several appealing characteristics: by not exporting the + symbols, there are no relocations when the shared library is + started and thus this makes for faster runtime loading + performance by the underlying dynamic loading mechanism. In + addition, they have the possibility of changing without impacting + ABI compatibility. + </para> + +<para>The following namespaces are transformed by the mapfile:</para> + +<variablelist> + + <varlistentry> +<term><code>namespace std</code></term> +<listitem><para> Defaults to exporting all symbols in label +<code>GLIBCXX</code> that do not begin with an underscore, ie +<code>__test_func</code> would not be exported by default. Select +exceptional symbols are allowed to be visible.</para></listitem> + </varlistentry> + + <varlistentry> +<term><code>namespace __gnu_cxx</code></term> +<listitem><para> Defaults to not exporting any symbols in label +<code>GLIBCXX</code>, select items are allowed to be visible.</para></listitem> + </varlistentry> + + <varlistentry> +<term><code>namespace __gnu_internal</code></term> +<listitem><para> Defaults to not exported, no items are allowed to be visible.</para></listitem> + </varlistentry> + + <varlistentry> +<term><code>namespace __cxxabiv1</code>, aliased to <code> namespace abi</code></term> +<listitem><para> Defaults to not exporting any symbols in label +<code>CXXABI</code>, select items are allowed to be visible.</para></listitem> + </varlistentry> + +</variablelist> +<para> +</para> +</listitem> + + <listitem><para>Freezing the API</para> + <para>Disallowed changes, as above, are not made on a stable release +branch. Enforcement tends to be less strict with GNU extensions that +standard includes.</para> +</listitem> +</orderedlist> + +</sect2> + +<sect2 id="abi.testing" xreflabel="abi.testing"> +<title>Testing</title> + + <sect3 id="abi.testing.single" xreflabel="abi.testing.single"> + <title>Single ABI Testing</title> + + <para> + Testing for GNU C++ ABI changes is composed of two distinct + areas: testing the C++ compiler (g++) for compiler changes, and + testing the C++ library (libstdc++) for library changes. + </para> + + <para> + Testing the C++ compiler ABI can be done various ways. + </para> + + <para> + One. Intel ABI checker. More information can be obtained <ulink + url="http://developer.intel.com/software/products/opensource/">here.</ulink> + </para> + +<para> +Two. +The second is yet unreleased, but has been announced on the gcc +mailing list. It is yet unspecified if these tools will be freely +available, and able to be included in a GNU project. Please contact +Mark Mitchell (mark@codesourcery.com) for more details, and current +status. +</para> + +<para> +Three. +Involves using the vlad.consistency test framework. This has also been +discussed on the gcc mailing lists. +</para> + +<para> +Testing the C++ library ABI can also be done various ways. +</para> + +<para> +One. +(Brendan Kehoe, Jeff Law suggestion to run 'make check-c++' two ways, +one with a new compiler and an old library, and the other with an old +compiler and a new library, and look for testsuite regressions) +</para> + +<para> +Details on how to set this kind of test up can be found here: +http://gcc.gnu.org/ml/gcc/2002-08/msg00142.html +</para> + +<para> +Two. +Use the 'make check-abi' rule in the libstdc++ Makefile. +</para> + +<para> +This is a proactive check the library ABI. Currently, exported symbol +names that are either weak or defined are checked against a last known +good baseline. Currently, this baseline is keyed off of 3.4.0 +binaries, as this was the last time the .so number was incremented. In +addition, all exported names are demangled, and the exported objects +are checked to make sure they are the same size as the same object in +the baseline. + +Notice that each baseline is relative to a <emphasis>default</emphasis> +configured library and compiler: in particular, if options such as +--enable-clocale, or --with-cpu, in case of multilibs, are used at +configure time, the check may fail, either because of substantive +differences or because of limitations of the current checking +machinery. +</para> + +<para> +This dataset is insufficient, yet a start. Also needed is a +comprehensive check for all user-visible types part of the standard +library for sizeof() and alignof() changes. +</para> + +<para> +Verifying compatible layouts of objects is not even attempted. It +should be possible to use sizeof, alignof, and offsetof to compute +offsets for each structure and type in the standard library, saving to +another datafile. Then, compute this in a similar way for new +binaries, and look for differences. +</para> + +<para> +Another approach might be to use the -fdump-class-hierarchy flag to +get information. However, currently this approach gives insufficient +data for use in library testing, as class data members, their offsets, +and other detailed data is not displayed with this flag. +(See g++/7470 on how this was used to find bugs.) +</para> + +<para> +Perhaps there are other C++ ABI checkers. If so, please notify +us. We'd like to know about them! +</para> + + </sect3> + <sect3 id="abi.testing.multi" xreflabel="abi.testing.multi"> + <title>Multiple ABI Testing</title> +<para> +A "C" application, dynamically linked to two shared libraries, liba, +libb. The dependent library liba is C++ shared library compiled with +gcc-3.3.x, and uses io, exceptions, locale, etc. The dependent library +libb is a C++ shared library compiled with gcc-3.4.x, and also uses io, +exceptions, locale, etc. +</para> + +<para> As above, libone is constructed as follows: </para> +<programlisting> +%$bld/H-x86-gcc-3.4.0/bin/g++ -fPIC -DPIC -c a.cc + +%$bld/H-x86-gcc-3.4.0/bin/g++ -shared -Wl,-soname -Wl,libone.so.1 -Wl,-O1 -Wl,-z,defs a.o -o libone.so.1.0.0 + +%ln -s libone.so.1.0.0 libone.so + +%$bld/H-x86-gcc-3.4.0/bin/g++ -c a.cc + +%ar cru libone.a a.o +</programlisting> + +<para> And, libtwo is constructed as follows: </para> + +<programlisting> +%$bld/H-x86-gcc-3.3.3/bin/g++ -fPIC -DPIC -c b.cc + +%$bld/H-x86-gcc-3.3.3/bin/g++ -shared -Wl,-soname -Wl,libtwo.so.1 -Wl,-O1 -Wl,-z,defs b.o -o libtwo.so.1.0.0 + +%ln -s libtwo.so.1.0.0 libtwo.so + +%$bld/H-x86-gcc-3.3.3/bin/g++ -c b.cc + +%ar cru libtwo.a b.o +</programlisting> + +<para> ...with the resulting libraries looking like </para> + +<screen> +<computeroutput> +%ldd libone.so.1.0.0 + libstdc++.so.6 => /usr/lib/libstdc++.so.6 (0x40016000) + libm.so.6 => /lib/tls/libm.so.6 (0x400fa000) + libgcc_s.so.1 => /mnt/hd/bld/gcc/gcc/libgcc_s.so.1 (0x4011c000) + libc.so.6 => /lib/tls/libc.so.6 (0x40125000) + /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x00355000) + +%ldd libtwo.so.1.0.0 + libstdc++.so.5 => /usr/lib/libstdc++.so.5 (0x40027000) + libm.so.6 => /lib/tls/libm.so.6 (0x400e1000) + libgcc_s.so.1 => /mnt/hd/bld/gcc/gcc/libgcc_s.so.1 (0x40103000) + libc.so.6 => /lib/tls/libc.so.6 (0x4010c000) + /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x00355000) +</computeroutput> +</screen> + +<para> + Then, the "C" compiler is used to compile a source file that uses + functions from each library. +</para> +<programlisting> +gcc test.c -g -O2 -L. -lone -ltwo /usr/lib/libstdc++.so.5 /usr/lib/libstdc++.so.6 +</programlisting> + +<para> + Which gives the expected: +</para> + +<screen> +<computeroutput> +%ldd a.out + libstdc++.so.5 => /usr/lib/libstdc++.so.5 (0x00764000) + libstdc++.so.6 => /usr/lib/libstdc++.so.6 (0x40015000) + libc.so.6 => /lib/tls/libc.so.6 (0x0036d000) + libm.so.6 => /lib/tls/libm.so.6 (0x004a8000) + libgcc_s.so.1 => /mnt/hd/bld/gcc/gcc/libgcc_s.so.1 (0x400e5000) + /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x00355000) +</computeroutput> +</screen> + +<para> + This resulting binary, when executed, will be able to safely use + code from both liba, and the dependent libstdc++.so.6, and libb, + with the dependent libstdc++.so.5. +</para> + </sect3> +</sect2> + +<sect2 id="abi.issues" xreflabel="abi.issues"> +<title>Outstanding Issues</title> + +<para> + Some features in the C++ language make versioning especially + difficult. In particular, compiler generated constructs such as + implicit instantiations for templates, typeinfo information, and + virtual tables all may cause ABI leakage across shared library + boundaries. Because of this, mixing C++ ABI's is not recommended at + this time. +</para> + +<para> + For more background on this issue, see these bugzilla entries: +</para> + +<para> +<ulink url="http://gcc.gnu.org/PR24660">24660: versioning weak symbols in libstdc++</ulink> +</para> + +<para> +<ulink url="http://gcc.gnu.org/PR19664">19664: libstdc++ headers should have pop/push of the visibility around the declarations</ulink> +</para> + +</sect2> + +<bibliography id="abi.biblio" xreflabel="abi.biblio"> +<title>Bibliography</title> + + <biblioentry> + <title> + ABIcheck, a vague idea of checking ABI compatibility + </title> + + <biblioid> + <ulink url="http://abicheck.sourceforge.net/"> + </ulink> + </biblioid> + </biblioentry> + + <biblioentry> + <title> + C++ ABI Reference + </title> + + <biblioid> + <ulink url="http://www.codesourcery.com/cxx-abi"> + </ulink> + </biblioid> + </biblioentry> + + <biblioentry> + <title> + Intel® Compilers for Linux* -Compatibility with the GNU Compilers + </title> + + <biblioid> + <ulink url="http://developer.intel.com/software/products/compilers/techtopics/LinuxCompilersCompatibility.htm"> + </ulink> + </biblioid> + </biblioentry> + + <biblioentry> + <title> + Intel® Compilers for Linux* -Compatibility with the GNU Compilers + </title> + + <biblioid> + <ulink url="http://developer.intel.com/software/products/compilers/techtopics/LinuxCompilersCompatibility.htm"> + </ulink> + </biblioid> + </biblioentry> + + <biblioentry> + <title> + Sun Solaris 2.9 : Linker and Libraries Guide (document 816-1386) + </title> + + <biblioid> + <ulink url="http://docs.sun.com/?p=/doc/816-1386&a=load"> + </ulink> + </biblioid> + </biblioentry> + + + <biblioentry> + <title> + Sun Solaris 2.9 : C++ Migration Guide (document 816-2459) + </title> + + <biblioid> + <ulink url="http://docs.sun.com/db/prod/solaris.9"> + </ulink> + </biblioid> + </biblioentry> + + <biblioentry> + <title> + ELF Symbol Versioning + </title> + + <author> + <firstname>Ulrich</firstname> + <surname>Drepper</surname> + </author> + + <biblioid> + <ulink url="http://people.redhat.com/drepper/symbol-versioning"> + </ulink> + </biblioid> + </biblioentry> + + <biblioentry> + <title> + C++ ABI for the ARM Architecture + </title> + + <biblioid> + <ulink url="http://www.arm.com/miscPDFs/8033.pdf"> + </ulink> + </biblioid> + </biblioentry> + + <biblioentry> + <title> + Dynamic Shared Objects: Survey and Issues + </title> + <subtitle> + ISO C++ J16/06-0046 + </subtitle> + + <author> + <firstname>Benjamin</firstname> + <surname>Kosnik</surname> + </author> + + <biblioid> + <ulink url="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2006/n1976.html"> + </ulink> + </biblioid> + </biblioentry> + + <biblioentry> + <title> + Versioning With Namespaces + </title> + <subtitle> + ISO C++ J16/06-0083 + </subtitle> + + <author> + <firstname>Benjamin</firstname> + <surname>Kosnik</surname> + </author> + + <biblioid> + <ulink url="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2006/n2013.html"> + </ulink> + </biblioid> + </biblioentry> + +</bibliography> + +</sect1>
\ No newline at end of file diff --git a/libstdc++-v3/doc/xml/manual/algorithms.xml b/libstdc++-v3/doc/xml/manual/algorithms.xml new file mode 100644 index 00000000000..6f1a16af24f --- /dev/null +++ b/libstdc++-v3/doc/xml/manual/algorithms.xml @@ -0,0 +1,104 @@ +<?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.algorithms" xreflabel="Algorithms"> +<?dbhtml filename="algorithms.html"?> + +<partinfo> + <keywordset> + <keyword> + ISO C++ + </keyword> + <keyword> + library + </keyword> + <keyword> + algorithm + </keyword> + </keywordset> +</partinfo> + +<title>Algorithms</title> + +<preface> + <title></title> +<para> + The neatest accomplishment of the algorithms chapter is that all the + work is done via iterators, not containers directly. This means two + important things: +</para> +<orderedlist> + <listitem> + <para> + Anything that behaves like an iterator can be used in one of + these algorithms. Raw pointers make great candidates, thus + built-in arrays are fine containers, as well as your own iterators. + </para> + </listitem> + <listitem> + <para> + The algorithms do not (and cannot) affect the container as a + whole; only the things between the two iterator endpoints. If + you pass a range of iterators only enclosing the middle third of + a container, then anything outside that range is inviolate. + </para> + </listitem> + </orderedlist> + <para> + Even strings can be fed through the algorithms here, although the + string class has specialized versions of many of these functions + (for example, <code>string::find()</code>). Most of the examples + on this page will use simple arrays of integers as a playground + for algorithms, just to keep things simple. The use of + <emphasis>N</emphasis> as a size in the examples is to keep + things easy to read but probably won't be valid code. You can + use wrappers such as those described in the <ulink + url="../23_containers/howto.html">containers chapter</ulink> to + keep real code readable. + </para> + <para> + The single thing that trips people up the most is the definition + of <emphasis>range</emphasis> used with iterators; the famous + "past-the-end" rule that everybody loves to hate. The + <ulink url="../24_iterators/howto.html#2">iterators + chapter</ulink> of this document has a complete explanation of + this simple rule that seems to cause so much confusion. Once you + get <emphasis>range</emphasis> into your head (it's not that + hard, honest!), then the algorithms are a cakewalk. + </para> +</preface> + +<!-- Chapter 01 : Non Modifying --> + +<!-- Chapter 02 : Mutating --> +<chapter id="manual.algorithms.mutating" xreflabel="Mutating"> + <title>Mutating</title> + + <sect1 id="algorithms.mutating.swap" xreflabel="swap"> + <title><function>swap</function></title> + + <sect2 id="algorithms.swap.specializations" xreflabel="Specializations"> + <title>Specializations</title> + + <para>If you call <code> std::swap(x,y); </code> where x and y are standard + containers, then the call will automatically be replaced by a call to + <code> x.swap(y); </code> instead. + </para> + <para>This allows member functions of each container class to take over, and + containers' swap functions should have O(1) complexity according to + the standard. (And while "should" allows implementations to + behave otherwise and remain compliant, this implementation does in + fact use constant-time swaps.) This should not be surprising, since + for two containers of the same type to swap contents, only some + internal pointers to storage need to be exchanged. + </para> + + </sect2> + </sect1> +</chapter> + +<!-- Chapter 03 : Sorting --> + +</part> diff --git a/libstdc++-v3/doc/xml/manual/allocator.xml b/libstdc++-v3/doc/xml/manual/allocator.xml new file mode 100644 index 00000000000..213d82b7e59 --- /dev/null +++ b/libstdc++-v3/doc/xml/manual/allocator.xml @@ -0,0 +1,659 @@ +<sect1 id="manual.util.memory.allocator" xreflabel="Allocator"> +<?dbhtml filename="allocator.html"?> + +<sect1info> + <keywordset> + <keyword> + ISO C++ + </keyword> + <keyword> + allocator + </keyword> + </keywordset> +</sect1info> + +<title>Allocators</title> + +<para> + Memory management for Standard Library entities is encapsulated in a + class template called <classname>allocator</classname>. The + <classname>allocator</classname> abstraction is used throughout the + library in <classname>string</classname>, container classes, + algorithnms, and parts of iostreams. This class, and base classes of + it, are the superset of available free store (<quote>heap</quote>) + management classes. +</para> + +<sect2 id="allocator.req" xreflabel="allocator.req"> +<title>Requirements</title> + + <para> + The C++ standard only gives a few directives in this area: + </para> + <itemizedlist> + <listitem> + <para> + When you add elements to a container, and the container must + allocate more memory to hold them, the container makes the + request via its <type>Allocator</type> template + parameter, which is usually aliased to + <type>allocator_type</type>. This includes adding chars + to the string class, which acts as a regular STL container in + this respect. + </para> + </listitem> + <listitem> + <para> + The default <type>Allocator</type> argument of every + container-of-T is <classname>allocator<T></classname>. + </para> + </listitem> + <listitem> + <para> + The interface of the <classname>allocator<T></classname> class is + extremely simple. It has about 20 public declarations (nested + typedefs, member functions, etc), but the two which concern us most + are: + </para> + <programlisting> + T* allocate (size_type n, const void* hint = 0); + void deallocate (T* p, size_type n); + </programlisting> + + <para> + The <varname>n</varname> arguments in both those + functions is a <emphasis>count</emphasis> of the number of + <type>T</type>'s to allocate space for, <emphasis>not their + total size</emphasis>. + (This is a simplification; the real signatures use nested typedefs.) + </para> + </listitem> + <listitem> + <para> + The storage is obtained by calling <function>::operator + new</function>, but it is unspecified when or how + often this function is called. The use of the + <varname>hint</varname> is unspecified, but intended as an + aid to locality if an implementation so + desires. <constant>[20.4.1.1]/6</constant> + </para> + </listitem> + </itemizedlist> + + <para> + Complete details cam be found in the C++ standard, look in + <constant>[20.4 Memory]</constant>. + </para> + +</sect2> + +<sect2 id="allocator.design_issues" xreflabel="allocator.design_issues"> +<title>Design Issues</title> + + <para> + The easiest way of fulfilling the requirements is to call + <function>operator new</function> each time a container needs + memory, and to call <function>operator delete</function> each time + the container releases memory. This method may be <ulink + url="http://gcc.gnu.org/ml/libstdc++/2001-05/msg00105.html">slower</ulink> + than caching the allocations and re-using previously-allocated + memory, but has the advantage of working correctly across a wide + variety of hardware and operating systems, including large + clusters. The <classname>__gnu_cxx::new_allocator</classname> + implements the simple operator new and operator delete semantics, + while <classname>__gnu_cxx::malloc_allocator</classname> + implements much the same thing, only with the C language functions + <function>std::malloc</function> and <function>free</function>. + </para> + + <para> + Another approach is to use intelligence within the allocator + class to cache allocations. This extra machinery can take a variety + of forms: a bitmap index, an index into an exponentially increasing + power-of-two-sized buckets, or simpler fixed-size pooling cache. + The cache is shared among all the containers in the program: when + your program's <classname>std::vector<int></classname> gets + cut in half and frees a bunch of its storage, that memory can be + reused by the private + <classname>std::list<WonkyWidget></classname> brought in from + a KDE library that you linked against. And operators + <function>new</function> and <function>delete</function> are not + always called to pass the memory on, either, which is a speed + bonus. Examples of allocators that use these techniques are + <classname>__gnu_cxx::bitmap_allocator</classname>, + <classname>__gnu_cxx::pool_allocator</classname>, and + <classname>__gnu_cxx::__mt_alloc</classname>. + </para> + + <para> + Depending on the implementation techniques used, the underlying + operating system, and compilation environment, scaling caching + allocators can be tricky. In particular, order-of-destruction and + order-of-creation for memory pools may be difficult to pin down + with certainty, which may create problems when used with plugins + or loading and unloading shared objects in memory. As such, using + caching allocators on systems that do not support + <function>abi::__cxa_atexit</function> is not recommended. + </para> + +</sect2> + +<sect2 id="allocator.impl" xreflabel="allocator.impl"> +<title>Implementation</title> + + <sect3> + <title>Interface Design</title> + + <para> + The only allocator interface that + is support is the standard C++ interface. As such, all STL + containers have been adjusted, and all external allocators have + been modified to support this change. + </para> + + <para> + The class <classname>allocator</classname> just has typedef, + constructor, and rebind members. It inherits from one of the + high-speed extension allocators, covered below. Thus, all + allocation and deallocation depends on the base class. + </para> + + <para> + The base class that <classname>allocator</classname> is derived from + may not be user-configurable. +</para> + + </sect3> + + <sect3> + <title>Selecting Default Allocation Policy</title> + + <para> + It's difficult to pick an allocation strategy that will provide + maximum utility, without excessively penalizing some behavior. In + fact, it's difficult just deciding which typical actions to measure + for speed. + </para> + + <para> + Three synthetic benchmarks have been created that provide data + that is used to compare different C++ allocators. These tests are: + </para> + + <orderedlist> + <listitem> + <para> + Insertion. + </para> + <para> + Over multiple iterations, various STL container + objects have elements inserted to some maximum amount. A variety + of allocators are tested. + Test source for <ulink url="http://gcc.gnu.org/viewcvs/trunk/libstdc%2B%2B-v3/testsuite/performance/23_containers/insert/sequence.cc?view=markup">sequence</ulink> + and <ulink url="http://gcc.gnu.org/viewcvs/trunk/libstdc%2B%2B-v3/testsuite/performance/23_containers/insert/associative.cc?view=markup">associative</ulink> + containers. + </para> + + </listitem> + + <listitem> + <para> + Insertion and erasure in a multi-threaded environment. + </para> + <para> + This test shows the ability of the allocator to reclaim memory + on a pre-thread basis, as well as measuring thread contention + for memory resources. + Test source + <ulink url="http://gcc.gnu.org/viewcvs/trunk/libstdc%2B%2B-v3/testsuite/performance/23_containers/insert_erase/associative.cc?view=markup">here</ulink>. + </para> + </listitem> + + <listitem> + <para> + A threaded producer/consumer model. + </para> + <para> + Test source for + <ulink url="http://gcc.gnu.org/viewcvs/trunk/libstdc%2B%2B-v3/testsuite/performance/23_containers/producer_consumer/sequence.cc?view=markup">sequence</ulink> + and + <ulink url="http://gcc.gnu.org/viewcvs/trunk/libstdc%2B%2B-v3/testsuite/performance/23_containers/producer_consumer/associative.cc?view=markup">associative</ulink> + containers. + </para> + </listitem> + </orderedlist> + + <para> + The current default choice for + <classname>allocator</classname> is + <classname>__gnu_cxx::new_allocator</classname>. + </para> + + </sect3> + + <sect3> + <title>Disabling Memory Caching</title> + + <para> + In use, <classname>allocator</classname> may allocate and + deallocate using implementation-specified strategies and + heuristics. Because of this, every call to an allocator object's + <function>allocate</function> member function may not actually + call the global operator new. This situation is also duplicated + for calls to the <function>deallocate</function> member + function. + </para> + + <para> + This can be confusing. + </para> + + <para> + In particular, this can make debugging memory errors more + difficult, especially when using third party tools like valgrind or + debug versions of <function>new</function>. + </para> + + <para> + There are various ways to solve this problem. One would be to use + a custom allocator that just called operators + <function>new</function> and <function>delete</function> + directly, for every allocation. (See + <filename>include/ext/new_allocator.h</filename>, for instance.) + However, that option would involve changing source code to use + the a non-default allocator. Another option is to force the + default allocator to remove caching and pools, and to directly + allocate with every call of <function>allocate</function> and + directly deallocate with every call of + <function>deallocate</function>, regardless of efficiency. As it + turns out, this last option is also available. + </para> + + + <para> + To globally disable memory caching within the library for the + default allocator, merely set + <constant>GLIBCXX_FORCE_NEW</constant> (with any value) in the + system's environment before running the program. If your program + crashes with <constant>GLIBCXX_FORCE_NEW</constant> in the + environment, it likely means that you linked against objects + built against the older library (objects which might still using the + cached allocations...). + </para> + + </sect3> + +</sect2> + +<sect2 id="allocator.using" xreflabel="allocator.using"> +<title>Using a Specific Allocator</title> + + <para> + You can specify different memory management schemes on a + per-container basis, by overriding the default + <type>Allocator</type> template parameter. For example, an easy + (but non-portable) method of specifying that only <function>malloc</function> or <function>free</function> + should be used instead of the default node allocator is: + </para> + <programlisting> + std::list <int, __gnu_cxx::malloc_allocator<int> > malloc_list;</programlisting> + <para> + Likewise, a debugging form of whichever allocator is currently in use: + </para> + <programlisting> + std::deque <int, __gnu_cxx::debug_allocator<std::allocator<int> > > debug_deque; + </programlisting> +</sect2> + +<sect2 id="allocator.custom" xreflabel="allocator.custom"> +<title>Custom Allocators</title> + + <para> + Writing a portable C++ allocator would dictate that the interface + would look much like the one specified for + <classname>allocator</classname>. Additional member functions, but + not subtractions, would be permissible. + </para> + + <para> + Probably the best place to start would be to copy one of the + extension allocators: say a simple one like + <classname>new_allocator</classname>. + </para> + +</sect2> + +<sect2 id="allocator.ext" xreflabel="allocator.ext"> +<title>Extension Allocators</title> + + <para> + Several other allocators are provided as part of this + implementation. The location of the extension allocators and their + names have changed, but in all cases, functionality is + equivalent. Starting with gcc-3.4, all extension allocators are + standard style. Before this point, SGI style was the norm. Because of + this, the number of template arguments also changed. Here's a simple + chart to track the changes. + </para> + + <para> + More details on each of these extension allocators follows. + </para> + <orderedlist> + <listitem> + <para> + <classname>new_allocator</classname> + </para> + <para> + Simply wraps <function>::operator new</function> + and <function>::operator delete</function>. + </para> + </listitem> + <listitem> + <para> + <classname>malloc_allocator</classname> + </para> + <para> + Simply wraps <function>malloc</function> and + <function>free</function>. There is also a hook for an + out-of-memory handler (for + <function>new</function>/<function>delete</function> this is + taken care of elsewhere). + </para> + </listitem> + <listitem> + <para> + <classname>array_allocator</classname> + </para> + <para> + Allows allocations of known and fixed sizes using existing + global or external storage allocated via construction of + <classname>std::tr1::array</classname> objects. By using this + allocator, fixed size containers (including + <classname>std::string</classname>) can be used without + instances calling <function>::operator new</function> and + <function>::operator delete</function>. This capability + allows the use of STL abstractions without runtime + complications or overhead, even in situations such as program + startup. For usage examples, please consult the testsuite. + </para> + </listitem> + <listitem> + <para> + <classname>debug_allocator</classname> + </para> + <para> + A wrapper around an arbitrary allocator A. It passes on + slightly increased size requests to A, and uses the extra + memory to store size information. When a pointer is passed + to <function>deallocate()</function>, the stored size is + checked, and <function>assert()</function> is used to + guarantee they match. + </para> + </listitem> + <listitem> + <para> + <classname>throw_allocator</classname> + </para> + <para> + Includes memory tracking and marking abilities as well as hooks for + throwing exceptinos at configurable intervals (including random, + all, none). + </para> + </listitem> + <listitem> + <para> + <classname>__pool_alloc</classname> + </para> + <para> + A high-performance, single pool allocator. The reusable + memory is shared among identical instantiations of this type. + It calls through <function>::operator new</function> to + obtain new memory when its lists run out. If a client + container requests a block larger than a certain threshold + size, then the pool is bypassed, and the allocate/deallocate + request is passed to <function>::operator new</function> + directly. + </para> + + <para> + Older versions of this class take a boolean template + parameter, called <varname>thr</varname>, and an integer template + parameter, called <varname>inst</varname>. + </para> + + <para> + The <varname>inst</varname> number is used to track additional memory + pools. The point of the number is to allow multiple + instantiations of the classes without changing the semantics at + all. All three of + </para> + + <programlisting> + typedef __pool_alloc<true,0> normal; + typedef __pool_alloc<true,1> private; + typedef __pool_alloc<true,42> also_private; + </programlisting> + <para> + behave exactly the same way. However, the memory pool for each type + (and remember that different instantiations result in different types) + remains separate. + </para> + <para> + The library uses <emphasis>0</emphasis> in all its instantiations. If you + wish to keep separate free lists for a particular purpose, use a + different number. + </para> + <para>The <varname>thr</varname> boolean determines whether the + pool should be manipulated atomically or not. When + <varname>thr</varname> = <constant>true</constant>, the allocator + is is threadsafe, while <varname>thr</varname> = + <constant>false</constant>, and is slightly faster but unsafe for + multiple threads. + </para> + + <para> + For thread-enabled configurations, the pool is locked with a + single big lock. In some situations, this implementation detail + may result in severe performance degredation. + </para> + + <para> + (Note that the GCC thread abstraction layer allows us to provide + safe zero-overhead stubs for the threading routines, if threads + were disabled at configuration time.) + </para> + </listitem> + + <listitem> + <para> + <classname>__mt_alloc</classname> + </para> + <para> + A high-performance fixed-size allocator with + exponentially-increasing allocations. It has its own + documentation, found <ulink + url="../ext/mt_allocator.html">here</ulink>. + </para> + </listitem> + + <listitem> + <para> + <classname>bitmap_allocator</classname> + </para> + <para> + A high-performance allocator that uses a bit-map to keep track + of the used and unused memory locations. It has its own + documentation, found <ulink + url="../ext/ballocator_doc.html">here</ulink>. + </para> + </listitem> + </orderedlist> +</sect2> + + +<bibliography id="allocator.biblio" xreflabel="allocator.biblio"> +<title>Bibliography</title> + + <biblioentry> + <title> + ISO/IEC 14882:1998 Programming languages - C++ + </title> + + <abbrev> + isoc++_1998 + </abbrev> + <pagenums>20.4 Memory</pagenums> + </biblioentry> + + <biblioentry> + <title>The Standard Librarian: What Are Allocators Good + </title> + + <abbrev> + austernm + </abbrev> + + <author> + <firstname>Matt</firstname> + <surname>Austern</surname> + </author> + + <publisher> + <publishername> + C/C++ Users Journal + </publishername> + </publisher> + + <biblioid> + <ulink url="http://www.cuj.com/documents/s=8000/cujcexp1812austern/"> + </ulink> + </biblioid> + </biblioentry> + + <biblioentry> + <title>The Hoard Memory Allocator</title> + + <abbrev> + emeryb + </abbrev> + + <author> + <firstname>Emery</firstname> + <surname>Berger</surname> + </author> + + <biblioid> + <ulink url="http://www.cs.umass.edu/~emery/hoard/"> + </ulink> + </biblioid> + </biblioentry> + + <biblioentry> + <title>Reconsidering Custom Memory Allocation</title> + + <abbrev> + bergerzorn + </abbrev> + + <author> + <firstname>Emery</firstname> + <surname>Berger</surname> + </author> + <author> + <firstname>Ben</firstname> + <surname>Zorn</surname> + </author> + <author> + <firstname>Kathryn</firstname> + <surname>McKinley</surname> + </author> + + <copyright> + <year>2002</year> + <holder>OOPSLA</holder> + </copyright> + + <biblioid> + <ulink url="http://www.cs.umass.edu/~emery/pubs/berger-oopsla2002.pdf"> + </ulink> + </biblioid> + </biblioentry> + + + <biblioentry> + <title>Allocator Types</title> + + <abbrev> + kreftlanger + </abbrev> + + <author> + <firstname>Klaus</firstname> + <surname>Kreft</surname> + </author> + <author> + <firstname>Angelika</firstname> + <surname>Langer</surname> + </author> + + <publisher> + <publishername> + C/C++ Users Journal + </publishername> + </publisher> + + <biblioid> + <ulink url="http://www.langer.camelot.de/Articles/C++Report/Allocators/Allocators.html"> + </ulink> + </biblioid> + </biblioentry> + + <biblioentry> + <title>The C++ Programming Language</title> + + <abbrev> + tcpl + </abbrev> + + <author> + <firstname>Bjarne</firstname> + <surname>Stroustrup</surname> + </author> + <copyright> + <year>2000</year> + <holder></holder> + </copyright> + <pagenums>19.4 Allocators</pagenums> + + <publisher> + <publishername> + Addison Wesley + </publishername> + </publisher> + </biblioentry> + + <biblioentry> + <title>Yalloc: A Recycling C++ Allocator</title> + + <abbrev> + yenf + </abbrev> + + <author> + <firstname>Felix</firstname> + <surname>Yen</surname> + </author> + <copyright> + <year></year> + <holder></holder> + </copyright> + + <biblioid> + <ulink url="http://home.earthlink.net/~brimar/yalloc/"> + </ulink> + </biblioid> + </biblioentry> +</bibliography> + +</sect1> diff --git a/libstdc++-v3/doc/xml/manual/appendix_contributing.xml b/libstdc++-v3/doc/xml/manual/appendix_contributing.xml new file mode 100644 index 00000000000..033bd7dbbef --- /dev/null +++ b/libstdc++-v3/doc/xml/manual/appendix_contributing.xml @@ -0,0 +1,1847 @@ +<?xml version='1.0'?> +<!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" +[ ]> + +<appendix id="appendix.contrib" xreflabel="Contributing"> +<?dbhtml filename="appendix_contributing.html"?> + +<appendixinfo> + <keywordset> + <keyword> + ISO C++ + </keyword> + <keyword> + library + </keyword> + </keywordset> +</appendixinfo> + +<title>Contributing</title> + +<para> + The GNU C++ Library follows an open development model. Active + contributors are assigned maintainer-ship responsibility, and given + write access to the source repository. First time contributors + should follow this procedure: +</para> + +<sect1 id="contrib.list" xreflabel="Contributor Checklist"> + <title>Contributor Checklist</title> + + <sect2 id="list.reading" xreflabel="list.reading"> + <title>Reading</title> + +<itemizedlist> + <listitem><para> Get and read the relevant sections of the C++ language +specification. Copies of the full ISO 14882 standard are available on +line via the ISO mirror site for committee members. Non-members, or +those who have not paid for the privilege of sitting on the committee +and sustained their two meeting commitment for voting rights, may get +a copy of the standard from their respective national standards +organization. In the USA, this national standards organization is ANSI +and their web-site is right + + <ulink url="http://www.ansi.org">here.</ulink> +(And if you've already registered with them, clicking this link will take you to directly to the place where you can +<ulink url="http://webstore.ansi.org/ansidocstore/product.asp?sku=ISO%2FIEC+14882%3A2003">buy the standard on-line.)</ulink> +</para></listitem> + +<listitem><para> The library working group bugs, and known defects, can be obtained here: + <ulink url="http://www.open-std.org/jtc1/sc22/wg21/">http://www.open-std.org/jtc1/sc22/wg21 </ulink> +</para></listitem> + +<listitem><para> The newsgroup dedicated to standardization issues is comp.std.c++: this FAQ for this group is quite useful and can be found <ulink url="http://www.jamesd.demon.co.uk/csc/faq.html"> here </ulink>. +</para></listitem> + + <listitem><para> Peruse the <ulink url="http://www.gnu.org/prep/standards_toc.html">GNU Coding Standards</ulink>, and chuckle when you hit the part about "Using Languages Other Than C." +</para></listitem> + + <listitem><para> Be familiar with the extensions that preceded these general GNU rules. These style issues for libstdc++ can be found in the file C++STYLE, located in the root level of the distribution, or <ulink url="C++STYLE"> here. </ulink> +</para></listitem> + + <listitem><para> And last but certainly not least, read the library-specific information found <ulink url="../documentation.html"> here.</ulink> +</para></listitem> + +</itemizedlist> + + </sect2> + <sect2 id="list.copyright" xreflabel="list.copyright"> + <title>Assignment</title> +<para> +Small changes can be accepted without a copyright assignment form on +file. New code and additions to the library need completed copyright +assignment form on file at the FSF. Note: your employer may be required +to fill out appropriate disclaimer forms as well. +</para> + +<para> + Historically, the libstdc++ assignment form added the following + question: +</para> + +<para> + <quote> + Which Belgian comic book character is better, Tintin or Asterix, and + why? + </quote> +</para> + +<para> +While not strictly necessary, humoring the maintainers and answering +this question would be appreciated. +</para> + +<para> +For more information about getting a copyright assignment, please see +<ulink url="http://www.gnu.org/prep/maintain/html_node/Legal-Matters.html">Legal +Matters</ulink>. +</para> + +<para> +Please contact Benjamin Kosnik at +<email>bkoz+assign@redhat.com</email> if you are confused +about the assignment or have general licensing questions. When +requesting an assignment form from +<email>mailto:assign@gnu.org</email>, please cc the libstdc++ +maintainer above so that progress can be monitored. +</para> + </sect2> + + <sect2 id="list.getting" xreflabel="list.getting"> + <title>Getting Sources</title> + <para> + <ulink url="http://gcc.gnu.org/svnwrite.html">Getting write access + (look for "Write after approval")</ulink> + </para> + </sect2> + + <sect2 id="list.patches" xreflabel="list.patches"> + <title>Submitting Patches</title> + + +<para> +Every patch must have several pieces of information before it can be +properly evaluated. Ideally (and to ensure the fastest possible +response from the maintainers) it would have all of these pieces: +</para> + +<itemizedlist> + + <listitem><para> A description of the bug and how your patch fixes this bug. For + new features a description of the feature and your implementation. </para></listitem> + + <listitem><para> A ChangeLog entry as plain text; see the various ChangeLog files + for format and content. If using you are using emacs as your editor, + simply position the insertion point at the beginning of your change + and hit CX-4a to bring up the appropriate ChangeLog + entry. See--magic! Similar functionality also exists for vi. </para></listitem> + + <listitem><para> A testsuite submission or sample program that will easily and + simply show the existing error or test new functionality. </para></listitem> + + <listitem><para> The patch itself. If you are accessing the SVN repository + use "svn update; svn diff NEW"; else, use "diff -cp OLD NEW" + ... If your version of diff does not support these options, then + get the latest version of GNU diff. The <ulink url="http://gcc.gnu.org/wiki/SvnTricks">SVN Tricks</ulink> wiki page + has information on customising the output of <code>svn diff</code>.</para></listitem> + + <listitem><para> When you have all these pieces, bundle them up in a mail message +and send it to libstdc++@gcc.gnu.org. All patches and related +discussion should be sent to the libstdc++ mailing list. </para></listitem> + +</itemizedlist> + + </sect2> + + </sect1> + + <sect1 id="contrib.coding_style" xreflabel="Coding Style"> + <title>Coding Style</title> + <para> + </para> + <sect2 id="coding_style.bad_identifiers" xreflabel="coding_style.bad"> + <title>Bad Itentifiers</title> +<para> +Identifiers that conflict and should be avoided. +</para> + +<literallayout> + +This is the list of names "reserved to the implementation" that +have been claimed by certain compilers and system headers of interest, +and should not be used in the library. It will grow, of course. +We generally are interested in names that are not all-caps, except +for those like "_T" + +For Solarix: +_B +_C +_L +_N +_P +_S +_U +_X +_E1 +.. +_E24 + +Irix adds: +_A +_G + +MS adds: +_T + +BSD adds: +__used +__unused +__inline +_Complex +__istype +__maskrune +__tolower +__toupper +__wchar_t +__wint_t +_res +_res_ext +__tg_* + +For GCC: + + [Note that this list is out of date. It applies to the old + name-mangling; in G++ 3.0 and higher a different name-mangling is + used. In addition, many of the bugs relating to G++ interpreting + these names as operators have been fixed.] + + The full set of __* identifiers (combined from gcc/cp/lex.c and + gcc/cplus-dem.c) that are either old or new, but are definitely + recognized by the demangler, is: + +__aa +__aad +__ad +__addr +__adv +__aer +__als +__alshift +__amd +__ami +__aml +__amu +__aor +__apl +__array +__ars +__arshift +__as +__bit_and +__bit_ior +__bit_not +__bit_xor +__call +__cl +__cm +__cn +__co +__component +__compound +__cond +__convert +__delete +__dl +__dv +__eq +__er +__ge +__gt +__indirect +__le +__ls +__lt +__max +__md +__method_call +__mi +__min +__minus +__ml +__mm +__mn +__mult +__mx +__ne +__negate +__new +__nop +__nt +__nw +__oo +__op +__or +__pl +__plus +__postdecrement +__postincrement +__pp +__pt +__rf +__rm +__rs +__sz +__trunc_div +__trunc_mod +__truth_andif +__truth_not +__truth_orif +__vc +__vd +__vn + +SGI badnames: +__builtin_alloca +__builtin_fsqrt +__builtin_sqrt +__builtin_fabs +__builtin_dabs +__builtin_cast_f2i +__builtin_cast_i2f +__builtin_cast_d2ll +__builtin_cast_ll2d +__builtin_copy_dhi2i +__builtin_copy_i2dhi +__builtin_copy_dlo2i +__builtin_copy_i2dlo +__add_and_fetch +__sub_and_fetch +__or_and_fetch +__xor_and_fetch +__and_and_fetch +__nand_and_fetch +__mpy_and_fetch +__min_and_fetch +__max_and_fetch +__fetch_and_add +__fetch_and_sub +__fetch_and_or +__fetch_and_xor +__fetch_and_and +__fetch_and_nand +__fetch_and_mpy +__fetch_and_min +__fetch_and_max +__lock_test_and_set +__lock_release +__lock_acquire +__compare_and_swap +__synchronize +__high_multiply +__unix +__sgi +__linux__ +__i386__ +__i486__ +__cplusplus +__embedded_cplusplus +// long double conversion members mangled as __opr +// http://gcc.gnu.org/ml/libstdc++/1999-q4/msg00060.html +_opr +</literallayout> + </sect2> + + <sect2 id="coding_style.example" xreflabel="coding_style.example"> + <title>By Example</title> +<literallayout> + +This library is written to appropriate C++ coding standards. As such, +it is intended to precede the recommendations of the GNU Coding +Standard, which can be referenced in full here: + +http://www.gnu.org/prep/standards/standards.html#Formatting + +The rest of this is also interesting reading, but skip the "Design +Advice" part. + +The GCC coding conventions are here, and are also useful: +http://gcc.gnu.org/codingconventions.html + +In addition, because it doesn't seem to be stated explicitly anywhere +else, there is an 80 column source limit. + +ChangeLog entries for member functions should use the +classname::member function name syntax as follows: + +1999-04-15 Dennis Ritchie <dr@att.com> + + * src/basic_file.cc (__basic_file::open): Fix thinko in + _G_HAVE_IO_FILE_OPEN bits. + +Notable areas of divergence from what may be previous local practice +(particularly for GNU C) include: + +01. Pointers and references + char* p = "flop"; + char& c = *p; + -NOT- + char *p = "flop"; // wrong + char &c = *p; // wrong + + Reason: In C++, definitions are mixed with executable code. Here, + p is being initialized, not *p. This is near-universal + practice among C++ programmers; it is normal for C hackers + to switch spontaneously as they gain experience. + +02. Operator names and parentheses + operator==(type) + -NOT- + operator == (type) // wrong + + Reason: The == is part of the function name. Separating + it makes the declaration look like an expression. + +03. Function names and parentheses + void mangle() + -NOT- + void mangle () // wrong + + Reason: no space before parentheses (except after a control-flow + keyword) is near-universal practice for C++. It identifies the + parentheses as the function-call operator or declarator, as + opposed to an expression or other overloaded use of parentheses. + +04. Template function indentation + template<typename T> + void + template_function(args) + { } + -NOT- + template<class T> + void template_function(args) {}; + + Reason: In class definitions, without indentation whitespace is + needed both above and below the declaration to distinguish + it visually from other members. (Also, re: "typename" + rather than "class".) T often could be int, which is + not a class. ("class", here, is an anachronism.) + +05. Template class indentation + template<typename _CharT, typename _Traits> + class basic_ios : public ios_base + { + public: + // Types: + }; + -NOT- + template<class _CharT, class _Traits> + class basic_ios : public ios_base + { + public: + // Types: + }; + -NOT- + template<class _CharT, class _Traits> + class basic_ios : public ios_base + { + public: + // Types: + }; + +06. Enumerators + enum + { + space = _ISspace, + print = _ISprint, + cntrl = _IScntrl + }; + -NOT- + enum { space = _ISspace, print = _ISprint, cntrl = _IScntrl }; + +07. Member initialization lists + All one line, separate from class name. + + gribble::gribble() + : _M_private_data(0), _M_more_stuff(0), _M_helper(0); + { } + -NOT- + gribble::gribble() : _M_private_data(0), _M_more_stuff(0), _M_helper(0); + { } + +08. Try/Catch blocks + try + { + // + } + catch (...) + { + // + } + -NOT- + try { + // + } catch(...) { + // + } + +09. Member functions declarations and definitions + Keywords such as extern, static, export, explicit, inline, etc + go on the line above the function name. Thus + + virtual int + foo() + -NOT- + virtual int foo() + + Reason: GNU coding conventions dictate return types for functions + are on a separate line than the function name and parameter list + for definitions. For C++, where we have member functions that can + be either inline definitions or declarations, keeping to this + standard allows all member function names for a given class to be + aligned to the same margin, increasing readibility. + + +10. Invocation of member functions with "this->" + For non-uglified names, use this->name to call the function. + + this->sync() + -NOT- + sync() + + Reason: Koenig lookup. + +11. Namespaces + namespace std + { + blah blah blah; + } // namespace std + + -NOT- + + namespace std { + blah blah blah; + } // namespace std + +12. Spacing under protected and private in class declarations: + space above, none below + ie + + public: + int foo; + + -NOT- + public: + + int foo; + +13. Spacing WRT return statements. + no extra spacing before returns, no parenthesis + ie + + } + return __ret; + + -NOT- + } + + return __ret; + + -NOT- + + } + return (__ret); + + +14. Location of global variables. + All global variables of class type, whether in the "user visable" + space (e.g., cin) or the implementation namespace, must be defined + as a character array with the appropriate alignment and then later + re-initialized to the correct value. + + This is due to startup issues on certain platforms, such as AIX. + For more explanation and examples, see src/globals.cc. All such + variables should be contained in that file, for simplicity. + +15. Exception abstractions + Use the exception abstractions found in functexcept.h, which allow + C++ programmers to use this library with -fno-exceptions. (Even if + that is rarely advisable, it's a necessary evil for backwards + compatibility.) + +16. Exception error messages + All start with the name of the function where the exception is + thrown, and then (optional) descriptive text is added. Example: + + __throw_logic_error(__N("basic_string::_S_construct NULL not valid")); + + Reason: The verbose terminate handler prints out exception::what(), + as well as the typeinfo for the thrown exception. As this is the + default terminate handler, by putting location info into the + exception string, a very useful error message is printed out for + uncaught exceptions. So useful, in fact, that non-programmers can + give useful error messages, and programmers can intelligently + speculate what went wrong without even using a debugger. + +17. The doxygen style guide to comments is a separate document, + see index. + +The library currently has a mixture of GNU-C and modern C++ coding +styles. The GNU C usages will be combed out gradually. + +Name patterns: + +For nonstandard names appearing in Standard headers, we are constrained +to use names that begin with underscores. This is called "uglification". +The convention is: + + Local and argument names: __[a-z].* + + Examples: __count __ix __s1 + + Type names and template formal-argument names: _[A-Z][^_].* + + Examples: _Helper _CharT _N + + Member data and function names: _M_.* + + Examples: _M_num_elements _M_initialize () + + Static data members, constants, and enumerations: _S_.* + + Examples: _S_max_elements _S_default_value + +Don't use names in the same scope that differ only in the prefix, +e.g. _S_top and _M_top. See BADNAMES for a list of forbidden names. +(The most tempting of these seem to be and "_T" and "__sz".) + +Names must never have "__" internally; it would confuse name +unmanglers on some targets. Also, never use "__[0-9]", same reason. + +-------------------------- + +[BY EXAMPLE] + +#ifndef _HEADER_ +#define _HEADER_ 1 + +namespace std +{ + class gribble + { + public: + gribble() throw(); + + gribble(const gribble&); + + explicit + gribble(int __howmany); + + gribble& + operator=(const gribble&); + + virtual + ~gribble() throw (); + + // Start with a capital letter, end with a period. + inline void + public_member(const char* __arg) const; + + // In-class function definitions should be restricted to one-liners. + int + one_line() { return 0 } + + int + two_lines(const char* arg) + { return strchr(arg, 'a'); } + + inline int + three_lines(); // inline, but defined below. + + // Note indentation. + template<typename _Formal_argument> + void + public_template() const throw(); + + template<typename _Iterator> + void + other_template(); + + private: + class _Helper; + + int _M_private_data; + int _M_more_stuff; + _Helper* _M_helper; + int _M_private_function(); + + enum _Enum + { + _S_one, + _S_two + }; + + static void + _S_initialize_library(); + }; + +// More-or-less-standard language features described by lack, not presence. +# ifndef _G_NO_LONGLONG + extern long long _G_global_with_a_good_long_name; // avoid globals! +# endif + + // Avoid in-class inline definitions, define separately; + // likewise for member class definitions: + inline int + gribble::public_member() const + { int __local = 0; return __local; } + + class gribble::_Helper + { + int _M_stuff; + + friend class gribble; + }; +} + +// Names beginning with "__": only for arguments and +// local variables; never use "__" in a type name, or +// within any name; never use "__[0-9]". + +#endif /* _HEADER_ */ + + +namespace std +{ + template<typename T> // notice: "typename", not "class", no space + long_return_value_type<with_many, args> + function_name(char* pointer, // "char *pointer" is wrong. + char* argument, + const Reference& ref) + { + // int a_local; /* wrong; see below. */ + if (test) + { + nested code + } + + int a_local = 0; // declare variable at first use. + + // char a, b, *p; /* wrong */ + char a = 'a'; + char b = a + 1; + char* c = "abc"; // each variable goes on its own line, always. + + // except maybe here... + for (unsigned i = 0, mask = 1; mask; ++i, mask <<= 1) { + // ... + } + } + + gribble::gribble() + : _M_private_data(0), _M_more_stuff(0), _M_helper(0); + { } + + inline int + gribble::three_lines() + { + // doesn't fit in one line. + } +} // namespace std + + +</literallayout> + </sect2> + </sect1> + + <sect1 id="contrib.doc_style" xreflabel="Documentation Style"> + <title>Documentation Style</title> + <para> + </para> + <sect2 id="doc_style.doxygen" xreflabel="doc_style.doxygen"> + <title>Doxygen</title> + <sect3 id="doxygen.generating" xreflabel="doxygen.generating"> + <title>Generating the Doxygen Files</title> + +<para>The Makefile rules <code>'make doc-doxygen-html'</code>, + and <code>'make doc-doxygen-man'</code> in the libstdc++ build + directory generate the HTML docs, the and the man pages, + respectively. Prerequisite tools are Bash 2.x, + <ulink url="http://www.doxygen.org/">Doxygen</ulink>, a working version of <code>g++</code> somewhere in the PATH, and + the <ulink url="http://www.gnu.org/software/coreutils/">GNU coreutils</ulink>. + + In addition, to generate the pretty pictures and hierarchy graphs, the + <ulink url= + "http://www.research.att.com/sw/tools/graphviz/download.html">Graphviz</ulink> + package will need to be installed. + (g++ is used to build a program which manipulates man pages. GNU versions + of find, xargs, and possibly sed and grep are used, just because the GNU + versions make things very easy.) +</para> + +<para>Careful observers will see that the Makefile rules simply call a script + from the source tree, <code>run_doxygen</code>, which does the actual work + of running Doxygen and then (most importantly) massaging the output files. + If for some reason you prefer to not go through the Makefile, you can call + this script directly. (Start by passing <code>'--help'</code>.) +</para> + +<para>If you wish to tweak the Doxygen settings, do so by editing + <code>docs/doxygen/user.cfg.in</code>. Notes to v3-hackers are written in + triple-# comments. +</para> + + </sect3> + + <sect3 id="doxygen.markup" xreflabel="doxygen.markup"> + <title>Markup</title> + +<para>In general, libstdc++ files should be formatted according to the GNU + C++ Coding Standard rules found in the file + <ulink url="http://gcc.gnu.org/onlinedocs/libstdc++/17_intro/C++STYLE">C++STYLE</ulink>. + Before any doxygen-specific formatting tweaks are made, please try to make + sure that the initial formatting is sound. +</para> + +<para>Adding Doxygen markup to a file (informally called "doxygenating") is very + simple. The Doxygen manual can be found + <ulink url="http://www.stack.nl/~dimitri/doxygen/download.html#latestman">here</ulink>. + We try to use a very-recent version of Doxygen. +</para> + +<para>For classes, use deque/vector/list and std::pair as examples. For + functions, see their member functions, and the free functions in + <code>stl_algobase.h</code>. Member functions of other container-like + types should read similarly to these member functions. +</para> + +<para>These points accompany the first list in section 3.1 of the Doxygen manual: +</para> +<orderedlist> + <listitem><para>Use the Javadoc style...</para></listitem> + <listitem><para>...not the Qt style. The intermediate *'s are preferred.</para></listitem> + <listitem><para>Use the triple-slash style only for one-line comments (the "brief" mode). + Very recent versions of Doxygen permit full-mode comments in triple-slash + blocks, but the formatting still comes out wonky.</para></listitem> + <listitem><para>This is disgusting. Don't do this.</para></listitem> +</orderedlist> + +<para>Use the @-style of commands, not the !-style. Please be careful about + whitespace in your markup comments. Most of the time it doesn't matter; + doxygen absorbs most whitespace, and both HTML and *roff are agnostic about + whitespace. However, in <pre> blocks and @code/@endcode sections, + spacing can have "interesting" effects. +</para> + +<para>Use either kind of grouping, as appropriate. <code>doxygroups.cc</code> + exists for this purpose. See <code>stl_iterator.h</code> for a good + example of the "other" kind of grouping. +</para> + +<para>Please use markup tags like @p and @a when referring to things such as the + names of function parameters. Use @e for emphasis when necessary. Use @c + to refer to other standard names. (Examples of all these abound in the + present code.) +</para> + + </sect3> + + </sect2> + + <sect2 id="doc_style.docbook" xreflabel="doc_style.docbook"> + <title>Docbook</title> + +<literallayout> + +Which files are important: + +Main page +spine.xml - index to documentation set + +manual/spine.xml - index to manual +manual/*.xml - chapters and sections of the manual + +faq.xml - index to FAQ +api.xml - index to source level / API + +All *.txml files are template xml files, ie otherwise empty files with +the correct structure, suitable for filling in. + + +Cannonical Writing Style + +class template +function template +member function template +(via C++ Templates, Vandevoorde) + +class in namespace std: allocator, not std::allocator + +header file: iostream, not <iostream> + + +Translation + +HTML to XML rough equivalents + +<p> <para> + +<pre> <computeroutput> +<pre> <programlisting> +<pre> <literallayout> + +<ul> <itemizedlist> +<ol> <orderedlist> +<il> <listitem> + +<dl> <variablelist> + + <varlistentry> +<dt> <term> +</dt> </term> +<dd> <listitem> +</dt> </listitem> + </varlistentry> + +<a href <ulink url +<code> <literal> +<code> <programlisting> + +<strong> <emphasis> +<em> <emphasis> +" <quote> + +ctype.h <filename class="headerfile"></filename> + + +build_dir <filename class="directory">path_to_build_dir</filename> + +Finer gradations of <code> + +<classname> <classname>string</classname> + <classname>vector<></classname> + <function>fs.clear()</function> + +<structname> + +<function> <function>clear()</function> + +<type> <type>long long</type> + +<varname> <varname>fs</varname> + +<literal> <literal>-Weffc++</literal> + <literal>rel_ops</literal> + +<constant> <constant>_GNU_SOURCE</constant> + <constant>3.0</constant> + +<filename> + +<command> <command>g++</command> + +<errortext> <errortext>foo Concept </errortext> + + +General structure + +<set> + <book> + </book> + + <book> + <chapter> + </chapter> + </book> + + + <book> + <part> + <chapter> + <section> + </section> + + <sect1> + </sect1> + + <sect1> + <sect2> + </sect2> + </sect1> + </chapter> + + <chapter> + </chapter> + </part> + </book> + + +</set> + +</literallayout> + </sect2> + + </sect1> + + <sect1 id="contrib.design_notes" xreflabel="Design Notes"> + <title>Design Notes</title> + <para> + </para> + +<literallayout> + +The Library +----------- + +This paper is covers two major areas: + + - Features and policies not mentioned in the standard that + the quality of the library implementation depends on, including + extensions and "implementation-defined" features; + + - Plans for required but unimplemented library features and + optimizations to them. + +Overhead +-------- + +The standard defines a large library, much larger than the standard +C library. A naive implementation would suffer substantial overhead +in compile time, executable size, and speed, rendering it unusable +in many (particularly embedded) applications. The alternative demands +care in construction, and some compiler support, but there is no +need for library subsets. + +What are the sources of this overhead? There are four main causes: + + - The library is specified almost entirely as templates, which + with current compilers must be included in-line, resulting in + very slow builds as tens or hundreds of thousands of lines + of function definitions are read for each user source file. + Indeed, the entire SGI STL, as well as the dos Reis valarray, + are provided purely as header files, largely for simplicity in + porting. Iostream/locale is (or will be) as large again. + + - The library is very flexible, specifying a multitude of hooks + where users can insert their own code in place of defaults. + When these hooks are not used, any time and code expended to + support that flexibility is wasted. + + - Templates are often described as causing to "code bloat". In + practice, this refers (when it refers to anything real) to several + independent processes. First, when a class template is manually + instantiated in its entirely, current compilers place the definitions + for all members in a single object file, so that a program linking + to one member gets definitions of all. Second, template functions + which do not actually depend on the template argument are, under + current compilers, generated anew for each instantiation, rather + than being shared with other instantiations. Third, some of the + flexibility mentioned above comes from virtual functions (both in + regular classes and template classes) which current linkers add + to the executable file even when they manifestly cannot be called. + + - The library is specified to use a language feature, exceptions, + which in the current gcc compiler ABI imposes a run time and + code space cost to handle the possibility of exceptions even when + they are not used. Under the new ABI (accessed with -fnew-abi), + there is a space overhead and a small reduction in code efficiency + resulting from lost optimization opportunities associated with + non-local branches associated with exceptions. + +What can be done to eliminate this overhead? A variety of coding +techniques, and compiler, linker and library improvements and +extensions may be used, as covered below. Most are not difficult, +and some are already implemented in varying degrees. + +Overhead: Compilation Time +-------------------------- + +Providing "ready-instantiated" template code in object code archives +allows us to avoid generating and optimizing template instantiations +in each compilation unit which uses them. However, the number of such +instantiations that are useful to provide is limited, and anyway this +is not enough, by itself, to minimize compilation time. In particular, +it does not reduce time spent parsing conforming headers. + +Quicker header parsing will depend on library extensions and compiler +improvements. One approach is some variation on the techniques +previously marketed as "pre-compiled headers", now standardized as +support for the "export" keyword. "Exported" template definitions +can be placed (once) in a "repository" -- really just a library, but +of template definitions rather than object code -- to be drawn upon +at link time when an instantiation is needed, rather than placed in +header files to be parsed along with every compilation unit. + +Until "export" is implemented we can put some of the lengthy template +definitions in #if guards or alternative headers so that users can skip +over the the full definitions when they need only the ready-instantiated +specializations. + +To be precise, this means that certain headers which define +templates which users normally use only for certain arguments +can be instrumented to avoid exposing the template definitions +to the compiler unless a macro is defined. For example, in +<string>, we might have: + + template <class _CharT, ... > class basic_string { + ... // member declarations + }; + ... // operator declarations + + #ifdef _STRICT_ISO_ + # if _G_NO_TEMPLATE_EXPORT + # include <bits/std_locale.h> // headers needed by definitions + # ... + # include <bits/string.tcc> // member and global template definitions. + # endif + #endif + +Users who compile without specifying a strict-ISO-conforming flag +would not see many of the template definitions they now see, and rely +instead on ready-instantiated specializations in the library. This +technique would be useful for the following substantial components: +string, locale/iostreams, valarray. It would *not* be useful or +usable with the following: containers, algorithms, iterators, +allocator. Since these constitute a large (though decreasing) +fraction of the library, the benefit the technique offers is +limited. + +The language specifies the semantics of the "export" keyword, but +the gcc compiler does not yet support it. When it does, problems +with large template inclusions can largely disappear, given some +minor library reorganization, along with the need for the apparatus +described above. + +Overhead: Flexibility Cost +-------------------------- + +The library offers many places where users can specify operations +to be performed by the library in place of defaults. Sometimes +this seems to require that the library use a more-roundabout, and +possibly slower, way to accomplish the default requirements than +would be used otherwise. + +The primary protection against this overhead is thorough compiler +optimization, to crush out layers of inline function interfaces. +Kuck & Associates has demonstrated the practicality of this kind +of optimization. + +The second line of defense against this overhead is explicit +specialization. By defining helper function templates, and writing +specialized code for the default case, overhead can be eliminated +for that case without sacrificing flexibility. This takes full +advantage of any ability of the optimizer to crush out degenerate +code. + +The library specifies many virtual functions which current linkers +load even when they cannot be called. Some minor improvements to the +compiler and to ld would eliminate any such overhead by simply +omitting virtual functions that the complete program does not call. +A prototype of this work has already been done. For targets where +GNU ld is not used, a "pre-linker" could do the same job. + +The main areas in the standard interface where user flexibility +can result in overhead are: + + - Allocators: Containers are specified to use user-definable + allocator types and objects, making tuning for the container + characteristics tricky. + + - Locales: the standard specifies locale objects used to implement + iostream operations, involving many virtual functions which use + streambuf iterators. + + - Algorithms and containers: these may be instantiated on any type, + frequently duplicating code for identical operations. + + - Iostreams and strings: users are permitted to use these on their + own types, and specify the operations the stream must use on these + types. + +Note that these sources of overhead are _avoidable_. The techniques +to avoid them are covered below. + +Code Bloat +---------- + +In the SGI STL, and in some other headers, many of the templates +are defined "inline" -- either explicitly or by their placement +in class definitions -- which should not be inline. This is a +source of code bloat. Matt had remarked that he was relying on +the compiler to recognize what was too big to benefit from inlining, +and generate it out-of-line automatically. However, this also can +result in code bloat except where the linker can eliminate the extra +copies. + +Fixing these cases will require an audit of all inline functions +defined in the library to determine which merit inlining, and moving +the rest out of line. This is an issue mainly in chapters 23, 25, and +27. Of course it can be done incrementally, and we should generally +accept patches that move large functions out of line and into ".tcc" +files, which can later be pulled into a repository. Compiler/linker +improvements to recognize very large inline functions and move them +out-of-line, but shared among compilation units, could make this +work unnecessary. + +Pre-instantiating template specializations currently produces large +amounts of dead code which bloats statically linked programs. The +current state of the static library, libstdc++.a, is intolerable on +this account, and will fuel further confused speculation about a need +for a library "subset". A compiler improvement that treats each +instantiated function as a separate object file, for linking purposes, +would be one solution to this problem. An alternative would be to +split up the manual instantiation files into dozens upon dozens of +little files, each compiled separately, but an abortive attempt at +this was done for <string> and, though it is far from complete, it +is already a nuisance. A better interim solution (just until we have +"export") is badly needed. + +When building a shared library, the current compiler/linker cannot +automatically generate the instantiatiations needed. This creates a +miserable situation; it means any time something is changed in the +library, before a shared library can be built someone must manually +copy the declarations of all templates that are needed by other parts +of the library to an "instantiation" file, and add it to the build +system to be compiled and linked to the library. This process is +readily automated, and should be automated as soon as possible. +Users building their own shared libraries experience identical +frustrations. + +Sharing common aspects of template definitions among instantiations +can radically reduce code bloat. The compiler could help a great +deal here by recognizing when a function depends on nothing about +a template parameter, or only on its size, and giving the resulting +function a link-name "equate" that allows it to be shared with other +instantiations. Implementation code could take advantage of the +capability by factoring out code that does not depend on the template +argument into separate functions to be merged by the compiler. + +Until such a compiler optimization is implemented, much can be done +manually (if tediously) in this direction. One such optimization is +to derive class templates from non-template classes, and move as much +implementation as possible into the base class. Another is to partial- +specialize certain common instantiations, such as vector<T*>, to share +code for instantiations on all types T. While these techniques work, +they are far from the complete solution that a compiler improvement +would afford. + +Overhead: Expensive Language Features +------------------------------------- + +The main "expensive" language feature used in the standard library +is exception support, which requires compiling in cleanup code with +static table data to locate it, and linking in library code to use +the table. For small embedded programs the amount of such library +code and table data is assumed by some to be excessive. Under the +"new" ABI this perception is generally exaggerated, although in some +cases it may actually be excessive. + +To implement a library which does not use exceptions directly is +not difficult given minor compiler support (to "turn off" exceptions +and ignore exception constructs), and results in no great library +maintenance difficulties. To be precise, given "-fno-exceptions", +the compiler should treat "try" blocks as ordinary blocks, and +"catch" blocks as dead code to ignore or eliminate. Compiler +support is not strictly necessary, except in the case of "function +try blocks"; otherwise the following macros almost suffice: + + #define throw(X) + #define try if (true) + #define catch(X) else if (false) + +However, there may be a need to use function try blocks in the +library implementation, and use of macros in this way can make +correct diagnostics impossible. Furthermore, use of this scheme +would require the library to call a function to re-throw exceptions +from a try block. Implementing the above semantics in the compiler +is preferable. + +Given the support above (however implemented) it only remains to +replace code that "throws" with a call to a well-documented "handler" +function in a separate compilation unit which may be replaced by +the user. The main source of exceptions that would be difficult +for users to avoid is memory allocation failures, but users can +define their own memory allocation primitives that never throw. +Otherwise, the complete list of such handlers, and which library +functions may call them, would be needed for users to be able to +implement the necessary substitutes. (Fortunately, they have the +source code.) + +Opportunities +------------- + +The template capabilities of C++ offer enormous opportunities for +optimizing common library operations, well beyond what would be +considered "eliminating overhead". In particular, many operations +done in Glibc with macros that depend on proprietary language +extensions can be implemented in pristine Standard C++. For example, +the chapter 25 algorithms, and even C library functions such as strchr, +can be specialized for the case of static arrays of known (small) size. + +Detailed optimization opportunities are identified below where +the component where they would appear is discussed. Of course new +opportunities will be identified during implementation. + +Unimplemented Required Library Features +--------------------------------------- + +The standard specifies hundreds of components, grouped broadly by +chapter. These are listed in excruciating detail in the CHECKLIST +file. + + 17 general + 18 support + 19 diagnostics + 20 utilities + 21 string + 22 locale + 23 containers + 24 iterators + 25 algorithms + 26 numerics + 27 iostreams + Annex D backward compatibility + +Anyone participating in implementation of the library should obtain +a copy of the standard, ISO 14882. People in the U.S. can obtain an +electronic copy for US$18 from ANSI's web site. Those from other +countries should visit http://www.iso.ch/ to find out the location +of their country's representation in ISO, in order to know who can +sell them a copy. + +The emphasis in the following sections is on unimplemented features +and optimization opportunities. + +Chapter 17 General +------------------- + +Chapter 17 concerns overall library requirements. + +The standard doesn't mention threads. A multi-thread (MT) extension +primarily affects operators new and delete (18), allocator (20), +string (21), locale (22), and iostreams (27). The common underlying +support needed for this is discussed under chapter 20. + +The standard requirements on names from the C headers create a +lot of work, mostly done. Names in the C headers must be visible +in the std:: and sometimes the global namespace; the names in the +two scopes must refer to the same object. More stringent is that +Koenig lookup implies that any types specified as defined in std:: +really are defined in std::. Names optionally implemented as +macros in C cannot be macros in C++. (An overview may be read at +<http://www.cantrip.org/cheaders.html>). The scripts "inclosure" +and "mkcshadow", and the directories shadow/ and cshadow/, are the +beginning of an effort to conform in this area. + +A correct conforming definition of C header names based on underlying +C library headers, and practical linking of conforming namespaced +customer code with third-party C libraries depends ultimately on +an ABI change, allowing namespaced C type names to be mangled into +type names as if they were global, somewhat as C function names in a +namespace, or C++ global variable names, are left unmangled. Perhaps +another "extern" mode, such as 'extern "C-global"' would be an +appropriate place for such type definitions. Such a type would +affect mangling as follows: + + namespace A { + struct X {}; + extern "C-global" { // or maybe just 'extern "C"' + struct Y {}; + }; + } + void f(A::X*); // mangles to f__FPQ21A1X + void f(A::Y*); // mangles to f__FP1Y + +(It may be that this is really the appropriate semantics for regular +'extern "C"', and 'extern "C-global"', as an extension, would not be +necessary.) This would allow functions declared in non-standard C headers +(and thus fixable by neither us nor users) to link properly with functions +declared using C types defined in properly-namespaced headers. The +problem this solves is that C headers (which C++ programmers do persist +in using) frequently forward-declare C struct tags without including +the header where the type is defined, as in + + struct tm; + void munge(tm*); + +Without some compiler accommodation, munge cannot be called by correct +C++ code using a pointer to a correctly-scoped tm* value. + +The current C headers use the preprocessor extension "#include_next", +which the compiler complains about when run "-pedantic". +(Incidentally, it appears that "-fpedantic" is currently ignored, +probably a bug.) The solution in the C compiler is to use +"-isystem" rather than "-I", but unfortunately in g++ this seems +also to wrap the whole header in an 'extern "C"' block, so it's +unusable for C++ headers. The correct solution appears to be to +allow the various special include-directory options, if not given +an argument, to affect subsequent include-directory options additively, +so that if one said + + -pedantic -iprefix $(prefix) \ + -idirafter -ino-pedantic -ino-extern-c -iwithprefix -I g++-v3 \ + -iwithprefix -I g++-v3/ext + +the compiler would search $(prefix)/g++-v3 and not report +pedantic warnings for files found there, but treat files in +$(prefix)/g++-v3/ext pedantically. (The undocumented semantics +of "-isystem" in g++ stink. Can they be rescinded? If not it +must be replaced with something more rationally behaved.) + +All the C headers need the treatment above; in the standard these +headers are mentioned in various chapters. Below, I have only +mentioned those that present interesting implementation issues. + +The components identified as "mostly complete", below, have not been +audited for conformance. In many cases where the library passes +conformance tests we have non-conforming extensions that must be +wrapped in #if guards for "pedantic" use, and in some cases renamed +in a conforming way for continued use in the implementation regardless +of conformance flags. + +The STL portion of the library still depends on a header +stl/bits/stl_config.h full of #ifdef clauses. This apparatus +should be replaced with autoconf/automake machinery. + +The SGI STL defines a type_traits<> template, specialized for +many types in their code including the built-in numeric and +pointer types and some library types, to direct optimizations of +standard functions. The SGI compiler has been extended to generate +specializations of this template automatically for user types, +so that use of STL templates on user types can take advantage of +these optimizations. Specializations for other, non-STL, types +would make more optimizations possible, but extending the gcc +compiler in the same way would be much better. Probably the next +round of standardization will ratify this, but probably with +changes, so it probably should be renamed to place it in the +implementation namespace. + +The SGI STL also defines a large number of extensions visible in +standard headers. (Other extensions that appear in separate headers +have been sequestered in subdirectories ext/ and backward/.) All +these extensions should be moved to other headers where possible, +and in any case wrapped in a namespace (not std!), and (where kept +in a standard header) girded about with macro guards. Some cannot be +moved out of standard headers because they are used to implement +standard features. The canonical method for accommodating these +is to use a protected name, aliased in macro guards to a user-space +name. Unfortunately C++ offers no satisfactory template typedef +mechanism, so very ad-hoc and unsatisfactory aliasing must be used +instead. + +Implementation of a template typedef mechanism should have the highest +priority among possible extensions, on the same level as implementation +of the template "export" feature. + +Chapter 18 Language support +---------------------------- + +Headers: <limits> <new> <typeinfo> <exception> +C headers: <cstddef> <climits> <cfloat> <cstdarg> <csetjmp> + <ctime> <csignal> <cstdlib> (also 21, 25, 26) + +This defines the built-in exceptions, rtti, numeric_limits<>, +operator new and delete. Much of this is provided by the +compiler in its static runtime library. + +Work to do includes defining numeric_limits<> specializations in +separate files for all target architectures. Values for integer types +except for bool and wchar_t are readily obtained from the C header +<limits.h>, but values for the remaining numeric types (bool, wchar_t, +float, double, long double) must be entered manually. This is +largely dog work except for those members whose values are not +easily deduced from available documentation. Also, this involves +some work in target configuration to identify the correct choice of +file to build against and to install. + +The definitions of the various operators new and delete must be +made thread-safe, which depends on a portable exclusion mechanism, +discussed under chapter 20. Of course there is always plenty of +room for improvements to the speed of operators new and delete. + +<cstdarg>, in Glibc, defines some macros that gcc does not allow to +be wrapped into an inline function. Probably this header will demand +attention whenever a new target is chosen. The functions atexit(), +exit(), and abort() in cstdlib have different semantics in C++, so +must be re-implemented for C++. + +Chapter 19 Diagnostics +----------------------- + +Headers: <stdexcept> +C headers: <cassert> <cerrno> + +This defines the standard exception objects, which are "mostly complete". +Cygnus has a version, and now SGI provides a slightly different one. +It makes little difference which we use. + +The C global name "errno", which C allows to be a variable or a macro, +is required in C++ to be a macro. For MT it must typically result in +a function call. + +Chapter 20 Utilities +--------------------- +Headers: <utility> <functional> <memory> +C header: <ctime> (also in 18) + +SGI STL provides "mostly complete" versions of all the components +defined in this chapter. However, the auto_ptr<> implementation +is known to be wrong. Furthermore, the standard definition of it +is known to be unimplementable as written. A minor change to the +standard would fix it, and auto_ptr<> should be adjusted to match. + +Multi-threading affects the allocator implementation, and there must +be configuration/installation choices for different users' MT +requirements. Anyway, users will want to tune allocator options +to support different target conditions, MT or no. + +The primitives used for MT implementation should be exposed, as an +extension, for users' own work. We need cross-CPU "mutex" support, +multi-processor shared-memory atomic integer operations, and single- +processor uninterruptible integer operations, and all three configurable +to be stubbed out for non-MT use, or to use an appropriately-loaded +dynamic library for the actual runtime environment, or statically +compiled in for cases where the target architecture is known. + +Chapter 21 String +------------------ +Headers: <string> +C headers: <cctype> <cwctype> <cstring> <cwchar> (also in 27) + <cstdlib> (also in 18, 25, 26) + +We have "mostly-complete" char_traits<> implementations. Many of the +char_traits<char> operations might be optimized further using existing +proprietary language extensions. + +We have a "mostly-complete" basic_string<> implementation. The work +to manually instantiate char and wchar_t specializations in object +files to improve link-time behavior is extremely unsatisfactory, +literally tripling library-build time with no commensurate improvement +in static program link sizes. It must be redone. (Similar work is +needed for some components in chapters 22 and 27.) + +Other work needed for strings is MT-safety, as discussed under the +chapter 20 heading. + +The standard C type mbstate_t from <cwchar> and used in char_traits<> +must be different in C++ than in C, because in C++ the default constructor +value mbstate_t() must be the "base" or "ground" sequence state. +(According to the likely resolution of a recently raised Core issue, +this may become unnecessary. However, there are other reasons to +use a state type not as limited as whatever the C library provides.) +If we might want to provide conversions from (e.g.) internally- +represented EUC-wide to externally-represented Unicode, or vice- +versa, the mbstate_t we choose will need to be more accommodating +than what might be provided by an underlying C library. + +There remain some basic_string template-member functions which do +not overload properly with their non-template brethren. The infamous +hack akin to what was done in vector<> is needed, to conform to +23.1.1 para 10. The CHECKLIST items for basic_string marked 'X', +or incomplete, are so marked for this reason. + +Replacing the string iterators, which currently are simple character +pointers, with class objects would greatly increase the safety of the +client interface, and also permit a "debug" mode in which range, +ownership, and validity are rigorously checked. The current use of +raw pointers as string iterators is evil. vector<> iterators need the +same treatment. Note that the current implementation freely mixes +pointers and iterators, and that must be fixed before safer iterators +can be introduced. + +Some of the functions in <cstring> are different from the C version. +generally overloaded on const and non-const argument pointers. For +example, in <cstring> strchr is overloaded. The functions isupper +etc. in <cctype> typically implemented as macros in C are functions +in C++, because they are overloaded with others of the same name +defined in <locale>. + +Many of the functions required in <cwctype> and <cwchar> cannot be +implemented using underlying C facilities on intended targets because +such facilities only partly exist. + +Chapter 22 Locale +------------------ +Headers: <locale> +C headers: <clocale> + +We have a "mostly complete" class locale, with the exception of +code for constructing, and handling the names of, named locales. +The ways that locales are named (particularly when categories +(e.g. LC_TIME, LC_COLLATE) are different) varies among all target +environments. This code must be written in various versions and +chosen by configuration parameters. + +Members of many of the facets defined in <locale> are stubs. Generally, +there are two sets of facets: the base class facets (which are supposed +to implement the "C" locale) and the "byname" facets, which are supposed +to read files to determine their behavior. The base ctype<>, collate<>, +and numpunct<> facets are "mostly complete", except that the table of +bitmask values used for "is" operations, and corresponding mask values, +are still defined in libio and just included/linked. (We will need to +implement these tables independently, soon, but should take advantage +of libio where possible.) The num_put<>::put members for integer types +are "mostly complete". + +A complete list of what has and has not been implemented may be +found in CHECKLIST. However, note that the current definition of +codecvt<wchar_t,char,mbstate_t> is wrong. It should simply write +out the raw bytes representing the wide characters, rather than +trying to convert each to a corresponding single "char" value. + +Some of the facets are more important than others. Specifically, +the members of ctype<>, numpunct<>, num_put<>, and num_get<> facets +are used by other library facilities defined in <string>, <istream>, +and <ostream>, and the codecvt<> facet is used by basic_filebuf<> +in <fstream>, so a conforming iostream implementation depends on +these. + +The "long long" type eventually must be supported, but code mentioning +it should be wrapped in #if guards to allow pedantic-mode compiling. + +Performance of num_put<> and num_get<> depend critically on +caching computed values in ios_base objects, and on extensions +to the interface with streambufs. + +Specifically: retrieving a copy of the locale object, extracting +the needed facets, and gathering data from them, for each call to +(e.g.) operator<< would be prohibitively slow. To cache format +data for use by num_put<> and num_get<> we have a _Format_cache<> +object stored in the ios_base::pword() array. This is constructed +and initialized lazily, and is organized purely for utility. It +is discarded when a new locale with different facets is imbued. + +Using only the public interfaces of the iterator arguments to the +facet functions would limit performance by forbidding "vector-style" +character operations. The streambuf iterator optimizations are +described under chapter 24, but facets can also bypass the streambuf +iterators via explicit specializations and operate directly on the +streambufs, and use extended interfaces to get direct access to the +streambuf internal buffer arrays. These extensions are mentioned +under chapter 27. These optimizations are particularly important +for input parsing. + +Unused virtual members of locale facets can be omitted, as mentioned +above, by a smart linker. + +Chapter 23 Containers +---------------------- +Headers: <deque> <list> <queue> <stack> <vector> <map> <set> <bitset> + +All the components in chapter 23 are implemented in the SGI STL. +They are "mostly complete"; they include a large number of +nonconforming extensions which must be wrapped. Some of these +are used internally and must be renamed or duplicated. + +The SGI components are optimized for large-memory environments. For +embedded targets, different criteria might be more appropriate. Users +will want to be able to tune this behavior. We should provide +ways for users to compile the library with different memory usage +characteristics. + +A lot more work is needed on factoring out common code from different +specializations to reduce code size here and in chapter 25. The +easiest fix for this would be a compiler/ABI improvement that allows +the compiler to recognize when a specialization depends only on the +size (or other gross quality) of a template argument, and allow the +linker to share the code with similar specializations. In its +absence, many of the algorithms and containers can be partial- +specialized, at least for the case of pointers, but this only solves +a small part of the problem. Use of a type_traits-style template +allows a few more optimization opportunities, more if the compiler +can generate the specializations automatically. + +As an optimization, containers can specialize on the default allocator +and bypass it, or take advantage of details of its implementation +after it has been improved upon. + +Replacing the vector iterators, which currently are simple element +pointers, with class objects would greatly increase the safety of the +client interface, and also permit a "debug" mode in which range, +ownership, and validity are rigorously checked. The current use of +pointers for iterators is evil. + +As mentioned for chapter 24, the deque iterator is a good example of +an opportunity to implement a "staged" iterator that would benefit +from specializations of some algorithms. + +Chapter 24 Iterators +--------------------- +Headers: <iterator> + +Standard iterators are "mostly complete", with the exception of +the stream iterators, which are not yet templatized on the +stream type. Also, the base class template iterator<> appears +to be wrong, so everything derived from it must also be wrong, +currently. + +The streambuf iterators (currently located in stl/bits/std_iterator.h, +but should be under bits/) can be rewritten to take advantage of +friendship with the streambuf implementation. + +Matt Austern has identified opportunities where certain iterator +types, particularly including streambuf iterators and deque +iterators, have a "two-stage" quality, such that an intermediate +limit can be checked much more quickly than the true limit on +range operations. If identified with a member of iterator_traits, +algorithms may be specialized for this case. Of course the +iterators that have this quality can be identified by specializing +a traits class. + +Many of the algorithms must be specialized for the streambuf +iterators, to take advantage of block-mode operations, in order +to allow iostream/locale operations' performance not to suffer. +It may be that they could be treated as staged iterators and +take advantage of those optimizations. + +Chapter 25 Algorithms +---------------------- +Headers: <algorithm> +C headers: <cstdlib> (also in 18, 21, 26)) + +The algorithms are "mostly complete". As mentioned above, they +are optimized for speed at the expense of code and data size. + +Specializations of many of the algorithms for non-STL types would +give performance improvements, but we must use great care not to +interfere with fragile template overloading semantics for the +standard interfaces. Conventionally the standard function template +interface is an inline which delegates to a non-standard function +which is then overloaded (this is already done in many places in +the library). Particularly appealing opportunities for the sake of +iostream performance are for copy and find applied to streambuf +iterators or (as noted elsewhere) for staged iterators, of which +the streambuf iterators are a good example. + +The bsearch and qsort functions cannot be overloaded properly as +required by the standard because gcc does not yet allow overloading +on the extern-"C"-ness of a function pointer. + +Chapter 26 Numerics +-------------------- +Headers: <complex> <valarray> <numeric> +C headers: <cmath>, <cstdlib> (also 18, 21, 25) + +Numeric components: Gabriel dos Reis's valarray, Drepper's complex, +and the few algorithms from the STL are "mostly done". Of course +optimization opportunities abound for the numerically literate. It +is not clear whether the valarray implementation really conforms +fully, in the assumptions it makes about aliasing (and lack thereof) +in its arguments. + +The C div() and ldiv() functions are interesting, because they are the +only case where a C library function returns a class object by value. +Since the C++ type div_t must be different from the underlying C type +(which is in the wrong namespace) the underlying functions div() and +ldiv() cannot be re-used efficiently. Fortunately they are trivial to +re-implement. + +Chapter 27 Iostreams +--------------------- +Headers: <iosfwd> <streambuf> <ios> <ostream> <istream> <iostream> + <iomanip> <sstream> <fstream> +C headers: <cstdio> <cwchar> (also in 21) + +Iostream is currently in a very incomplete state. <iosfwd>, <iomanip>, +ios_base, and basic_ios<> are "mostly complete". basic_streambuf<> and +basic_ostream<> are well along, but basic_istream<> has had little work +done. The standard stream objects, <sstream> and <fstream> have been +started; basic_filebuf<> "write" functions have been implemented just +enough to do "hello, world". + +Most of the istream and ostream operators << and >> (with the exception +of the op<<(integer) ones) have not been changed to use locale primitives, +sentry objects, or char_traits members. + +All these templates should be manually instantiated for char and +wchar_t in a way that links only used members into user programs. + +Streambuf is fertile ground for optimization extensions. An extended +interface giving iterator access to its internal buffer would be very +useful for other library components. + +Iostream operations (primarily operators << and >>) can take advantage +of the case where user code has not specified a locale, and bypass locale +operations entirely. The current implementation of op<</num_put<>::put, +for the integer types, demonstrates how they can cache encoding details +from the locale on each operation. There is lots more room for +optimization in this area. + +The definition of the relationship between the standard streams +cout et al. and stdout et al. requires something like a "stdiobuf". +The SGI solution of using double-indirection to actually use a +stdio FILE object for buffering is unsatisfactory, because it +interferes with peephole loop optimizations. + +The <sstream> header work has begun. stringbuf can benefit from +friendship with basic_string<> and basic_string<>::_Rep to use +those objects directly as buffers, and avoid allocating and making +copies. + +The basic_filebuf<> template is a complex beast. It is specified to +use the locale facet codecvt<> to translate characters between native +files and the locale character encoding. In general this involves +two buffers, one of "char" representing the file and another of +"char_type", for the stream, with codecvt<> translating. The process +is complicated by the variable-length nature of the translation, and +the need to seek to corresponding places in the two representations. +For the case of basic_filebuf<char>, when no translation is needed, +a single buffer suffices. A specialized filebuf can be used to reduce +code space overhead when no locale has been imbued. Matt Austern's +work at SGI will be useful, perhaps directly as a source of code, or +at least as an example to draw on. + +Filebuf, almost uniquely (cf. operator new), depends heavily on +underlying environmental facilities. In current releases iostream +depends fairly heavily on libio constant definitions, but it should +be made independent. It also depends on operating system primitives +for file operations. There is immense room for optimizations using +(e.g.) mmap for reading. The shadow/ directory wraps, besides the +standard C headers, the libio.h and unistd.h headers, for use mainly +by filebuf. These wrappings have not been completed, though there +is scaffolding in place. + +The encapulation of certain C header <cstdio> names presents an +interesting problem. It is possible to define an inline std::fprintf() +implemented in terms of the 'extern "C"' vfprintf(), but there is no +standard vfscanf() to use to implement std::fscanf(). It appears that +vfscanf but be re-implemented in C++ for targets where no vfscanf +extension has been defined. This is interesting in that it seems +to be the only significant case in the C library where this kind of +rewriting is necessary. (Of course Glibc provides the vfscanf() +extension.) (The functions related to exit() must be rewritten +for other reasons.) + + +Annex D +------- +Headers: <strstream> + +Annex D defines many non-library features, and many minor +modifications to various headers, and a complete header. +It is "mostly done", except that the libstdc++-2 <strstream> +header has not been adopted into the library, or checked to +verify that it matches the draft in those details that were +clarified by the committee. Certainly it must at least be +moved into the std namespace. + +We still need to wrap all the deprecated features in #if guards +so that pedantic compile modes can detect their use. + +Nonstandard Extensions +---------------------- +Headers: <iostream.h> <strstream.h> <hash> <rbtree> + <pthread_alloc> <stdiobuf> (etc.) + +User code has come to depend on a variety of nonstandard components +that we must not omit. Much of this code can be adopted from +libstdc++-v2 or from the SGI STL. This particularly includes +<iostream.h>, <strstream.h>, and various SGI extensions such +as <hash_map.h>. Many of these are already placed in the +subdirectories ext/ and backward/. (Note that it is better to +include them via "<backward/hash_map.h>" or "<ext/hash_map>" than +to search the subdirectory itself via a "-I" directive. +</literallayout> + </sect1> + +</appendix> diff --git a/libstdc++-v3/doc/xml/manual/appendix_free.xml b/libstdc++-v3/doc/xml/manual/appendix_free.xml new file mode 100644 index 00000000000..038d4558e6e --- /dev/null +++ b/libstdc++-v3/doc/xml/manual/appendix_free.xml @@ -0,0 +1,176 @@ +<?xml version='1.0'?> +<!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" +[ ]> + +<appendix id="appendix.free" xreflabel="Free"> +<?dbhtml filename="appendix_free.html"?> + +<appendixinfo> + <keywordset> + <keyword> + ISO C++ + </keyword> + <keyword> + library + </keyword> + </keywordset> +</appendixinfo> + +<title>Free Software Needs Free Documentation</title> + +<para> +The biggest deficiency in free operating systems is not in the +software--it is the lack of good free manuals that we can include in +these systems. Many of our most important programs do not come with +full manuals. Documentation is an essential part of any software +package; when an important free software package does not come with a +free manual, that is a major gap. We have many such gaps today. +</para> + +<para> +Once upon a time, many years ago, I thought I would learn Perl. I got +a copy of a free manual, but I found it hard to read. When I asked +Perl users about alternatives, they told me that there were better +introductory manuals--but those were not free. +</para> + +<para> +Why was this? The authors of the good manuals had written them for +O'Reilly Associates, which published them with restrictive terms--no +copying, no modification, source files not available--which exclude +them from the free software community. +</para> + +<para> +That wasn't the first time this sort of thing has happened, and (to +our community's great loss) it was far from the last. Proprietary +manual publishers have enticed a great many authors to restrict their +manuals since then. Many times I have heard a GNU user eagerly tell +me about a manual that he is writing, with which he expects to help +the GNU project--and then had my hopes dashed, as he proceeded to +explain that he had signed a contract with a publisher that would +restrict it so that we cannot use it. +</para> + +<para> +Given that writing good English is a rare skill among programmers, we +can ill afford to lose manuals this way. +</para> + +<para> + Free documentation, like free software, is a matter of freedom, +not price. The problem with these manuals was not that O'Reilly +Associates charged a price for printed copies--that in itself is fine. +(The Free Software Foundation <ulink url="http://www.gnu.org/doc/doc.html">sells printed copies</ulink> of +free GNU manuals, too.) But GNU manuals are available in source code +form, while these manuals are available only on paper. GNU manuals +come with permission to copy and modify; the Perl manuals do not. +These restrictions are the problems. +</para> + +<para> +The criterion for a free manual is pretty much the same as for free +software: it is a matter of giving all users certain freedoms. +Redistribution (including commercial redistribution) must be +permitted, so that the manual can accompany every copy of the program, +on-line or on paper. Permission for modification is crucial too. +</para> + +<para> +As a general rule, I don't believe that it is essential for people to +have permission to modify all sorts of articles and books. The issues +for writings are not necessarily the same as those for software. For +example, I don't think you or I are obliged to give permission to +modify articles like this one, which describe our actions and our +views. +</para> + +<para> +But there is a particular reason why the freedom to modify is crucial +for documentation for free software. When people exercise their right +to modify the software, and add or change its features, if they are +conscientious they will change the manual too--so they can provide +accurate and usable documentation with the modified program. A manual +which forbids programmers to be conscientious and finish the job, or +more precisely requires them to write a new manual from scratch if +they change the program, does not fill our community's needs. +</para> + +<para> +While a blanket prohibition on modification is unacceptable, some +kinds of limits on the method of modification pose no problem. For +example, requirements to preserve the original author's copyright +notice, the distribution terms, or the list of authors, are ok. It is +also no problem to require modified versions to include notice that +they were modified, even to have entire sections that may not be +deleted or changed, as long as these sections deal with nontechnical +topics. (Some GNU manuals have them.) +</para> + +<para> +These kinds of restrictions are not a problem because, as a practical +matter, they don't stop the conscientious programmer from adapting the +manual to fit the modified program. In other words, they don't block +the free software community from making full use of the manual. +</para> + +<para> +However, it must be possible to modify all the <emphasis>technical</emphasis> +content of the manual, and then distribute the result in all the usual +media, through all the usual channels; otherwise, the restrictions do +block the community, the manual is not free, and so we need another +manual. +</para> + +<para> +Unfortunately, it is often hard to find someone to write another +manual when a proprietary manual exists. The obstacle is that many +users think that a proprietary manual is good enough--so they don't +see the need to write a free manual. They do not see that the free +operating system has a gap that needs filling. +</para> + +<para> +Why do users think that proprietary manuals are good enough? Some +have not considered the issue. I hope this article will do something +to change that. +</para> + +<para> +Other users consider proprietary manuals acceptable for the same +reason so many people consider proprietary software acceptable: they +judge in purely practical terms, not using freedom as a criterion. +These people are entitled to their opinions, but since those opinions +spring from values which do not include freedom, they are no guide for +those of us who do value freedom. +</para> + +<para> +Please spread the word about this issue. We continue to lose manuals +to proprietary publishing. If we spread the word that proprietary +manuals are not sufficient, perhaps the next person who wants to help +GNU by writing documentation will realize, before it is too late, that +he must above all make it free. +</para> + +<para> +We can also encourage commercial publishers to sell free, copylefted +manuals instead of proprietary ones. One way you can help this is to +check the distribution terms of a manual before you buy it, and +prefer copylefted manuals to non-copylefted ones. +</para> +<para> +[Note: We now maintain a <ulink url="http://www.fsf.org/licensing/doc/other-free-books.html">web page +that lists free books available from other publishers</ulink>]. +</para> + +<para>Copyright © 2004, 2005, 2006, 2007 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA</para> + +<para>Verbatim copying and distribution of this entire article are +permitted worldwide, without royalty, in any medium, provided this +notice is preserved.</para> + +<para>Report any problems or suggestions to <email>webmaster@fsf.org</email>.</para> + +</appendix> diff --git a/libstdc++-v3/doc/xml/manual/appendix_porting.xml b/libstdc++-v3/doc/xml/manual/appendix_porting.xml new file mode 100644 index 00000000000..faa24125013 --- /dev/null +++ b/libstdc++-v3/doc/xml/manual/appendix_porting.xml @@ -0,0 +1,47 @@ +<?xml version='1.0'?> +<!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" +[ ]> + +<appendix id="appendix.porting" xreflabel="Porting"> +<?dbhtml filename="appendix_porting.html"?> + +<appendixinfo> + <keywordset> + <keyword> + ISO C++ + </keyword> + <keyword> + library + </keyword> + </keywordset> +</appendixinfo> + +<title>Porting and Maintenance</title> + + <!-- Hacking the Build System --> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" + parse="xml" href="build_hacking.xml"> + </xi:include> + + <!-- Internals: Porting to New Hardware or Operating Systems --> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" + parse="xml" href="internals.xml"> + </xi:include> + + <!-- ABI Policy and Guidelines --> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" + parse="xml" href="abi.xml"> + </xi:include> + + <!-- API Evolution and Deprecation History --> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" + parse="xml" href="evolution.xml"> + </xi:include> + + <!-- Backwards Compatibility --> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" + parse="xml" href="backwards_compatibility.xml"> + </xi:include> + +</appendix> diff --git a/libstdc++-v3/doc/xml/manual/auto_ptr.xml b/libstdc++-v3/doc/xml/manual/auto_ptr.xml new file mode 100644 index 00000000000..a7a0e97bc6c --- /dev/null +++ b/libstdc++-v3/doc/xml/manual/auto_ptr.xml @@ -0,0 +1,133 @@ +<sect1 id="manual.util.memory.auto_ptr" xreflabel="auto_ptr"> +<?dbhtml filename="auto_ptr.html"?> + +<sect1info> + <keywordset> + <keyword> + ISO C++ + </keyword> + <keyword> + auto_ptr + </keyword> + </keywordset> +</sect1info> + +<title>auto_ptr</title> + +<sect2 id="auto_ptr.limitations" xreflabel="auto_ptr.limitations"> +<title>Limitations</title> + + <para>Explaining all of the fun and delicious things that can + happen with misuse of the <classname>auto_ptr</classname> class + template (called <acronym>AP</acronym> here) would take some + time. Suffice it to say that the use of <acronym>AP</acronym> + safely in the presence of copying has some subtleties. + </para> + <para> + The AP class is a really + nifty idea for a smart pointer, but it is one of the dumbest of + all the smart pointers -- and that's fine. + </para> + <para> + AP is not meant to be a supersmart solution to all resource + leaks everywhere. Neither is it meant to be an effective form + of garbage collection (although it can help, a little bit). + And it can <emphasis>not</emphasis>be used for arrays! + </para> + <para> + <acronym>AP</acronym> is meant to prevent nasty leaks in the + presence of exceptions. That's <emphasis>all</emphasis>. This + code is AP-friendly: + </para> + <programlisting> + // Not a recommend naming scheme, but good for web-based FAQs. + typedef std::auto_ptr<MyClass> APMC; + + extern function_taking_MyClass_pointer (MyClass*); + extern some_throwable_function (); + + void func (int data) + { + APMC ap (new MyClass(data)); + + some_throwable_function(); // this will throw an exception + + function_taking_MyClass_pointer (ap.get()); + } + </programlisting> + <para>When an exception gets thrown, the instance of MyClass that's + been created on the heap will be <function>delete</function>'d as the stack is + unwound past <function>func()</function>. + </para> + <para>Changing that code as follows is not <acronym>AP</acronym>-friendly: + </para> + <programlisting> + APMC ap (new MyClass[22]); + </programlisting> + <para>You will get the same problems as you would without the use + of <acronym>AP</acronym>: + </para> + <programlisting> + char* array = new char[10]; // array new... + ... + delete array; // ...but single-object delete + </programlisting> + <para> + AP cannot tell whether the pointer you've passed at creation points + to one or many things. If it points to many things, you are about + to die. AP is trivial to write, however, so you could write your + own <code>auto_array_ptr</code> for that situation (in fact, this has + been done many times; check the mailing lists, Usenet, Boost, etc). + </para> +</sect2> + +<sect2 id="auto_ptr.using" xreflabel="auto_ptr.using"> +<title>Use in Containers</title> + + <para> + </para> + <para>All of the <ulink url="../23_containers/howto.html">containers</ulink> + described in the standard library require their contained types + to have, among other things, a copy constructor like this: + </para> + <programlisting> + struct My_Type + { + My_Type (My_Type const&); + }; + </programlisting> + <para> + Note the const keyword; the object being copied shouldn't change. + The template class <code>auto_ptr</code> (called AP here) does not + meet this requirement. Creating a new AP by copying an existing + one transfers ownership of the pointed-to object, which means that + the AP being copied must change, which in turn means that the + copy ctors of AP do not take const objects. + </para> + <para> + The resulting rule is simple: <emphasis>Never ever use a + container of auto_ptr objects</emphasis>. The standard says that + <quote>undefined</quote> behavior is the result, but it is + guaranteed to be messy. + </para> + <para> + To prevent you from doing this to yourself, the + <ulink url="../19_diagnostics/howto.html#3">concept checks</ulink> built + in to this implementation will issue an error if you try to + compile code like this: + </para> + <programlisting> + #include <vector> + #include <memory> + + void f() + { + std::vector< std::auto_ptr<int> > vec_ap_int; + } + </programlisting> + <para> +Should you try this with the checks enabled, you will see an error. + </para> +</sect2> + +</sect1>
\ No newline at end of file diff --git a/libstdc++-v3/doc/xml/manual/backwards_compatibility.xml b/libstdc++-v3/doc/xml/manual/backwards_compatibility.xml new file mode 100644 index 00000000000..49a0ca813b6 --- /dev/null +++ b/libstdc++-v3/doc/xml/manual/backwards_compatibility.xml @@ -0,0 +1,1315 @@ +<sect1 id="manual.appendix.porting.backwards" xreflabel="backwards"> +<?dbhtml filename="backwards.html"?> + +<sect1info> + <keywordset> + <keyword> + ISO C++ + </keyword> + <keyword> + backwards + </keyword> + </keywordset> +</sect1info> + +<title>Backwards Compatibility</title> + +<sect2 id="backwards.first" xreflabel="backwards.first"> +<title>First</title> + +<para>The first generation GNU C++ library was called libg++. It was a +separate GNU project, although reliably paired with GCC. Rumors imply +that it had a working relationship with at least two kinds of +dinosaur. +</para> + +<para>Some background: libg++ was designed and created when there was no +ISO standard to provide guidance. Classes like linked lists are now +provided for by <classname>list<T></classname> and do not need to be +created by <function>genclass</function>. (For that matter, templates exist +now and are well-supported, whereas genclass (mostly) predates them.) +</para> + +<para>There are other classes in libg++ that are not specified in the +ISO Standard (e.g., statistical analysis). While there are a lot of +really useful things that are used by a lot of people, the Standards +Committee couldn't include everything, and so a lot of those +<quote>obvious</quote> classes didn't get included. +</para> + +<para>Known Issues include many of the limitations of its immediate ancestor.</para> + +<para>Portability notes and known implementation limitations are as follows.</para> + +<sect3> + <title>No <code>ios_base</code></title> + +<para> At least some older implementations don't have <code>std::ios_base</code>, so you should use <code>std::ios::badbit</code>, <code>std::ios::failbit</code> and <code>std::ios::eofbit</code> and <code>std::ios::goodbit</code>. +</para> +</sect3> + +<sect3> +<title>No <code>cout</code> in <code>ostream.h</code>, no <code>cin</code> in <code>istream.h</code></title> + +<para> + In earlier versions of the standard, + <filename class="headerfile">fstream.h</filename>, + <filename class="headerfile">ostream.h</filename> + and <filename class="headerfile">istream.h</filename> + used to define + <code>cout</code>, <code>cin</code> and so on. ISO C++ specifies that one needs to include + <filename class="headerfile">iostream</filename> + explicitly to get the required definitions. + </para> +<para> Some include adjustment may be required.</para> + +<para>This project is no longer maintained or supported, and the sources +archived. For the desperate, +the <ulink url="http://gcc.gnu.org/extensions.html">GCC extensions +page</ulink> describes where to find the last libg++ source. The code is +considered replaced and rewritten. +</para> +</sect3> +</sect2> + +<sect2 id="backwards.second" xreflabel="backwards.second"> +<title>Second</title> + +<para> + The second generation GNU C++ library was called libstdc++, or + libstdc++-v2. It spans the time between libg++ and pre-ISO C++ + standardization and is usually associated with the following GCC + releases: egcs 1.x, gcc 2.95, and gcc 2.96. +</para> + +<para> + The STL portions of this library are based on SGI/HP STL release 3.11. +</para> + +<para> + This project is no longer maintained or supported, and the sources + archived. The code is considered replaced and rewritten. +</para> + +<para> + Portability notes and known implementation limitations are as follows. +</para> + +<sect3> + <title>Namespace <code>std::</code> not supported</title> + + <para> + Some care is required to support C++ compiler and or library + implementation that do not have the standard library in + <code>namespace std</code>. + </para> + + <para> + The following sections list some possible solutions to support compilers + that cannot ignore <code>std::</code>-qualified names. + </para> + + <para> + First, see if the compiler has a flag for this. Namespace + back-portability-issues are generally not a problem for g++ + compilers that do not have libstdc++ in <code>std::</code>, as the + compilers use <code>-fno-honor-std</code> (ignore + <code>std::</code>, <code>:: = std::</code>) by default. That is, + the responsibility for enabling or disabling <code>std::</code> is + on the user; the maintainer does not have to care about it. This + probably applies to some other compilers as well. + </para> + + <para> + Second, experiment with a variety of pre-processor tricks. + </para> + + <para> + By defining <code>std</code> as a macro, fully-qualified namespace + calls become global. Volia. + </para> + +<programlisting> +#ifdef WICKEDLY_OLD_COMPILER +# define std +#endif +</programlisting> + + <para> + Thanks to Juergen Heinzl who posted this solution on gnu.gcc.help. + </para> + + <para> + Another pre-processor based approach is to define a macro + <code>NAMESPACE_STD</code>, which is defined to either + <quote> </quote> or <quote>std</quote> based on a compile-type + test. On GNU systems, this can be done with autotools by means of + an autoconf test (see below) for <code>HAVE_NAMESPACE_STD</code>, + then using that to set a value for the <code>NAMESPACE_STD</code> + macro. At that point, one is able to use + <code>NAMESPACE_STD::string</code>, which will evaluate to + <code>std::string</code> or <code>::string</code> (ie, in the + global namespace on systems that do not put <code>string</code> in + <code>std::</code>). + </para> + +<programlisting> +dnl @synopsis AC_CXX_NAMESPACE_STD +dnl +dnl If the compiler supports namespace std, define +dnl HAVE_NAMESPACE_STD. +dnl +dnl @category Cxx +dnl @author Todd Veldhuizen +dnl @author Luc Maisonobe <luc@spaceroots.org> +dnl @version 2004-02-04 +dnl @license AllPermissive +AC_DEFUN([AC_CXX_NAMESPACE_STD], [ + AC_CACHE_CHECK(if g++ supports namespace std, + ac_cv_cxx_have_std_namespace, + [AC_LANG_SAVE + AC_LANG_CPLUSPLUS + AC_TRY_COMPILE([#include <iostream> + std::istream& is = std::cin;],, + ac_cv_cxx_have_std_namespace=yes, ac_cv_cxx_have_std_namespace=no) + AC_LANG_RESTORE + ]) + if test "$ac_cv_cxx_have_std_namespace" = yes; then + AC_DEFINE(HAVE_NAMESPACE_STD,,[Define if g++ supports namespace std. ]) + fi +]) +</programlisting> +</sect3> + +<sect3> +<title>Illegal iterator usage</title> +<para> + The following illustrate implementation-allowed illegal iterator + use, and then correct use. +</para> + +<itemizedlist> + <listitem> + <para> + you cannot do <code>ostream::operator<<(iterator)</code> + to print the address of the iterator => use + <code>operator<< &*iterator</code> instead + </para> + </listitem> + <listitem> + <para> + you cannot clear an iterator's reference (<code>iterator = + 0</code>) => use <code>iterator = iterator_type();</code> + </para> + </listitem> + <listitem> + <para> + <code>if (iterator)</code> won't work any more => use + <code>if (iterator != iterator_type())</code> + </para> + </listitem> +</itemizedlist> +</sect3> + +<sect3> + <title><code>isspace</code> from <filename class="headerfile">cctype</filename> is a macro + </title> + + <para> + Glibc 2.0.x and 2.1.x define <filename + class="headerfile">ctype.h</filename> functionality as macros + (isspace, isalpha etc.). + </para> + + <para> + This implementations of libstdc++, however, keep these functions + as macros, and so it is not back-portable to use fully qualified + names. For example: + </para> + +<programlisting> +#include <cctype> +int main() { std::isspace('X'); } +</programlisting> + +<para> + Results in something like this: +</para> + +<programlisting> +std:: (__ctype_b[(int) ( ( 'X' ) )] & (unsigned short int) _ISspace ) ; +</programlisting> + +<para> + A solution is to modify a header-file so that the compiler tells + <filename class="headerfile">ctype.h</filename> to define functions + instead of macros: +</para> + +<programlisting> +// This keeps isalnum, et al from being propagated as macros. +#if __linux__ +# define __NO_CTYPE 1 +#endif +</programlisting> + +<para> + Then, include <filename class="headerfile">ctype.h</filename> +</para> + +<para> + Another problem arises if you put a <code>using namespace + std;</code> declaration at the top, and include <filename + class="headerfile">ctype.h</filename>. This will result in + ambiguities between the definitions in the global namespace + (<filename class="headerfile">ctype.h</filename>) and the + definitions in namespace <code>std::</code> + (<code><cctype></code>). +</para> +</sect3> + +<sect3> +<title>No <code>vector::at</code>, <code>deque::at</code>, <code>string::at</code></title> + +<para> + One solution is to add an autoconf-test for this: +</para> + +<programlisting> +AC_MSG_CHECKING(for container::at) +AC_TRY_COMPILE( +[ +#include <vector> +#include <deque> +#include <string> + +using namespace std; +], +[ +deque<int> test_deque(3); +test_deque.at(2); +vector<int> test_vector(2); +test_vector.at(1); +string test_string(<quote>test_string</quote>); +test_string.at(3); +], +[AC_MSG_RESULT(yes) +AC_DEFINE(HAVE_CONTAINER_AT)], +[AC_MSG_RESULT(no)]) +</programlisting> + +<para> + If you are using other (non-GNU) compilers it might be a good idea + to check for <code>string::at</code> separately. +</para> + +</sect3> + +<sect3> +<title>No <code>std::char_traits<char>::eof</code></title> + +<para> + Use some kind of autoconf test, plus this: +</para> + +<programlisting> +#ifdef HAVE_CHAR_TRAITS +#define CPP_EOF std::char_traits<char>::eof() +#else +#define CPP_EOF EOF +#endif +</programlisting> + +</sect3> + +<sect3> +<title>No <code>string::clear</code></title> + +<para> + There are two functions for deleting the contents of a string: + <code>clear</code> and <code>erase</code> (the latter returns the + string). +</para> + +<programlisting> +void +clear() { _M_mutate(0, this->size(), 0); } +</programlisting> + +<programlisting> +basic_string& +erase(size_type __pos = 0, size_type __n = npos) +{ + return this->replace(_M_check(__pos), _M_fold(__pos, __n), + _M_data(), _M_data()); +} +</programlisting> + +<para> + Unfortunately, ut <code>clear</code> is not implemented in this + version, so you should use <code>erase</code> (which is probably + faster than <code>operator=(charT*)</code>). +</para> +</sect3> + +<sect3> +<title> + Removal of <code>ostream::form</code> and <code>istream::scan</code> + extensions +</title> + +<para> + These are no longer supported. Please use stringstreams instead. +</para> +</sect3> + +<sect3> +<title>No <code>basic_stringbuf</code>, <code>basic_stringstream</code></title> + +<para> + Although the ISO standard <code>i/ostringstream</code>-classes are + provided, (<filename class="headerfile">sstream</filename>), for + compatibility with older implementations the pre-ISO + <code>i/ostrstream</code> (<filename + class="headerfile">strstream</filename>) interface is also provided, + with these caveats: +</para> + +<itemizedlist> + <listitem> + <para> + <code>strstream</code> is considered to be deprecated + </para> + </listitem> + <listitem> + <para> + <code>strstream</code> is limited to <code>char</code> + </para> + </listitem> + <listitem> + <para> + with <code>ostringstream</code> you don't have to take care of + terminating the string or freeing its memory + </para> + </listitem> + <listitem> + <para> + <code>istringstream</code> can be re-filled (clear(); + str(input);) + </para> + </listitem> +</itemizedlist> + +<para> + You can then use output-stringstreams like this: +</para> + +<programlisting> +#ifdef HAVE_SSTREAM +# include <sstream> +#else +# include <strstream> +#endif + +#ifdef HAVE_SSTREAM + std::ostringstream oss; +#else + std::ostrstream oss; +#endif + +oss << <quote>Name=</quote> << m_name << <quote>, number=</quote> << m_number << std::endl; +... +#ifndef HAVE_SSTREAM + oss << std::ends; // terminate the char*-string +#endif + +// str() returns char* for ostrstream and a string for ostringstream +// this also causes ostrstream to think that the buffer's memory +// is yours +m_label.set_text(oss.str()); +#ifndef HAVE_SSTREAM + // let the ostrstream take care of freeing the memory + oss.freeze(false); +#endif +</programlisting> + +<para> + Input-stringstreams can be used similarly: +</para> + +<programlisting> +std::string input; +... +#ifdef HAVE_SSTREAM +std::istringstream iss(input); +#else +std::istrstream iss(input.c_str()); +#endif + +int i; +iss >> i; +</programlisting> + +<para> One (the only?) restriction is that an istrstream cannot be re-filled: +</para> + +<programlisting> +std::istringstream iss(numerator); +iss >> m_num; +// this is not possible with istrstream +iss.clear(); +iss.str(denominator); +iss >> m_den; +</programlisting> + +<para> +If you don't care about speed, you can put these conversions in + a template-function: +</para> +<programlisting> +template <class X> +void fromString(const string& input, X& any) +{ +#ifdef HAVE_SSTREAM +std::istringstream iss(input); +#else +std::istrstream iss(input.c_str()); +#endif +X temp; +iss >> temp; +if (iss.fail()) +throw runtime_error(..) +any = temp; +} +</programlisting> + +<para> + Another example of using stringstreams is in <link + linkend="strings.string.shrink">this howto</link>. +</para> + +<para> There is additional information in the libstdc++-v2 info files, in +particular <quote>info iostream</quote>. +</para> +</sect3> + +<sect3> + <title>Little or no wide character support</title> + <para> + Classes <classname>wstring</classname> and + <classname>char_traits<wchar_t></classname> are + not supported. + </para> +</sect3> + +<sect3> + <title>No templatized iostreams</title> + <para> + Classes <classname>wfilebuf</classname> and + <classname>wstringstream</classname> are not supported. + </para> +</sect3> + +<sect3> +<title>Thread safety issues</title> + + <para> + Earlier GCC releases had a somewhat different approach to + threading configuration and proper compilation. Before GCC 3.0, + configuration of the threading model was dictated by compiler + command-line options and macros (both of which were somewhat + thread-implementation and port-specific). There were no + guarantees related to being able to link code compiled with one + set of options and macro setting with another set. + </para> + + <para> + For GCC 3.0, configuration of the threading model used with + libraries and user-code is performed when GCC is configured and + built using the --enable-threads and --disable-threads options. + The ABI is stable for symbol name-mangling and limited functional + compatibility exists between code compiled under different + threading models. + </para> + + <para> + The libstdc++ library has been designed so that it can be used in + multithreaded applications (with libstdc++-v2 this was only true + of the STL parts.) The first problem is finding a + <emphasis>fast</emphasis> method of implementation portable to + all platforms. Due to historical reasons, some of the library is + written against per-CPU-architecture spinlocks and other parts + against the gthr.h abstraction layer which is provided by gcc. A + minor problem that pops up every so often is different + interpretations of what "thread-safe" means for a + library (not a general program). We currently use the <ulink + url="http://www.sgi.com/tech/stl/thread_safety.html">same + definition that SGI</ulink> uses for their STL subset. However, + the exception for read-only containers only applies to the STL + components. This definition is widely-used and something similar + will be used in the next version of the C++ standard library. + </para> + + <para> + Here is a small link farm to threads (no pun) in the mail + archives that discuss the threading problem. Each link is to the + first relevant message in the thread; from there you can use + "Thread Next" to move down the thread. This farm is in + latest-to-oldest order. + </para> + + <itemizedlist> + <listitem> + <para> + Our threading expert Loren gives a breakdown of <ulink + url="http://gcc.gnu.org/ml/libstdc++/2001-10/msg00024.html">the + six situations involving threads</ulink> for the 3.0 + release series. + </para> + </listitem> + <listitem> + <para> + <ulink url="http://gcc.gnu.org/ml/libstdc++/2001-05/msg00384.html"> + This message</ulink> inspired a recent updating of issues with + threading and the SGI STL library. It also contains some + example POSIX-multithreaded STL code. + </para> + </listitem> + </itemizedlist> + + <para> + (A large selection of links to older messages has been removed; + many of the messages from 1999 were lost in a disk crash, and the + few people with access to the backup tapes have been too swamped + with work to restore them. Many of the points have been + superseded anyhow.) + </para> +</sect3> + +</sect2> + +<sect2 id="backwards.third" xreflabel="backwards.third"> +<title>Third</title> + +<para> The third generation GNU C++ library is called libstdc++, or +libstdc++-v3. +</para> + + <para>The subset commonly known as the Standard Template Library + (chapters 23 through 25, mostly) is adapted from the final release + of the SGI STL (version 3.3), with extensive changes. + </para> + + <para>A more formal description of the V3 goals can be found in the + official <ulink url="../17_intro/DESIGN">design document</ulink>. + </para> + +<para>Portability notes and known implementation limitations are as follows.</para> + +<sect3> +<title>Pre-ISO headers moved to backwards or removed</title> + +<para> The pre-ISO C++ headers + (<code>iostream.h</code>, <code>defalloc.h</code> etc.) are + available, unlike previous libstdc++ versions, but inclusion + generates a warning that you are using deprecated headers. +</para> + + <para>This compatibility layer is constructed by including the + standard C++ headers, and injecting any items in + <code>std::</code> into the global namespace. + </para> + <para>For those of you new to ISO C++ (welcome, time travelers!), no, + that isn't a typo. Yes, the headers really have new names. + Marshall Cline's C++ FAQ Lite has a good explanation in <ulink url="http://www.parashift.com/c++-faq-lite/coding-standards.html#faq-27.4">item + [27.4]</ulink>. + </para> + +<para> Some include adjustment may be required. What follows is an +autoconf test that defines <code>PRE_STDCXX_HEADERS</code> when they +exist.</para> + +<programlisting> +# AC_HEADER_PRE_STDCXX +AC_DEFUN([AC_HEADER_PRE_STDCXX], [ + AC_CACHE_CHECK(for pre-ISO C++ include files, + ac_cv_cxx_pre_stdcxx, + [AC_LANG_SAVE + AC_LANG_CPLUSPLUS + ac_save_CXXFLAGS="$CXXFLAGS" + CXXFLAGS="$CXXFLAGS -Wno-deprecated" + + # Omit defalloc.h, as compilation with newer compilers is problematic. + AC_TRY_COMPILE([ + #include <new.h> + #include <iterator.h> + #include <alloc.h> + #include <set.h> + #include <hashtable.h> + #include <hash_set.h> + #include <fstream.h> + #include <tempbuf.h> + #include <istream.h> + #include <bvector.h> + #include <stack.h> + #include <rope.h> + #include <complex.h> + #include <ostream.h> + #include <heap.h> + #include <iostream.h> + #include <function.h> + #include <multimap.h> + #include <pair.h> + #include <stream.h> + #include <iomanip.h> + #include <slist.h> + #include <tree.h> + #include <vector.h> + #include <deque.h> + #include <multiset.h> + #include <list.h> + #include <map.h> + #include <algobase.h> + #include <hash_map.h> + #include <algo.h> + #include <queue.h> + #include <streambuf.h> + ],, + ac_cv_cxx_pre_stdcxx=yes, ac_cv_cxx_pre_stdcxx=no) + CXXFLAGS="$ac_save_CXXFLAGS" + AC_LANG_RESTORE + ]) + if test "$ac_cv_cxx_pre_stdcxx" = yes; then + AC_DEFINE(PRE_STDCXX_HEADERS,,[Define if pre-ISO C++ header files are present. ]) + fi +]) +</programlisting> + +<para>Porting between pre-ISO headers and ISO headers is simple: headers +like <filename class="headerfile">vector.h</filename> can be replaced with <filename class="headerfile">vector</filename> and a using +directive <code>using namespace std;</code> can be put at the global +scope. This should be enough to get this code compiling, assuming the +other usage is correct. +</para> +</sect3> + +<sect3> +<title>Extension headers hash_map, hash_set moved to ext or backwards</title> + + <para>At this time most of the features of the SGI STL extension have been + replaced by standardized libraries. + In particular, the unordered_map and unordered_set containers of TR1 + are suitable replacement for the non-standard hash_map and hash_set + containers in the SGI STL. + </para> +<para> Header files <filename class="headerfile">hash_map</filename> and <filename class="headerfile">hash_set</filename> moved +to <filename class="headerfile">ext/hash_map</filename> and <filename class="headerfile">ext/hash_set</filename>, +respectively. At the same time, all types in these files are enclosed +in <code>namespace __gnu_cxx</code>. Later versions move deprecate +these files, and suggest using TR1's <filename class="headerfile">unordered_map</filename> +and <filename class="headerfile">unordered_set</filename> instead. +</para> + + <para>The extensions are no longer in the global or <code>std</code> + namespaces, instead they are declared in the <code>__gnu_cxx</code> + namespace. For maximum portability, consider defining a namespace + alias to use to talk about extensions, e.g.: + </para> + <programlisting> + #ifdef __GNUC__ + #if __GNUC__ < 3 + #include <hash_map.h> + namespace extension { using ::hash_map; }; // inherit globals + #else + #include <backward/hash_map> + #if __GNUC__ == 3 && __GNUC_MINOR__ == 0 + namespace extension = std; // GCC 3.0 + #else + namespace extension = ::__gnu_cxx; // GCC 3.1 and later + #endif + #endif + #else // ... there are other compilers, right? + namespace extension = std; + #endif + + extension::hash_map<int,int> my_map; + </programlisting> + <para>This is a bit cleaner than defining typedefs for all the + instantiations you might need. + </para> + + +<para>The following autoconf tests check for working HP/SGI hash containers. +</para> + +<programlisting> +# AC_HEADER_EXT_HASH_MAP +AC_DEFUN([AC_HEADER_EXT_HASH_MAP], [ + AC_CACHE_CHECK(for ext/hash_map, + ac_cv_cxx_ext_hash_map, + [AC_LANG_SAVE + AC_LANG_CPLUSPLUS + ac_save_CXXFLAGS="$CXXFLAGS" + CXXFLAGS="$CXXFLAGS -Werror" + AC_TRY_COMPILE([#include <ext/hash_map>], [using __gnu_cxx::hash_map;], + ac_cv_cxx_ext_hash_map=yes, ac_cv_cxx_ext_hash_map=no) + CXXFLAGS="$ac_save_CXXFLAGS" + AC_LANG_RESTORE + ]) + if test "$ac_cv_cxx_ext_hash_map" = yes; then + AC_DEFINE(HAVE_EXT_HASH_MAP,,[Define if ext/hash_map is present. ]) + fi +]) +</programlisting> + +<programlisting> +# AC_HEADER_EXT_HASH_SET +AC_DEFUN([AC_HEADER_EXT_HASH_SET], [ + AC_CACHE_CHECK(for ext/hash_set, + ac_cv_cxx_ext_hash_set, + [AC_LANG_SAVE + AC_LANG_CPLUSPLUS + ac_save_CXXFLAGS="$CXXFLAGS" + CXXFLAGS="$CXXFLAGS -Werror" + AC_TRY_COMPILE([#include <ext/hash_set>], [using __gnu_cxx::hash_set;], + ac_cv_cxx_ext_hash_set=yes, ac_cv_cxx_ext_hash_set=no) + CXXFLAGS="$ac_save_CXXFLAGS" + AC_LANG_RESTORE + ]) + if test "$ac_cv_cxx_ext_hash_set" = yes; then + AC_DEFINE(HAVE_EXT_HASH_SET,,[Define if ext/hash_set is present. ]) + fi +]) +</programlisting> +</sect3> + +<sect3> +<title>No <code>ios::nocreate/ios::noreplace</code>. +</title> + +<para> The existence of <code>ios::nocreate</code> being used for +input-streams has been confirmed, most probably because the author +thought it would be more correct to specify nocreate explicitly. So +it can be left out for input-streams. +</para> + +<para>For output streams, <quote>nocreate</quote> is probably the default, +unless you specify <code>std::ios::trunc</code> ? To be safe, you can +open the file for reading, check if it has been opened, and then +decide whether you want to create/replace or not. To my knowledge, +even older implementations support <code>app</code>, <code>ate</code> +and <code>trunc</code> (except for <code>app</code> ?). +</para> +</sect3> + +<sect3> +<title> +No <code>stream::attach(int fd)</code> +</title> + +<para> + Phil Edwards writes: It was considered and rejected for the ISO + standard. Not all environments use file descriptors. Of those + that do, not all of them use integers to represent them. + </para> + +<para> + For a portable solution (among systems which use + filedescriptors), you need to implement a subclass of + <code>std::streambuf</code> (or + <code>std::basic_streambuf<..></code>) which opens a file + given a descriptor, and then pass an instance of this to the + stream-constructor. + </para> + +<para> + An extension is available that implements this. + <filename class="headerfile">ext/stdio_filebuf.h</filename> 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> + +<para> + For another example of this, refer to + <ulink url="http://www.josuttis.com/cppcode/fdstream.html">fdstream example</ulink> + by Nicolai Josuttis. +</para> +</sect3> + +<sect3> +<title> +Support for C++98 dialect. +</title> + +<para>Check for complete library coverage of the C++1998/2003 standard. +</para> + +<programlisting> +# AC_HEADER_STDCXX_98 +AC_DEFUN([AC_HEADER_STDCXX_98], [ + AC_CACHE_CHECK(for ISO C++ 98 include files, + ac_cv_cxx_stdcxx_98, + [AC_LANG_SAVE + AC_LANG_CPLUSPLUS + AC_TRY_COMPILE([ + #include <cassert> + #include <cctype> + #include <cerrno> + #include <cfloat> + #include <ciso646> + #include <climits> + #include <clocale> + #include <cmath> + #include <csetjmp> + #include <csignal> + #include <cstdarg> + #include <cstddef> + #include <cstdio> + #include <cstdlib> + #include <cstring> + #include <ctime> + + #include <algorithm> + #include <bitset> + #include <complex> + #include <deque> + #include <exception> + #include <fstream> + #include <functional> + #include <iomanip> + #include <ios> + #include <iosfwd> + #include <iostream> + #include <istream> + #include <iterator> + #include <limits> + #include <list> + #include <locale> + #include <map> + #include <memory> + #include <new> + #include <numeric> + #include <ostream> + #include <queue> + #include <set> + #include <sstream> + #include <stack> + #include <stdexcept> + #include <streambuf> + #include <string> + #include <typeinfo> + #include <utility> + #include <valarray> + #include <vector> + ],, + ac_cv_cxx_stdcxx_98=yes, ac_cv_cxx_stdcxx_98=no) + AC_LANG_RESTORE + ]) + if test "$ac_cv_cxx_stdcxx_98" = yes; then + AC_DEFINE(STDCXX_98_HEADERS,,[Define if ISO C++ 1998 header files are present. ]) + fi +]) +</programlisting> +</sect3> + +<sect3> +<title> +Support for C++TR1 dialect. +</title> + +<para>Check for library coverage of the TR1 standard. +</para> + +<programlisting> +# AC_HEADER_STDCXX_TR1 +AC_DEFUN([AC_HEADER_STDCXX_TR1], [ + AC_CACHE_CHECK(for ISO C++ TR1 include files, + ac_cv_cxx_stdcxx_tr1, + [AC_LANG_SAVE + AC_LANG_CPLUSPLUS + AC_TRY_COMPILE([ + #include <tr1/array> + #include <tr1/ccomplex> + #include <tr1/cctype> + #include <tr1/cfenv> + #include <tr1/cfloat> + #include <tr1/cinttypes> + #include <tr1/climits> + #include <tr1/cmath> + #include <tr1/complex> + #include <tr1/cstdarg> + #include <tr1/cstdbool> + #include <tr1/cstdint> + #include <tr1/cstdio> + #include <tr1/cstdlib> + #include <tr1/ctgmath> + #include <tr1/ctime> + #include <tr1/cwchar> + #include <tr1/cwctype> + #include <tr1/functional> + #include <tr1/memory> + #include <tr1/random> + #include <tr1/regex> + #include <tr1/tuple> + #include <tr1/type_traits> + #include <tr1/unordered_set> + #include <tr1/unordered_map> + #include <tr1/utility> + ],, + ac_cv_cxx_stdcxx_tr1=yes, ac_cv_cxx_stdcxx_tr1=no) + AC_LANG_RESTORE + ]) + if test "$ac_cv_cxx_stdcxx_tr1" = yes; then + AC_DEFINE(STDCXX_TR1_HEADERS,,[Define if ISO C++ TR1 header files are present. ]) + fi +]) +</programlisting> + +<para>An alternative is to check just for specific TR1 includes, such as <unordered_map> and <unordered_set>. +</para> + +<programlisting> +# AC_HEADER_TR1_UNORDERED_MAP +AC_DEFUN([AC_HEADER_TR1_UNORDERED_MAP], [ + AC_CACHE_CHECK(for tr1/unordered_map, + ac_cv_cxx_tr1_unordered_map, + [AC_LANG_SAVE + AC_LANG_CPLUSPLUS + AC_TRY_COMPILE([#include <tr1/unordered_map>], [using std::tr1::unordered_map;], + ac_cv_cxx_tr1_unordered_map=yes, ac_cv_cxx_tr1_unordered_map=no) + AC_LANG_RESTORE + ]) + if test "$ac_cv_cxx_tr1_unordered_map" = yes; then + AC_DEFINE(HAVE_TR1_UNORDERED_MAP,,[Define if tr1/unordered_map is present. ]) + fi +]) +</programlisting> + +<programlisting> +# AC_HEADER_TR1_UNORDERED_SET +AC_DEFUN([AC_HEADER_TR1_UNORDERED_SET], [ + AC_CACHE_CHECK(for tr1/unordered_set, + ac_cv_cxx_tr1_unordered_set, + [AC_LANG_SAVE + AC_LANG_CPLUSPLUS + AC_TRY_COMPILE([#include <tr1/unordered_set>], [using std::tr1::unordered_set;], + ac_cv_cxx_tr1_unordered_set=yes, ac_cv_cxx_tr1_unordered_set=no) + AC_LANG_RESTORE + ]) + if test "$ac_cv_cxx_tr1_unordered_set" = yes; then + AC_DEFINE(HAVE_TR1_UNORDERED_SET,,[Define if tr1/unordered_set is present. ]) + fi +]) +</programlisting> +</sect3> + + +<sect3> +<title> +Support for C++0x dialect. +</title> + +<para>Check for baseline language coverage in the compiler for the C++0xstandard. +</para> + +<programlisting> +# AC_COMPILE_STDCXX_OX +AC_DEFUN([AC_COMPILE_STDCXX_0X], [ + AC_CACHE_CHECK(if g++ supports C++0x features without additional flags, + ac_cv_cxx_compile_cxx0x_native, + [AC_LANG_SAVE + AC_LANG_CPLUSPLUS + AC_TRY_COMPILE([ + template <typename T> + struct check + { + static_assert(sizeof(int) <= sizeof(T), "not big enough"); + }; + + typedef check<check<bool>> right_angle_brackets; + + int a; + decltype(a) b; + + typedef check<int> check_type; + check_type c; + check_type&& cr = c;],, + ac_cv_cxx_compile_cxx0x_native=yes, ac_cv_cxx_compile_cxx0x_native=no) + AC_LANG_RESTORE + ]) + + AC_CACHE_CHECK(if g++ supports C++0x features with -std=c++0x, + ac_cv_cxx_compile_cxx0x_cxx, + [AC_LANG_SAVE + AC_LANG_CPLUSPLUS + ac_save_CXXFLAGS="$CXXFLAGS" + CXXFLAGS="$CXXFLAGS -std=c++0x" + AC_TRY_COMPILE([ + template <typename T> + struct check + { + static_assert(sizeof(int) <= sizeof(T), "not big enough"); + }; + + typedef check<check<bool>> right_angle_brackets; + + int a; + decltype(a) b; + + typedef check<int> check_type; + check_type c; + check_type&& cr = c;],, + ac_cv_cxx_compile_cxx0x_cxx=yes, ac_cv_cxx_compile_cxx0x_cxx=no) + CXXFLAGS="$ac_save_CXXFLAGS" + AC_LANG_RESTORE + ]) + + AC_CACHE_CHECK(if g++ supports C++0x features with -std=gnu++0x, + ac_cv_cxx_compile_cxx0x_gxx, + [AC_LANG_SAVE + AC_LANG_CPLUSPLUS + ac_save_CXXFLAGS="$CXXFLAGS" + CXXFLAGS="$CXXFLAGS -std=gnu++0x" + AC_TRY_COMPILE([ + template <typename T> + struct check + { + static_assert(sizeof(int) <= sizeof(T), "not big enough"); + }; + + typedef check<check<bool>> right_angle_brackets; + + int a; + decltype(a) b; + + typedef check<int> check_type; + check_type c; + check_type&& cr = c;],, + ac_cv_cxx_compile_cxx0x_gxx=yes, ac_cv_cxx_compile_cxx0x_gxx=no) + CXXFLAGS="$ac_save_CXXFLAGS" + AC_LANG_RESTORE + ]) + + if test "$ac_cv_cxx_compile_cxx0x_native" = yes || + test "$ac_cv_cxx_compile_cxx0x_cxx" = yes || + test "$ac_cv_cxx_compile_cxx0x_gxx" = yes; then + AC_DEFINE(HAVE_STDCXX_0X,,[Define if g++ supports C++0x features. ]) + fi +]) +</programlisting> + + +<para>Check for library coverage of the C++0xstandard. +</para> + +<programlisting> +# AC_HEADER_STDCXX_0X +AC_DEFUN([AC_HEADER_STDCXX_0X], [ + AC_CACHE_CHECK(for ISO C++ 0x include files, + ac_cv_cxx_stdcxx_0x, + [AC_REQUIRE([AC_COMPILE_STDCXX_0X]) + AC_LANG_SAVE + AC_LANG_CPLUSPLUS + ac_save_CXXFLAGS="$CXXFLAGS" + CXXFLAGS="$CXXFLAGS -std=gnu++0x" + + AC_TRY_COMPILE([ + #include <cassert> + #include <ccomplex> + #include <cctype> + #include <cerrno> + #include <cfenv> + #include <cfloat> + #include <cinttypes> + #include <ciso646> + #include <climits> + #include <clocale> + #include <cmath> + #include <csetjmp> + #include <csignal> + #include <cstdarg> + #include <cstdbool> + #include <cstddef> + #include <cstdint> + #include <cstdio> + #include <cstdlib> + #include <cstring> + #include <ctgmath> + #include <ctime> + #include <cwchar> + #include <cwctype> + + #include <algorithm> + #include <array> + #include <bitset> + #include <complex> + #include <deque> + #include <exception> + #include <fstream> + #include <functional> + #include <iomanip> + #include <ios> + #include <iosfwd> + #include <iostream> + #include <istream> + #include <iterator> + #include <limits> + #include <list> + #include <locale> + #include <map> + #include <memory> + #include <new> + #include <numeric> + #include <ostream> + #include <queue> + #include <random> + #include <regex> + #include <set> + #include <sstream> + #include <stack> + #include <stdexcept> + #include <streambuf> + #include <string> + #include <tuple> + #include <typeinfo> + #include <type_traits> + #include <unordered_map> + #include <unordered_set> + #include <utility> + #include <valarray> + #include <vector> + ],, + ac_cv_cxx_stdcxx_0x=yes, ac_cv_cxx_stdcxx_0x=no) + AC_LANG_RESTORE + CXXFLAGS="$ac_save_CXXFLAGS" + ]) + if test "$ac_cv_cxx_stdcxx_0x" = yes; then + AC_DEFINE(STDCXX_0X_HEADERS,,[Define if ISO C++ 0x header files are present. ]) + fi +]) +</programlisting> + +<para>As is the case for TR1 support, these autoconf macros can be made for a finer-grained, per-header-file check. For <unordered_map> +</para> + +<programlisting> +# AC_HEADER_UNORDERED_MAP +AC_DEFUN([AC_HEADER_UNORDERED_MAP], [ + AC_CACHE_CHECK(for unordered_map, + ac_cv_cxx_unordered_map, + [AC_REQUIRE([AC_COMPILE_STDCXX_0X]) + AC_LANG_SAVE + AC_LANG_CPLUSPLUS + ac_save_CXXFLAGS="$CXXFLAGS" + CXXFLAGS="$CXXFLAGS -std=gnu++0x" + AC_TRY_COMPILE([#include <unordered_map>], [using std::unordered_map;], + ac_cv_cxx_unordered_map=yes, ac_cv_cxx_unordered_map=no) + CXXFLAGS="$ac_save_CXXFLAGS" + AC_LANG_RESTORE + ]) + if test "$ac_cv_cxx_unordered_map" = yes; then + AC_DEFINE(HAVE_UNORDERED_MAP,,[Define if unordered_map is present. ]) + fi +]) +</programlisting> + +<programlisting> +# AC_HEADER_UNORDERED_SET +AC_DEFUN([AC_HEADER_UNORDERED_SET], [ + AC_CACHE_CHECK(for unordered_set, + ac_cv_cxx_unordered_set, + [AC_REQUIRE([AC_COMPILE_STDCXX_0X]) + AC_LANG_SAVE + AC_LANG_CPLUSPLUS + ac_save_CXXFLAGS="$CXXFLAGS" + CXXFLAGS="$CXXFLAGS -std=gnu++0x" + AC_TRY_COMPILE([#include <unordered_set>], [using std::unordered_set;], + ac_cv_cxx_unordered_set=yes, ac_cv_cxx_unordered_set=no) + CXXFLAGS="$ac_save_CXXFLAGS" + AC_LANG_RESTORE + ]) + if test "$ac_cv_cxx_unordered_set" = yes; then + AC_DEFINE(HAVE_UNORDERED_SET,,[Define if unordered_set is present. ]) + fi +]) +</programlisting> +</sect3> + +<sect3> +<title> + Container::iterator_type is not necessarily Container::value_type* +</title> + +<para> + This is a change in behavior from the previous version. Now, most + <type>iterator_type</type> typedefs in container classes are POD + objects, not <type>value_type</type> pointers. +</para> +</sect3> + +</sect2> + +<bibliography id="backwards.biblio" xreflabel="backwards.biblio"> +<title>Bibliography</title> + + <biblioentry> + <abbrev> + kegel41 + </abbrev> + + <title> + Migrating to GCC 4.1 + </title> + + <author> + <firstname>Dan</firstname> + <surname>Kegel</surname> + </author> + + <biblioid> + <ulink url="http://www.kegel.com/gcc/gcc4.html"> + </ulink> + </biblioid> + </biblioentry> + + + <biblioentry> + <abbrev> + kegel41 + </abbrev> + + <title> + Building the Whole Debian Archive with GCC 4.1: A Summary + </title> + + <author> + <firstname>Martin</firstname> + <surname>Michlmayr</surname> + </author> + + <biblioid> + <ulink url="http://lists.debian.org/debian-gcc/2006/03/msg00405.html"> + </ulink> + </biblioid> + </biblioentry> + + + <biblioentry> + <abbrev> + lbl32 + </abbrev> + + <title> + Migration guide for GCC-3.2 + </title> + + <biblioid> + <ulink url="http://annwm.lbl.gov/~leggett/Atlas/gcc-3.2.html"> + </ulink> + </biblioid> + </biblioentry> + +</bibliography> + +</sect1>
\ No newline at end of file diff --git a/libstdc++-v3/doc/xml/manual/bitmap_allocator.xml b/libstdc++-v3/doc/xml/manual/bitmap_allocator.xml new file mode 100644 index 00000000000..e05fc16c56a --- /dev/null +++ b/libstdc++-v3/doc/xml/manual/bitmap_allocator.xml @@ -0,0 +1,559 @@ +<sect1 id="manual.ext.allocator.bitmap" xreflabel="mt allocator"> +<?dbhtml filename="bitmap_allocator.html"?> + +<sect1info> + <keywordset> + <keyword> + ISO C++ + </keyword> + <keyword> + allocator + </keyword> + </keywordset> +</sect1info> + +<title>bitmap_allocator</title> + +<para> +</para> + +<sect2 id="allocator.bitmap.design" xreflabel="allocator.bitmap.design"> +<title>Design</title> + + <para> + As this name suggests, this allocator uses a bit-map to keep track + of the used and unused memory locations for it's book-keeping + purposes. + </para> + <para> + This allocator will make use of 1 single bit to keep track of + whether it has been allocated or not. A bit 1 indicates free, + while 0 indicates allocated. This has been done so that you can + easily check a collection of bits for a free block. This kind of + Bitmapped strategy works best for single object allocations, and + with the STL type parameterized allocators, we do not need to + choose any size for the block which will be represented by a + single bit. This will be the size of the parameter around which + the allocator has been parameterized. Thus, close to optimal + performance will result. Hence, this should be used for node based + containers which call the allocate function with an argument of 1. + </para> + + <para> + The bitmapped allocator's internal pool is exponentially growing. + Meaning that internally, the blocks acquired from the Free List + Store will double every time the bitmapped allocator runs out of + memory. + </para> + + <para> + The macro <literal>__GTHREADS</literal> decides whether to use + Mutex Protection around every allocation/deallocation. The state + of the macro is picked up automatically from the gthr abstraction + layer. + </para> + +</sect2> + +<sect2 id="allocator.bitmap.impl" xreflabel="allocator.bitmap.impl"> +<title>Implementation</title> + +<sect3 id="bitmap.impl.free_list_store" xreflabel="Free List Store"> + <title>Free List Store</title> + + <para> + The Free List Store (referred to as FLS for the remaining part of this + document) is the Global memory pool that is shared by all instances of + the bitmapped allocator instantiated for any type. This maintains a + sorted order of all free memory blocks given back to it by the + bitmapped allocator, and is also responsible for giving memory to the + bitmapped allocator when it asks for more. + </para> + <para> + Internally, there is a Free List threshold which indicates the + Maximum number of free lists that the FLS can hold internally + (cache). Currently, this value is set at 64. So, if there are + more than 64 free lists coming in, then some of them will be given + back to the OS using operator delete so that at any given time the + Free List's size does not exceed 64 entries. This is done because + a Binary Search is used to locate an entry in a free list when a + request for memory comes along. Thus, the run-time complexity of + the search would go up given an increasing size, for 64 entries + however, lg(64) == 6 comparisons are enough to locate the correct + free list if it exists. + </para> + <para> + Suppose the free list size has reached it's threshold, then the + largest block from among those in the list and the new block will + be selected and given back to the OS. This is done because it + reduces external fragmentation, and allows the OS to use the + larger blocks later in an orderly fashion, possibly merging them + later. Also, on some systems, large blocks are obtained via calls + to mmap, so giving them back to free system resources becomes most + important. + </para> + <para> + The function _S_should_i_give decides the policy that determines + whether the current block of memory should be given to the + allocator for the request that it has made. That's because we may + not always have exact fits for the memory size that the allocator + requests. We do this mainly to prevent external fragmentation at + the cost of a little internal fragmentation. Now, the value of + this internal fragmentation has to be decided by this function. I + can see 3 possibilities right now. Please add more as and when you + find better strategies. + </para> + +<orderedlist> + <listitem><para>Equal size check. Return true only when the 2 blocks are of equal +size.</para></listitem> + <listitem><para>Difference Threshold: Return true only when the _block_size is +greater than or equal to the _required_size, and if the _BS is > _RS +by a difference of less than some THRESHOLD value, then return true, +else return false. </para></listitem> + <listitem><para>Percentage Threshold. Return true only when the _block_size is +greater than or equal to the _required_size, and if the _BS is > _RS +by a percentage of less than some THRESHOLD value, then return true, +else return false.</para></listitem> +</orderedlist> + + <para> + Currently, (3) is being used with a value of 36% Maximum wastage per + Super Block. + </para> +</sect3> + +<sect3 id="bitmap.impl.super_block" xreflabel="Super Block"> + <title>Super Block</title> + + <para> + A super block is the block of memory acquired from the FLS from + which the bitmap allocator carves out memory for single objects + and satisfies the user's requests. These super blocks come in + sizes that are powers of 2 and multiples of 32 + (_Bits_Per_Block). Yes both at the same time! That's because the + next super block acquired will be 2 times the previous one, and + also all super blocks have to be multiples of the _Bits_Per_Block + value. + </para> + <para> + How does it interact with the free list store? + </para> + <para> + The super block is contained in the FLS, and the FLS is responsible for + getting / returning Super Bocks to and from the OS using operator new + as defined by the C++ standard. + </para> +</sect3> + +<sect3 id="bitmap.impl.super_block_data" xreflabel="Super Block Data"> + <title>Super Block Data Layout</title> + <para> + Each Super Block will be of some size that is a multiple of the + number of Bits Per Block. Typically, this value is chosen as + Bits_Per_Byte x sizeof(size_t). On an x86 system, this gives the + figure 8 x 4 = 32. Thus, each Super Block will be of size 32 + x Some_Value. This Some_Value is sizeof(value_type). For now, let + it be called 'K'. Thus, finally, Super Block size is 32 x K bytes. + </para> + <para> + This value of 32 has been chosen because each size_t has 32-bits + and Maximum use of these can be made with such a figure. + </para> + <para> + Consider a block of size 64 ints. In memory, it would look like this: + (assume a 32-bit system where, size_t is a 32-bit entity). + </para> + +<table frame='all'> +<title>Bitmap Allocator Memory Map</title> +<tgroup cols='5' align='left' colsep='1' rowsep='1'> +<colspec colname='c1'></colspec> +<colspec colname='c2'></colspec> +<colspec colname='c3'></colspec> +<colspec colname='c4'></colspec> +<colspec colname='c5'></colspec> + +<tbody> + <row> + <entry>268</entry> + <entry>0</entry> + <entry>4294967295</entry> + <entry>4294967295</entry> + <entry>Data -> Space for 64 ints</entry> + </row> +</tbody> +</tgroup> +</table> + + <para> + The first Column(268) represents the size of the Block in bytes as + seen by the Bitmap Allocator. Internally, a global free list is + used to keep track of the free blocks used and given back by the + bitmap allocator. It is this Free List Store that is responsible + for writing and managing this information. Actually the number of + bytes allocated in this case would be: 4 + 4 + (4x2) + (64x4) = + 272 bytes, but the first 4 bytes are an addition by the Free List + Store, so the Bitmap Allocator sees only 268 bytes. These first 4 + bytes about which the bitmapped allocator is not aware hold the + value 268. + </para> + + <para> + What do the remaining values represent?</para> + <para> + The 2nd 4 in the expression is the sizeof(size_t) because the + Bitmapped Allocator maintains a used count for each Super Block, + which is initially set to 0 (as indicated in the diagram). This is + incremented every time a block is removed from this super block + (allocated), and decremented whenever it is given back. So, when + the used count falls to 0, the whole super block will be given + back to the Free List Store. + </para> + <para> + The value 4294967295 represents the integer corresponding to the bit + representation of all bits set: 11111111111111111111111111111111. + </para> + <para> + The 3rd 4x2 is size of the bitmap itself, which is the size of 32-bits + x 2, + which is 8-bytes, or 2 x sizeof(size_t). + </para> +</sect3> + +<sect3 id="bitmap.impl.max_wasted" xreflabel="Max Wasted Percentage"> + <title>Maximum Wasted Percentage</title> + + <para> + This has nothing to do with the algorithm per-se, + only with some vales that must be chosen correctly to ensure that the + allocator performs well in a real word scenario, and maintains a good + balance between the memory consumption and the allocation/deallocation + speed. + </para> + <para> + The formula for calculating the maximum wastage as a percentage: + </para> + + <para> +(32 x k + 1) / (2 x (32 x k + 1 + 32 x c)) x 100. + </para> + + <para> + Where, k => The constant overhead per node. eg. for list, it is + 8 bytes, and for map it is 12 bytes. c => The size of the + base type on which the map/list is instantiated. Thus, suppose the + type1 is int and type2 is double, they are related by the relation + sizeof(double) == 2*sizeof(int). Thus, all types must have this + double size relation for this formula to work properly. + </para> + <para> + Plugging-in: For List: k = 8 and c = 4 (int and double), we get: + 33.376% + </para> + + <para> +For map/multimap: k = 12, and c = 4 (int and double), we get: 37.524% + </para> + <para> + Thus, knowing these values, and based on the sizeof(value_type), we may + create a function that returns the Max_Wastage_Percentage for us to use. + </para> + +</sect3> + +<sect3 id="bitmap.impl.allocate" xreflabel="Allocate"> + <title><function>allocate</function></title> + + <para> + The allocate function is specialized for single object allocation + ONLY. Thus, ONLY if n == 1, will the bitmap_allocator's + specialized algorithm be used. Otherwise, the request is satisfied + directly by calling operator new. + </para> + <para> + Suppose n == 1, then the allocator does the following: + </para> + <orderedlist> + <listitem> + <para> + Checks to see whether a free block exists somewhere in a region + of memory close to the last satisfied request. If so, then that + block is marked as allocated in the bit map and given to the + user. If not, then (2) is executed. + </para> + </listitem> + <listitem> + <para> + Is there a free block anywhere after the current block right + up to the end of the memory that we have? If so, that block is + found, and the same procedure is applied as above, and + returned to the user. If not, then (3) is executed. + </para> + </listitem> + <listitem> + <para> + Is there any block in whatever region of memory that we own + free? This is done by checking + </para> + <itemizedlist> + <listitem> + <para> + The use count for each super block, and if that fails then + </para> + </listitem> + <listitem> + <para> + The individual bit-maps for each super block. + </para> + </listitem> + </itemizedlist> + + <para> + Note: Here we are never touching any of the memory that the + user will be given, and we are confining all memory accesses + to a small region of memory! This helps reduce cache + misses. If this succeeds then we apply the same procedure on + that bit-map as (1), and return that block of memory to the + user. However, if this process fails, then we resort to (4). + </para> + </listitem> + <listitem> + <para> + This process involves Refilling the internal exponentially + growing memory pool. The said effect is achieved by calling + _S_refill_pool which does the following: + </para> + <itemizedlist> + <listitem> + <para> + Gets more memory from the Global Free List of the Required + size. + </para> + </listitem> + <listitem> + <para> + Adjusts the size for the next call to itself. + </para> + </listitem> + <listitem> + <para> + Writes the appropriate headers in the bit-maps. + </para> + </listitem> + <listitem> + <para> + Sets the use count for that super-block just allocated to 0 + (zero). + </para> + </listitem> + <listitem> + <para> + All of the above accounts to maintaining the basic invariant + for the allocator. If the invariant is maintained, we are + sure that all is well. Now, the same process is applied on + the newly acquired free blocks, which are dispatched + accordingly. + </para> + </listitem> + </itemizedlist> + </listitem> +</orderedlist> + +<para> +Thus, you can clearly see that the allocate function is nothing but a +combination of the next-fit and first-fit algorithm optimized ONLY for +single object allocations. +</para> + +</sect3> + +<sect3 id="bitmap.impl.deallocate" xreflabel="Deallocate"> + <title><function>deallocate</function></title> + <para> + The deallocate function again is specialized for single objects ONLY. + For all n belonging to > 1, the operator delete is called without + further ado, and the deallocate function returns. + </para> + <para> + However for n == 1, a series of steps are performed: + </para> + + <orderedlist> + <listitem><para> + We first need to locate that super-block which holds the memory + location given to us by the user. For that purpose, we maintain + a static variable _S_last_dealloc_index, which holds the index + into the vector of block pairs which indicates the index of the + last super-block from which memory was freed. We use this + strategy in the hope that the user will deallocate memory in a + region close to what he/she deallocated the last time around. If + the check for belongs_to succeeds, then we determine the bit-map + for the given pointer, and locate the index into that bit-map, + and mark that bit as free by setting it. + </para></listitem> + <listitem><para> + If the _S_last_dealloc_index does not point to the memory block + that we're looking for, then we do a linear search on the block + stored in the vector of Block Pairs. This vector in code is + called _S_mem_blocks. When the corresponding super-block is + found, we apply the same procedure as we did for (1) to mark the + block as free in the bit-map. + </para></listitem> + </orderedlist> + + <para> + Now, whenever a block is freed, the use count of that particular + super block goes down by 1. When this use count hits 0, we remove + that super block from the list of all valid super blocks stored in + the vector. While doing this, we also make sure that the basic + invariant is maintained by making sure that _S_last_request and + _S_last_dealloc_index point to valid locations within the vector. + </para> +</sect3> + +<sect3 id="bitmap.impl.questions" xreflabel="Questions"> + <title>Questions</title> + + <sect4 id="bitmap.impl.question.1" xreflabel="Question 1"> + <title>1</title> + <para> +Q1) The "Data Layout" section is +cryptic. I have no idea of what you are trying to say. Layout of what? +The free-list? Each bitmap? The Super Block? + </para> + <para> + The layout of a Super Block of a given +size. In the example, a super block of size 32 x 1 is taken. The +general formula for calculating the size of a super block is +32 x sizeof(value_type) x 2^n, where n ranges from 0 to 32 for 32-bit +systems. + </para> + </sect4> + + <sect4 id="bitmap.impl.question.2" xreflabel="Question 2"> + <title>2</title> + <para> + And since I just mentioned the +term `each bitmap', what in the world is meant by it? What does each +bitmap manage? How does it relate to the super block? Is the Super +Block a bitmap as well? + </para> + <para> + Each bitmap is part of a Super Block which is made up of 3 parts + as I have mentioned earlier. Re-iterating, 1. The use count, + 2. The bit-map for that Super Block. 3. The actual memory that + will be eventually given to the user. Each bitmap is a multiple + of 32 in size. If there are 32 x (2^3) blocks of single objects + to be given, there will be '32 x (2^3)' bits present. Each 32 + bits managing the allocated / free status for 32 blocks. Since + each size_t contains 32-bits, one size_t can manage up to 32 + blocks' status. Each bit-map is made up of a number of size_t, + whose exact number for a super-block of a given size I have just + mentioned. + </para> + </sect4> + + <sect4 id="bitmap.impl.question.3" xreflabel="Question 3"> + <title>3</title> + <para> + How do the allocate and deallocate functions work in regard to + bitmaps? + </para> + <para> + The allocate and deallocate functions manipulate the bitmaps and + have nothing to do with the memory that is given to the user. As + I have earlier mentioned, a 1 in the bitmap's bit field + indicates free, while a 0 indicates allocated. This lets us + check 32 bits at a time to check whether there is at lease one + free block in those 32 blocks by testing for equality with + (0). Now, the allocate function will given a memory block find + the corresponding bit in the bitmap, and will reset it (i.e., + make it re-set (0)). And when the deallocate function is called, + it will again set that bit after locating it to indicate that + that particular block corresponding to this bit in the bit-map + is not being used by anyone, and may be used to satisfy future + requests. + </para> + <para> + e.g.: Consider a bit-map of 64-bits as represented below: + 1111111111111111111111111111111111111111111111111111111111111111 + </para> + + <para> + Now, when the first request for allocation of a single object + comes along, the first block in address order is returned. And + since the bit-maps in the reverse order to that of the address + order, the last bit (LSB if the bit-map is considered as a + binary word of 64-bits) is re-set to 0. + </para> + + <para> + The bit-map now looks like this: + 1111111111111111111111111111111111111111111111111111111111111110 + </para> + </sect4> +</sect3> + +<sect3 id="bitmap.impl.locality" xreflabel="Locality"> + <title>Locality</title> + <para> + Another issue would be whether to keep the all bitmaps in a + separate area in memory, or to keep them near the actual blocks + that will be given out or allocated for the client. After some + testing, I've decided to keep these bitmaps close to the actual + blocks. This will help in 2 ways. + </para> + + <orderedlist> + <listitem><para>Constant time access for the bitmap themselves, since no kind of +look up will be needed to find the correct bitmap list or it's +equivalent.</para></listitem> + <listitem><para>And also this would preserve the cache as far as possible.</para></listitem> + </orderedlist> + + <para> + So in effect, this kind of an allocator might prove beneficial from a + purely cache point of view. But this allocator has been made to try and + roll out the defects of the node_allocator, wherein the nodes get + skewed about in memory, if they are not returned in the exact reverse + order or in the same order in which they were allocated. Also, the + new_allocator's book keeping overhead is too much for small objects and + single object allocations, though it preserves the locality of blocks + very well when they are returned back to the allocator. + </para> +</sect3> + +<sect3 id="bitmap.impl.grow_policy" xreflabel="Grow Policy"> + <title>Overhead and Grow Policy</title> + <para> + Expected overhead per block would be 1 bit in memory. Also, once + the address of the free list has been found, the cost for + allocation/deallocation would be negligible, and is supposed to be + constant time. For these very reasons, it is very important to + minimize the linear time costs, which include finding a free list + with a free block while allocating, and finding the corresponding + free list for a block while deallocating. Therefore, I have + decided that the growth of the internal pool for this allocator + will be exponential as compared to linear for + node_allocator. There, linear time works well, because we are + mainly concerned with speed of allocation/deallocation and memory + consumption, whereas here, the allocation/deallocation part does + have some linear/logarithmic complexity components in it. Thus, to + try and minimize them would be a good thing to do at the cost of a + little bit of memory. + </para> + + <para> + Another thing to be noted is the pool size will double every time + the internal pool gets exhausted, and all the free blocks have + been given away. The initial size of the pool would be + sizeof(size_t) x 8 which is the number of bits in an integer, + which can fit exactly in a CPU register. Hence, the term given is + exponential growth of the internal pool. + </para> +</sect3> + +</sect2> + +</sect1>
\ No newline at end of file diff --git a/libstdc++-v3/doc/xml/manual/build.xml b/libstdc++-v3/doc/xml/manual/build.xml new file mode 100644 index 00000000000..d5d78291f43 --- /dev/null +++ b/libstdc++-v3/doc/xml/manual/build.xml @@ -0,0 +1,182 @@ +<sect1 id="manual.intro.setup.build" xreflabel="Building"> +<?dbhtml filename="build.html"?> + +<sect1info> + <keywordset> + <keyword> + ISO C++ + </keyword> + <keyword> + build + </keyword> + </keywordset> +</sect1info> + +<title>Build</title> + +<para> + Because libstdc++ is part of GCC, the primary source for + installation instructions is + <ulink url="http://gcc.gnu.org/install/">the GCC install page</ulink>. + Additional data is given here only where it applies to libstdc++. +</para> + +<sect2 id="build.prereq" xreflabel="build.prereq"> +<title>Prerequisites</title> + <para> + The list of software needed to build the library is kept with the + rest of the compiler, at + <ulink url="http://gcc.gnu.org/install/prerequisites.html"> + http://gcc.gnu.org/install/prerequisites.html</ulink>. The same page + also lists the tools you will need if you wish to modify the source. + </para> + + <para>As of GCC 4.0.1 the minimum version of binutils required to build + libstdc++ is <code>2.15.90.0.1.1</code>. You can get snapshots + (as well as releases) of binutils from + <ulink url="ftp://sources.redhat.com/pub/binutils"> + ftp://sources.redhat.com/pub/binutils</ulink>. + Older releases of libstdc++ do not require such a recent version, + but to take full advantage of useful space-saving features and + bug-fixes you should use a recent binutils if possible. + The configure process will automatically detect and use these + features if the underlying support is present. + </para> + + <para> + Finally, a few system-specific requirements: + </para> + + <variablelist> + <varlistentry> + <term>linux</term> + + <listitem> + <para> + If gcc 3.1.0 or later on is being used on linux, an attempt + will be made to use "C" library functionality necessary for + C++ named locale support. For gcc 3.2.1 and later, this + means that glibc 2.2.5 or later is required and the "C" + library de_DE locale information must be installed. + </para> + + <para> + Note however that the sanity checks involving the de_DE + locale are skipped when an explicit --enable-clocale=gnu + configure option is used: only the basic checks are carried + out, defending against misconfigurations. + </para> + + <para> + If the 'gnu' locale model is being used, the following + locales are used and tested in the libstdc++ testsuites. + The first column is the name of the locale, the second is + the character set it is expected to use. + </para> +<programlisting> +de_DE ISO-8859-1 +de_DE@euro ISO-8859-15 +en_HK ISO-8859-1 +en_PH ISO-8859-1 +en_US ISO-8859-1 +en_US.ISO-8859-1 ISO-8859-1 +en_US.ISO-8859-15 ISO-8859-15 +en_US.UTF-8 UTF-8 +es_ES ISO-8859-1 +es_MX ISO-8859-1 +fr_FR ISO-8859-1 +fr_FR@euro ISO-8859-15 +is_IS UTF-8 +it_IT ISO-8859-1 +ja_JP.eucjp EUC-JP +se_NO.UTF-8 UTF-8 +ta_IN UTF-8 +zh_TW BIG5 +</programlisting> + <para>Failure to have the underlying "C" library locale + information installed will mean that C++ named locales for the + above regions will not work: because of this, the libstdc++ + testsuite will skip the named locale tests. If this isn't an + issue, don't worry about it. If named locales are needed, the + underlying locale information must be installed. Note that + rebuilding libstdc++ after the "C" locales are installed is not + necessary. + </para> + + <para> + To install support for locales, do only one of the following: + </para> + + <itemizedlist> + <listitem> + <para>install all locales</para> + <itemizedlist> + <listitem> + <para>with RedHat Linux: + </para> + <para> <code> export LC_ALL=C </code> + </para> + <para> <code> rpm -e glibc-common --nodeps </code> + </para> + <para> + <code> rpm -i --define "_install_langs all" + glibc-common-2.2.5-34.i386.rpm + </code> + </para> + </listitem> + <listitem> + <para> + Instructions for other operating systems solicited. + </para> + </listitem> + </itemizedlist> + </listitem> + <listitem> + <para>install just the necessary locales</para> + <itemizedlist> + <listitem> + <para>with Debian Linux:</para> + <para> Add the above list, as shown, to the file + <code>/etc/locale.gen</code> </para> + <para> run <code>/usr/sbin/locale-gen</code> </para> + </listitem> + <listitem> + <para>on most Unix-like operating systems:</para> + <para><code> localedef -i de_DE -f ISO-8859-1 de_DE </code></para> + <para>(repeat for each entry in the above list) </para> + </listitem> + <listitem> + <para> + Instructions for other operating systems solicited. + </para> + </listitem> + </itemizedlist> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + </variablelist> + +</sect2> + +<sect2 id="build.configure" xreflabel="build.make"> +<title>Make</title> + <para>If you have never done this before, you should read the basic + <ulink url="http://gcc.gnu.org/install/">GCC Installation + Instructions</ulink> first. Read <emphasis>all of them</emphasis>. + <emphasis>Twice.</emphasis> + </para> + <para>When building libstdc++ you'll have to configure + the entire <emphasis>gccsrcdir</emphasis> directory. The full list of libstdc++ + specific configuration options, not dependent on the specific compiler + release being used, can be found <ulink url="configopts.html">here</ulink>. + </para> + <para>Consider possibly using --enable-languages=c++ to save time by only + building the C++ language parts. + </para> + + <programlisting> + cd <emphasis>gccbuilddir</emphasis> + <emphasis>gccsrcdir</emphasis>/configure --prefix=<emphasis>destdir</emphasis> --other-opts...</programlisting> +</sect2> +</sect1>
\ No newline at end of file diff --git a/libstdc++-v3/doc/xml/manual/build_hacking.xml b/libstdc++-v3/doc/xml/manual/build_hacking.xml new file mode 100644 index 00000000000..b420f4f0706 --- /dev/null +++ b/libstdc++-v3/doc/xml/manual/build_hacking.xml @@ -0,0 +1,354 @@ +<sect1 id="appendix.porting.build_hacking" xreflabel="build_hacking"> +<?dbhtml filename="build_hacking.html"?> + +<sect1info> + <keywordset> + <keyword> + C++ + </keyword> + <keyword> + BUILD_HACKING + </keyword> + <keyword> + version + </keyword> + <keyword> + dynamic + </keyword> + <keyword> + shared + </keyword> + </keywordset> +</sect1info> + +<title>Configure and Build Hacking</title> + +<sect2 id="build_hacking.prereq" xreflabel="build_hacking.prereq"> + <title>Prerequisites</title> + <para> + As noted <ulink + url="http://gcc.gnu.org/install/prerequisites.html">previously</ulink>, + certain other tools are necessary for hacking on files that + control configure (<code>configure.ac</code>, + <code>acinclude.m4</code>) and make + (<code>Makefile.am</code>). These additional tools + (<code>automake</code>, and <code>autoconf</code>) are further + described in detail in their respective manuals. All the libraries + in GCC try to stay in sync with each other in terms of versions of + the auto-tools used, so please try to play nicely with the + neighbors. + </para> +</sect2> + +<sect2 id="build_hacking.map" xreflabel="build_hacking.map"> + <title>Overview: What Comes from Where</title> + + <screen> + <inlinemediaobject> + <imageobject> + <imagedata fileref="../images/confdeps.png"/> + </imageobject> + <textobject> + <phrase>Dependency Graph Configure to Build Files</phrase> + </textobject> + </inlinemediaobject> + </screen> + + <para> + Regenerate all generated files by using the command sequence + <code>"autoreconf"</code> at the top level of the libstdc++ source + directory. The following will also work, but is much more complex: + <code>"aclocal-1.7 && autoconf-2.59 && + autoheader-2.59 && automake-1.7"</code> The version + numbers may be absent entirely or otherwise vary depending on + <ulink url="http://gcc.gnu.org/install/prerequisites.html">the + current requirements</ulink> and your vendor's choice of + installation names. + </para> +</sect2> + +<sect2 id="build_hacking.scripts" xreflabel="build_hacking.scripts"> + <title>Storing Information in non-AC files (like configure.host)</title> + + <para> + Until that glorious day when we can use AC_TRY_LINK with a + cross-compiler, we have to hardcode the results of what the tests + would have shown if they could be run. So we have an inflexible + mess like crossconfig.m4. + </para> + + <para> + Wouldn't it be nice if we could store that information in files + like configure.host, which can be modified without needing to + regenerate anything, and can even be tweaked without really + knowing how the configury all works? Perhaps break the pieces of + crossconfig.m4 out and place them in their appropriate + config/{cpu,os} directory. + </para> + + <para> + Alas, writing macros like + "<code>AC_DEFINE(HAVE_A_NICE_DAY)</code>" can only be done inside + files which are passed through autoconf. Files which are pure + shell script can be source'd at configure time. Files which + contain autoconf macros must be processed with autoconf. We could + still try breaking the pieces out into "config/*/cross.m4" bits, + for instance, but then we would need arguments to aclocal/autoconf + to properly find them all when generating configure. I would + discourage that. +</para> +</sect2> + +<sect2 id="build_hacking.conventions" xreflabel="build_hacking.conventions"> + <title>Coding and Commenting Conventions</title> + + <para> + Most comments should use {octothorpes, shibboleths, hash marks, + pound signs, whatevers} rather than "dnl". Nearly all comments in + configure.ac should. Comments inside macros written in ancilliary + .m4 files should. About the only comments which should + <emphasis>not</emphasis> use #, but use dnl instead, are comments + <emphasis>outside</emphasis> our own macros in the ancilliary + files. The difference is that # comments show up in + <code>configure</code> (which is most helpful for debugging), + while dnl'd lines just vanish. Since the macros in ancilliary + files generate code which appears in odd places, their "outside" + comments tend to not be useful while reading + <code>configure</code>. + </para> + + <para> + Do not use any <code>$target*</code> variables, such as + <code>$target_alias</code>. The single exception is in + configure.ac, for automake+dejagnu's sake. + </para> +</sect2> + +<sect2 id="build_hacking.acinclude" xreflabel="build_hacking.acinclude"> + <title>The acinclude.m4 layout</title> + <para> + The nice thing about acinclude.m4/aclocal.m4 is that macros aren't + actually performed/called/expanded/whatever here, just loaded. So + we can arrange the contents however we like. As of this writing, + acinclude.m4 is arranged as follows: + </para> + <programlisting> + GLIBCXX_CHECK_HOST + GLIBCXX_TOPREL_CONFIGURE + GLIBCXX_CONFIGURE + </programlisting> + <para> + All the major variable "discovery" is done here. CXX, multilibs, + etc. + </para> + <programlisting> + fragments included from elsewhere + </programlisting> + <para> + Right now, "fragments" == "the math/linkage bits". + </para> +<programlisting> + GLIBCXX_CHECK_COMPILER_FEATURES + GLIBCXX_CHECK_LINKER_FEATURES + GLIBCXX_CHECK_WCHAR_T_SUPPORT +</programlisting> +<para> + Next come extra compiler/linker feature tests. Wide character + support was placed here because I couldn't think of another place + for it. It will probably get broken apart like the math tests, + because we're still disabling wchars on systems which could actually + support them. +</para> +<programlisting> + GLIBCXX_CHECK_SETRLIMIT_ancilliary + GLIBCXX_CHECK_SETRLIMIT + GLIBCXX_CHECK_S_ISREG_OR_S_IFREG + GLIBCXX_CHECK_POLL + GLIBCXX_CHECK_WRITEV + + GLIBCXX_CONFIGURE_TESTSUITE +</programlisting> +<para> + Feature tests which only get used in one place. Here, things used + only in the testsuite, plus a couple bits used in the guts of I/O. +</para> +<programlisting> + GLIBCXX_EXPORT_INCLUDES + GLIBCXX_EXPORT_FLAGS + GLIBCXX_EXPORT_INSTALL_INFO +</programlisting> +<para> + Installation variables, multilibs, working with the rest of the + compiler. Many of the critical variables used in the makefiles are + set here. +</para> +<programlisting> + GLIBGCC_ENABLE + GLIBCXX_ENABLE_C99 + GLIBCXX_ENABLE_CHEADERS + GLIBCXX_ENABLE_CLOCALE + GLIBCXX_ENABLE_CONCEPT_CHECKS + GLIBCXX_ENABLE_CSTDIO + GLIBCXX_ENABLE_CXX_FLAGS + GLIBCXX_ENABLE_C_MBCHAR + GLIBCXX_ENABLE_DEBUG + GLIBCXX_ENABLE_DEBUG_FLAGS + GLIBCXX_ENABLE_LONG_LONG + GLIBCXX_ENABLE_PCH + GLIBCXX_ENABLE_SJLJ_EXCEPTIONS + GLIBCXX_ENABLE_SYMVERS + GLIBCXX_ENABLE_THREADS +</programlisting> +<para> + All the features which can be controlled with enable/disable + configure options. Note how they're alphabetized now? Keep them + like that. :-) +</para> +<programlisting> + AC_LC_MESSAGES + libtool bits +</programlisting> +<para> + Things which we don't seem to use directly, but just has to be + present otherwise stuff magically goes wonky. +</para> + +</sect2> + +<sect2 id="build_hacking.enable" xreflabel="build_hacking.enable"> + <title><constant>GLIBCXX_ENABLE</constant>, the <literal>--enable</literal> maker</title> + + <para> + All the GLIBCXX_ENABLE_FOO macros use a common helper, + GLIBCXX_ENABLE. (You don't have to use it, but it's easy.) The + helper does two things for us: + </para> + +<orderedlist> + <listitem> + <para> + Builds the call to the AC_ARG_ENABLE macro, with --help text + properly quoted and aligned. (Death to changequote!) + </para> + </listitem> + <listitem> + <para> + Checks the result against a list of allowed possibilities, and + signals a fatal error if there's no match. This means that the + rest of the GLIBCXX_ENABLE_FOO macro doesn't need to test for + strange arguments, nor do we need to protect against + empty/whitespace strings with the <code>"x$foo" = "xbar"</code> + idiom. + </para> + </listitem> +</orderedlist> + +<para>Doing these things correctly takes some extra autoconf/autom4te code, + which made our macros nearly illegible. So all the ugliness is factored + out into this one helper macro. +</para> + +<para>Many of the macros take an argument, passed from when they are expanded + in configure.ac. The argument controls the default value of the + enable/disable switch. Previously, the arguments themselves had defaults. + Now they don't, because that's extra complexity with zero gain for us. +</para> + +<para>There are three "overloaded signatures". When reading the descriptions + below, keep in mind that the brackets are autoconf's quotation characters, + and that they will be stripped. Examples of just about everything occur + in acinclude.m4, if you want to look. +</para> + +<programlisting> + GLIBCXX_ENABLE (FEATURE, DEFAULT, HELP-ARG, HELP-STRING) + GLIBCXX_ENABLE (FEATURE, DEFAULT, HELP-ARG, HELP-STRING, permit a|b|c) + GLIBCXX_ENABLE (FEATURE, DEFAULT, HELP-ARG, HELP-STRING, SHELL-CODE-HANDLER) +</programlisting> + +<itemizedlist> + <listitem> + <para> + FEATURE is the string that follows --enable. The results of the + test (such as it is) will be in the variable $enable_FEATURE, + where FEATURE has been squashed. Example: + <code>[extra-foo]</code>, controlled by the --enable-extra-foo + option and stored in $enable_extra_foo. + </para> + </listitem> + <listitem> + <para> + DEFAULT is the value to store in $enable_FEATURE if the user does + not pass --enable/--disable. It should be one of the permitted + values passed later. Examples: <code>[yes]</code>, or + <code>[bar]</code>, or <code>[$1]</code> (which passes the + argument given to the GLIBCXX_ENABLE_FOO macro as the + default). + </para> + <para> + For cases where we need to probe for particular models of things, + it is useful to have an undocumented "auto" value here (see + GLIBCXX_ENABLE_CLOCALE for an example). + </para> + </listitem> + <listitem> + <para> + HELP-ARG is any text to append to the option string itself in the + --help output. Examples: <code>[]</code> (i.e., an empty string, + which appends nothing), <code>[=BAR]</code>, which produces + <code>--enable-extra-foo=BAR</code>, and + <code>[@<:@=BAR@:>@]</code>, which produces + <code>--enable-extra-foo[=BAR]</code>. See the difference? See + what it implies to the user? + </para> + <para> + If you're wondering what that line noise in the last example was, + that's how you embed autoconf special characters in output text. + They're called <ulink + url="http://www.gnu.org/software/autoconf/manual/autoconf-2.57/html_node/autoconf_95.html#SEC95"><emphasis>quadrigraphs</emphasis></ulink> + and you should use them whenever necessary. + </para> + </listitem> + <listitem> + <para>HELP-STRING is what you think it is. Do not include the + "default" text like we used to do; it will be done for you by + GLIBCXX_ENABLE. By convention, these are not full English + sentences. Example: [turn on extra foo] + </para> + </listitem> +</itemizedlist> + +<para> + With no other arguments, only the standard autoconf patterns are + allowed: "<code>--{enable,disable}-foo[={yes,no}]</code>" The + $enable_FEATURE variable is guaranteed to equal either "yes" or "no" + after the macro. If the user tries to pass something else, an + explanatory error message will be given, and configure will halt. +</para> + +<para> + The second signature takes a fifth argument, "<code>[permit + a | b | c | ...]</code>" + This allows <emphasis>a</emphasis> or <emphasis>b</emphasis> or + ... after the equals sign in the option, and $enable_FEATURE is + guaranteed to equal one of them after the macro. Note that if you + want to allow plain --enable/--disable with no "=whatever", you must + include "yes" and "no" in the list of permitted values. Also note + that whatever you passed as DEFAULT must be in the list. If the + user tries to pass something not on the list, a semi-explanatory + error message will be given, and configure will halt. Example: + <code>[permit generic|gnu|ieee_1003.1-2001|yes|no|auto]</code> +</para> + +<para> + The third signature takes a fifth argument. It is arbitrary shell + code to execute if the user actually passes the enable/disable + option. (If the user does not, the default is used. Duh.) No + argument checking at all is done in this signature. See + GLIBCXX_ENABLE_CXX_FLAGS for an example of handling, and an error + message. +</para> + +</sect2> + +</sect1>
\ No newline at end of file diff --git a/libstdc++-v3/doc/xml/manual/codecvt.xml b/libstdc++-v3/doc/xml/manual/codecvt.xml new file mode 100644 index 00000000000..4c14d6253f0 --- /dev/null +++ b/libstdc++-v3/doc/xml/manual/codecvt.xml @@ -0,0 +1,730 @@ +<sect1 id="manual.localization.facet.codecvt" xreflabel="codecvt"> +<?dbhtml filename="codecvt.html"?> + +<sect1info> + <keywordset> + <keyword> + ISO C++ + </keyword> + <keyword> + codecvt + </keyword> + </keywordset> +</sect1info> + +<title>codecvt</title> + +<para> +The standard class codecvt attempts to address conversions between +different character encoding schemes. In particular, the standard +attempts to detail conversions between the implementation-defined wide +characters (hereafter referred to as wchar_t) and the standard type +char that is so beloved in classic <quote>C</quote> (which can now be +referred to as narrow characters.) This document attempts to describe +how the GNU libstdc++ implementation deals with the conversion between +wide and narrow characters, and also presents a framework for dealing +with the huge number of other encodings that iconv can convert, +including Unicode and UTF8. Design issues and requirements are +addressed, and examples of correct usage for both the required +specializations for wide and narrow characters and the +implementation-provided extended functionality are given. +</para> + +<sect2 id="facet.codecvt.req" xreflabel="facet.codecvt.req"> +<title>Requirements</title> + +<para> +Around page 425 of the C++ Standard, this charming heading comes into view: +</para> + +<blockquote> +<para> +22.2.1.5 - Template class codecvt +</para> +</blockquote> + +<para> +The text around the codecvt definition gives some clues: +</para> + +<blockquote> +<para> +<emphasis> +-1- The class codecvt<internT,externT,stateT> is for use when +converting from one codeset to another, such as from wide characters +to multibyte characters, between wide character encodings such as +Unicode and EUC. +</emphasis> +</para> +</blockquote> + +<para> +Hmm. So, in some unspecified way, Unicode encodings and +translations between other character sets should be handled by this +class. +</para> + +<blockquote> +<para> +<emphasis> +-2- The stateT argument selects the pair of codesets being mapped between. +</emphasis> +</para> +</blockquote> + +<para> +Ah ha! Another clue... +</para> + +<blockquote> +<para> +<emphasis> +-3- The instantiations required in the Table ?? +(lib.locale.category), namely codecvt<wchar_t,char,mbstate_t> and +codecvt<char,char,mbstate_t>, convert the implementation-defined +native character set. codecvt<char,char,mbstate_t> implements a +degenerate conversion; it does not convert at +all. codecvt<wchar_t,char,mbstate_t> converts between the native +character sets for tiny and wide characters. Instantiations on +mbstate_t perform conversion between encodings known to the library +implementor. Other encodings can be converted by specializing on a +user-defined stateT type. The stateT object can contain any state that +is useful to communicate to or from the specialized do_convert member. +</emphasis> +</para> +</blockquote> + +<para> +At this point, a couple points become clear: +</para> + +<para> +One: The standard clearly implies that attempts to add non-required +(yet useful and widely used) conversions need to do so through the +third template parameter, stateT.</para> + +<para> +Two: The required conversions, by specifying mbstate_t as the third +template parameter, imply an implementation strategy that is mostly +(or wholly) based on the underlying C library, and the functions +mcsrtombs and wcsrtombs in particular.</para> +</sect2> + +<sect2 id="facet.codecvt.design" xreflabel="facet.codecvt.design"> +<title>Design</title> + +<sect3 id="codecvt.design.wchar_t_size" xreflabel="codecvt.design.wchar_t_size"> + <title><type>wchar_t</type> Size</title> + + <para> + The simple implementation detail of wchar_t's size seems to + repeatedly confound people. Many systems use a two byte, + unsigned integral type to represent wide characters, and use an + internal encoding of Unicode or UCS2. (See AIX, Microsoft NT, + Java, others.) Other systems, use a four byte, unsigned integral + type to represent wide characters, and use an internal encoding + of UCS4. (GNU/Linux systems using glibc, in particular.) The C + programming language (and thus C++) does not specify a specific + size for the type wchar_t. + </para> + + <para> + Thus, portable C++ code cannot assume a byte size (or endianness) either. + </para> + </sect3> + +<sect3 id="codecvt.design.unicode" xreflabel="codecvt.design.unicode"> + <title>Support for Unicode</title> + <para> + Probably the most frequently asked question about code conversion + is: "So dudes, what's the deal with Unicode strings?" + The dude part is optional, but apparently the usefulness of + Unicode strings is pretty widely appreciated. Sadly, this specific + encoding (And other useful encodings like UTF8, UCS4, ISO 8859-10, + etc etc etc) are not mentioned in the C++ standard. + </para> + + <para> + A couple of comments: + </para> + + <para> + The thought that all one needs to convert between two arbitrary + codesets is two types and some kind of state argument is + unfortunate. In particular, encodings may be stateless. The naming + of the third parameter as stateT is unfortunate, as what is really + needed is some kind of generalized type that accounts for the + issues that abstract encodings will need. The minimum information + that is required includes: + </para> + + <itemizedlist> + <listitem> + <para> + Identifiers for each of the codesets involved in the + conversion. For example, using the iconv family of functions + from the Single Unix Specification (what used to be called + X/Open) hosted on the GNU/Linux operating system allows + bi-directional mapping between far more than the following + tantalizing possibilities: + </para> + + <para> + (An edited list taken from <code>`iconv --list`</code> on a + Red Hat 6.2/Intel system: + </para> + +<blockquote> +<programlisting> +8859_1, 8859_9, 10646-1:1993, 10646-1:1993/UCS4, ARABIC, ARABIC7, +ASCII, EUC-CN, EUC-JP, EUC-KR, EUC-TW, GREEK-CCIcode, GREEK, GREEK7-OLD, +GREEK7, GREEK8, HEBREW, ISO-8859-1, ISO-8859-2, ISO-8859-3, +ISO-8859-4, ISO-8859-5, ISO-8859-6, ISO-8859-7, ISO-8859-8, +ISO-8859-9, ISO-8859-10, ISO-8859-11, ISO-8859-13, ISO-8859-14, +ISO-8859-15, ISO-10646, ISO-10646/UCS2, ISO-10646/UCS4, +ISO-10646/UTF-8, ISO-10646/UTF8, SHIFT-JIS, SHIFT_JIS, UCS-2, UCS-4, +UCS2, UCS4, UNICODE, UNICODEBIG, UNICODELIcodeLE, US-ASCII, US, UTF-8, +UTF-16, UTF8, UTF16). +</programlisting> +</blockquote> + +<para> +For iconv-based implementations, string literals for each of the +encodings (ie. "UCS-2" and "UTF-8") are necessary, +although for other, +non-iconv implementations a table of enumerated values or some other +mechanism may be required. +</para> +</listitem> + +<listitem><para> + Maximum length of the identifying string literal. +</para></listitem> + +<listitem><para> + Some encodings require explicit endian-ness. As such, some kind + of endian marker or other byte-order marker will be necessary. See + "Footnotes for C/C++ developers" in Haible for more information on + UCS-2/Unicode endian issues. (Summary: big endian seems most likely, + however implementations, most notably Microsoft, vary.) +</para></listitem> + +<listitem><para> + Types representing the conversion state, for conversions involving + the machinery in the "C" library, or the conversion descriptor, for + conversions using iconv (such as the type iconv_t.) Note that the + conversion descriptor encodes more information than a simple encoding + state type. +</para></listitem> + +<listitem><para> + Conversion descriptors for both directions of encoding. (ie, both + UCS-2 to UTF-8 and UTF-8 to UCS-2.) +</para></listitem> + +<listitem><para> + Something to indicate if the conversion requested if valid. +</para></listitem> + +<listitem><para> + Something to represent if the conversion descriptors are valid. +</para></listitem> + +<listitem><para> + Some way to enforce strict type checking on the internal and + external types. As part of this, the size of the internal and + external types will need to be known. +</para></listitem> +</itemizedlist> +</sect3> + +<sect3 id="codecvt.design.issues" xreflabel="codecvt.design.issues"> + <title>Other Issues</title> +<para> +In addition, multi-threaded and multi-locale environments also impact +the design and requirements for code conversions. In particular, they +affect the required specialization codecvt<wchar_t, char, mbstate_t> +when implemented using standard "C" functions. +</para> + +<para> +Three problems arise, one big, one of medium importance, and one small. +</para> + +<para> +First, the small: mcsrtombs and wcsrtombs may not be multithread-safe +on all systems required by the GNU tools. For GNU/Linux and glibc, +this is not an issue. +</para> + +<para> +Of medium concern, in the grand scope of things, is that the functions +used to implement this specialization work on null-terminated +strings. Buffers, especially file buffers, may not be null-terminated, +thus giving conversions that end prematurely or are otherwise +incorrect. Yikes! +</para> + +<para> +The last, and fundamental problem, is the assumption of a global +locale for all the "C" functions referenced above. For something like +C++ iostreams (where codecvt is explicitly used) the notion of +multiple locales is fundamental. In practice, most users may not run +into this limitation. However, as a quality of implementation issue, +the GNU C++ library would like to offer a solution that allows +multiple locales and or simultaneous usage with computationally +correct results. In short, libstdc++ is trying to offer, as an +option, a high-quality implementation, damn the additional complexity! +</para> + +<para> +For the required specialization codecvt<wchar_t, char, mbstate_t> , +conversions are made between the internal character set (always UCS4 +on GNU/Linux) and whatever the currently selected locale for the +LC_CTYPE category implements. +</para> + +</sect3> + +</sect2> + +<sect2 id="facet.codecvt.impl" xreflabel="facet.codecvt.impl"> +<title>Implementation</title> + +<para> +The two required specializations are implemented as follows: +</para> + +<para> +<code> +codecvt<char, char, mbstate_t> +</code> +</para> +<para> +This is a degenerate (ie, does nothing) specialization. Implementing +this was a piece of cake. +</para> + +<para> +<code> +codecvt<char, wchar_t, mbstate_t> +</code> +</para> + +<para> +This specialization, by specifying all the template parameters, pretty +much ties the hands of implementors. As such, the implementation is +straightforward, involving mcsrtombs for the conversions between char +to wchar_t and wcsrtombs for conversions between wchar_t and char. +</para> + +<para> +Neither of these two required specializations deals with Unicode +characters. As such, libstdc++ implements a partial specialization +of the codecvt class with and iconv wrapper class, encoding_state as the +third template parameter. +</para> + +<para> +This implementation should be standards conformant. First of all, the +standard explicitly points out that instantiations on the third +template parameter, stateT, are the proper way to implement +non-required conversions. Second of all, the standard says (in Chapter +17) that partial specializations of required classes are a-ok. Third +of all, the requirements for the stateT type elsewhere in the standard +(see 21.1.2 traits typedefs) only indicate that this type be copy +constructible. +</para> + +<para> +As such, the type encoding_state is defined as a non-templatized, POD +type to be used as the third type of a codecvt instantiation. This +type is just a wrapper class for iconv, and provides an easy interface +to iconv functionality. +</para> + +<para> +There are two constructors for encoding_state: +</para> + +<para> +<code> +encoding_state() : __in_desc(0), __out_desc(0) +</code> +</para> +<para> +This default constructor sets the internal encoding to some default +(currently UCS4) and the external encoding to whatever is returned by +nl_langinfo(CODESET). +</para> + +<para> +<code> +encoding_state(const char* __int, const char* __ext) +</code> +</para> + +<para> +This constructor takes as parameters string literals that indicate the +desired internal and external encoding. There are no defaults for +either argument. +</para> + +<para> +One of the issues with iconv is that the string literals identifying +conversions are not standardized. Because of this, the thought of +mandating and or enforcing some set of pre-determined valid +identifiers seems iffy: thus, a more practical (and non-migraine +inducing) strategy was implemented: end-users can specify any string +(subject to a pre-determined length qualifier, currently 32 bytes) for +encodings. It is up to the user to make sure that these strings are +valid on the target system. +</para> + +<para> +<code> +void +_M_init() +</code> +</para> +<para> +Strangely enough, this member function attempts to open conversion +descriptors for a given encoding_state object. If the conversion +descriptors are not valid, the conversion descriptors returned will +not be valid and the resulting calls to the codecvt conversion +functions will return error. +</para> + +<para> +<code> +bool +_M_good() +</code> +</para> + +<para> +Provides a way to see if the given encoding_state object has been +properly initialized. If the string literals describing the desired +internal and external encoding are not valid, initialization will +fail, and this will return false. If the internal and external +encodings are valid, but iconv_open could not allocate conversion +descriptors, this will also return false. Otherwise, the object is +ready to convert and will return true. +</para> + +<para> +<code> +encoding_state(const encoding_state&) +</code> +</para> + +<para> +As iconv allocates memory and sets up conversion descriptors, the copy +constructor can only copy the member data pertaining to the internal +and external code conversions, and not the conversion descriptors +themselves. +</para> + +<para> +Definitions for all the required codecvt member functions are provided +for this specialization, and usage of codecvt<internal character type, +external character type, encoding_state> is consistent with other +codecvt usage. +</para> + +</sect2> + +<sect2 id="facet.codecvt.use" xreflabel="facet.codecvt.use"> +<title>Use</title> +<para>A conversions involving string literal.</para> + +<programlisting> + typedef codecvt_base::result result; + typedef unsigned short unicode_t; + typedef unicode_t int_type; + typedef char ext_type; + typedef encoding_state state_type; + typedef codecvt<int_type, ext_type, state_type> unicode_codecvt; + + const ext_type* e_lit = "black pearl jasmine tea"; + int size = strlen(e_lit); + int_type i_lit_base[24] = + { 25088, 27648, 24832, 25344, 27392, 8192, 28672, 25856, 24832, 29184, + 27648, 8192, 27136, 24832, 29440, 27904, 26880, 28160, 25856, 8192, 29696, + 25856, 24832, 2560 + }; + const int_type* i_lit = i_lit_base; + const ext_type* efrom_next; + const int_type* ifrom_next; + ext_type* e_arr = new ext_type[size + 1]; + ext_type* eto_next; + int_type* i_arr = new int_type[size + 1]; + int_type* ito_next; + + // construct a locale object with the specialized facet. + locale loc(locale::classic(), new unicode_codecvt); + // sanity check the constructed locale has the specialized facet. + VERIFY( has_facet<unicode_codecvt>(loc) ); + const unicode_codecvt& cvt = use_facet<unicode_codecvt>(loc); + // convert between const char* and unicode strings + unicode_codecvt::state_type state01("UNICODE", "ISO_8859-1"); + initialize_state(state01); + result r1 = cvt.in(state01, e_lit, e_lit + size, efrom_next, + i_arr, i_arr + size, ito_next); + VERIFY( r1 == codecvt_base::ok ); + VERIFY( !int_traits::compare(i_arr, i_lit, size) ); + VERIFY( efrom_next == e_lit + size ); + VERIFY( ito_next == i_arr + size ); +</programlisting> + +</sect2> + +<sect2 id="facet.codecvt.future" xreflabel="facet.codecvt.future"> +<title>Future</title> +<itemizedlist> +<listitem> + <para> + a. things that are sketchy, or remain unimplemented: + do_encoding, max_length and length member functions + are only weakly implemented. I have no idea how to do + this correctly, and in a generic manner. Nathan? +</para> +</listitem> + +<listitem> + <para> + b. conversions involving std::string + </para> + <itemizedlist> + <listitem><para> + how should operators != and == work for string of + different/same encoding? + </para></listitem> + + <listitem><para> + what is equal? A byte by byte comparison or an + encoding then byte comparison? + </para></listitem> + + <listitem><para> + conversions between narrow, wide, and unicode strings + </para></listitem> + </itemizedlist> +</listitem> +<listitem><para> + c. conversions involving std::filebuf and std::ostream +</para> + <itemizedlist> + <listitem><para> + how to initialize the state object in a + standards-conformant manner? + </para></listitem> + + <listitem><para> + how to synchronize the "C" and "C++" + conversion information? + </para></listitem> + + <listitem><para> + wchar_t/char internal buffers and conversions between + internal/external buffers? + </para></listitem> + </itemizedlist> +</listitem> +</itemizedlist> +</sect2> + + +<bibliography id="facet.codecvt.biblio" xreflabel="facet.codecvt.biblio"> +<title>Bibliography</title> + + <biblioentry> + <title> + The GNU C Library + </title> + + <author> + <surname>McGrath</surname> + <firstname>Roland</firstname> + </author> + <author> + <surname>Drepper</surname> + <firstname>Ulrich</firstname> + </author> + + <copyright> + <year>2007</year> + <holder>FSF</holder> + </copyright> + <pagenums>Chapters 6 Character Set Handling and 7 Locales and Internationalization</pagenums> + + </biblioentry> + + <biblioentry> + <title> + Correspondence + </title> + + <author> + <surname>Drepper</surname> + <firstname>Ulrich</firstname> + </author> + + <copyright> + <year>2002</year> + <holder></holder> + </copyright> + </biblioentry> + + <biblioentry> + <title> + ISO/IEC 14882:1998 Programming languages - C++ + </title> + + <copyright> + <year>1998</year> + <holder>ISO</holder> + </copyright> + </biblioentry> + + <biblioentry> + <title> + ISO/IEC 9899:1999 Programming languages - C + </title> + + <copyright> + <year>1999</year> + <holder>ISO</holder> + </copyright> + </biblioentry> + + <biblioentry> + <title> + System Interface Definitions, Issue 6 (IEEE Std. 1003.1-200x) + </title> + + <copyright> + <year>1999</year> + <holder> + The Open Group/The Institute of Electrical and Electronics Engineers, Inc.</holder> + </copyright> + + <biblioid> + <ulink url="http://www.opennc.org/austin/docreg.html"> + </ulink> + </biblioid> + + </biblioentry> + + <biblioentry> + <title> + The C++ Programming Language, Special Edition + </title> + + <author> + <surname>Stroustrup</surname> + <firstname>Bjarne</firstname> + </author> + + <copyright> + <year>2000</year> + <holder>Addison Wesley, Inc.</holder> + </copyright> + <pagenums>Appendix D</pagenums> + + <publisher> + <publishername> + Addison Wesley + </publishername> + </publisher> + + </biblioentry> + + + <biblioentry> + <title> + Standard C++ IOStreams and Locales + </title> + <subtitle> + Advanced Programmer's Guide and Reference + </subtitle> + + <author> + <surname>Langer</surname> + <firstname>Angelika</firstname> + </author> + + <author> + <surname>Kreft</surname> + <firstname>Klaus</firstname> + </author> + + <copyright> + <year>2000</year> + <holder>Addison Wesley Longman, Inc.</holder> + </copyright> + + <publisher> + <publishername> + Addison Wesley Longman + </publishername> + </publisher> + + </biblioentry> + + <biblioentry> + <title> + A brief description of Normative Addendum 1 + </title> + + <author> + <surname>Feather</surname> + <firstname>Clive</firstname> + </author> + + <pagenums>Extended Character Sets</pagenums> + <biblioid> + <ulink url="http://www.lysator.liu.se/c/na1.html"> + </ulink> + </biblioid> + + </biblioentry> + + <biblioentry> + <title> + The Unicode HOWTO + </title> + + <author> + <surname>Haible</surname> + <firstname>Bruno</firstname> + </author> + + <biblioid> + <ulink url="ftp://ftp.ilog.fr/pub/Users/haible/utf8/Unicode-HOWTO.html"> + </ulink> + </biblioid> + + </biblioentry> + + <biblioentry> + <title> + UTF-8 and Unicode FAQ for Unix/Linux + </title> + + <author> + <surname>Khun</surname> + <firstname>Markus</firstname> + </author> + + <biblioid> + <ulink url="http://www.cl.cam.ac.uk/~mgk25/unicode.html"> + </ulink> + </biblioid> + + </biblioentry> + + +</bibliography> + +</sect1>
\ No newline at end of file diff --git a/libstdc++-v3/doc/xml/manual/concurrency.xml b/libstdc++-v3/doc/xml/manual/concurrency.xml new file mode 100644 index 00000000000..5740e424373 --- /dev/null +++ b/libstdc++-v3/doc/xml/manual/concurrency.xml @@ -0,0 +1,334 @@ +<?xml version='1.0'?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" +[ ]> + +<chapter id="manual.ext.concurrency" xreflabel="Concurrency Extensions"> +<?dbhtml filename="concurrency.html"?> + +<chapterinfo> + <keywordset> + <keyword> + ISO C++ + </keyword> + <keyword> + library + </keyword> + </keywordset> +</chapterinfo> + +<title>Concurrency</title> + +<sect1 id="manual.ext.concurrency.design" xreflabel="Design"> + <title>Design</title> + + <sect2 id="manual.ext.concurrency.design.threads" xreflabel="Threads API"> + <title>Interface to Locks and Mutexes</title> + +<para>The file <ext/concurrence.h> contains all the higher-level +constructs for playing with threads. In contrast to the atomics layer, +the concurrence layer consists largely of types. All types are defined within <code>namespace __gnu_cxx</code>. +</para> + +<para> +These types can be used in a portable manner, regardless of the +specific environment. They are carefully designed to provide optimum +efficiency and speed, abstracting out underlying thread calls and +accesses when compiling for single-threaded situations (even on hosts +that support multiple threads.) +</para> + +<para>The enumerated type <code>_Lock_policy</code> details the set of +available locking +policies: <code>_S_single</code>, <code>_S_mutex</code>, +and <code>_S_atomic</code>. +</para> + +<itemizedlist> +<listitem><para><code>_S_single</code></para> +<para>Indicates single-threaded code that does not need locking. +</para> + +</listitem> +<listitem><para><code>_S_mutex</code></para> +<para>Indicates multi-threaded code using thread-layer abstractions. +</para> +</listitem> +<listitem><para><code>_S_atomic</code></para> +<para>Indicates multi-threaded code using atomic operations. +</para> +</listitem> +</itemizedlist> + +<para>The compile-time constant <code>__default_lock_policy</code> is set +to one of the three values above, depending on characteristics of the +host environment and the current compilation flags. +</para> + +<para>Two more datatypes make up the rest of the +interface: <code>__mutex</code>, and <code>__scoped_lock</code>. +</para> + +<para> +</para> + +<para>The scoped lock idiom is well-discussed within the C++ +community. This version takes a <code>__mutex</code> reference, and +locks it during construction of <code>__scoped_locke</code> and +unlocks it during destruction. This is an efficient way of locking +critical sections, while retaining exception-safety. +</para> + </sect2> + + <sect2 id="manual.ext.concurrency.design.atomics" xreflabel="Atomic API"> + <title>Interface to Atomic Functions</title> + + +<para> +Two functions and one type form the base of atomic support. +</para> + + +<para>The type <code>_Atomic_word</code> is a signed integral type +supporting atomic operations. +</para> + +<para> +The two functions functions are: +</para> + +<programlisting> +_Atomic_word +__exchange_and_add_dispatch(volatile _Atomic_word*, int); + +void +__atomic_add_dispatch(volatile _Atomic_word*, int); +</programlisting> + +<para>Both of these functions are declared in the header file +<ext/atomicity.h>, and are in <code>namespace __gnu_cxx</code>. +</para> + +<itemizedlist> +<listitem><para> +<code> +__exchange_and_add_dispatch +</code> +</para> +<para>Adds the second argument's value to the first argument. Returns the old value. +</para> +</listitem> +<listitem><para> +<code> +__atomic_add_dispatch +</code> +</para> +<para>Adds the second argument's value to the first argument. Has no return value. +</para> +</listitem> +</itemizedlist> + +<para> +These functions forward to one of several specialized helper +functions, depending on the circumstances. For instance, +</para> + +<para> +<code> +__exchange_and_add_dispatch +</code> +</para> + +<para> +Calls through to either of: +</para> + +<itemizedlist> +<listitem><para><code>__exchange_and_add</code> +</para> +<para>Multi-thread version. Inlined if compiler-generated builtin atomics +can be used, otherwise resolved at link time to a non-builtin code +sequence. +</para> +</listitem> + +<listitem><para><code>__exchange_and_add_single</code> +</para> +<para>Single threaded version. Inlined.</para> +</listitem> +</itemizedlist> + +<para>However, only <code>__exchange_and_add_dispatch</code> +and <code>__atomic_add_dispatch</code> should be used. These functions +can be used in a portable manner, regardless of the specific +environment. They are carefully designed to provide optimum efficiency +and speed, abstracting out atomic accesses when they are not required +(even on hosts that support compiler intrinsics for atomic +operations.) +</para> + +<para> +In addition, there are two macros +</para> + +<para> +<code> +_GLIBCXX_READ_MEM_BARRIER +</code> +</para> +<para> +<code> +_GLIBCXX_WRITE_MEM_BARRIER +</code> +</para> + +<para> +Which expand to the appropriate write and read barrier required by the +host hardware and operating system. +</para> + </sect2> + +</sect1> + + +<sect1 id="manual.ext.concurrency.impl" xreflabel="Implementation"> + <title>Implementation</title> + <sect2 id="manual.ext.concurrency.impl.atomic_fallbacks" xreflabel="Atomic F"> + <title>Using Builitin Atomic Functions</title> + +<para>The functions for atomic operations described above are either +implemented via compiler intrinsics (if the underlying host is +capable) or by library fallbacks.</para> + +<para>Compiler intrinsics (builtins) are always preferred. However, as +the compiler builtins for atomics are not universally implemented, +using them directly is problematic, and can result in undefined +function calls. (An example of an undefined symbol from the use +of <code>__sync_fetch_and_add</code> on an unsupported host is a +missing reference to <code>__sync_fetch_and_add_4</code>.) +</para> + +<para>In addition, on some hosts the compiler intrinsics are enabled +conditionally, via the <code>-march</code> command line flag. This makes +usage vary depending on the target hardware and the flags used during +compile. +</para> + +<para> If builtins are possible, <code>_GLIBCXX_ATOMIC_BUILTINS</code> +will be defined. +</para> + + +<para>For the following hosts, intrinsics are enabled by default. +</para> + +<itemizedlist> + <listitem><para>alpha</para></listitem> + <listitem><para>ia64</para></listitem> + <listitem><para>powerpc</para></listitem> + <listitem><para>s390</para></listitem> +</itemizedlist> + +<para>For others, some form of <code>-march</code> may work. On +non-ancient x86 hardware, <code>-march=native</code> usually does the +trick.</para> + +<para> For hosts without compiler intrinsics, but with capable +hardware, hand-crafted assembly is selected. This is the case for the following hosts: +</para> + +<itemizedlist> + <listitem><para>cris</para></listitem> + <listitem><para>hppa</para></listitem> + <listitem><para>i386</para></listitem> + <listitem><para>i486</para></listitem> + <listitem><para>m48k</para></listitem> + <listitem><para>mips</para></listitem> + <listitem><para>sparc</para></listitem> +</itemizedlist> + +<para>And for the rest, a simulated atomic lock via pthreads. +</para> + +<para> Detailed information about compiler intrinsics for atomic operations can be found in the GCC <ulink url="http://gcc.gnu.org/onlinedocs/gcc/Atomic-Builtins.html"> documentation</ulink>. +</para> + +<para> More details on the library fallbacks from the porting <ulink url="http://gcc.gnu.org/onlinedocs/libstdc++/17_intro/porting.html#Thread%20safety">section</ulink>. +</para> + + + </sect2> + <sect2 id="manual.ext.concurrency.impl.thread" xreflabel="Pthread"> + <title>Thread Abstraction</title> + +<para>A thin layer above IEEE 1003.1 (ie pthreads) is used to abstract +the thread interface for GCC. This layer is called "gthread," and is +comprised of one header file that wraps the host's default thread layer with +a POSIX-like interface. +</para> + +<para> The file <gthr-default.h> points to the deduced wrapper for +the current host. In libstdc++ implementation files, +<bits/gthr.h> is used to select the proper gthreads file. +</para> + +<para>Within libstdc++ sources, all calls to underlying thread functionality +use this layer. More detail as to the specific interface can be found in the source <ulink url="http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/gthr_8h-source.html">documentation</ulink>. +</para> + +<para>By design, the gthread layer is interoperable with the types, +functions, and usage found in the usual <pthread.h> file, +including <code>pthread_t</code>, <code>pthread_once_t</code>, <code>pthread_create</code>, +etc. +</para> + + </sect2> +</sect1> + +<sect1 id="manual.ext.concurrency.use" xreflabel="Use"> + + <title>Use</title> + +<para>Typical usage of the last two constructs is demonstrated as follows: +</para> + +<programlisting> +#include <ext/concurrence.h> + +namespace +{ + __gnu_cxx::__mutex safe_base_mutex; +} // anonymous namespace + +namespace other +{ + void + foo() + { + __gnu_cxx::__scoped_lock sentry(safe_base_mutex); + for (int i = 0; i < max; ++i) + { + _Safe_iterator_base* __old = __iter; + __iter = __iter-<_M_next; + __old-<_M_detach_single(); + } +} +</programlisting> + +<para>In this sample code, an anonymous namespace is used to keep +the <code>__mutex</code> private to the compilation unit, +and <code>__scoped_lock</code> is used to guard access to the critical +section within the for loop, locking the mutex on creation and freeing +the mutex as control moves out of this block. +</para> + +<para>Several exception classes are used to keep track of +concurrence-related errors. These classes +are: <code>__concurrence_lock_error</code>, <code>__concurrence_unlock_error</code>, <code>__concurrence_wait_error</code>, +and <code>__concurrence_broadcast_error</code>. +</para> + + +</sect1> + +</chapter> diff --git a/libstdc++-v3/doc/xml/manual/configure.xml b/libstdc++-v3/doc/xml/manual/configure.xml new file mode 100644 index 00000000000..a47635cd029 --- /dev/null +++ b/libstdc++-v3/doc/xml/manual/configure.xml @@ -0,0 +1,318 @@ +<sect1 id="manual.intro.setup.configure" xreflabel="Configuring"> +<?dbhtml filename="configure.html"?> + +<sect1info> + <keywordset> + <keyword> + ISO C++ + </keyword> + <keyword> + configure + </keyword> + <keyword> + options + </keyword> + </keywordset> +</sect1info> + +<title>Configure</title> + +<para> + Here are some of the non-obvious options to libstdc++'s configure. + Keep in mind that + <!-- This SECnn should be the "Choosing Package Options" section. --> + <ulink url="http://www.gnu.org/software/autoconf/manual/autoconf-2.57/html_node/autoconf_131.html#SEC131">they + all have opposite forms as well</ulink> + (enable/disable and with/without). The defaults are for <emphasis>current + development sources</emphasis>, which may be different than those for + released versions. +</para> +<para>The canonical way to find out the configure options that are + available for a given set of libstdc++ sources is to go to the + source directory and then type:<code> ./configure --help</code> +</para> + +<variablelist> + <varlistentry><term><code>--enable-multilib</code>[default]</term> + <listitem><para>This is part of the generic multilib support for building cross + compilers. As such, targets like "powerpc-elf" will have + libstdc++ built many different ways: "-msoft-float" + and not, etc. A different libstdc++ will be built for each of + the different multilib versions. This option is on by default. + </para> + </listitem></varlistentry> + + <varlistentry><term><code>--enable-sjlj-exceptions</code></term> + <listitem><para>Forces old, set-jump/long-jump exception handling model. If + at all possible, the new, frame unwinding exception handling routines + should be used instead, as they significantly reduce both + runtime memory usage and executable size. This option can + change the library ABI. + </para> + </listitem></varlistentry> + + <varlistentry><term><code>--enable-version-specific-runtime-libs</code></term> + <listitem><para>Specify that run-time libraries should be installed in the + compiler-specific subdirectory (i.e., + <code>${libdir}/gcc-lib/${target_alias}/${gcc_version}</code>) + instead of <code>${libdir}</code>. This option is useful if you + intend to use several versions of gcc in parallel. In addition, + libstdc++'s include files will be installed in + <code>${libdir}/gcc-lib/${target_alias}/${gcc_version}/include/g++</code>, + unless you also specify + <literal>--with-gxx-include-dir=<filename class="directory">dirname</filename></literal> during configuration. + </para> + </listitem></varlistentry> + + <varlistentry><term><code>--with-gxx-include-dir=<include-files dir></code></term> + <listitem><para>Adds support for named libstdc++ include directory. For instance, + the following puts all the libstdc++ headers into a directory + called "2.97-20001008" instead of the usual + "c++/(version)". + </para> + <programlisting> + --with-gxx-include-dir=/foo/H-x86-gcc-3-c-gxx-inc/include/2.97-20001008</programlisting> </listitem></varlistentry> + + <varlistentry><term><code>--enable-cstdio</code></term> + <listitem><para>This is an abbreviated form of <code>'--enable-cstdio=stdio'</code> + (described next). This option can change the library ABI. + </para> + </listitem></varlistentry> + + <varlistentry><term><code>--enable-cstdio=OPTION</code></term> + <listitem><para>Select a target-specific I/O package. At the moment, the only + choice is to use 'stdio', a generic "C" abstraction. + The default is 'stdio'. + </para> + </listitem></varlistentry> + + <varlistentry><term><code>--enable-clocale</code></term> + <listitem><para>This is an abbreviated form of <code>'--enable-clocale=generic'</code> + (described next). This option can change the library ABI. + </para> + </listitem></varlistentry> + + <varlistentry><term><code>--enable-clocale=OPTION</code></term> + <listitem><para>Select a target-specific underlying locale package. The + choices are 'ieee_1003.1-2001' to specify an X/Open, Standard Unix + (IEEE Std. 1003.1-2001) model based on langinfo/iconv/catgets, + 'gnu' to specify a model based on functionality from the GNU C + library (langinfo/iconv/gettext) (from <ulink url="http://sources.redhat.com/glibc/">glibc</ulink>, the GNU C + library), or 'generic' to use a generic "C" + abstraction which consists of "C" locale info. + </para> + + <para>As part of the configuration process, the "C" library is + probed both for sufficient vintage, and installed locale + data. If either of these elements are not present, the C++ + locale model default to 'generic.' On glibc-based systems of + version 2.2.5 and above with installed locale files, 'gnu' is + automatically selected. + </para> + </listitem></varlistentry> + + <varlistentry><term><code>--enable-libstdcxx-allocator</code></term> + <listitem><para>This is an abbreviated form of + <code>'--enable-libstdcxx-allocator=auto'</code> (described + next). This option can change the library ABI. + </para> + </listitem></varlistentry> + + <varlistentry><term><code>--enable-libstdcxx-allocator=OPTION </code></term> + <listitem><para>Select a target-specific underlying std::allocator. The + choices are 'new' to specify a wrapper for new, 'malloc' to + specify a wrapper for malloc, 'mt' for a fixed power of two allocator + (<ulink url="ext/mt_allocator.html">documented</ulink> under extensions), + 'pool' for the SGI pooled allocator or 'bitmap' for a bitmap allocator. + This option can change the library ABI. + </para> + </listitem></varlistentry> + + <varlistentry><term><code>--enable-cheaders=OPTION</code></term> + <listitem><para>This allows the user to define the approach taken for C header + compatibility with C++. Options are c, c_std, and c_global. + These correspond to the source directory's include/c, + include/c_std, and include/c_global, and may also include + include/c_compatibility. The default is c_global. + </para> + </listitem></varlistentry> + + <varlistentry><term><code>--enable-threads</code></term> + <listitem><para>This is an abbreviated form of <code>'--enable-threads=yes'</code> + (described next). This option can change the library ABI. + </para> + </listitem></varlistentry> + + <varlistentry><term><code>--enable-threads=OPTION</code></term> + <listitem><para>Select a threading library. A full description is given in the + general <ulink url="http://gcc.gnu.org/install/configure.html">compiler + configuration instructions</ulink>. + </para> + </listitem></varlistentry> + + <varlistentry><term><code>--enable-libstdcxx-debug</code></term> + <listitem><para>Build separate debug libraries in addition to what is normally built. + By default, the debug libraries are compiled with + <code> CXXFLAGS='-g3 -O0'</code> + , are installed in <code>${libdir}/debug</code>, and have the + same names and versioning information as the non-debug + libraries. This option is off by default. + </para> + <para>Note this make command, executed in + the build directory, will do much the same thing, without the + configuration difference and without building everything twice: + <code>make CXXFLAGS='-g3 -O0' all</code> + </para> + </listitem></varlistentry> + + <varlistentry><term><code>--enable-libstdcxx-debug-flags=FLAGS</code></term> + + <listitem><para>This option is only valid when <code> --enable-debug </code> + is also specified, and applies to the debug builds only. With + this option, you can pass a specific string of flags to the + compiler to use when building the debug versions of libstdc++. + FLAGS is a quoted string of options, like + </para> + <programlisting> + --enable-libstdcxx-debug-flags='-g3 -O1 -gdwarf-2'</programlisting> + </listitem></varlistentry> + + <varlistentry><term><code>--enable-cxx-flags=FLAGS</code></term> + <listitem><para>With this option, you can pass a string of -f (functionality) + flags to the compiler to use when building libstdc++. This + option can change the library ABI. FLAGS is a quoted string of + options, like + </para> + <programlisting> + --enable-cxx-flags='-fvtable-gc -fomit-frame-pointer -ansi'</programlisting> + <para> + Note that the flags don't necessarily have to all be -f flags, + as shown, but usually those are the ones that will make sense + for experimentation and configure-time overriding. + </para> + <para>The advantage of --enable-cxx-flags over setting CXXFLAGS in + the 'make' environment is that, if files are automatically + rebuilt, the same flags will be used when compiling those files + as well, so that everything matches. + </para> + <para>Fun flags to try might include combinations of + </para> + <programlisting> + -fstrict-aliasing + -fno-exceptions + -ffunction-sections + -fvtable-gc</programlisting> + <para>and opposite forms (-fno-) of the same. Tell us (the libstdc++ + mailing list) if you discover more! + </para> + </listitem></varlistentry> + + <varlistentry><term><code>--enable-c99</code></term> + <listitem><para>The "long long" type was introduced in C99, along + with many other functions for wide characters, and math + classification macros, etc. If enabled, all C99 functions not + specified by the C++ standard will be put into <code>namespace + __gnu_cxx</code>, and then all these names will + be injected into namespace std, so that C99 functions can be + used "as if" they were in the C++ standard (as they + will eventually be in some future revision of the standard, + without a doubt). By default, C99 support is on, assuming the + configure probes find all the necessary functions and bits + necessary. This option can change the library ABI. + </para> + </listitem></varlistentry> + + <varlistentry><term><code>--enable-wchar_t</code>[default]</term> + <listitem><para>Template specializations for the "wchar_t" type are + required for wide character conversion support. Disabling + wide character specializations may be expedient for initial + porting efforts, but builds only a subset of what is required by + ISO, and is not recommended. By default, this option is on. + This option can change the library ABI. + </para> + </listitem></varlistentry> + + <varlistentry><term><code>--enable-long-long </code></term> + <listitem><para>The "long long" type was introduced in C99. It is + provided as a GNU extension to C++98 in g++. This flag builds + support for "long long" into the library (specialized + templates and the like for iostreams). This option is on by default: + if enabled, users will have to either use the new-style "C" + headers by default (i.e., <cmath> not <math.h>) + or add appropriate compile-time flags to all compile lines to + allow "C" visibility of this feature (on GNU/Linux, + the flag is -D_ISOC99_SOURCE, which is added automatically via + CPLUSPLUS_CPP_SPEC's addition of _GNU_SOURCE). + This option can change the library ABI. + </para> + </listitem></varlistentry> + + <varlistentry><term><code>--enable-fully-dynamic-string</code></term> + <listitem><para>This option enables a special version of basic_string avoiding + the optimization that allocates empty objects in static memory. + Mostly useful together with shared memory allocators, see PR + libstdc++/16612 for details. + </para> + </listitem></varlistentry> + + <varlistentry><term><code>--enable-concept-checks</code></term> + <listitem><para>This turns on additional compile-time checks for instantiated + library templates, in the form of specialized templates, + <ulink url="19_diagnostics/howto.html#3">described here</ulink>. They + can help users discover when they break the rules of the STL, before + their programs run. + </para> + </listitem></varlistentry> + + <varlistentry><term><code>--enable-symvers[=style]</code></term> + + <listitem><para>In 3.1 and later, tries to turn on symbol versioning in the + shared library (if a shared library has been + requested). Values for 'style' that are currently supported + are 'gnu', 'gnu-versioned-namespace', 'darwin', and + 'darwin-export'. Both gnu- options require that a recent + version of the GNU linker be in use. Both darwin options are + equivalent. With no style given, the configure script will try + to guess correct defaults for the host system, probe to see if + additional requirements are necessary and present for + activation, and if so, will turn symbol versioning on. This + option can change the library ABI. + </para> + + </listitem></varlistentry> + + <varlistentry><term><code>--enable-visibility</code></term> + <listitem><para> In 4.2 and later, enables or disables visibility attributes. + If enabled (as by default), and the compiler seems capable of + passing the simple sanity checks thrown at it, adjusts items + in namespace std, namespace std::tr1, and namespace __gnu_cxx + so that -fvisibility options work. + </para> + </listitem></varlistentry> + + <varlistentry><term><code>--enable-libstdcxx-pch</code></term> + <listitem><para>In 3.4 and later, tries to turn on the generation of + stdc++.h.gch, a pre-compiled file including all the standard + C++ includes. If enabled (as by default), and the compiler + seems capable of passing the simple sanity checks thrown at + it, try to build stdc++.h.gch as part of the make process. + In addition, this generated file is used later on (by appending <code> + --include bits/stdc++.h </code> to CXXFLAGS) when running the + testsuite. + </para> + </listitem></varlistentry> + + <varlistentry><term><code>--disable-hosted-libstdcxx</code></term> + <listitem> + <para> + By default, a complete <emphasis>hosted</emphasis> C++ library is + built. The C++ Standard also describes a + <emphasis>freestanding</emphasis> environment, in which only a + minimal set of headers are provided. This option builds such an + environment. + </para> + </listitem></varlistentry> +</variablelist> + + +</sect1>
\ No newline at end of file diff --git a/libstdc++-v3/doc/xml/manual/containers.xml b/libstdc++-v3/doc/xml/manual/containers.xml new file mode 100644 index 00000000000..a13d52734a4 --- /dev/null +++ b/libstdc++-v3/doc/xml/manual/containers.xml @@ -0,0 +1,441 @@ +<?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.containers" xreflabel="Containers"> +<?dbhtml filename="containers.html"?> + +<partinfo> + <keywordset> + <keyword> + ISO C++ + </keyword> + <keyword> + library + </keyword> + </keywordset> +</partinfo> + +<title>Containers</title> + +<!-- Chapter 01 : Sequences --> +<chapter id="manual.containers.sequences" xreflabel="Sequences"> + <title>Sequences</title> + +<sect1 id="containers.sequences.list" xreflabel="list"> + <title>list</title> + <sect2 id="sequences.list.size" xreflabel="list::size() is O(n)"> + <title>list::size() is O(n)</title> + <para> + Yes it is, and that's okay. This is a decision that we preserved + when we imported SGI's STL implementation. The following is + quoted from <ulink + url="http://www.sgi.com/tech/stl/FAQ.html">their FAQ</ulink>: + </para> + <blockquote> + <para> + The size() member function, for list and slist, takes time + proportional to the number of elements in the list. This was a + deliberate tradeoff. The only way to get a constant-time + size() for linked lists would be to maintain an extra member + variable containing the list's size. This would require taking + extra time to update that variable (it would make splice() a + linear time operation, for example), and it would also make the + list larger. Many list algorithms don't require that extra + word (algorithms that do require it might do better with + vectors than with lists), and, when it is necessary to maintain + an explicit size count, it's something that users can do + themselves. + </para> + <para> + This choice is permitted by the C++ standard. The standard says + that size() <quote>should</quote> be constant time, and + <quote>should</quote> does not mean the same thing as + <quote>shall</quote>. This is the officially recommended ISO + wording for saying that an implementation is supposed to do + something unless there is a good reason not to. + </para> + <para> + One implication of linear time size(): you should never write + </para> + <programlisting> + if (L.size() == 0) + ... + </programlisting> + + <para> + Instead, you should write + </para> + + <programlisting> + if (L.empty()) + ... + </programlisting> + </blockquote> + </sect2> +</sect1> + +<sect1 id="containers.sequences.vector" xreflabel="vector"> + <title>vector</title> + <para> + </para> + <sect2 id="sequences.vector.management" xreflabel="Space Overhead Management"> + <title>Space Overhead Management</title> + <para> + In <ulink + url="http://gcc.gnu.org/ml/libstdc++/2002-04/msg00105.html">this + message to the list</ulink>, Daniel Kostecky announced work on an + alternate form of <code>std::vector</code> that would support + hints on the number of elements to be over-allocated. The design + was also described, along with possible implementation choices. + </para> + <para> + The first two alpha releases were announced <ulink + url="http://gcc.gnu.org/ml/libstdc++/2002-07/msg00048.html">here</ulink> + and <ulink + url="http://gcc.gnu.org/ml/libstdc++/2002-07/msg00111.html">here</ulink>. + The releases themselves are available at + <ulink url="http://www.kotelna.sk/dk/sw/caphint/"> + http://www.kotelna.sk/dk/sw/caphint/</ulink>. + </para> + + </sect2></sect1> +</chapter> + +<!-- Chapter 02 : Associative --> +<chapter id="manual.containers.associative" xreflabel="Associative"> + <title>Associative</title> + + <sect1 id="containers.associative.insert_hints" xreflabel="Insertion Hints"> + <title>Insertion Hints</title> + <para> + Section [23.1.2], Table 69, of the C++ standard lists this + function for all of the associative containers (map, set, etc): + </para> + <programlisting> + a.insert(p,t); + </programlisting> + <para> + where 'p' is an iterator into the container 'a', and 't' is the + item to insert. The standard says that <quote><code>t</code> is + inserted as close as possible to the position just prior to + <code>p</code>.</quote> (Library DR #233 addresses this topic, + referring to <ulink + url='http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2005/n1780.html'>N1780</ulink>. + Since version 4.2 GCC implements the resolution to DR 233, so + that insertions happen as close as possible to the hint. For + earlier releases the hint was only used as described below. + </para> + <para> + Here we'll describe how the hinting works in the libstdc++ + implementation, and what you need to do in order to take + advantage of it. (Insertions can change from logarithmic + complexity to amortized constant time, if the hint is properly + used.) Also, since the current implementation is based on the + SGI STL one, these points may hold true for other library + implementations also, since the HP/SGI code is used in a lot of + places. + </para> + <para> + In the following text, the phrases <emphasis>greater + than</emphasis> and <emphasis>less than</emphasis> refer to the + results of the strict weak ordering imposed on the container by + its comparison object, which defaults to (basically) + <quote><</quote>. Using those phrases is semantically sloppy, + but I didn't want to get bogged down in syntax. I assume that if + you are intelligent enough to use your own comparison objects, + you are also intelligent enough to assign <quote>greater</quote> + and <quote>lesser</quote> their new meanings in the next + paragraph. *grin* + </para> + <para> + If the <code>hint</code> parameter ('p' above) is equivalent to: + </para> + <itemizedlist> + <listitem> + <para> + <code>begin()</code>, then the item being inserted should + have a key less than all the other keys in the container. + The item will be inserted at the beginning of the container, + becoming the new entry at <code>begin()</code>. + </para> + </listitem> + <listitem> + <para> + <code>end()</code>, then the item being inserted should have + a key greater than all the other keys in the container. The + item will be inserted at the end of the container, becoming + the new entry at <code>end()</code>. + </para> + </listitem> + <listitem> + <para> + neither <code>begin()</code> nor <code>end()</code>, then: + Let <code>h</code> be the entry in the container pointed to + by <code>hint</code>, that is, <code>h = *hint</code>. Then + the item being inserted should have a key less than that of + <code>h</code>, and greater than that of the item preceding + <code>h</code>. The new item will be inserted between + <code>h</code> and <code>h</code>'s predecessor. + </para> + </listitem> + </itemizedlist> + <para> + For <code>multimap</code> and <code>multiset</code>, the + restrictions are slightly looser: <quote>greater than</quote> + should be replaced by <quote>not less than</quote>and <quote>less + than</quote> should be replaced by <quote>not greater + than.</quote> (Why not replace greater with + greater-than-or-equal-to? You probably could in your head, but + the mathematicians will tell you that it isn't the same thing.) + </para> + <para> + If the conditions are not met, then the hint is not used, and the + insertion proceeds as if you had called <code> a.insert(t) + </code> instead. (<emphasis>Note </emphasis> that GCC releases + prior to 3.0.2 had a bug in the case with <code>hint == + begin()</code> for the <code>map</code> and <code>set</code> + classes. You should not use a hint argument in those releases.) + </para> + <para> + This behavior goes well with other containers' + <code>insert()</code> functions which take an iterator: if used, + the new item will be inserted before the iterator passed as an + argument, same as the other containers. + </para> + <para> + <emphasis>Note </emphasis> also that the hint in this + implementation is a one-shot. The older insertion-with-hint + routines check the immediately surrounding entries to ensure that + the new item would in fact belong there. If the hint does not + point to the correct place, then no further local searching is + done; the search begins from scratch in logarithmic time. + </para> + </sect1> + + + <sect1 id="containers.associative.bitset" xreflabel="bitset"> + <title>bitset</title> + <sect2 id="associative.bitset.size_variable" xreflabel="Variable"> + <title>Size Variable</title> + <para> + No, you cannot write code of the form + </para> + <!-- Careful, the leading spaces in PRE show up directly. --> + <programlisting> + #include <bitset> + + void foo (size_t n) + { + std::bitset<n> bits; + .... + } + </programlisting> + <para> + because <code>n</code> must be known at compile time. Your + compiler is correct; it is not a bug. That's the way templates + work. (Yes, it <emphasis>is</emphasis> a feature.) + </para> + <para> + There are a couple of ways to handle this kind of thing. Please + consider all of them before passing judgement. They include, in + no particular order: + </para> + <itemizedlist> + <listitem><para>A very large N in <code>bitset<N></code>.</para></listitem> + <listitem><para>A container<bool>.</para></listitem> + <listitem><para>Extremely weird solutions.</para></listitem> + </itemizedlist> + <para> + <emphasis>A very large N in + <code>bitset<N></code>. </emphasis> It has been + pointed out a few times in newsgroups that N bits only takes up + (N/8) bytes on most systems, and division by a factor of eight is + pretty impressive when speaking of memory. Half a megabyte given + over to a bitset (recall that there is zero space overhead for + housekeeping info; it is known at compile time exactly how large + the set is) will hold over four million bits. If you're using + those bits as status flags (e.g., + <quote>changed</quote>/<quote>unchanged</quote> flags), that's a + <emphasis>lot</emphasis> of state. + </para> + <para> + You can then keep track of the <quote>maximum bit used</quote> + during some testing runs on representative data, make note of how + many of those bits really need to be there, and then reduce N to + a smaller number. Leave some extra space, of course. (If you + plan to write code like the incorrect example above, where the + bitset is a local variable, then you may have to talk your + compiler into allowing that much stack space; there may be zero + space overhead, but it's all allocated inside the object.) + </para> + <para> + <emphasis>A container<bool>. </emphasis> The + Committee made provision for the space savings possible with that + (N/8) usage previously mentioned, so that you don't have to do + wasteful things like <code>Container<char></code> or + <code>Container<short int></code>. Specifically, + <code>vector<bool></code> is required to be specialized for + that space savings. + </para> + <para> + The problem is that <code>vector<bool></code> doesn't + behave like a normal vector anymore. There have been recent + journal articles which discuss the problems (the ones by Herb + Sutter in the May and July/August 1999 issues of C++ Report cover + it well). Future revisions of the ISO C++ Standard will change + the requirement for <code>vector<bool></code> + specialization. In the meantime, <code>deque<bool></code> + is recommended (although its behavior is sane, you probably will + not get the space savings, but the allocation scheme is different + than that of vector). + </para> + <para> + <emphasis>Extremely weird solutions. </emphasis> If + you have access to the compiler and linker at runtime, you can do + something insane, like figuring out just how many bits you need, + then writing a temporary source code file. That file contains an + instantiation of <code>bitset</code> for the required number of + bits, inside some wrapper functions with unchanging signatures. + Have your program then call the compiler on that file using + Position Independent Code, then open the newly-created object + file and load those wrapper functions. You'll have an + instantiation of <code>bitset<N></code> for the exact + <code>N</code> that you need at the time. Don't forget to delete + the temporary files. (Yes, this <emphasis>can</emphasis> be, and + <emphasis>has been</emphasis>, done.) + </para> + <!-- I wonder if this next paragraph will get me in trouble... --> + <para> + This would be the approach of either a visionary genius or a + raving lunatic, depending on your programming and management + style. Probably the latter. + </para> + <para> + Which of the above techniques you use, if any, are up to you and + your intended application. Some time/space profiling is + indicated if it really matters (don't just guess). And, if you + manage to do anything along the lines of the third category, the + author would love to hear from you... + </para> + <para> + Also note that the implementation of bitset used in libstdc++ has + <ulink url="../ext/sgiexts.html#ch23">some extensions</ulink>. + </para> + + </sect2> + <sect2 id="associative.bitset.type_string" xreflabel="Type String"> + <title>Type String</title> + <para> + </para> + <para> + Bitmasks do not take char* nor const char* arguments in their + constructors. This is something of an accident, but you can read + about the problem: follow the library's <quote>Links</quote> from + the homepage, and from the C++ information <quote>defect + reflector</quote> link, select the library issues list. Issue + number 116 describes the problem. + </para> + <para> + For now you can simply make a temporary string object using the + constructor expression: + </para> + <programlisting> + std::bitset<5> b ( std::string(<quote>10110</quote>) ); + </programlisting> + + <para> + instead of + </para> + + <programlisting> + std::bitset<5> b ( <quote>10110</quote> ); // invalid + </programlisting> + </sect2> + </sect1> + +</chapter> + +<!-- Chapter 03 : Interacting with C --> +<chapter id="manual.containers.c" xreflabel="Interacting with C"> + <title>Interacting with C</title> + + <sect1 id="containers.c.vs_array" xreflabel="Containers vs. Arrays"> + <title>Containers vs. Arrays</title> + <para> + You're writing some code and can't decide whether to use builtin + arrays or some kind of container. There are compelling reasons + to use one of the container classes, but you're afraid that + you'll eventually run into difficulties, change everything back + to arrays, and then have to change all the code that uses those + data types to keep up with the change. + </para> + <para> + If your code makes use of the standard algorithms, this isn't as + scary as it sounds. The algorithms don't know, nor care, about + the kind of <quote>container</quote> on which they work, since + the algorithms are only given endpoints to work with. For the + container classes, these are iterators (usually + <code>begin()</code> and <code>end()</code>, but not always). + For builtin arrays, these are the address of the first element + and the <ulink + url="../24_iterators/howto.html#2">past-the-end</ulink> element. + </para> + <para> + Some very simple wrapper functions can hide all of that from the + rest of the code. For example, a pair of functions called + <code>beginof</code> can be written, one that takes an array, + another that takes a vector. The first returns a pointer to the + first element, and the second returns the vector's + <code>begin()</code> iterator. + </para> + <para> + The functions should be made template functions, and should also + be declared inline. As pointed out in the comments in the code + below, this can lead to <code>beginof</code> being optimized out + of existence, so you pay absolutely nothing in terms of increased + code size or execution time. + </para> + <para> + The result is that if all your algorithm calls look like + </para> + <programlisting> + std::transform(beginof(foo), endof(foo), beginof(foo), SomeFunction); + </programlisting> + <para> + then the type of foo can change from an array of ints to a vector + of ints to a deque of ints and back again, without ever changing + any client code. + </para> + <para> + This author has a collection of such functions, called + <quote>*of</quote> because they all extend the builtin + <quote>sizeof</quote>. It started with some Usenet discussions + on a transparent way to find the length of an array. A + simplified and much-reduced version for easier reading is <ulink + url="wrappers_h.txt">given here</ulink>. + </para> + <para> + Astute readers will notice two things at once: first, that the + container class is still a <code>vector<T></code> instead + of a more general <code>Container<T></code>. This would + mean that three functions for <code>deque</code> would have to be + added, another three for <code>list</code>, and so on. This is + due to problems with getting template resolution correct; I find + it easier just to give the extra three lines and avoid confusion. + </para> + <para> + Second, the line + </para> + <programlisting> + inline unsigned int lengthof (T (&)[sz]) { return sz; } + </programlisting> + <para> + looks just weird! Hint: unused parameters can be left nameless. + </para> + </sect1> + +</chapter> + +</part> diff --git a/libstdc++-v3/doc/xml/manual/ctype.xml b/libstdc++-v3/doc/xml/manual/ctype.xml new file mode 100644 index 00000000000..8ecd7b9c3d2 --- /dev/null +++ b/libstdc++-v3/doc/xml/manual/ctype.xml @@ -0,0 +1,259 @@ +<sect1 id="manual.localization.facet.ctype" xreflabel="ctype"> +<?dbhtml filename="ctype.html"?> + +<sect1info> + <keywordset> + <keyword> + ISO C++ + </keyword> + <keyword> + ctype + </keyword> + </keywordset> +</sect1info> + +<title>ctype</title> + +<sect2 id="facet.ctype.impl" xreflabel="facet.ctype.impl"> +<title>Implementation</title> + + <sect3> + <title>Specializations</title> + +<para> +For the required specialization codecvt<wchar_t, char, mbstate_t> , +conversions are made between the internal character set (always UCS4 +on GNU/Linux) and whatever the currently selected locale for the +LC_CTYPE category implements. +</para> + +<para> +The two required specializations are implemented as follows: +</para> + +<para> +<code> +ctype<char> +</code> +</para> +<para> +This is simple specialization. Implementing this was a piece of cake. +</para> + +<para> +<code> +ctype<wchar_t> +</code> +</para> +<para> +This specialization, by specifying all the template parameters, pretty +much ties the hands of implementors. As such, the implementation is +straightforward, involving mcsrtombs for the conversions between char +to wchar_t and wcsrtombs for conversions between wchar_t and char. +</para> + +<para> +Neither of these two required specializations deals with Unicode +characters. +</para> + + </sect3> +</sect2> + +<sect2 id="facet.ctype.future" xreflabel="facet.ctype.future"> +<title>Future</title> + + +<itemizedlist> + <listitem> + <para> + How to deal with the global locale issue? + </para></listitem> + + <listitem> + <para> + How to deal with different types than char, wchar_t? </para></listitem> + + <listitem><para> + Overlap between codecvt/ctype: narrow/widen + </para></listitem> + + <listitem> + <para> + Mask typedef in codecvt_base, argument types in codecvt. what + is know about this type? + </para></listitem> + + <listitem> + <para> + Why mask* argument in codecvt? + </para></listitem> + + <listitem> + <para> + Can this be made (more) generic? is there a simple way to + straighten out the configure-time mess that is a by-product of + this class? + </para></listitem> + + <listitem> + <para> + Get the ctype<wchar_t>::mask stuff under control. Need to + make some kind of static table, and not do lookup evertime + somebody hits the do_is... functions. Too bad we can't just + redefine mask for ctype<wchar_t> + </para></listitem> + + <listitem> + <para> + Rename abstract base class. See if just smash-overriding is a + better approach. Clarify, add sanity to naming. + </para> + </listitem> + +</itemizedlist> + + +</sect2> + + +<bibliography id="facet.ctype.biblio" xreflabel="facet.ctype.biblio"> +<title>Bibliography</title> + + <biblioentry> + <title> + The GNU C Library + </title> + + <author> + <surname>McGrath</surname> + <firstname>Roland</firstname> + </author> + <author> + <surname>Drepper</surname> + <firstname>Ulrich</firstname> + </author> + + <copyright> + <year>2007</year> + <holder>FSF</holder> + </copyright> + <pagenums>Chapters 6 Character Set Handling and 7 Locales and Internationalization</pagenums> + + </biblioentry> + + <biblioentry> + <title> + Correspondence + </title> + + <author> + <surname>Drepper</surname> + <firstname>Ulrich</firstname> + </author> + + <copyright> + <year>2002</year> + <holder></holder> + </copyright> + </biblioentry> + + <biblioentry> + <title> + ISO/IEC 14882:1998 Programming languages - C++ + </title> + + <copyright> + <year>1998</year> + <holder>ISO</holder> + </copyright> + </biblioentry> + + <biblioentry> + <title> + ISO/IEC 9899:1999 Programming languages - C + </title> + + <copyright> + <year>1999</year> + <holder>ISO</holder> + </copyright> + </biblioentry> + + <biblioentry> + <title> + System Interface Definitions, Issue 6 (IEEE Std. 1003.1-200x) + </title> + + <copyright> + <year>1999</year> + <holder> + The Open Group/The Institute of Electrical and Electronics Engineers, Inc.</holder> + </copyright> + + <biblioid> + <ulink url="http://www.opennc.org/austin/docreg.html"> + </ulink> + </biblioid> + + </biblioentry> + + <biblioentry> + <title> + The C++ Programming Language, Special Edition + </title> + + <author> + <surname>Stroustrup</surname> + <firstname>Bjarne</firstname> + </author> + + <copyright> + <year>2000</year> + <holder>Addison Wesley, Inc.</holder> + </copyright> + <pagenums>Appendix D</pagenums> + + <publisher> + <publishername> + Addison Wesley + </publishername> + </publisher> + + </biblioentry> + + + <biblioentry> + <title> + Standard C++ IOStreams and Locales + </title> + <subtitle> + Advanced Programmer's Guide and Reference + </subtitle> + + <author> + <surname>Langer</surname> + <firstname>Angelika</firstname> + </author> + + <author> + <surname>Kreft</surname> + <firstname>Klaus</firstname> + </author> + + <copyright> + <year>2000</year> + <holder>Addison Wesley Longman, Inc.</holder> + </copyright> + + <publisher> + <publishername> + Addison Wesley Longman + </publishername> + </publisher> + + </biblioentry> + +</bibliography> + +</sect1>
\ No newline at end of file diff --git a/libstdc++-v3/doc/xml/manual/debug.xml b/libstdc++-v3/doc/xml/manual/debug.xml new file mode 100644 index 00000000000..b52a2469161 --- /dev/null +++ b/libstdc++-v3/doc/xml/manual/debug.xml @@ -0,0 +1,245 @@ +<sect1 id="manual.intro.using.debug" xreflabel="Debugging Support"> +<?dbhtml filename="debug.html"?> + +<sect1info> + <keywordset> + <keyword> + C++ + </keyword> + <keyword> + debug + </keyword> + </keywordset> +</sect1info> + +<title>Debugging Support</title> + +<para> + There are numerous things that can be done to improve the ease with + which C++ binaries are debugged when using the GNU tool chain. Here + are some of them. +</para> + +<sect2 id="debug.compiler" xreflabel="debug.compiler"> +<title>Using <command>g++</command></title> + <para> + Compiler flags determine how debug information is transmitted + between compilation and debug or analysis tools. + </para> + + <para> + The default optimizations and debug flags for a libstdc++ build + are <code>-g -O2</code>. However, both debug and optimization + flags can be varied to change debugging characteristics. For + instance, turning off all optimization via the <code>-g -O0</code> + flag will disable inlining, so that stepping through all + functions, including inlined constructors and destructors, is + possible. In addition, + <code>-fno-eliminate-unused-debug-types</code> can be used when + additional debug information, such as nested class info, is + desired. +</para> + +<para> + Or, the debug format that the compiler and debugger use to + communicate information about source constructs can be changed via + <code> -gdwarf-2 </code> or <code> -gstabs </code> flags: some + debugging formats permit more expressive type and scope information + to be shown in gdb. The default debug information for a particular + platform can be identified via the value set by the + PREFERRED_DEBUGGING_TYPE macro in the gcc sources. +</para> + +<para> + Many other options are available: please see <ulink + url="http://gcc.gnu.org/onlinedocs/gcc/Debugging-Options.html#Debugging%20Options">"Options + for Debugging Your Program"</ulink> in Using the GNU Compiler + Collection (GCC) for a complete list. +</para> +</sect2> + +<sect2 id="debug.req" xreflabel="debug.req"> +<title>Debug Versions of Library Binary Files</title> + +<para> + If you would like debug symbols in libstdc++, there are two ways to + build libstdc++ with debug flags. The first is to run make from the + toplevel in a freshly-configured tree with +</para> +<programlisting> + --enable-libstdcxx-debug +</programlisting> +<para>and perhaps</para> +<programlisting> + --enable-libstdcxx-debug-flags='...' +</programlisting> +<para> + to create a separate debug build. Both the normal build and the + debug build will persist, without having to specify + <code>CXXFLAGS</code>, and the debug library will be installed in a + separate directory tree, in <code>(prefix)/lib/debug</code>. For + more information, look at the <ulink + url="configopts.html">configuration options</ulink> document. +</para> + +<para> + A second approach is to use the configuration flags +</para> +<programlisting> + make CXXFLAGS='-g3 -O0' all +</programlisting> + +<para> + This quick and dirty approach is often sufficient for quick + debugging tasks, when you cannot or don't want to recompile your + application to use the <ulink url="#safe">debug mode</ulink>.</para> +</sect2> + +<sect2 id="debug.memory" xreflabel="debug.memory"> +<title>Memory Leak Hunting</title> + +<para> + There are various third party memory tracing and debug utilities + that can be used to provide detailed memory allocation information + about C++ code. An exhaustive list of tools is not going to be + attempted, but includes <code>mtrace</code>, <code>valgrind</code>, + <code>mudflap</code>, and the non-free commercial product + <code>purify</code>. In addition, <code>libcwd</code> has a + replacement for the global new and delete operators that can track + memory allocation and deallocation and provide useful memory + statistics. +</para> + +<para> + Regardless of the memory debugging tool being used, there is one + thing of great importance to keep in mind when debugging C++ code + that uses <code>new</code> and <code>delete</code>: there are + different kinds of allocation schemes that can be used by <code> + std::allocator </code>. For implementation details, see the <ulink + url="ext/mt_allocator.html">mt allocator</ulink> documentation and + look specifically for <code>GLIBCXX_FORCE_NEW</code>. +</para> + +<para> + In a nutshell, the default allocator used by <code> + std::allocator</code> is a high-performance pool allocator, and can + give the mistaken impression that in a suspect executable, memory is + being leaked, when in reality the memory "leak" is a pool being used + by the library's allocator and is reclaimed after program + termination. +</para> + +<para> + For valgrind, there are some specific items to keep in mind. First + of all, use a version of valgrind that will work with current GNU + C++ tools: the first that can do this is valgrind 1.0.4, but later + versions should work at least as well. Second of all, use a + completely unoptimized build to avoid confusing valgrind. Third, use + GLIBCXX_FORCE_NEW to keep extraneous pool allocation noise from + cluttering debug information. +</para> + +<para> + Fourth, it may be necessary to force deallocation in other libraries + as well, namely the "C" library. On linux, this can be accomplished + with the appropriate use of the <code>__cxa_atexit</code> or + <code>atexit</code> functions. +</para> + +<programlisting> + #include <cstdlib> + + extern "C" void __libc_freeres(void); + + void do_something() { } + + int main() + { + atexit(__libc_freeres); + do_something(); + return 0; + } +</programlisting> + + +<para>or, using <code>__cxa_atexit</code>:</para> + +<programlisting> + extern "C" void __libc_freeres(void); + extern "C" int __cxa_atexit(void (*func) (void *), void *arg, void *d); + + void do_something() { } + + int main() + { + extern void* __dso_handle __attribute__ ((__weak__)); + __cxa_atexit((void (*) (void *)) __libc_freeres, NULL, + &__dso_handle ? __dso_handle : NULL); + do_test(); + return 0; + } +</programlisting> + +<para> + Suggested valgrind flags, given the suggestions above about setting + up the runtime environment, library, and test file, might be: +</para> +<programlisting> + valgrind -v --num-callers=20 --leak-check=yes --leak-resolution=high --show-reachable=yes a.out +</programlisting> + +</sect2> + +<sect2 id="debug.gdb" xreflabel="debug.gdb"> +<title>Using <command>gdb</command></title> + <para> + </para> + +<para> + Many options are available for gdb itself: please see <ulink + url="http://sources.redhat.com/gdb/current/onlinedocs/gdb_13.html#SEC109"> + "GDB features for C++" </ulink> in the gdb documentation. Also + recommended: the other parts of this manual. +</para> + +<para> + These settings can either be switched on in at the gdb command line, + or put into a .gdbint file to establish default debugging + characteristics, like so: +</para> + +<programlisting> + set print pretty on + set print object on + set print static-members on + set print vtbl on + set print demangle on + set demangle-style gnu-v3 +</programlisting> +</sect2> + +<sect2 id="debug.exceptions" xreflabel="debug.exceptions"> +<title>Tracking uncaught exceptions</title> +<para> + The <link linkend="support.termination.verbose">verbose + termination handler</link> gives information about uncaught + exceptions which are killing the program. It is described in the + linked-to page. +</para> +</sect2> + +<sect2 id="debug.debug_mode" xreflabel="debug.debug_mode"> +<title>Debug Mode</title> + <para> The <link linkend="manual.ext.debug_mode">Debug Mode</link> + has compile and run-time checks for many containers. + </para> +</sect2> + +<sect2 id="debug.compile_time_checks" xreflabel="debug.compile_time_checks"> +<title>Compile Time Checking</title> + <para> The <link linkend="manual.ext.compile_checks">Compile-Time + Checks</link> Extension has compile-time checks for many algorithms. + </para> +</sect2> + +</sect1>
\ No newline at end of file diff --git a/libstdc++-v3/doc/xml/manual/debug_mode.xml b/libstdc++-v3/doc/xml/manual/debug_mode.xml new file mode 100644 index 00000000000..e5f3becd590 --- /dev/null +++ b/libstdc++-v3/doc/xml/manual/debug_mode.xml @@ -0,0 +1,888 @@ +<?xml version='1.0'?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" +[ ]> + +<chapter id="manual.ext.debug_mode" xreflabel="Debug Mode"> +<?dbhtml filename="debug_mode.html"?> + +<chapterinfo> + <keywordset> + <keyword> + C++ + </keyword> + <keyword> + library + </keyword> + <keyword> + debug + </keyword> + </keywordset> +</chapterinfo> + +<title>Debug Mode</title> + +<sect1 id="manual.ext.debug_mode.intro" xreflabel="Intro"> + <title>Intro</title> + <para> + By default, libstdc++ is built with efficiency in mind, and + therefore performs little or no error checking that is not + required by the C++ standard. This means that programs that + incorrectly use the C++ standard library will exhibit behavior + that is not portable and may not even be predictable, because they + tread into implementation-specific or undefined behavior. To + detect some of these errors before they can become problematic, + libstdc++ offers a debug mode that provides additional checking of + library facilities, and will report errors in the use of libstdc++ + as soon as they can be detected by emitting a description of the + problem to standard error and aborting the program. This debug + mode is available with GCC 3.4.0 and later versions. + </para> + + <para> + The libstdc++ debug mode performs checking for many areas of the + C++ standard, but the focus is on checking interactions among + standard iterators, containers, and algorithms, including: + </para> + + <itemizedlist> + <listitem><para><emphasis>Safe iterators</emphasis>: Iterators keep track of the + container whose elements they reference, so errors such as + incrementing a past-the-end iterator or dereferencing an iterator + that points to a container that has been destructed are diagnosed + immediately.</para></listitem> + + <listitem><para><emphasis>Algorithm preconditions</emphasis>: Algorithms attempt to + validate their input parameters to detect errors as early as + possible. For instance, the <code>set_intersection</code> + algorithm requires that its iterator + parameters <code>first1</code> and <code>last1</code> form a valid + iterator range, and that the sequence + [<code>first1</code>, <code>last1</code>) is sorted according to + the same predicate that was passed + to <code>set_intersection</code>; the libstdc++ debug mode will + detect an error if the sequence is not sorted or was sorted by a + different predicate.</para></listitem> + </itemizedlist> + +</sect1> + +<sect1 id="manual.ext.debug_mode.semantics" xreflabel="Semantics"> + <title>Semantics</title> + <para> + </para> + +<para>A program that uses the C++ standard library correctly + will maintain the same semantics under debug mode as it had with + the normal (release) library. All functional and exception-handling + guarantees made by the normal library also hold for the debug mode + library, with one exception: performance guarantees made by the + normal library may not hold in the debug mode library. For + instance, erasing an element in a <code>std::list</code> is a + constant-time operation in normal library, but in debug mode it is + linear in the number of iterators that reference that particular + list. So while your (correct) program won't change its results, it + is likely to execute more slowly.</para> + +<para>libstdc++ includes many extensions to the C++ standard library. In + some cases the extensions are obvious, such as the hashed + associative containers, whereas other extensions give predictable + results to behavior that would otherwise be undefined, such as + throwing an exception when a <code>std::basic_string</code> is + constructed from a NULL character pointer. This latter category also + includes implementation-defined and unspecified semantics, such as + the growth rate of a vector. Use of these extensions is not + considered incorrect, so code that relies on them will not be + rejected by debug mode. However, use of these extensions may affect + the portability of code to other implementations of the C++ standard + library, and is therefore somewhat hazardous. For this reason, the + libstdc++ debug mode offers a "pedantic" mode (similar to + GCC's <code>-pedantic</code> compiler flag) that attempts to emulate + the semantics guaranteed by the C++ standard. For + instance, constructing a <code>std::basic_string</code> with a NULL + character pointer would result in an exception under normal mode or + non-pedantic debug mode (this is a libstdc++ extension), whereas + under pedantic debug mode libstdc++ would signal an error. To enable + the pedantic debug mode, compile your program with + both <code>-D_GLIBCXX_DEBUG</code> + and <code>-D_GLIBCXX_DEBUG_PEDANTIC</code> . + (N.B. In GCC 3.4.x and 4.0.0, due to a bug, + <code>-D_GLIBXX_DEBUG_PEDANTIC</code> was also needed. The problem has + been fixed in GCC 4.0.1 and later versions.) </para> + +<para>The following library components provide extra debugging + capabilities in debug mode:</para> +<itemizedlist> + <listitem><para><code>std::basic_string</code> (no safe iterators and see note below)</para></listitem> + <listitem><para><code>std::bitset</code></para></listitem> + <listitem><para><code>std::deque</code></para></listitem> + <listitem><para><code>std::list</code></para></listitem> + <listitem><para><code>std::map</code></para></listitem> + <listitem><para><code>std::multimap</code></para></listitem> + <listitem><para><code>std::multiset</code></para></listitem> + <listitem><para><code>std::set</code></para></listitem> + <listitem><para><code>std::vector</code></para></listitem> + <listitem><para><code>std::unordered_map</code></para></listitem> + <listitem><para><code>std::unordered_multimap</code></para></listitem> + <listitem><para><code>std::unordered_set</code></para></listitem> + <listitem><para><code>std::unordered_multiset</code></para></listitem> +</itemizedlist> + +<para>N.B. although there are precondition checks for some string operations, +e.g. <code>operator[]</code>, +they will not always be run when using the <code>char</code> and +<code>wchar_t</code> specialisations (<code>std::string</code> and +<code>std::wstring</code>). This is because libstdc++ uses GCC's +<code>extern template</code> extension to provide explicit instantiations +of <code>std::string</code> and <code>std::wstring</code>, and those +explicit instantiations don't include the debug-mode checks. If the +containing functions are inlined then the checks will run, so compiling +with <code>-O1</code> might be enough to enable them. Alternatively +<code>-D_GLIBCXX_EXTERN_TEMPLATE=0</code> will suppress the declarations +of the explicit instantiations and cause the functions to be instantiated +with the debug-mode checks included, but this is unsupported and not +guaranteed to work. For full debug-mode support you can use the +<code>__gnu_debug::basic_string</code> debugging container directly, +which always works correctly. +</para> + +</sect1> + +<sect1 id="manual.ext.debug_mode.using" xreflabel="Using"> + <title>Using</title> + <para> + </para> +<sect2 id="debug_mode.using.mode" xreflabel="Using Mode"> + <title>Using the Debug Mode</title> + +<para>To use the libstdc++ debug mode, compile your application with the + compiler flag <code>-D_GLIBCXX_DEBUG</code>. Note that this flag + changes the sizes and behavior of standard class templates such + as <code>std::vector</code>, and therefore you can only link code + compiled with debug mode and code compiled without debug mode if no + instantiation of a container is passed between the two translation + units.</para> + +<para>By default, error messages are formatted to fit on lines of about + 78 characters. The environment variable + <code>GLIBCXX_DEBUG_MESSAGE_LENGTH</code> can be used to request a + different length.</para> + +</sect2> + +<sect2 id="debug_mode.using.specific" xreflabel="Using Specific"> + <title>Using a Specific Debug Container</title> +<para>When it is not feasible to recompile your entire application, or + only specific containers need checking, debugging containers are + available as GNU extensions. These debugging containers are + functionally equivalent to the standard drop-in containers used in + debug mode, but they are available in a separate namespace as GNU + extensions and may be used in programs compiled with either release + mode or with debug mode. The + following table provides the names and headers of the debugging + containers: +</para> + +<table frame='all'> +<title>Debugging Containers</title> +<tgroup cols='6' align='left' colsep='1' rowsep='1'> +<colspec colname='c1'></colspec> +<colspec colname='c2'></colspec> +<colspec colname='c3'></colspec> +<colspec colname='c4'></colspec> + +<thead> + <row> + <entry>Container</entry> + <entry>Header</entry> + <entry>Debug container</entry> + <entry>Debug header</entry> + </row> +</thead> +<tbody> + <row> + <entry><classname>std::bitset</classname></entry> + <entry><filename class="headerfile">bitset</filename></entry> + <entry><classname>__gnu_debug::bitset</classname></entry> + <entry><filename class="headerfile">bitset</filename></entry> + </row> + <row> + <entry><classname>std::deque</classname></entry> + <entry><filename class="headerfile">deque</filename></entry> + <entry><classname>__gnu_debug::deque</classname></entry> + <entry><filename class="headerfile">deque</filename></entry> + </row> + <row> + <entry><classname>std::list</classname></entry> + <entry><filename class="headerfile">list</filename></entry> + <entry><classname>__gnu_debug::list</classname></entry> + <entry><filename class="headerfile">list</filename></entry> + </row> + <row> + <entry><classname>std::map</classname></entry> + <entry><filename class="headerfile">map</filename></entry> + <entry><classname>__gnu_debug::map</classname></entry> + <entry><filename class="headerfile">map</filename></entry> + </row> + <row> + <entry><classname>std::multimap</classname></entry> + <entry><filename class="headerfile">map</filename></entry> + <entry><classname>__gnu_debug::multimap</classname></entry> + <entry><filename class="headerfile">map</filename></entry> + </row> + <row> + <entry><classname>std::multiset</classname></entry> + <entry><filename class="headerfile">set</filename></entry> + <entry><classname>__gnu_debug::multiset</classname></entry> + <entry><filename class="headerfile">set</filename></entry> + </row> + <row> + <entry><classname>std::set</classname></entry> + <entry><filename class="headerfile">set</filename></entry> + <entry><classname>__gnu_debug::set</classname></entry> + <entry><filename class="headerfile">set</filename></entry> + </row> + <row> + <entry><classname>std::string</classname></entry> + <entry><filename class="headerfile">string</filename></entry> + <entry><classname>__gnu_debug::string</classname></entry> + <entry><filename class="headerfile">string</filename></entry> + </row> + <row> + <entry><classname>std::wstring</classname></entry> + <entry><filename class="headerfile">string</filename></entry> + <entry><classname>__gnu_debug::wstring</classname></entry> + <entry><filename class="headerfile">string</filename></entry> + </row> + <row> + <entry><classname>std::basic_string</classname></entry> + <entry><filename class="headerfile">string</filename></entry> + <entry><classname>__gnu_debug::basic_string</classname></entry> + <entry><filename class="headerfile">string</filename></entry> + </row> + <row> + <entry><classname>std::vector</classname></entry> + <entry><filename class="headerfile">vector</filename></entry> + <entry><classname>__gnu_debug::vector</classname></entry> + <entry><filename class="headerfile">vector</filename></entry> + </row> +</tbody> +</tgroup> +</table> + +<para>In addition, when compiling in C++0x mode, these additional +containers have additional debug capability. +</para> + +<table frame='all'> +<title>Debugging Containers C++0x</title> +<tgroup cols='6' align='left' colsep='1' rowsep='1'> +<colspec colname='c1'></colspec> +<colspec colname='c2'></colspec> +<colspec colname='c3'></colspec> +<colspec colname='c4'></colspec> + +<thead> + <row> + <entry>Container</entry> + <entry>Header</entry> + <entry>Debug container</entry> + <entry>Debug header</entry> + </row> +</thead> +<tbody> + <row> + <entry><classname>std::unordered_map</classname></entry> + <entry><filename class="headerfile">unordered_map</filename></entry> + <entry><classname>__gnu_debug::unordered_map</classname></entry> + <entry><filename class="headerfile">unordered_map</filename></entry> + </row> + <row> + <entry><classname>std::unordered_multimap</classname></entry> + <entry><filename class="headerfile">unordered_map</filename></entry> + <entry><classname>__gnu_debug::unordered_multimap</classname></entry> + <entry><filename class="headerfile">unordered_map</filename></entry> + </row> + <row> + <entry><classname>std::unordered_set</classname></entry> + <entry><filename class="headerfile">unordered_set</filename></entry> + <entry><classname>__gnu_debug::unordered_set</classname></entry> + <entry><filename class="headerfile">unordered_set</filename></entry> + </row> + <row> + <entry><classname>std::unordered_multiset</classname></entry> + <entry><filename class="headerfile">unordered_set</filename></entry> + <entry><classname>__gnu_debug::unordered_multiset</classname></entry> + <entry><filename class="headerfile">unordered_set</filename></entry> + </row> +</tbody> +</tgroup> +</table> +</sect2> +</sect1> + +<sect1 id="manual.ext.debug_mode.design" xreflabel="Design"> + <title>Design</title> + <para> + </para> + <sect2 id="manual.ext.debug_mode.design.goals" xreflabel="Goals"> + <title>Goals</title> + <para> + </para> +<para> The libstdc++ debug mode replaces unsafe (but efficient) standard + containers and iterators with semantically equivalent safe standard + containers and iterators to aid in debugging user programs. The + following goals directed the design of the libstdc++ debug mode:</para> + + <itemizedlist> + + <listitem><para><emphasis>Correctness</emphasis>: the libstdc++ debug mode must not change + the semantics of the standard library for all cases specified in + the ANSI/ISO C++ standard. The essence of this constraint is that + any valid C++ program should behave in the same manner regardless + of whether it is compiled with debug mode or release mode. In + particular, entities that are defined in namespace std in release + mode should remain defined in namespace std in debug mode, so that + legal specializations of namespace std entities will remain + valid. A program that is not valid C++ (e.g., invokes undefined + behavior) is not required to behave similarly, although the debug + mode will abort with a diagnostic when it detects undefined + behavior.</para></listitem> + + <listitem><para><emphasis>Performance</emphasis>: the additional of the libstdc++ debug mode + must not affect the performance of the library when it is compiled + in release mode. Performance of the libstdc++ debug mode is + secondary (and, in fact, will be worse than the release + mode).</para></listitem> + + <listitem><para><emphasis>Usability</emphasis>: the libstdc++ debug mode should be easy to + use. It should be easily incorporated into the user's development + environment (e.g., by requiring only a single new compiler switch) + and should produce reasonable diagnostics when it detects a + problem with the user program. Usability also involves detection + of errors when using the debug mode incorrectly, e.g., by linking + a release-compiled object against a debug-compiled object if in + fact the resulting program will not run correctly.</para></listitem> + + <listitem><para><emphasis>Minimize recompilation</emphasis>: While it is expected that + users recompile at least part of their program to use debug + mode, the amount of recompilation affects the + detect-compile-debug turnaround time. This indirectly affects the + usefulness of the debug mode, because debugging some applications + may require rebuilding a large amount of code, which may not be + feasible when the suspect code may be very localized. There are + several levels of conformance to this requirement, each with its + own usability and implementation characteristics. In general, the + higher-numbered conformance levels are more usable (i.e., require + less recompilation) but are more complicated to implement than + the lower-numbered conformance levels. + <orderedlist> + <listitem><para><emphasis>Full recompilation</emphasis>: The user must recompile his or + her entire application and all C++ libraries it depends on, + including the C++ standard library that ships with the + compiler. This must be done even if only a small part of the + program can use debugging features.</para></listitem> + + <listitem><para><emphasis>Full user recompilation</emphasis>: The user must recompile + his or her entire application and all C++ libraries it depends + on, but not the C++ standard library itself. This must be done + even if only a small part of the program can use debugging + features. This can be achieved given a full recompilation + system by compiling two versions of the standard library when + the compiler is installed and linking against the appropriate + one, e.g., a multilibs approach.</para></listitem> + + <listitem><para><emphasis>Partial recompilation</emphasis>: The user must recompile the + parts of his or her application and the C++ libraries it + depends on that will use the debugging facilities + directly. This means that any code that uses the debuggable + standard containers would need to be recompiled, but code + that does not use them (but may, for instance, use IOStreams) + would not have to be recompiled.</para></listitem> + + <listitem><para><emphasis>Per-use recompilation</emphasis>: The user must recompile the + parts of his or her application and the C++ libraries it + depends on where debugging should occur, and any other code + that interacts with those containers. This means that a set of + translation units that accesses a particular standard + container instance may either be compiled in release mode (no + checking) or debug mode (full checking), but must all be + compiled in the same way; a translation unit that does not see + that standard container instance need not be recompiled. This + also means that a translation unit <emphasis>A</emphasis> that contains a + particular instantiation + (say, <code>std::vector<int></code>) compiled in release + mode can be linked against a translation unit <emphasis>B</emphasis> that + contains the same instantiation compiled in debug mode (a + feature not present with partial recompilation). While this + behavior is technically a violation of the One Definition + Rule, this ability tends to be very important in + practice. The libstdc++ debug mode supports this level of + recompilation. </para></listitem> + + <listitem><para><emphasis>Per-unit recompilation</emphasis>: The user must only + recompile the translation units where checking should occur, + regardless of where debuggable standard containers are + used. This has also been dubbed "<code>-g</code> mode", + because the <code>-g</code> compiler switch works in this way, + emitting debugging information at a per--translation-unit + granularity. We believe that this level of recompilation is in + fact not possible if we intend to supply safe iterators, leave + the program semantics unchanged, and not regress in + performance under release mode because we cannot associate + extra information with an iterator (to form a safe iterator) + without either reserving that space in release mode + (performance regression) or allocating extra memory associated + with each iterator with <code>new</code> (changes the program + semantics).</para></listitem> + </orderedlist> + </para></listitem> + </itemizedlist> + </sect2> + + <sect2 id="manual.ext.debug_mode.design.methods" xreflabel="Methods"> + <title>Methods</title> + <para> + </para> +<para>This section provides an overall view of the design of the + libstdc++ debug mode and details the relationship between design + decisions and the stated design goals.</para> + + <sect3 id="debug_mode.design.methods.wrappers" xreflabel="Method Wrapper"> + <title>The Wrapper Model</title> +<para>The libstdc++ debug mode uses a wrapper model where the debugging + versions of library components (e.g., iterators and containers) form + a layer on top of the release versions of the library + components. The debugging components first verify that the operation + is correct (aborting with a diagnostic if an error is found) and + will then forward to the underlying release-mode container that will + perform the actual work. This design decision ensures that we cannot + regress release-mode performance (because the release-mode + containers are left untouched) and partially enables <ulink url="#mixing">mixing debug and release code</ulink> at link time, + although that will not be discussed at this time.</para> + +<para>Two types of wrappers are used in the implementation of the debug + mode: container wrappers and iterator wrappers. The two types of + wrappers interact to maintain relationships between iterators and + their associated containers, which are necessary to detect certain + types of standard library usage errors such as dereferencing + past-the-end iterators or inserting into a container using an + iterator from a different container.</para> + + <sect4 id="debug_mode.design.methods.safe_iter" xreflabel="Method Safe Iter"> + <title>Safe Iterators</title> +<para>Iterator wrappers provide a debugging layer over any iterator that + is attached to a particular container, and will manage the + information detailing the iterator's state (singular, + dereferenceable, etc.) and tracking the container to which the + iterator is attached. Because iterators have a well-defined, common + interface the iterator wrapper is implemented with the iterator + adaptor class template <code>__gnu_debug::_Safe_iterator</code>, + which takes two template parameters:</para> + +<itemizedlist> + <listitem><para><code>Iterator</code>: The underlying iterator type, which must + be either the <code>iterator</code> or <code>const_iterator</code> + typedef from the sequence type this iterator can reference.</para></listitem> + + <listitem><para><code>Sequence</code>: The type of sequence that this iterator + references. This sequence must be a safe sequence (discussed below) + whose <code>iterator</code> or <code>const_iterator</code> typedef + is the type of the safe iterator.</para></listitem> +</itemizedlist> + </sect4> + + <sect4 id="debug_mode.design.methods.safe_seq" xreflabel="Method Safe Seq"> + <title>Safe Sequences (Containers)</title> + +<para>Container wrappers provide a debugging layer over a particular + container type. Because containers vary greatly in the member + functions they support and the semantics of those member functions + (especially in the area of iterator invalidation), container + wrappers are tailored to the container they reference, e.g., the + debugging version of <code>std::list</code> duplicates the entire + interface of <code>std::list</code>, adding additional semantic + checks and then forwarding operations to the + real <code>std::list</code> (a public base class of the debugging + version) as appropriate. However, all safe containers inherit from + the class template <code>__gnu_debug::_Safe_sequence</code>, + instantiated with the type of the safe container itself (an instance + of the curiously recurring template pattern).</para> + +<para>The iterators of a container wrapper will be + <ulink url="#safe_iterator">safe iterators</ulink> that reference sequences + of this type and wrap the iterators provided by the release-mode + base class. The debugging container will use only the safe + iterators within its own interface (therefore requiring the user to + use safe iterators, although this does not change correct user + code) and will communicate with the release-mode base class with + only the underlying, unsafe, release-mode iterators that the base + class exports.</para> + +<para> The debugging version of <code>std::list</code> will have the + following basic structure:</para> + +<programlisting> +template<typename _Tp, typename _Allocator = allocator<_Tp> + class debug-list : + public release-list<_Tp, _Allocator>, + public __gnu_debug::_Safe_sequence<debug-list<_Tp, _Allocator> > + { + typedef release-list<_Tp, _Allocator> _Base; + typedef debug-list<_Tp, _Allocator> _Self; + + public: + typedef __gnu_debug::_Safe_iterator<typename _Base::iterator, _Self> iterator; + typedef __gnu_debug::_Safe_iterator<typename _Base::const_iterator, _Self> const_iterator; + + // duplicate std::list interface with debugging semantics + }; +</programlisting> + </sect4> + </sect3> + + <sect3 id="debug_mode.design.methods.precond" xreflabel="Precondition check"> + <title>Precondition Checking</title> +<para>The debug mode operates primarily by checking the preconditions of + all standard library operations that it supports. Preconditions that + are always checked (regardless of whether or not we are in debug + mode) are checked via the <code>__check_xxx</code> macros defined + and documented in the source + file <code>include/debug/debug.h</code>. Preconditions that may or + may not be checked, depending on the debug-mode + macro <code>_GLIBCXX_DEBUG</code>, are checked via + the <code>__requires_xxx</code> macros defined and documented in the + same source file. Preconditions are validated using any additional + information available at run-time, e.g., the containers that are + associated with a particular iterator, the position of the iterator + within those containers, the distance between two iterators that may + form a valid range, etc. In the absence of suitable information, + e.g., an input iterator that is not a safe iterator, these + precondition checks will silently succeed.</para> + +<para>The majority of precondition checks use the aforementioned macros, + which have the secondary benefit of having prewritten debug + messages that use information about the current status of the + objects involved (e.g., whether an iterator is singular or what + sequence it is attached to) along with some static information + (e.g., the names of the function parameters corresponding to the + objects involved). When not using these macros, the debug mode uses + either the debug-mode assertion + macro <code>_GLIBCXX_DEBUG_ASSERT</code> , its pedantic + cousin <code>_GLIBCXX_DEBUG_PEDASSERT</code>, or the assertion + check macro that supports more advance formulation of error + messages, <code>_GLIBCXX_DEBUG_VERIFY</code>. These macros are + documented more thoroughly in the debug mode source code.</para> + </sect3> + + <sect3 id="debug_mode.design.methods.coexistence" xreflabel="Coexistence"> + <title>Release- and debug-mode coexistence</title> +<para>The libstdc++ debug mode is the first debug mode we know of that + is able to provide the "Per-use recompilation" (4) guarantee, that + allows release-compiled and debug-compiled code to be linked and + executed together without causing unpredictable behavior. This + guarantee minimizes the recompilation that users are required to + perform, shortening the detect-compile-debug bughunting cycle + and making the debug mode easier to incorporate into development + environments by minimizing dependencies.</para> + +<para>Achieving link- and run-time coexistence is not a trivial + implementation task. To achieve this goal we required a small + extension to the GNU C++ compiler (described in the GCC Manual for + C++ Extensions, see <ulink url="http://gcc.gnu.org/onlinedocs/gcc/Strong-Using.html">strong + using</ulink>), and a complex organization of debug- and + release-modes. The end result is that we have achieved per-use + recompilation but have had to give up some checking of the + <code>std::basic_string</code> class template (namely, safe + iterators). +</para> + + <sect4 id="methods.coexistence.compile" xreflabel="Compile"> + <title>Compile-time coexistence of release- and debug-mode components</title> + +<para>Both the release-mode components and the debug-mode + components need to exist within a single translation unit so that + the debug versions can wrap the release versions. However, only one + of these components should be user-visible at any particular + time with the standard name, e.g., <code>std::list</code>. </para> + +<para>In release mode, we define only the release-mode version of the + component with its standard name and do not include the debugging + component at all. The release mode version is defined within the + namespace <code>std</code>. Minus the namespace associations, this + method leaves the behavior of release mode completely unchanged from + its behavior prior to the introduction of the libstdc++ debug + mode. Here's an example of what this ends up looking like, in + C++.</para> + +<programlisting> +namespace std +{ + template<typename _Tp, typename _Alloc = allocator<_Tp> > + class list + { + // ... + }; +} // namespace std +</programlisting> + +<para>In debug mode we include the release-mode container (which is now +defined in in the namespace <code>__norm</code>) and also the +debug-mode container. The debug-mode container is defined within the +namespace <code>__debug</code>, which is associated with namespace +<code>std</code> via the GNU namespace association extension. This +method allows the debug and release versions of the same component to +coexist at compile-time and link-time without causing an unreasonable +maintenance burden, while minimizing confusion. Again, this boils down +to C++ code as follows:</para> + +<programlisting> +namespace std +{ + namespace __norm + { + template<typename _Tp, typename _Alloc = allocator<_Tp> > + class list + { + // ... + }; + } // namespace __gnu_norm + + namespace __debug + { + template<typename _Tp, typename _Alloc = allocator<_Tp> > + class list + : public __norm::list<_Tp, _Alloc>, + public __gnu_debug::_Safe_sequence<list<_Tp, _Alloc> > + { + // ... + }; + } // namespace __norm + + using namespace __debug __attribute__ ((strong)); +} +</programlisting> + </sect4> + + <sect4 id="methods.coexistence.link" xreflabel="Link"> + <title>Link- and run-time coexistence of release- and + debug-mode components</title> + +<para>Because each component has a distinct and separate release and +debug implementation, there are are no issues with link-time +coexistence: the separate namespaces result in different mangled +names, and thus unique linkage.</para> + +<para>However, components that are defined and used within the C++ +standard library itself face additional constraints. For instance, +some of the member functions of <code> std::moneypunct</code> return +<code>std::basic_string</code>. Normally, this is not a problem, but +with a mixed mode standard library that could be using either +debug-mode or release-mode <code> basic_string</code> objects, things +get more complicated. As the return value of a function is not +encoded into the mangled name, there is no way to specify a +release-mode or a debug-mode string. In practice, this results in +runtime errors. A simplified example of this problem is as follows. +</para> + +<para> Take this translation unit, compiled in debug-mode: </para> +<programlisting> +// -D_GLIBCXX_DEBUG +#include <string> + +std::string test02(); + +std::string test01() +{ + return test02(); +} + +int main() +{ + test01(); + return 0; +} +</programlisting> + +<para> ... and linked to this translation unit, compiled in release mode:</para> + +<programlisting> +#include <string> + +std::string +test02() +{ + return std::string("toast"); +} +</programlisting> + +<para> For this reason we cannot easily provide safe iterators for + the <code>std::basic_string</code> class template, as it is present + throughout the C++ standard library. For instance, locale facets + define typedefs that include <code>basic_string</code>: in a mixed + debug/release program, should that typedef be based on the + debug-mode <code>basic_string</code> or the + release-mode <code>basic_string</code>? While the answer could be + "both", and the difference hidden via renaming a la the + debug/release containers, we must note two things about locale + facets:</para> + +<orderedlist> + <listitem><para>They exist as shared state: one can create a facet in one + translation unit and access the facet via the same type name in a + different translation unit. This means that we cannot have two + different versions of locale facets, because the types would not be + the same across debug/release-mode translation unit barriers.</para></listitem> + + <listitem><para>They have virtual functions returning strings: these functions + mangle in the same way regardless of the mangling of their return + types (see above), and their precise signatures can be relied upon + by users because they may be overridden in derived classes.</para></listitem> +</orderedlist> + +<para>With the design of libstdc++ debug mode, we cannot effectively hide + the differences between debug and release-mode strings from the + user. Failure to hide the differences may result in unpredictable + behavior, and for this reason we have opted to only + perform <code>basic_string</code> changes that do not require ABI + changes. The effect on users is expected to be minimal, as there are + simple alternatives (e.g., <code>__gnu_debug::basic_string</code>), + and the usability benefit we gain from the ability to mix debug- and + release-compiled translation units is enormous.</para> + </sect4> + + <sect4 id="methods.coexistence.alt" xreflabel="Alternatives"> +<title>Alternatives for Coexistence</title> + +<para>The coexistence scheme above was chosen over many alternatives, + including language-only solutions and solutions that also required + extensions to the C++ front end. The following is a partial list of + solutions, with justifications for our rejection of each.</para> + +<itemizedlist> + <listitem><para><emphasis>Completely separate debug/release libraries</emphasis>: This is by + far the simplest implementation option, where we do not allow any + coexistence of debug- and release-compiled translation units in a + program. This solution has an extreme negative affect on usability, + because it is quite likely that some libraries an application + depends on cannot be recompiled easily. This would not meet + our <emphasis>usability</emphasis> or <emphasis>minimize recompilation</emphasis> criteria + well.</para></listitem> + + <listitem><para><emphasis>Add a <code>Debug</code> boolean template parameter</emphasis>: + Partial specialization could be used to select the debug + implementation when <code>Debug == true</code>, and the state + of <code>_GLIBCXX_DEBUG</code> could decide whether the + default <code>Debug</code> argument is <code>true</code> + or <code>false</code>. This option would break conformance with the + C++ standard in both debug <emphasis>and</emphasis> release modes. This would + not meet our <emphasis>correctness</emphasis> criteria. </para></listitem> + + <listitem><para><emphasis>Packaging a debug flag in the allocators</emphasis>: We could + reuse the <code>Allocator</code> template parameter of containers + by adding a sentinel wrapper <code>debug<></code> that + signals the user's intention to use debugging, and pick up + the <code>debug<></code> allocator wrapper in a partial + specialization. However, this has two drawbacks: first, there is a + conformance issue because the default allocator would not be the + standard-specified <code>std::allocator<T></code>. Secondly + (and more importantly), users that specify allocators instead of + implicitly using the default allocator would not get debugging + containers. Thus this solution fails the <emphasis>correctness</emphasis> + criteria.</para></listitem> + + <listitem><para><emphasis>Define debug containers in another namespace, and employ + a <code>using</code> declaration (or directive)</emphasis>: This is an + enticing option, because it would eliminate the need for + the <code>link_name</code> extension by aliasing the + templates. However, there is no true template aliasing mechanism + is C++, because both <code>using</code> directives and using + declarations disallow specialization. This method fails + the <emphasis>correctness</emphasis> criteria.</para></listitem> + + <listitem><para><emphasis> Use implementation-specific properties of anonymous + namespaces. </emphasis> + See <ulink url="http://gcc.gnu.org/ml/libstdc++/2003-08/msg00004.html"> this post + </ulink> + This method fails the <emphasis>correctness</emphasis> criteria.</para></listitem> + + <listitem><para><emphasis>Extension: allow reopening on namespaces</emphasis>: This would + allow the debug mode to effectively alias the + namespace <code>std</code> to an internal namespace, such + as <code>__gnu_std_debug</code>, so that it is completely + separate from the release-mode <code>std</code> namespace. While + this will solve some renaming problems and ensure that + debug- and release-compiled code cannot be mixed unsafely, it ensures that + debug- and release-compiled code cannot be mixed at all. For + instance, the program would have two <code>std::cout</code> + objects! This solution would fails the <emphasis>minimize + recompilation</emphasis> requirement, because we would only be able to + support option (1) or (2).</para></listitem> + + <listitem><para><emphasis>Extension: use link name</emphasis>: This option involves + complicated re-naming between debug-mode and release-mode + components at compile time, and then a g++ extension called <emphasis> + link name </emphasis> to recover the original names at link time. There + are two drawbacks to this approach. One, it's very verbose, + relying on macro renaming at compile time and several levels of + include ordering. Two, ODR issues remained with container member + functions taking no arguments in mixed-mode settings resulting in + equivalent link names, <code> vector::push_back() </code> being + one example. + See <ulink url="http://gcc.gnu.org/ml/libstdc++/2003-08/msg00177.html">link + name</ulink> </para></listitem> +</itemizedlist> + +<para>Other options may exist for implementing the debug mode, many of + which have probably been considered and others that may still be + lurking. This list may be expanded over time to include other + options that we could have implemented, but in all cases the full + ramifications of the approach (as measured against the design goals + for a libstdc++ debug mode) should be considered first. The DejaGNU + testsuite includes some testcases that check for known problems with + some solutions (e.g., the <code>using</code> declaration solution + that breaks user specialization), and additional testcases will be + added as we are able to identify other typical problem cases. These + test cases will serve as a benchmark by which we can compare debug + mode implementations.</para> + </sect4> + </sect3> + </sect2> + + <sect2 id="manual.ext.debug_mode.design.other" xreflabel="Other"> + <title>Other Implementations</title> + <para> + </para> +<para> There are several existing implementations of debug modes for C++ + standard library implementations, although none of them directly + supports debugging for programs using libstdc++. The existing + implementations include:</para> +<itemizedlist> + <listitem><para><ulink url="http://www.mathcs.sjsu.edu/faculty/horstman/safestl.html">SafeSTL</ulink>: + SafeSTL was the original debugging version of the Standard Template + Library (STL), implemented by Cay S. Horstmann on top of the + Hewlett-Packard STL. Though it inspired much work in this area, it + has not been kept up-to-date for use with modern compilers or C++ + standard library implementations.</para></listitem> + + <listitem><para><ulink url="http://www.stlport.org/">STLport</ulink>: STLport is a free + implementation of the C++ standard library derived from the <ulink url="http://www.sgi.com/tech/stl/">SGI implementation</ulink>, and + ported to many other platforms. It includes a debug mode that uses a + wrapper model (that in some way inspired the libstdc++ debug mode + design), although at the time of this writing the debug mode is + somewhat incomplete and meets only the "Full user recompilation" (2) + recompilation guarantee by requiring the user to link against a + different library in debug mode vs. release mode.</para></listitem> + + <listitem><para><ulink url="http://www.metrowerks.com/mw/default.htm">Metrowerks + CodeWarrior</ulink>: The C++ standard library that ships with Metrowerks + CodeWarrior includes a debug mode. It is a full debug-mode + implementation (including debugging for CodeWarrior extensions) and + is easy to use, although it meets only the "Full recompilation" (1) + recompilation guarantee.</para></listitem> +</itemizedlist> + + </sect2> +</sect1> + +</chapter> diff --git a/libstdc++-v3/doc/xml/manual/diagnostics.xml b/libstdc++-v3/doc/xml/manual/diagnostics.xml new file mode 100644 index 00000000000..f43614c861e --- /dev/null +++ b/libstdc++-v3/doc/xml/manual/diagnostics.xml @@ -0,0 +1,126 @@ +<?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.diagnostics" xreflabel="Diagnostics"> +<?dbhtml filename="diagnostics.html"?> + +<partinfo> + <keywordset> + <keyword> + ISO C++ + </keyword> + <keyword> + library + </keyword> + </keywordset> +</partinfo> + +<title>Diagnostics</title> + +<chapter id="manual.diagnostics.exceptions" xreflabel="Exceptions"> + <title>Exceptions</title> + + <sect1 id="manual.diagnostics.exceptions.hierarchy" xreflabel="Exception Classes"> + <title>Exception Classes</title> + <para> + All exception objects are defined in one of the standard header + files: <filename>exception</filename>, + <filename>stdexcept</filename>, <filename>new</filename>, and + <filename>typeinfo</filename>. + </para> + + <para> + The base exception object is <classname>exception</classname>, + located in <filename>exception</filename>. This object has no + <classname>string</classname> member. + </para> + + <para> + Derived from this are several classes that may have a + <classname>string</classname> member: a full heirarchy can be + found in the <ulink url="http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/a00233.html">source documentation</ulink>. + </para> + + </sect1> + <sect1 id="manual.diagnostics.exceptions.data" xreflabel="Adding Data to Exceptions"> + <title>Adding Data to Exceptions</title> + <para> + The standard exception classes carry with them a single string as + data (usually describing what went wrong or where the 'throw' took + place). It's good to remember that you can add your own data to + these exceptions when extending the hierarchy: + </para> + <programlisting> + struct My_Exception : public std::runtime_error + { + public: + My_Exception (const string& whatarg) + : std::runtime_error(whatarg), e(errno), id(GetDataBaseID()) { } + int errno_at_time_of_throw() const { return e; } + DBID id_of_thing_that_threw() const { return id; } + protected: + int e; + DBID id; // some user-defined type + }; + </programlisting> + + </sect1> + <sect1 id="manual.diagnostics.exceptions.cancellation" xreflabel="Cancellation"> + <title>Cancellation</title> + <para> + </para> + </sect1> +</chapter> + +<chapter id="manual.diagnostics.concept_checking" xreflabel="Concept Checking"> + <title>Concept Checking</title> + <para> + In 1999, SGI added <quote>concept checkers</quote> 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 <classname>vector</classname> be + "Assignable" (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. + 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 + <literal>-D_GLIBCXX_CONCEPT_CHECKS</literal>. + </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> + +</part> diff --git a/libstdc++-v3/doc/xml/manual/evolution.xml b/libstdc++-v3/doc/xml/manual/evolution.xml new file mode 100644 index 00000000000..296e228311a --- /dev/null +++ b/libstdc++-v3/doc/xml/manual/evolution.xml @@ -0,0 +1,452 @@ +<sect1 id="appendix.porting.api" xreflabel="api"> +<?dbhtml filename="api.html"?> + +<sect1info> + <keywordset> + <keyword>ISO C++</keyword> + <keyword>api</keyword> + <keyword>evolution</keyword> + <keyword>deprecation</keyword> + <keyword>history</keyword> + </keywordset> +</sect1info> + +<title>API Evolution and Deprecation History</title> + +<para> +A list of user-visible changes, in cronological order +</para> + +<sect2 id="api.rel_300" xreflabel="api.rel_300"> +<title><constant>3.0</constant></title> + + <para> +Extensions moved to <filename class="directory">include/ext</filename>. + </para> + +<para> +Include files from the SGI/HP sources that pre-date the ISO standard +are added. These files are placed into +the <filename class="directory">include/backward</filename> directory and a deprecated warning +is added that notifies on inclusion (<literal>-Wno-deprecated</literal> +deactivates the warning.) +</para> + +<para>Deprecated include <filename class="headerfile">backward/strstream</filename> added.</para> + +<para>Removal of include <filename class="headerfile">builtinbuf.h</filename>, <filename class="headerfile">indstream.h</filename>, <filename class="headerfile">parsestream.h</filename>, <filename class="headerfile">PlotFile.h</filename>, <filename class="headerfile">SFile.h</filename>, <filename class="headerfile">stdiostream.h</filename>, and <filename class="headerfile">stream.h</filename>. +</para> + + + +</sect2> + +<sect2 id="api.rel_310" xreflabel="api.rel_310"> +<title><constant>3.1</constant></title> + <para> + </para> + +<para> +Extensions from SGI/HP moved from <code>namespace std</code> +to <code>namespace __gnu_cxx</code>. As part of this, the following +new includes are +added: <filename class="headerfile">ext/algorithm</filename>, <filename class="headerfile">ext/functional</filename>, <filename class="headerfile">ext/iterator</filename>, <filename class="headerfile">ext/memory</filename>, and <filename class="headerfile">ext/numeric</filename>. +</para> + +<para> +Extensions to <code>basic_filebuf</code> introduced: <code>__gnu_cxx::enc_filebuf</code>, and <code>__gnu_cxx::stdio_filebuf</code>. +</para> + +<para> +Extensions to tree data structures added in <filename class="headerfile">ext/rb_tree</filename>. +</para> + +<para> +Removal of <filename class="headerfile">ext/tree</filename>, moved to <filename class="headerfile">backward/tree.h</filename>. +</para> + +</sect2> + +<sect2 id="api.rel_320" xreflabel="api.rel_320"> +<title><constant>3.2</constant></title> + <para> + </para> +<para>Symbol versioning introduced for shared library.</para> + +<para>Removal of include <filename class="headerfile">backward/strstream.h</filename>.</para> + +<para>Allocator changes. Change <code>__malloc_alloc</code> to <code>malloc_allocator</code> and <code>__new_alloc</code> to <code>new_allocator</code>. </para> + + <para> For GCC releases from 2.95 through the 3.1 series, defining + <literal>__USE_MALLOC</literal> on the gcc command line would change the + default allocation strategy to instead use <code> malloc</code> and + <function>free</function>. See + <ulink url="../23_containers/howto.html#3">this note</ulink> + for details as to why this was something needing improvement. + </para> + + +<para>Error handling in iostreams cleaned up, made consistent. </para> + + +</sect2> + +<sect2 id="api.rel_330" xreflabel="api.rel_330"> +<title><constant>3.3</constant></title> + <para> + </para> +</sect2> + +<sect2 id="api.rel_340" xreflabel="api.rel_340"> +<title><constant>3.4</constant></title> + <para> + </para> +<para> +Large file support. +</para> + +<para> Extensions for generic characters and <code>char_traits</code> added in <filename class="headerfile">ext/pod_char_traits.h</filename>. +</para> + +<para> +Support for <code>wchar_t</code> specializations of <code>basic_filebuf</code> enhanced to support <code>UTF-8</code> and <code>Unicode</code>, depending on host. More hosts support basic <code>wchar_t</code> functionality. +</para> + +<para> +Support for <code>char_traits</code> beyond builtin types. +</para> + +<para> +Conformant <code>allocator</code> class and usage in containers. As +part of this, the following extensions are +added: <filename class="headerfile">ext/bitmap_allocator.h</filename>, <filename class="headerfile">ext/debug_allocator.h</filename>, <filename class="headerfile">ext/mt_allocator.h</filename>, <filename class="headerfile">ext/malloc_allocator.h</filename>,<filename class="headerfile">ext/new_allocator.h</filename>, <filename class="headerfile">ext/pool_allocator.h</filename>. +</para> + +<para> +This is a change from all previous versions, and may require +source-level changes due to allocator-related changes to structures +names and template parameters, filenames, and file locations. Some, +like <code>__simple_alloc, __allocator, __alloc, </code> and <code> +_Alloc_traits</code> have been removed. +</para> + +<para>Default behavior of <code>std::allocator</code> has changed.</para> + +<para> + Previous versions prior to 3.4 cache allocations in a memory + pool, instead of passing through to call the global allocation + operators (ie, <classname>__gnu_cxx::pool_allocator</classname>). More + recent versions default to the + simpler <classname>__gnu_cxx::new_allocator</classname>. +</para> + +<para> Previously, all allocators were written to the SGI + style, and all STL containers expected this interface. This + interface had a traits class called <code>_Alloc_traits</code> that + attempted to provide more information for compile-time allocation + selection and optimization. This traits class had another allocator + wrapper, <code>__simple_alloc<T,A></code>, which was a + wrapper around another allocator, A, which itself is an allocator + for instances of T. But wait, there's more: + <code>__allocator<T,A></code> is another adapter. Many of + the provided allocator classes were SGI style: such classes can be + changed to a conforming interface with this wrapper: + <code>__allocator<T, __alloc></code> is thus the same as + <code>allocator<T></code>. + </para> + + <para> The class <classname>allocator</classname> used the typedef + <type>__alloc</type> to select an underlying allocator that + satisfied memory allocation requests. The selection of this + underlying allocator was not user-configurable. + </para> + +<table frame='all'> +<title>Extension Allocators</title> +<tgroup cols='4' align='left' colsep='1' rowsep='1'> +<colspec colname='c1'></colspec> +<colspec colname='c2'></colspec> +<colspec colname='c3'></colspec> +<colspec colname='c4'></colspec> + + <thead> + <row> + <entry>Allocator (3.4)</entry> + <entry>Header (3.4)</entry> + <entry>Allocator (3.[0-3])</entry> + <entry>Header (3.[0-3])</entry> + </row> + </thead> + + <tbody> + <row> + <entry><classname>__gnu_cxx::new_allocator<T></classname></entry> + <entry><filename class="headerfile">ext/new_allocator.h</filename></entry> + <entry><classname>std::__new_alloc</classname></entry> + <entry><filename class="headerfile">memory</filename></entry> + </row> + <row> + <entry><classname>__gnu_cxx::malloc_allocator<T></classname></entry> + <entry><filename class="headerfile">ext/malloc_allocator.h</filename></entry> + <entry><classname>std::__malloc_alloc_template<int></classname></entry> + <entry><filename class="headerfile">memory</filename></entry> + </row> + <row> + <entry><classname>__gnu_cxx::debug_allocator<T></classname></entry> + <entry><filename class="headerfile">ext/debug_allocator.h</filename></entry> + <entry><classname>std::debug_alloc<T></classname></entry> + <entry><filename class="headerfile">memory</filename></entry> + </row> + <row> + <entry><classname>__gnu_cxx::__pool_alloc<T></classname></entry> + <entry><filename class="headerfile">ext/pool_allocator.h</filename></entry> + <entry><classname>std::__default_alloc_template<bool,int></classname></entry> + <entry><filename class="headerfile">memory</filename></entry> + </row> + <row> + <entry><classname>__gnu_cxx::__mt_alloc<T></classname></entry> + <entry><filename class="headerfile">ext/mt_allocator.h</filename></entry> + <entry> </entry> + <entry> </entry> + </row> + <row> + <entry><classname>__gnu_cxx::bitmap_allocator<T></classname></entry> + <entry><filename class="headerfile">ext/bitmap_allocator.h</filename></entry> + <entry> </entry> + <entry> </entry> + </row> + </tbody> +</tgroup> +</table> + + <para> Releases after gcc-3.4 have continued to add to the collection + of available allocators. All of these new allocators are + standard-style. The following table includes details, along with + the first released version of GCC that included the extension allocator. + </para> + +<table frame='all'> +<title>Extension Allocators Continued</title> +<tgroup cols='3' align='left' colsep='1' rowsep='1'> +<colspec colname='c1'></colspec> +<colspec colname='c2'></colspec> +<colspec colname='c3'></colspec> + +<thead> + <row> + <entry>Allocator</entry> + <entry>Include</entry> + <entry>Version</entry> + </row> +</thead> + +<tbody> + <row> + <entry><classname>__gnu_cxx::array_allocator<T></classname></entry> + <entry><filename class="headerfile">ext/array_allocator.h</filename></entry> + <entry>4.0.0</entry> + </row> + <row> + <entry><classname>__gnu_cxx::throw_allocator<T></classname></entry> + <entry><filename class="headerfile">ext/throw_allocator.h</filename></entry> + <entry>4.2.0</entry> + </row> +</tbody> +</tgroup> +</table> + + +<para> +Debug mode first appears. +</para> + +<para> +Precompiled header support <acronym>PCH</acronym> support. +</para> + +<para> +Macro guard for changed, from <literal>_GLIBCPP_</literal> to <literal>_GLIBCXX_</literal>. +</para> + +<para> +Extension <filename class="headerfile">ext/stdio_sync_filebuf.h</filename> added. +</para> + +<para> +Extension <filename class="headerfile">ext/demangle.h</filename> added. +</para> + + +</sect2> + +<sect2 id="api.rel_400" xreflabel="api.rel_400"> +<title><constant>4.0</constant></title> + <para> + </para> +<para> +TR1 features first appear. +</para> + +<para> +Extension allocator <filename class="headerfile">ext/array_allocator.h</filename> added. +</para> + +<para> +Extension <code>codecvt</code> specializations moved to <filename class="headerfile">ext/codecvt_specializations.h</filename>. +</para> + +<para> +Removal of <filename class="headerfile">ext/demangle.h</filename>. +</para> + + +</sect2> + +<sect2 id="api.rel_410" xreflabel="api.rel_410"> +<title><constant>4.1</constant></title> + <para> + </para> + + +<para> +Removal of <filename class="headerfile">cassert</filename> from all standard headers: now has to be explicitly included for <code>std::assert</code> calls. +</para> + +<para> Extensions for policy-based data structures first added. New includes, +types, namespace <code>pb_assoc</code>. +</para> + + + +<para> Extensions for typelists added in <filename class="headerfile">ext/typelist.h</filename>. +</para> + +<para> Extension for policy-based <code>basic_string</code> first added: <code>__gnu_cxx::__versa_string</code> in <filename class="headerfile">ext/vstring.h</filename>. +</para> + +</sect2> + +<sect2 id="api.rel_420" xreflabel="api.rel_420"> +<title><constant>4.2</constant></title> + <para> + </para> + + +<para> Default visibility attributes applied to <code>namespace std</code>. Support for <code>-fvisibility</code>. +</para> + +<para>TR1 <filename class="headerfile">random</filename>, <filename class="headerfile">complex</filename>, and C compatibility headers added.</para> + +<para> Extensions for concurrent programming consolidated +into <filename class="headerfile">ext/concurrence.h</filename> and <filename class="headerfile">ext/atomicity.h</filename>, +including change of namespace to <code>__gnu_cxx</code> in some +cases. Added types +include <code>_Lock_policy</code>, <code>__concurrence_lock_error</code>, <code>__concurrence_unlock_error</code>, <code>__mutex</code>, <code>__scoped_lock</code>.</para> + +<para> Extensions for type traits consolidated +into <filename class="headerfile">ext/type_traits.h</filename>. Additional traits are added +(<code>__conditional_type</code>, <code>__enable_if</code>, others.) +</para> + +<para> Extensions for policy-based data structures revised. New includes, +types, namespace moved to <code>__pb_ds</code>. +</para> + +<para> Extensions for debug mode modified: now nested in <code>namespace +std::__debug</code> and extensions in <code>namespace +__gnu_cxx::__debug</code>.</para> + +<para> Extensions added: <filename class="headerfile">ext/typelist.h</filename> +and <filename class="headerfile">ext/throw_allocator.h</filename>. +</para> + +</sect2> + +<sect2 id="api.rel_430" xreflabel="api.rel_430"> +<title><constant>4.3</constant></title> + <para> + </para> + + +<para> +C++0X features first appear. +</para> + +<para>TR1 <filename class="headerfile">regex</filename> and <filename class="headerfile">cmath</filename>'s mathematical special function added.</para> + +<para> +Backward include edit. +</para> +<itemizedlist> + <listitem> + <para>Removed</para> + <para> +<filename class="headerfile">algobase.h</filename> <filename class="headerfile">algo.h</filename> <filename class="headerfile">alloc.h</filename> <filename class="headerfile">bvector.h</filename> <filename class="headerfile">complex.h</filename> +<filename class="headerfile">defalloc.h</filename> <filename class="headerfile">deque.h</filename> <filename class="headerfile">fstream.h</filename> <filename class="headerfile">function.h</filename> <filename class="headerfile">hash_map.h</filename> <filename class="headerfile">hash_set.h</filename> +<filename class="headerfile">hashtable.h</filename> <filename class="headerfile">heap.h</filename> <filename class="headerfile">iomanip.h</filename> <filename class="headerfile">iostream.h</filename> <filename class="headerfile">istream.h</filename> <filename class="headerfile">iterator.h</filename> +<filename class="headerfile">list.h</filename> <filename class="headerfile">map.h</filename> <filename class="headerfile">multimap.h</filename> <filename class="headerfile">multiset.h</filename> <filename class="headerfile">new.h</filename> <filename class="headerfile">ostream.h</filename> <filename class="headerfile">pair.h</filename> <filename class="headerfile">queue.h</filename> <filename class="headerfile">rope.h</filename> <filename class="headerfile">set.h</filename> <filename class="headerfile">slist.h</filename> <filename class="headerfile">stack.h</filename> <filename class="headerfile">streambuf.h</filename> <filename class="headerfile">stream.h</filename> <filename class="headerfile">tempbuf.h</filename> +<filename class="headerfile">tree.h</filename> <filename class="headerfile">vector.h</filename> + </para> + </listitem> + <listitem> + <para>Added</para> + <para> + <filename class="headerfile">hash_map</filename> and <filename class="headerfile">hash_set</filename> + </para> + </listitem> + <listitem> + <para>Added in C++0x</para> + <para> + <filename class="headerfile">auto_ptr.h</filename> and <filename class="headerfile">binders.h</filename> + </para> + </listitem> + +</itemizedlist> + +<para> +Header dependency streamlining. +</para> + +<itemizedlist> + <listitem><para><filename class="headerfile">algorithm</filename> no longer includes <filename class="headerfile">climits</filename>, <filename class="headerfile">cstring</filename>, or <filename class="headerfile">iosfwd</filename> </para></listitem> + <listitem><para><filename class="headerfile">bitset</filename> no longer includes <filename class="headerfile">istream</filename> or <filename class="headerfile">ostream</filename>, adds <filename class="headerfile">iosfwd</filename> </para></listitem> + <listitem><para><filename class="headerfile">functional</filename> no longer includes <filename class="headerfile">cstddef</filename></para></listitem> + <listitem><para><filename class="headerfile">iomanip</filename> no longer includes <filename class="headerfile">istream</filename>, <filename class="headerfile">istream</filename>, or <filename class="headerfile">functional</filename>, adds <filename class="headerfile">ioswd</filename> </para></listitem> + <listitem><para><filename class="headerfile">numeric</filename> no longer includes <filename class="headerfile">iterator</filename></para></listitem> + <listitem><para><filename class="headerfile">string</filename> no longer includes <filename class="headerfile">algorithm</filename> or <filename class="headerfile">memory</filename></para></listitem> + + <listitem><para><filename class="headerfile">valarray</filename> no longer includes <filename class="headerfile">numeric</filename> or <filename class="headerfile">cstdlib</filename></para></listitem> + <listitem><para><filename class="headerfile">tr1/hashtable</filename> no longer includes <filename class="headerfile">memory</filename> or <filename class="headerfile">functional</filename></para></listitem> + <listitem><para><filename class="headerfile">tr1/memory</filename> no longer includes <filename class="headerfile">algorithm</filename></para></listitem> + <listitem><para><filename class="headerfile">tr1/random</filename> no longer includes <filename class="headerfile">algorithm</filename> or <filename class="headerfile">fstream</filename></para></listitem> +</itemizedlist> + +<para> +Debug mode for <filename class="headerfile">unordered_map</filename> and <filename class="headerfile">unordered_set</filename>. +</para> + +<para> +Parallel mode first appears. +</para> + +<para>Variadic template implementations of items in <filename class="headerfile">tuple</filename> and + <filename class="headerfile">functional</filename>. +</para> + +<para>Default <code>what</code> implementations give more elaborate + exception strings for <code>bad_cast</code>, + <code>bad_typeid</code>, <code>bad_exception</code>, and + <code>bad_alloc</code>. +</para> + +<para> +PCH binary files no longer installed. Instead, the source files are installed. +</para> + +<para> +Namespace pb_ds moved to __gnu_pb_ds. +</para> + +</sect2> + +</sect1>
\ No newline at end of file diff --git a/libstdc++-v3/doc/xml/manual/extensions.xml b/libstdc++-v3/doc/xml/manual/extensions.xml new file mode 100644 index 00000000000..517d3bba39f --- /dev/null +++ b/libstdc++-v3/doc/xml/manual/extensions.xml @@ -0,0 +1,577 @@ +<?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</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"> + <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"> + <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"> + <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"> + <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"> + <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 (lexigraphical_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"> + <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"> + <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"> + <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 11 : Demangling --> +<chapter id="manual.ext.demangle" xreflabel="Demangling"> + <title>Demangling</title> + <para> + Transforming C++ ABI itentifiers (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 12 : Concurrency --> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" + parse="xml" href="concurrency.xml"> +</xi:include> + +</part> diff --git a/libstdc++-v3/doc/xml/manual/internals.xml b/libstdc++-v3/doc/xml/manual/internals.xml new file mode 100644 index 00000000000..ccde22791bd --- /dev/null +++ b/libstdc++-v3/doc/xml/manual/internals.xml @@ -0,0 +1,548 @@ +<sect1 id="appendix.porting.internals" xreflabel="internals"> +<?dbhtml filename="internals.html"?> + +<sect1info> + <keywordset> + <keyword> + ISO C++ + </keyword> + <keyword> + internals + </keyword> + </keywordset> +</sect1info> + +<title>Porting to New Hardware or Operating Systems</title> + +<para> +</para> + + +<para>This document explains how to port libstdc++ (the GNU C++ library) to +a new target. +</para> + + <para>In order to make the GNU C++ library (libstdc++) work with a new +target, you must edit some configuration files and provide some new +header files. Unless this is done, libstdc++ will use generic +settings which may not be correct for your target; even if they are +correct, they will likely be inefficient. + </para> + + <para>Before you get started, make sure that you have a working C library on +your target. The C library need not precisely comply with any +particular standard, but should generally conform to the requirements +imposed by the ANSI/ISO standard. + </para> + + <para>In addition, you should try to verify that the C++ compiler generally +works. It is difficult to test the C++ compiler without a working +library, but you should at least try some minimal test cases. + </para> + + <para>(Note that what we think of as a "target," the library refers to as +a "host." The comment at the top of <code>configure.ac</code> explains why.) + </para> + + +<sect2 id="internals.os" xreflabel="internals.os"> +<title>Operating System</title> + +<para>If you are porting to a new operating system (as opposed to a new chip +using an existing operating system), you will need to create a new +directory in the <code>config/os</code> hierarchy. For example, the IRIX +configuration files are all in <code>config/os/irix</code>. There is no set +way to organize the OS configuration directory. For example, +<code>config/os/solaris/solaris-2.6</code> and +<code>config/os/solaris/solaris-2.7</code> are used as configuration +directories for these two versions of Solaris. On the other hand, both +Solaris 2.7 and Solaris 2.8 use the <code>config/os/solaris/solaris-2.7</code> +directory. The important information is that there needs to be a +directory under <code>config/os</code> to store the files for your operating +system. +</para> + + <para>You might have to change the <code>configure.host</code> file to ensure that +your new directory is activated. Look for the switch statement that sets +<code>os_include_dir</code>, and add a pattern to handle your operating system +if the default will not suffice. The switch statement switches on only +the OS portion of the standard target triplet; e.g., the <code>solaris2.8</code> +in <code>sparc-sun-solaris2.8</code>. If the new directory is named after the +OS portion of the triplet (the default), then nothing needs to be changed. + </para> + + <para>The first file to create in this directory, should be called +<code>os_defines.h</code>. This file contains basic macro definitions +that are required to allow the C++ library to work with your C library. + </para> + + <para>Several libstdc++ source files unconditionally define the macro +<code>_POSIX_SOURCE</code>. On many systems, defining this macro causes +large portions of the C library header files to be eliminated +at preprocessing time. Therefore, you may have to <code>#undef</code> this +macro, or define other macros (like <code>_LARGEFILE_SOURCE</code> or +<code>__EXTENSIONS__</code>). You won't know what macros to define or +undefine at this point; you'll have to try compiling the library and +seeing what goes wrong. If you see errors about calling functions +that have not been declared, look in your C library headers to see if +the functions are declared there, and then figure out what macros you +need to define. You will need to add them to the +<code>CPLUSPLUS_CPP_SPEC</code> macro in the GCC configuration file for your +target. It will not work to simply define these macros in +<code>os_defines.h</code>. + </para> + + <para>At this time, there are a few libstdc++-specific macros which may be +defined: + </para> + + <para><code>_GLIBCXX_USE_C99_CHECK</code> may be defined to 1 to check C99 +function declarations (which are not covered by specialization below) +found in system headers against versions found in the library headers +derived from the standard. + </para> + + <para><code>_GLIBCXX_USE_C99_DYNAMIC</code> may be defined to an expression that +yields 0 if and only if the system headers are exposing proper support +for C99 functions (which are not covered by specialization below). If +defined, it must be 0 while bootstrapping the compiler/rebuilding the +library. + </para> + + <para><code>_GLIBCXX_USE_C99_LONG_LONG_CHECK</code> may be defined to 1 to check +the set of C99 long long function declarations found in system headers +against versions found in the library headers derived from the +standard. + + </para> + <para><code>_GLIBCXX_USE_C99_LONG_LONG_DYNAMIC</code> may be defined to an +expression that yields 0 if and only if the system headers are +exposing proper support for the set of C99 long long functions. If +defined, it must be 0 while bootstrapping the compiler/rebuilding the +library. + </para> + <para><code>_GLIBCXX_USE_C99_FP_MACROS_DYNAMIC</code> may be defined to an +expression that yields 0 if and only if the system headers +are exposing proper support for the related set of macros. If defined, +it must be 0 while bootstrapping the compiler/rebuilding the library. + </para> + <para><code>_GLIBCXX_USE_C99_FLOAT_TRANSCENDENTALS_CHECK</code> may be defined +to 1 to check the related set of function declarations found in system +headers against versions found in the library headers derived from +the standard. + </para> + <para><code>_GLIBCXX_USE_C99_FLOAT_TRANSCENDENTALS_DYNAMIC</code> may be defined +to an expression that yields 0 if and only if the system headers +are exposing proper support for the related set of functions. If defined, +it must be 0 while bootstrapping the compiler/rebuilding the library. + </para> + <para>Finally, you should bracket the entire file in an include-guard, like +this: + </para> + +<programlisting> + +#ifndef _GLIBCXX_OS_DEFINES +#define _GLIBCXX_OS_DEFINES +... +#endif +</programlisting> + + <para>We recommend copying an existing <code>os_defines.h</code> to use as a +starting point. + </para> +</sect2> + + +<sect2 id="internals.cpu" xreflabel="internals.cpu"> +<title>CPU</title> + +<para>If you are porting to a new chip (as opposed to a new operating system +running on an existing chip), you will need to create a new directory in the +<code>config/cpu</code> hierarchy. Much like the <link linkend="internals.os">Operating system</link> setup, +there are no strict rules on how to organize the CPU configuration +directory, but careful naming choices will allow the configury to find your +setup files without explicit help. +</para> + + <para>We recommend that for a target triplet <code><CPU>-<vendor>-<OS></code>, you +name your configuration directory <code>config/cpu/<CPU></code>. If you do this, +the configury will find the directory by itself. Otherwise you will need to +edit the <code>configure.host</code> file and, in the switch statement that sets +<code>cpu_include_dir</code>, add a pattern to handle your chip. + </para> + + <para>Note that some chip families share a single configuration directory, for +example, <code>alpha</code>, <code>alphaev5</code>, and <code>alphaev6</code> all use the +<code>config/cpu/alpha</code> directory, and there is an entry in the +<code>configure.host</code> switch statement to handle this. + </para> + + <para>The <code>cpu_include_dir</code> sets default locations for the files controlling +<link linkend="internals.thread_safety">Thread safety</link> and <link linkend="internals.numeric_limits">Numeric limits</link>, if the defaults are not +appropriate for your chip. + </para> + +</sect2> + + +<sect2 id="internals.char_types" xreflabel="internals.char_types"> +<title>Character Types</title> + +<para>The library requires that you provide three header files to implement +character classification, analogous to that provided by the C libraries +<code><ctype.h></code> header. You can model these on the files provided in +<code>config/os/generic</code>. However, these files will almost +certainly need some modification. +</para> + + <para>The first file to write is <code>ctype_base.h</code>. This file provides +some very basic information about character classification. The libstdc++ +library assumes that your C library implements <code><ctype.h></code> by using +a table (indexed by character code) containing integers, where each of +these integers is a bit-mask indicating whether the character is +upper-case, lower-case, alphabetic, etc. The <code>ctype_base.h</code> +file gives the type of the integer, and the values of the various bit +masks. You will have to peer at your own <code><ctype.h></code> to figure out +how to define the values required by this file. + </para> + + <para>The <code>ctype_base.h</code> header file does not need include guards. +It should contain a single <code>struct</code> definition called +<code>ctype_base</code>. This <code>struct</code> should contain two type +declarations, and one enumeration declaration, like this example, taken +from the IRIX configuration: + </para> + +<programlisting> + struct ctype_base + { + typedef unsigned int mask; + typedef int* __to_type; + + enum + { + space = _ISspace, + print = _ISprint, + cntrl = _IScntrl, + upper = _ISupper, + lower = _ISlower, + alpha = _ISalpha, + digit = _ISdigit, + punct = _ISpunct, + xdigit = _ISxdigit, + alnum = _ISalnum, + graph = _ISgraph + }; + }; +</programlisting> + +<para>The <code>mask</code> type is the type of the elements in the table. If your +C library uses a table to map lower-case numbers to upper-case numbers, +and vice versa, you should define <code>__to_type</code> to be the type of the +elements in that table. If you don't mind taking a minor performance +penalty, or if your library doesn't implement <code>toupper</code> and +<code>tolower</code> in this way, you can pick any pointer-to-integer type, +but you must still define the type. +</para> + + <para>The enumeration should give definitions for all the values in the above +example, using the values from your native <code><ctype.h></code>. They can +be given symbolically (as above), or numerically, if you prefer. You do +not have to include <code><ctype.h></code> in this header; it will always be +included before <code>ctype_base.h</code> is included. + </para> + + <para>The next file to write is <code>ctype_noninline.h</code>, which also does +not require include guards. This file defines a few member functions +that will be included in <code>include/bits/locale_facets.h</code>. The first +function that must be written is the <code>ctype<char>::ctype</code> +constructor. Here is the IRIX example: + </para> + +<programlisting> +ctype<char>::ctype(const mask* __table = 0, bool __del = false, + size_t __refs = 0) + : _Ctype_nois<char>(__refs), _M_del(__table != 0 && __del), + _M_toupper(NULL), + _M_tolower(NULL), + _M_ctable(NULL), + _M_table(!__table + ? (const mask*) (__libc_attr._ctype_tbl->_class + 1) + : __table) + { } +</programlisting> + +<para>There are two parts of this that you might choose to alter. The first, +and most important, is the line involving <code>__libc_attr</code>. That is +IRIX system-dependent code that gets the base of the table mapping +character codes to attributes. You need to substitute code that obtains +the address of this table on your system. If you want to use your +operating system's tables to map upper-case letters to lower-case, and +vice versa, you should initialize <code>_M_toupper</code> and +<code>_M_tolower</code> with those tables, in similar fashion. +</para> + + <para>Now, you have to write two functions to convert from upper-case to +lower-case, and vice versa. Here are the IRIX versions: + </para> + +<programlisting> + char + ctype<char>::do_toupper(char __c) const + { return _toupper(__c); } + + char + ctype<char>::do_tolower(char __c) const + { return _tolower(__c); } +</programlisting> + +<para>Your C library provides equivalents to IRIX's <code>_toupper</code> and +<code>_tolower</code>. If you initialized <code>_M_toupper</code> and +<code>_M_tolower</code> above, then you could use those tables instead. +</para> + + <para>Finally, you have to provide two utility functions that convert strings +of characters. The versions provided here will always work - but you +could use specialized routines for greater performance if you have +machinery to do that on your system: + </para> + +<programlisting> + const char* + ctype<char>::do_toupper(char* __low, const char* __high) const + { + while (__low < __high) + { + *__low = do_toupper(*__low); + ++__low; + } + return __high; + } + + const char* + ctype<char>::do_tolower(char* __low, const char* __high) const + { + while (__low < __high) + { + *__low = do_tolower(*__low); + ++__low; + } + return __high; + } +</programlisting> + + <para>You must also provide the <code>ctype_inline.h</code> file, which +contains a few more functions. On most systems, you can just copy +<code>config/os/generic/ctype_inline.h</code> and use it on your system. + </para> + + <para>In detail, the functions provided test characters for particular +properties; they are analogous to the functions like <code>isalpha</code> and +<code>islower</code> provided by the C library. + </para> + + <para>The first function is implemented like this on IRIX: + </para> + +<programlisting> + bool + ctype<char>:: + is(mask __m, char __c) const throw() + { return (_M_table)[(unsigned char)(__c)] & __m; } +</programlisting> + +<para>The <code>_M_table</code> is the table passed in above, in the constructor. +This is the table that contains the bitmasks for each character. The +implementation here should work on all systems. +</para> + + <para>The next function is: + </para> + +<programlisting> + const char* + ctype<char>:: + is(const char* __low, const char* __high, mask* __vec) const throw() + { + while (__low < __high) + *__vec++ = (_M_table)[(unsigned char)(*__low++)]; + return __high; + } +</programlisting> + +<para>This function is similar; it copies the masks for all the characters +from <code>__low</code> up until <code>__high</code> into the vector given by +<code>__vec</code>. +</para> + + <para>The last two functions again are entirely generic: + </para> + +<programlisting> + const char* + ctype<char>:: + scan_is(mask __m, const char* __low, const char* __high) const throw() + { + while (__low < __high && !this->is(__m, *__low)) + ++__low; + return __low; + } + + const char* + ctype<char>:: + scan_not(mask __m, const char* __low, const char* __high) const throw() + { + while (__low < __high && this->is(__m, *__low)) + ++__low; + return __low; + } +</programlisting> + +</sect2> + + +<sect2 id="internals.thread_safety" xreflabel="internals.thread_safety"> +<title>Thread Safety</title> + +<para>The C++ library string functionality requires a couple of atomic +operations to provide thread-safety. If you don't take any special +action, the library will use stub versions of these functions that are +not thread-safe. They will work fine, unless your applications are +multi-threaded. +</para> + + <para>If you want to provide custom, safe, versions of these functions, there +are two distinct approaches. One is to provide a version for your CPU, +using assembly language constructs. The other is to use the +thread-safety primitives in your operating system. In either case, you +make a file called <code>atomicity.h</code>, and the variable +<code>ATOMICITYH</code> must point to this file. + </para> + + <para>If you are using the assembly-language approach, put this code in +<code>config/cpu/<chip>/atomicity.h</code>, where chip is the name of +your processor (see <link linkend="internals.cpu">CPU</link>). No additional changes are necessary to +locate the file in this case; <code>ATOMICITYH</code> will be set by default. + </para> + + <para>If you are using the operating system thread-safety primitives approach, +you can also put this code in the same CPU directory, in which case no more +work is needed to locate the file. For examples of this approach, +see the <code>atomicity.h</code> file for IRIX or IA64. + </para> + + <para>Alternatively, if the primitives are more closely related to the OS +than they are to the CPU, you can put the <code>atomicity.h</code> file in +the <link linkend="internals.os">Operating system</link> directory instead. In this case, you must +edit <code>configure.host</code>, and in the switch statement that handles +operating systems, override the <code>ATOMICITYH</code> variable to point to +the appropriate <code>os_include_dir</code>. For examples of this approach, +see the <code>atomicity.h</code> file for AIX. + </para> + + <para>With those bits out of the way, you have to actually write +<code>atomicity.h</code> itself. This file should be wrapped in an +include guard named <code>_GLIBCXX_ATOMICITY_H</code>. It should define one +type, and two functions. + </para> + + <para>The type is <code>_Atomic_word</code>. Here is the version used on IRIX: + </para> + +<programlisting> +typedef long _Atomic_word; +</programlisting> + +<para>This type must be a signed integral type supporting atomic operations. +If you're using the OS approach, use the same type used by your system's +primitives. Otherwise, use the type for which your CPU provides atomic +primitives. +</para> + + <para>Then, you must provide two functions. The bodies of these functions +must be equivalent to those provided here, but using atomic operations: + </para> + +<programlisting> + static inline _Atomic_word + __attribute__ ((__unused__)) + __exchange_and_add (_Atomic_word* __mem, int __val) + { + _Atomic_word __result = *__mem; + *__mem += __val; + return __result; + } + + static inline void + __attribute__ ((__unused__)) + __atomic_add (_Atomic_word* __mem, int __val) + { + *__mem += __val; + } +</programlisting> + +</sect2> + + +<sect2 id="internals.numeric_limits" xreflabel="internals.numeric_limits"> +<title>Numeric Limits</title> + +<para>The C++ library requires information about the fundamental data types, +such as the minimum and maximum representable values of each type. +You can define each of these values individually, but it is usually +easiest just to indicate how many bits are used in each of the data +types and let the library do the rest. For information about the +macros to define, see the top of <code>include/bits/std_limits.h</code>. +</para> + + <para>If you need to define any macros, you can do so in <code>os_defines.h</code>. +However, if all operating systems for your CPU are likely to use the +same values, you can provide a CPU-specific file instead so that you +do not have to provide the same definitions for each operating system. +To take that approach, create a new file called <code>cpu_limits.h</code> in +your CPU configuration directory (see <link linkend="internals.cpu">CPU</link>). + </para> + +</sect2> + + +<sect2 id="internals.libtool" xreflabel="internals.libtool"> +<title>Libtool</title> + +<para>The C++ library is compiled, archived and linked with libtool. +Explaining the full workings of libtool is beyond the scope of this +document, but there are a few, particular bits that are necessary for +porting. +</para> + + <para>Some parts of the libstdc++ library are compiled with the libtool +<code>--tags CXX</code> option (the C++ definitions for libtool). Therefore, +<code>ltcf-cxx.sh</code> in the top-level directory needs to have the correct +logic to compile and archive objects equivalent to the C version of libtool, +<code>ltcf-c.sh</code>. Some libtool targets have definitions for C but not +for C++, or C++ definitions which have not been kept up to date. + </para> + + <para>The C++ run-time library contains initialization code that needs to be +run as the library is loaded. Often, that requires linking in special +object files when the C++ library is built as a shared library, or +taking other system-specific actions. + </para> + + <para>The libstdc++ library is linked with the C version of libtool, even +though it is a C++ library. Therefore, the C version of libtool needs to +ensure that the run-time library initializers are run. The usual way to +do this is to build the library using <code>gcc -shared</code>. + </para> + + <para>If you need to change how the library is linked, look at +<code>ltcf-c.sh</code> in the top-level directory. Find the switch statement +that sets <code>archive_cmds</code>. Here, adjust the setting for your +operating system. + </para> + + +</sect2> + +</sect1>
\ No newline at end of file diff --git a/libstdc++-v3/doc/xml/manual/intro.xml b/libstdc++-v3/doc/xml/manual/intro.xml new file mode 100644 index 00000000000..1a51e9e44f9 --- /dev/null +++ b/libstdc++-v3/doc/xml/manual/intro.xml @@ -0,0 +1,664 @@ +<?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.intro" xreflabel="Introduction"> +<?dbhtml filename="intro.html"?> + +<partinfo> + <keywordset> + <keyword> + ISO C++ + </keyword> + <keyword> + library + </keyword> + </keywordset> +</partinfo> + +<title>Introduction</title> + +<!-- Chapter 01 : Status --> +<chapter id="manual.intro.status" xreflabel="Status"> + <title>Status</title> + + + <sect1 id="manual.intro.status.standard" xreflabel="Implementation Status"> + <title>Implementation Status</title> + + <!-- Section 01 : Status C++ 1998 --> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" + parse="xml" href="status_cxx1998.xml"> + </xi:include> + + <!-- Section 02 : Status C++ TR1 --> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" + parse="xml" href="status_cxxtr1.xml"> + </xi:include> + + <!-- Section 03 : Status C++ 200x --> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" + parse="xml" href="status_cxx200x.xml"> + </xi:include> + </sect1> + + <!-- Section 02 : License --> + <sect1 id="manual.intro.status.license" xreflabel="License"> + <title>License</title> + <para> + There are two licenses affecting GNU libstdc++: one for the code, + and one for the documentation. + </para> + + <para> + There is a license section in the FAQ regarding common <link + linkend="faq.license">questions</link>. If you have more + questions, ask the FSF or the <ulink + url="http://gcc.gnu.org/lists.html">gcc mailing list</ulink>. + </para> + + <sect2 id="manual.intro.status.license.gpl" xreflabel="License GPL"> + <title>The Code: GPL</title> + + <para> + The source code is distributed under the <link + linkend="appendix.gpl-2.0">GNU General Public License version 2</link>, + with the so-called <quote>Runtime Exception</quote> + as follows (or see any header or implementation file): + </para> + + <literallayout> + As a special exception, you may use this file as part of a free software + library without restriction. Specifically, if other files instantiate + templates or use macros or inline functions from this file, or you compile + this file and link it with other files to produce an executable, this + file does not by itself cause the resulting executable to be covered by + the GNU General Public License. This exception does not however + invalidate any other reasons why the executable file might be covered by + the GNU General Public License. + </literallayout> + + <para> + Hopefully that text is self-explanatory. If it isn't, you need to speak + to your lawyer, or the Free Software Foundation. + </para> + </sect2> + + <sect2 id="manual.intro.status.license.fdl" xreflabel="License FDL"> + <title>The Documentation: GPL, FDL</title> + + <para> + The documentation shipped with the library and made available over + the web, excluding the pages generated from source comments, are + copyrighted by the Free Software Foundation, and placed under the + <link linkend="appendix.gfdl-1.2"> GNU Free Documentation + License version 1.2</link>. There are no Front-Cover Texts, no + Back-Cover Texts, and no Invariant Sections. + </para> + + <para> + For documentation generated by doxygen or other automated tools + via processing source code comments and markup, the original source + code license applies to the generated files. Thus, the doxygen + documents are licensed <link linkend="appendix.gpl-2.0">GPL</link>. + </para> + + <para> + If you plan on making copies of the documentation, please let us know. + We can probably offer suggestions. + </para> + </sect2> + + </sect1> + + <!-- Section 03 : Known Bugs --> + <sect1 id="manual.intro.status.bugs" xreflabel="Bugs"> + <title>Bugs</title> + + <sect2 id="manual.intro.status.bugs.impl" xreflabel="Bugs impl"> + <title>Implementation Bugs</title> + <para> + Information on known bugs, details on efforts to fix them, and + fixed bugs are all available as part of the GCC bug tracking + system, <ulink + url="http://gcc.gnu.org/bugzilla">bugzilla</ulink>, with the + category set to <literal>libstdc++</literal>. + </para> + </sect2> + + <sect2 id="manual.intro.status.bugs.iso" xreflabel="Bugs iso"> + <title>Standard Bugs</title> + <para> + Everybody's got issues. Even the C++ Standard Library. + </para> + <para> + The Library Working Group, or LWG, is the ISO subcommittee responsible + for making changes to the library. They periodically publish an + Issues List containing problems and possible solutions. As they reach + a consensus on proposed solutions, we often incorporate the solution. + </para> + <para> + Here are the issues which have resulted in code changes to the library. + The links are to the specific defect reports from a <emphasis>partial + copy</emphasis> of the Issues List. You can read the full version online + at the <ulink url="http://www.open-std.org/jtc1/sc22/wg21/">ISO C++ + Committee homepage</ulink>, linked to on the + <ulink url="http://gcc.gnu.org/readings.html">GCC "Readings" + page</ulink>. If + you spend a lot of time reading the issues, we recommend downloading + the ZIP file and reading them locally. + </para> + <para> + (NB: <emphasis>partial copy</emphasis> means that not all + links within the lwg-*.html pages will work. Specifically, + links to defect reports that have not been accorded full DR + status will probably break. Rather than trying to mirror the + entire issues list on our overworked web server, we recommend + you go to the LWG homepage instead.) + </para> + <para> + If a DR is not listed here, we may simply not have gotten to + it yet; feel free to submit a patch. Search the include/bits + and src directories for appearances of + <constant>_GLIBCXX_RESOLVE_LIB_DEFECTS</constant> for examples + of style. Note that we usually do not make changes to the + code until an issue has reached <ulink url="lwg-active.html#DR">DR</ulink> status. + </para> + + <variablelist> + <varlistentry><term><ulink url="lwg-defects.html#5">5</ulink>: + <emphasis>string::compare specification questionable</emphasis> + </term> + <listitem><para>This should be two overloaded functions rather than a single function. + </para></listitem></varlistentry> + + <varlistentry><term><ulink url="lwg-defects.html#17">17</ulink>: + <emphasis>Bad bool parsing</emphasis> + </term> + <listitem><para>Apparently extracting Boolean values was messed up... + </para></listitem></varlistentry> + + <varlistentry><term><ulink url="lwg-defects.html#19">19</ulink>: + <emphasis>"Noconv" definition too vague</emphasis> + </term> + <listitem><para>If <code>codecvt::do_in</code> returns <code>noconv</code> there are + no changes to the values in <code>[to, to_limit)</code>. + </para></listitem></varlistentry> + + <varlistentry><term><ulink url="lwg-defects.html#22">22</ulink>: + <emphasis>Member open vs flags</emphasis> + </term> + <listitem><para>Re-opening a file stream does <emphasis>not</emphasis> clear the state flags. + </para></listitem></varlistentry> + + <varlistentry><term><ulink url="lwg-defects.html#25">25</ulink>: + <emphasis>String operator<< uses width() value wrong</emphasis> + </term> + <listitem><para>Padding issues. + </para></listitem></varlistentry> + + <varlistentry><term><ulink url="lwg-defects.html#48">48</ulink>: + <emphasis>Use of non-existent exception constructor</emphasis> + </term> + <listitem><para>An instance of <code>ios_base::failure</code> is constructed instead. + </para></listitem></varlistentry> + + <varlistentry><term><ulink url="lwg-defects.html#49">49</ulink>: + <emphasis>Underspecification of ios_base::sync_with_stdio</emphasis> + </term> + <listitem><para>The return type is the <emphasis>previous</emphasis> state of synchronization. + </para></listitem></varlistentry> + + <varlistentry><term><ulink url="lwg-defects.html#50">50</ulink>: + <emphasis>Copy constructor and assignment operator of ios_base</emphasis> + </term> + <listitem><para>These members functions are declared <code>private</code> and are + thus inaccessible. Specifying the correct semantics of + "copying stream state" was deemed too complicated. + </para></listitem></varlistentry> + + <varlistentry><term><ulink url="lwg-defects.html#60">60</ulink>: + <emphasis>What is a formatted input function?</emphasis> + </term> + <listitem><para>This DR made many widespread changes to <code>basic_istream</code> + and <code>basic_ostream</code> all of which have been implemented. + </para></listitem></varlistentry> + + <varlistentry><term><ulink url="lwg-defects.html#63">63</ulink>: + <emphasis>Exception-handling policy for unformatted output</emphasis> + </term> + <listitem><para>Make the policy consistent with that of formatted input, unformatted + input, and formatted output. + </para></listitem></varlistentry> + + <varlistentry><term><ulink url="lwg-defects.html#68">68</ulink>: + <emphasis>Extractors for char* should store null at end</emphasis> + </term> + <listitem><para>And they do now. An editing glitch in the last item in the list of + [27.6.1.2.3]/7. + </para></listitem></varlistentry> + + <varlistentry><term><ulink url="lwg-defects.html#74">74</ulink>: + <emphasis>Garbled text for codecvt::do_max_length</emphasis> + </term> + <listitem><para>The text of the standard was gibberish. Typos gone rampant. + </para></listitem></varlistentry> + + <varlistentry><term><ulink url="lwg-defects.html#75">75</ulink>: + <emphasis>Contradiction in codecvt::length's argument types</emphasis> + </term> + <listitem><para>Change the first parameter to <code>stateT&</code> and implement + the new effects paragraph. + </para></listitem></varlistentry> + + <varlistentry><term><ulink url="lwg-defects.html#83">83</ulink>: + <emphasis>string::npos vs. string::max_size()</emphasis> + </term> + <listitem><para>Safety checks on the size of the string should test against + <code>max_size()</code> rather than <code>npos</code>. + </para></listitem></varlistentry> + + <varlistentry><term><ulink url="lwg-defects.html#90">90</ulink>: + <emphasis>Incorrect description of operator>> for strings</emphasis> + </term> + <listitem><para>The effect contain <code>isspace(c,getloc())</code> which must be + replaced by <code>isspace(c,is.getloc())</code>. + </para></listitem></varlistentry> + + <varlistentry><term><ulink url="lwg-defects.html#91">91</ulink>: + <emphasis>Description of operator>> and getline() for string<> + might cause endless loop</emphasis> + </term> + <listitem><para>They behave as a formatted input function and as an unformatted + input function, respectively (except that <code>getline</code> is + not required to set <code>gcount</code>). + </para></listitem></varlistentry> + + <varlistentry><term><ulink url="lwg-defects.html#103">103</ulink>: + <emphasis>set::iterator is required to be modifiable, but this allows + modification of keys.</emphasis> + </term> + <listitem><para>For associative containers where the value type is the same as + the key type, both <code>iterator</code> and <code>const_iterator + </code> are constant iterators. + </para></listitem></varlistentry> + + <varlistentry><term><ulink url="lwg-defects.html#109">109</ulink>: + <emphasis>Missing binders for non-const sequence elements</emphasis> + </term> + <listitem><para>The <code>binder1st</code> and <code>binder2nd</code> didn't have an + <code>operator()</code> taking a non-const parameter. + </para></listitem></varlistentry> + + <varlistentry><term><ulink url="lwg-defects.html#110">110</ulink>: + <emphasis>istreambuf_iterator::equal not const</emphasis> + </term> + <listitem><para>This was not a const member function. Note that the DR says to + replace the function with a const one; we have instead provided an + overloaded version with identical contents. + </para></listitem></varlistentry> + + <varlistentry><term><ulink url="lwg-defects.html#117">117</ulink>: + <emphasis>basic_ostream uses nonexistent num_put member functions</emphasis> + </term> + <listitem><para><code>num_put::put()</code> was overloaded on the wrong types. + </para></listitem></varlistentry> + + <varlistentry><term><ulink url="lwg-defects.html#118">118</ulink>: + <emphasis>basic_istream uses nonexistent num_get member functions</emphasis> + </term> + <listitem><para>Same as 117, but for <code>num_get::get()</code>. + </para></listitem></varlistentry> + + <varlistentry><term><ulink url="lwg-defects.html#129">129</ulink>: + <emphasis>Need error indication from seekp() and seekg()</emphasis> + </term> + <listitem><para>These functions set <code>failbit</code> on error now. + </para></listitem></varlistentry> + + <varlistentry><term><ulink url="lwg-defects.html#136">136</ulink>: + <emphasis>seekp, seekg setting wrong streams?</emphasis> + </term> + <listitem><para><code>seekp</code> should only set the output stream, and + <code>seekg</code> should only set the input stream. + </para></listitem></varlistentry> + +<!--<varlistentry><term><ulink url="lwg-defects.html#159">159</ulink>: + <emphasis>Strange use of underflow()</emphasis> + </term> + <listitem><para>In fstream.tcc, the basic_filebuf<>::showmanyc() function + should probably not be calling <code>underflow()</code>. + </para></listitem></varlistentry> --> + + <varlistentry><term><ulink url="lwg-defects.html#167">167</ulink>: + <emphasis>Improper use of traits_type::length()</emphasis> + </term> + <listitem><para><code>op<<</code> with a <code>const char*</code> was + calculating an incorrect number of characters to write. + </para></listitem></varlistentry> + + <varlistentry><term><ulink url="lwg-defects.html#169">169</ulink>: + <emphasis>Bad efficiency of overflow() mandated</emphasis> + </term> + <listitem><para>Grow efficiently the internal array object. + </para></listitem></varlistentry> + + <varlistentry><term><ulink url="lwg-defects.html#171">171</ulink>: + <emphasis>Strange seekpos() semantics due to joint position</emphasis> + </term> + <listitem><para>Quite complex to summarize... + </para></listitem></varlistentry> + + <varlistentry><term><ulink url="lwg-defects.html#181">181</ulink>: + <emphasis>make_pair() unintended behavior</emphasis> + </term> + <listitem><para>This function used to take its arguments as reference-to-const, now + it copies them (pass by value). + </para></listitem></varlistentry> + + <varlistentry><term><ulink url="lwg-defects.html#195">195</ulink>: + <emphasis>Should basic_istream::sentry's constructor ever set eofbit?</emphasis> + </term> + <listitem><para>Yes, it can, specifically if EOF is reached while skipping whitespace. + </para></listitem></varlistentry> + + <varlistentry><term><ulink url="lwg-defects.html#211">211</ulink>: + <emphasis>operator>>(istream&, string&) doesn't set failbit</emphasis> + </term> + <listitem><para>If nothing is extracted into the string, <code>op>></code> now + sets <code>failbit</code> (which can cause an exception, etc., etc.). + </para></listitem></varlistentry> + + <varlistentry><term><ulink url="lwg-defects.html#214">214</ulink>: + <emphasis>set::find() missing const overload</emphasis> + </term> + <listitem><para>Both <code>set</code> and <code>multiset</code> were missing + overloaded find, lower_bound, upper_bound, and equal_range functions + for const instances. + </para></listitem></varlistentry> + + <varlistentry><term><ulink url="lwg-defects.html#231">231</ulink>: + <emphasis>Precision in iostream?</emphasis> + </term> + <listitem><para>For conversion from a floating-point type, <code>str.precision()</code> + is specified in the conversion specification. + </para></listitem></varlistentry> + + <varlistentry><term><ulink url="lwg-active.html#233">233</ulink>: + <emphasis>Insertion hints in associative containers</emphasis> + </term> + <listitem><para>Implement N1780, first check before then check after, insert as close + to hint as possible. + </para></listitem></varlistentry> + + <varlistentry><term><ulink url="lwg-defects.html#235">235</ulink>: + <emphasis>No specification of default ctor for reverse_iterator</emphasis> + </term> + <listitem><para>The declaration of <code>reverse_iterator</code> lists a default constructor. + However, no specification is given what this constructor should do. + </para></listitem></varlistentry> + + <varlistentry><term><ulink url="lwg-defects.html#241">241</ulink>: + <emphasis>Does unique_copy() require CopyConstructible and Assignable?</emphasis> + </term> + <listitem><para>Add a helper for forward_iterator/output_iterator, fix the existing + one for input_iterator/output_iterator to not rely on Assignability. + </para></listitem></varlistentry> + + <varlistentry><term><ulink url="lwg-defects.html#243">243</ulink>: + <emphasis>get and getline when sentry reports failure</emphasis> + </term> + <listitem><para>Store a null character only if the character array has a non-zero size. + </para></listitem></varlistentry> + + <varlistentry><term><ulink url="lwg-defects.html#251">251</ulink>: + <emphasis>basic_stringbuf missing allocator_type</emphasis> + </term> + <listitem><para>This nested typedef was originally not specified. + </para></listitem></varlistentry> + + <varlistentry><term><ulink url="lwg-defects.html#253">253</ulink>: + <emphasis>valarray helper functions are almost entirely useless</emphasis> + </term> + <listitem><para>Make the copy constructor and copy-assignment operator declarations + public in gslice_array, indirect_array, mask_array, slice_array; provide + definitions. + </para></listitem></varlistentry> + + <varlistentry><term><ulink url="lwg-defects.html#265">265</ulink>: + <emphasis>std::pair::pair() effects overly restrictive</emphasis> + </term> + <listitem><para>The default ctor would build its members from copies of temporaries; + now it simply uses their respective default ctors. + </para></listitem></varlistentry> + + <varlistentry><term><ulink url="lwg-defects.html#266">266</ulink>: + <emphasis>bad_exception::~bad_exception() missing Effects clause</emphasis> + </term> + <listitem><para>The <code>bad_</code>* classes no longer have destructors (they + are trivial), since no description of them was ever given. + </para></listitem></varlistentry> + + <varlistentry><term><ulink url="lwg-defects.html#271">271</ulink>: + <emphasis>basic_iostream missing typedefs</emphasis> + </term> + <listitem><para>The typedefs it inherits from its base classes can't be used, since + (for example) <code>basic_iostream<T>::traits_type</code> is ambiguous. + </para></listitem></varlistentry> + + <varlistentry><term><ulink url="lwg-defects.html#275">275</ulink>: + <emphasis>Wrong type in num_get::get() overloads</emphasis> + </term> + <listitem><para>Similar to 118. + </para></listitem></varlistentry> + + <varlistentry><term><ulink url="lwg-defects.html#280">280</ulink>: + <emphasis>Comparison of reverse_iterator to const reverse_iterator</emphasis> + </term> + <listitem><para>Add global functions with two template parameters. + (NB: not added for now a templated assignment operator) + </para></listitem></varlistentry> + + <varlistentry><term><ulink url="lwg-defects.html#292">292</ulink>: + <emphasis>Effects of a.copyfmt (a)</emphasis> + </term> + <listitem><para>If <code>(this == &rhs)</code> do nothing. + </para></listitem></varlistentry> + + <varlistentry><term><ulink url="lwg-defects.html#300">300</ulink>: + <emphasis>List::merge() specification incomplete</emphasis> + </term> + <listitem><para>If <code>(this == &x)</code> do nothing. + </para></listitem></varlistentry> + + <varlistentry><term><ulink url="lwg-defects.html#303">303</ulink>: + <emphasis>Bitset input operator underspecified</emphasis> + </term> + <listitem><para>Basically, compare the input character to <code>is.widen(0)</code> + and <code>is.widen(1)</code>. + </para></listitem></varlistentry> + + <varlistentry><term><ulink url="lwg-defects.html#305">305</ulink>: + <emphasis>Default behavior of codecvt<wchar_t, char, mbstate_t>::length()</emphasis> + </term> + <listitem><para>Do not specify what <code>codecvt<wchar_t, char, mbstate_t>::do_length</code> + must return. + </para></listitem></varlistentry> + + <varlistentry><term><ulink url="lwg-defects.html#328">328</ulink>: + <emphasis>Bad sprintf format modifier in money_put<>::do_put()</emphasis> + </term> + <listitem><para>Change the format string to "%.0Lf". + </para></listitem></varlistentry> + + <varlistentry><term><ulink url="lwg-defects.html#365">365</ulink>: + <emphasis>Lack of const-qualification in clause 27</emphasis> + </term> + <listitem><para>Add const overloads of <code>is_open</code>. + </para></listitem></varlistentry> + + <varlistentry><term><ulink url="lwg-defects.html#389">389</ulink>: + <emphasis>Const overload of valarray::operator[] returns by value</emphasis> + </term> + <listitem><para>Change it to return a <code>const T&</code>. + </para></listitem></varlistentry> + + <varlistentry><term><ulink url="lwg-defects.html#402">402</ulink>: + <emphasis>Wrong new expression in [some_]allocator::construct</emphasis> + </term> + <listitem><para>Replace "new" with "::new". + </para></listitem></varlistentry> + + <varlistentry><term><ulink url="lwg-defects.html#409">409</ulink>: + <emphasis>Closing an fstream should clear the error state</emphasis> + </term> + <listitem><para>Have <code>open</code> clear the error flags. + </para></listitem></varlistentry> + + <varlistentry><term><ulink url="lwg-active.html#431">431</ulink>: + <emphasis>Swapping containers with unequal allocators</emphasis> + </term> + <listitem><para>Implement Option 3, as per N1599. + </para></listitem></varlistentry> + + <varlistentry><term><ulink url="lwg-defects.html#432">432</ulink>: + <emphasis>stringbuf::overflow() makes only one write position + available</emphasis> + </term> + <listitem><para>Implement the resolution, beyond DR 169. + </para></listitem></varlistentry> + + <varlistentry><term><ulink url="lwg-defects.html#434">434</ulink>: + <emphasis>bitset::to_string() hard to use</emphasis> + </term> + <listitem><para>Add three overloads, taking fewer template arguments. + </para></listitem></varlistentry> + + <varlistentry><term><ulink url="lwg-defects.html#438">438</ulink>: + <emphasis>Ambiguity in the "do the right thing" clause</emphasis> + </term> + <listitem><para>Implement the resolution, basically cast less. + </para></listitem></varlistentry> + + <varlistentry><term><ulink url="lwg-defects.html#453">453</ulink>: + <emphasis>basic_stringbuf::seekoff need not always fail for an empty stream</emphasis> + </term> + <listitem><para>Don't fail if the next pointer is null and newoff is zero. + </para></listitem></varlistentry> + + <varlistentry><term><ulink url="lwg-defects.html#455">455</ulink>: + <emphasis>cerr::tie() and wcerr::tie() are overspecified</emphasis> + </term> + <listitem><para>Initialize cerr tied to cout and wcerr tied to wcout. + </para></listitem></varlistentry> + + <varlistentry><term><ulink url="lwg-defects.html#464">464</ulink>: + <emphasis>Suggestion for new member functions in standard containers</emphasis> + </term> + <listitem><para>Add <code>data()</code> to <code>std::vector</code> and + <code>at(const key_type&)</code> to <code>std::map</code>. + </para></listitem></varlistentry> + + <varlistentry><term><ulink url="lwg-defects.html#508">508</ulink>: + <emphasis>Bad parameters for ranlux64_base_01</emphasis> + </term> + <listitem><para>Fix the parameters. + </para></listitem></varlistentry> + + <varlistentry><term><ulink url="lwg-closed.html#512">512</ulink>: + <emphasis>Seeding subtract_with_carry_01 from a single unsigned long</emphasis> + </term> + <listitem><para>Construct a <code>linear_congruential</code> engine and seed with it. + </para></listitem></varlistentry> + + <varlistentry><term><ulink url="lwg-closed.html#526">526</ulink>: + <emphasis>Is it undefined if a function in the standard changes in + parameters?</emphasis> + </term> + <listitem><para>Use &value. + </para></listitem></varlistentry> + + <varlistentry><term><ulink url="lwg-defects.html#538">538</ulink>: + <emphasis>241 again: Does unique_copy() require CopyConstructible + and Assignable?</emphasis> + </term> + <listitem><para>In case of input_iterator/output_iterator rely on Assignability of + input_iterator' value_type. + </para></listitem></varlistentry> + + <varlistentry><term><ulink url="lwg-defects.html#541">541</ulink>: + <emphasis>shared_ptr template assignment and void</emphasis> + </term> + <listitem><para>Add an auto_ptr<void> specialization. + </para></listitem></varlistentry> + + <varlistentry><term><ulink url="lwg-defects.html#543">543</ulink>: + <emphasis>valarray slice default constructor</emphasis> + </term> + <listitem><para>Follow the straightforward proposed resolution. + </para></listitem></varlistentry> + + <varlistentry><term><ulink url="lwg-defects.html#586">586</ulink>: + <emphasis>string inserter not a formatted function</emphasis> + </term> + <listitem><para>Change it to be a formatted output function (i.e. catch exceptions). + </para></listitem></varlistentry> + + <varlistentry><term><ulink url="lwg-active.html#596">596</ulink>: + <emphasis>27.8.1.3 Table 112 omits "a+" and "a+b" modes</emphasis> + </term> + <listitem><para>Add the missing modes to fopen_mode. + </para></listitem></varlistentry> + + <varlistentry><term><ulink url="lwg-defects.html#660">660</ulink>: + <emphasis>Missing bitwise operations</emphasis> + </term> + <listitem><para>Add the missing operations. + </para></listitem></varlistentry> + + <varlistentry><term><ulink url="lwg-active.html#693">693</ulink>: + <emphasis>std::bitset::all() missing</emphasis> + </term> + <listitem><para>Add it, consistently with the discussion. + </para></listitem></varlistentry> + + <varlistentry><term><ulink url="lwg-active.html#695">695</ulink>: + <emphasis>ctype<char>::classic_table() not accessible</emphasis> + </term> + <listitem><para>Make the member functions table and classic_table public. + </para></listitem></varlistentry> + </variablelist> + + </sect2> + </sect1> +</chapter> + + +<!-- Chapter 02 : Setup --> +<chapter id="manual.intro.setup" xreflabel="Setup"> + <title>Setup</title> + + <!-- Section 01 : Configure --> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" + parse="xml" href="configure.xml"> + </xi:include> + + <!-- Section 02 : Build --> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" + parse="xml" href="build.xml"> + </xi:include> + + <!-- Section 03 : Test --> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" + parse="xml" href="test.xml"> + </xi:include> +</chapter> + + +<!-- Chapter 03 : Using --> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" + parse="xml" href="using.xml"> +</xi:include> + +</part> diff --git a/libstdc++-v3/doc/xml/manual/io.xml b/libstdc++-v3/doc/xml/manual/io.xml new file mode 100644 index 00000000000..8b6806f90a7 --- /dev/null +++ b/libstdc++-v3/doc/xml/manual/io.xml @@ -0,0 +1,665 @@ +<?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.io" xreflabel="Input and Output"> +<?dbhtml filename="io.html"?> + +<partinfo> + <keywordset> + <keyword> + ISO C++ + </keyword> + <keyword> + library + </keyword> + </keywordset> +</partinfo> + +<title>Input and Output</title> + +<!-- Chapter 01 : Iostream Objects --> +<chapter id="manual.io.objects" xreflabel="IO Objects"> + <title>Iostream Objects</title> + + <para>To minimize the time you have to wait on the compiler, it's good to + only include the headers you really need. Many people simply include + <iostream> when they don't need to -- and that can <emphasis>penalize + your runtime as well.</emphasis> Here are some tips on which header to use + for which situations, starting with the simplest. + </para> + <para><emphasis><iosfwd></emphasis> should be included whenever you simply + need the <emphasis>name</emphasis> of an I/O-related class, such as + "ofstream" or "basic_streambuf". Like the name + implies, these are forward declarations. (A word to all you fellow + old school programmers: trying to forward declare classes like + "class istream;" won't work. Look in the iosfwd header if + you'd like to know why.) For example, + </para> + <programlisting> + #include <iosfwd> + + class MyClass + { + .... + std::ifstream& input_file; + }; + + extern std::ostream& operator<< (std::ostream&, MyClass&); + </programlisting> + <para><emphasis><ios></emphasis> declares the base classes for the entire + I/O stream hierarchy, std::ios_base and std::basic_ios<charT>, the + counting types std::streamoff and std::streamsize, the file + positioning type std::fpos, and the various manipulators like + std::hex, std::fixed, std::noshowbase, and so forth. + </para> + <para>The ios_base class is what holds the format flags, the state flags, + and the functions which change them (setf(), width(), precision(), + etc). You can also store extra data and register callback functions + through ios_base, but that has been historically underused. Anything + which doesn't depend on the type of characters stored is consolidated + here. + </para> + <para>The template class basic_ios is the highest template class in the + hierarchy; it is the first one depending on the character type, and + holds all general state associated with that type: the pointer to the + polymorphic stream buffer, the facet information, etc. + </para> + <para><emphasis><streambuf></emphasis> declares the template class + basic_streambuf, and two standard instantiations, streambuf and + wstreambuf. If you need to work with the vastly useful and capable + stream buffer classes, e.g., to create a new form of storage + transport, this header is the one to include. + </para> + <para><emphasis><istream></emphasis>/<emphasis><ostream></emphasis> are + the headers to include when you are using the >>/<< + interface, or any of the other abstract stream formatting functions. + For example, + </para> + <programlisting> + #include <istream> + + std::ostream& operator<< (std::ostream& os, MyClass& c) + { + return os << c.data1() << c.data2(); + } + </programlisting> + <para>The std::istream and std::ostream classes are the abstract parents of + the various concrete implementations. If you are only using the + interfaces, then you only need to use the appropriate interface header. + </para> + <para><emphasis><iomanip></emphasis> provides "extractors and inserters + that alter information maintained by class ios_base and its derived + classes," such as std::setprecision and std::setw. If you need + to write expressions like <code>os << setw(3);</code> or + <code>is >> setbase(8);</code>, you must include <iomanip>. + </para> + <para><emphasis><sstream></emphasis>/<emphasis><fstream></emphasis> + declare the six stringstream and fstream classes. As they are the + standard concrete descendants of istream and ostream, you will already + know about them. + </para> + <para>Finally, <emphasis><iostream></emphasis> provides the eight standard + global objects (cin, cout, etc). To do this correctly, this header + also provides the contents of the <istream> and <ostream> + headers, but nothing else. The contents of this header look like + </para> + <programlisting> + #include <ostream> + #include <istream> + + namespace std + { + extern istream cin; + extern ostream cout; + .... + + // this is explained below + <emphasis>static ios_base::Init __foo;</emphasis> // not its real name + } + </programlisting> + <para>Now, the runtime penalty mentioned previously: the global objects + must be initialized before any of your own code uses them; this is + guaranteed by the standard. Like any other global object, they must + be initialized once and only once. This is typically done with a + construct like the one above, and the nested class ios_base::Init is + specified in the standard for just this reason. + </para> + <para>How does it work? Because the header is included before any of your + code, the <emphasis>__foo</emphasis> object is constructed before any of + your objects. (Global objects are built in the order in which they + are declared, and destroyed in reverse order.) The first time the + constructor runs, the eight stream objects are set up. + </para> + <para>The <code>static</code> keyword means that each object file compiled + from a source file containing <iostream> will have its own + private copy of <emphasis>__foo</emphasis>. There is no specified order + of construction across object files (it's one of those pesky NP + problems that make life so interesting), so one copy in each object + file means that the stream objects are guaranteed to be set up before + any of your code which uses them could run, thereby meeting the + requirements of the standard. + </para> + <para>The penalty, of course, is that after the first copy of + <emphasis>__foo</emphasis> is constructed, all the others are just wasted + processor time. The time spent is merely for an increment-and-test + inside a function call, but over several dozen or hundreds of object + files, that time can add up. (It's not in a tight loop, either.) + </para> + <para>The lesson? Only include <iostream> when you need to use one of + the standard objects in that source file; you'll pay less startup + time. Only include the header files you need to in general; your + compile times will go down when there's less parsing work to do. + </para> + +</chapter> + +<!-- Chapter 02 : Stream Buffers --> +<chapter id="manual.io.streambufs" xreflabel="Stream Buffers"> + <title>Stream Buffers</title> + + <sect1 id="io.streambuf.derived" xreflabel="Derived streambuf Classes"> + <title>Derived streambuf Classes</title> + <para> + </para> + + <para>Creating your own stream buffers for I/O can be remarkably easy. + If you are interested in doing so, we highly recommend two very + excellent books: + <ulink url="http://www.langer.camelot.de/iostreams.html">Standard C++ + IOStreams and Locales</ulink> by Langer and Kreft, ISBN 0-201-18395-1, and + <ulink url="http://www.josuttis.com/libbook/">The C++ Standard Library</ulink> + by Nicolai Josuttis, ISBN 0-201-37926-0. Both are published by + Addison-Wesley, who isn't paying us a cent for saying that, honest. + </para> + <para>Here is a simple example, io/outbuf1, from the Josuttis text. It + transforms everything sent through it to uppercase. This version + assumes many things about the nature of the character type being + used (for more information, read the books or the newsgroups): + </para> + <programlisting> + #include <iostream> + #include <streambuf> + #include <locale> + #include <cstdio> + + class outbuf : public std::streambuf + { + protected: + /* central output function + * - print characters in uppercase mode + */ + virtual int_type overflow (int_type c) { + if (c != EOF) { + // convert lowercase to uppercase + c = std::toupper(static_cast<char>(c),getloc()); + + // and write the character to the standard output + if (putchar(c) == EOF) { + return EOF; + } + } + return c; + } + }; + + int main() + { + // create special output buffer + outbuf ob; + // initialize output stream with that output buffer + std::ostream out(&ob); + + out << "31 hexadecimal: " + << std::hex << 31 << std::endl; + return 0; + } + </programlisting> + <para>Try it yourself! More examples can be found in 3.1.x code, in + <code>include/ext/*_filebuf.h</code>, and on + <ulink url="http://www.informatik.uni-konstanz.de/~kuehl/c++/iostream/">Dietmar + Kühl's IOStreams page</ulink>. + </para> + + </sect1> + + <sect1 id="io.streambuf.buffering" xreflabel="Buffering"> + <title>Buffering</title> + <para>First, are you sure that you understand buffering? Particularly + the fact that C++ may not, in fact, have anything to do with it? + </para> + <para>The rules for buffering can be a little odd, but they aren't any + different from those of C. (Maybe that's why they can be a bit + odd.) Many people think that writing a newline to an output + stream automatically flushes the output buffer. This is true only + when the output stream is, in fact, a terminal and not a file + or some other device -- and <emphasis>that</emphasis> may not even be true + since C++ says nothing about files nor terminals. All of that is + system-dependent. (The "newline-buffer-flushing only occurring + on terminals" thing is mostly true on Unix systems, though.) + </para> + <para>Some people also believe that sending <code>endl</code> down an + output stream only writes a newline. This is incorrect; after a + newline is written, the buffer is also flushed. Perhaps this + is the effect you want when writing to a screen -- get the text + out as soon as possible, etc -- but the buffering is largely + wasted when doing this to a file: + </para> + <programlisting> + output << "a line of text" << endl; + output << some_data_variable << endl; + output << "another line of text" << endl; </programlisting> + <para>The proper thing to do in this case to just write the data out + and let the libraries and the system worry about the buffering. + If you need a newline, just write a newline: + </para> + <programlisting> + output << "a line of text\n" + << some_data_variable << '\n' + << "another line of text\n"; </programlisting> + <para>I have also joined the output statements into a single statement. + You could make the code prettier by moving the single newline to + the start of the quoted text on the last line, for example. + </para> + <para>If you do need to flush the buffer above, you can send an + <code>endl</code> if you also need a newline, or just flush the buffer + yourself: + </para> + <programlisting> + output << ...... << flush; // can use std::flush manipulator + output.flush(); // or call a member fn </programlisting> + <para>On the other hand, there are times when writing to a file should + be like writing to standard error; no buffering should be done + because the data needs to appear quickly (a prime example is a + log file for security-related information). The way to do this is + just to turn off the buffering <emphasis>before any I/O operations at + all</emphasis> have been done (note that opening counts as an I/O operation): + </para> + <programlisting> + std::ofstream os; + std::ifstream is; + int i; + + os.rdbuf()->pubsetbuf(0,0); + is.rdbuf()->pubsetbuf(0,0); + + os.open("/foo/bar/baz"); + is.open("/qux/quux/quuux"); + ... + os << "this data is written immediately\n"; + is >> i; // and this will probably cause a disk read </programlisting> + <para>Since all aspects of buffering are handled by a streambuf-derived + member, it is necessary to get at that member with <code>rdbuf()</code>. + Then the public version of <code>setbuf</code> can be called. The + arguments are the same as those for the Standard C I/O Library + function (a buffer area followed by its size). + </para> + <para>A great deal of this is implementation-dependent. For example, + <code>streambuf</code> does not specify any actions for its own + <code>setbuf()</code>-ish functions; the classes derived from + <code>streambuf</code> each define behavior that "makes + sense" for that class: an argument of (0,0) turns off buffering + for <code>filebuf</code> but does nothing at all for its siblings + <code>stringbuf</code> and <code>strstreambuf</code>, and specifying + anything other than (0,0) has varying effects. + User-defined classes derived from <code>streambuf</code> can + do whatever they want. (For <code>filebuf</code> and arguments for + <code>(p,s)</code> other than zeros, libstdc++ does what you'd expect: + the first <code>s</code> bytes of <code>p</code> are used as a buffer, + which you must allocate and deallocate.) + </para> + <para>A last reminder: there are usually more buffers involved than + just those at the language/library level. Kernel buffers, disk + buffers, and the like will also have an effect. Inspecting and + changing those are system-dependent. + </para> + + </sect1> +</chapter> + +<!-- Chapter 03 : Memory-based Streams --> +<chapter id="manual.io.memstreams" xreflabel="Memory Streams"> + <title>Memory Based Streams</title> + <sect1 id="manual.io.memstreams.compat" xreflabel="Compatibility strstream"> + <title>Compatibility With strstream</title> + <para> + </para> + <para>Stringstreams (defined in the header <code><sstream></code>) + are in this author's opinion one of the coolest things since + sliced time. An example of their use is in the Received Wisdom + section for Chapter 21 (Strings), + <ulink url="../21_strings/howto.html#1.1internal"> describing how to + format strings</ulink>. + </para> + <para>The quick definition is: they are siblings of ifstream and ofstream, + and they do for <code>std::string</code> what their siblings do for + files. All that work you put into writing <code><<</code> and + <code>>></code> functions for your classes now pays off + <emphasis>again!</emphasis> Need to format a string before passing the string + to a function? Send your stuff via <code><<</code> to an + ostringstream. You've read a string as input and need to parse it? + Initialize an istringstream with that string, and then pull pieces + out of it with <code>>></code>. Have a stringstream and need to + get a copy of the string inside? Just call the <code>str()</code> + member function. + </para> + <para>This only works if you've written your + <code><<</code>/<code>>></code> functions correctly, though, + and correctly means that they take istreams and ostreams as + parameters, not i<emphasis>f</emphasis>streams and o<emphasis>f</emphasis>streams. If they + take the latter, then your I/O operators will work fine with + file streams, but with nothing else -- including stringstreams. + </para> + <para>If you are a user of the strstream classes, you need to update + your code. You don't have to explicitly append <code>ends</code> to + terminate the C-style character array, you don't have to mess with + "freezing" functions, and you don't have to manage the + memory yourself. The strstreams have been officially deprecated, + which means that 1) future revisions of the C++ Standard won't + support them, and 2) if you use them, people will laugh at you. + </para> + + + </sect1> +</chapter> + +<!-- Chapter 04 : File-based Streams --> +<chapter id="manual.io.filestreams" xreflabel="File Streams"> + <title>File Based Streams</title> + + <sect1 id="manual.io.filestreams.copying_a_file" xreflabel="Copying a File"> + <title>Copying a File</title> + <para> + </para> + + <para>So you want to copy a file quickly and easily, and most important, + completely portably. And since this is C++, you have an open + ifstream (call it IN) and an open ofstream (call it OUT): + </para> + <programlisting> + #include <fstream> + + std::ifstream IN ("input_file"); + std::ofstream OUT ("output_file"); </programlisting> + <para>Here's the easiest way to get it completely wrong: + </para> + <programlisting> + OUT << IN;</programlisting> + <para>For those of you who don't already know why this doesn't work + (probably from having done it before), I invite you to quickly + create a simple text file called "input_file" containing + the sentence + </para> + <programlisting> + The quick brown fox jumped over the lazy dog.</programlisting> + <para>surrounded by blank lines. Code it up and try it. The contents + of "output_file" may surprise you. + </para> + <para>Seriously, go do it. Get surprised, then come back. It's worth it. + </para> + <para>The thing to remember is that the <code>basic_[io]stream</code> classes + handle formatting, nothing else. In particular, they break up on + whitespace. The actual reading, writing, and storing of data is + handled by the <code>basic_streambuf</code> family. Fortunately, the + <code>operator<<</code> is overloaded to take an ostream and + a pointer-to-streambuf, in order to help with just this kind of + "dump the data verbatim" situation. + </para> + <para>Why a <emphasis>pointer</emphasis> to streambuf and not just a streambuf? Well, + the [io]streams hold pointers (or references, depending on the + implementation) to their buffers, not the actual + buffers. This allows polymorphic behavior on the part of the buffers + as well as the streams themselves. The pointer is easily retrieved + using the <code>rdbuf()</code> member function. Therefore, the easiest + way to copy the file is: + </para> + <programlisting> + OUT << IN.rdbuf();</programlisting> + <para>So what <emphasis>was</emphasis> happening with OUT<<IN? Undefined + behavior, since that particular << isn't defined by the Standard. + I have seen instances where it is implemented, but the character + extraction process removes all the whitespace, leaving you with no + blank lines and only "Thequickbrownfox...". With + libraries that do not define that operator, IN (or one of IN's + member pointers) sometimes gets converted to a void*, and the output + file then contains a perfect text representation of a hexadecimal + address (quite a big surprise). Others don't compile at all. + </para> + <para>Also note that none of this is specific to o<emphasis>*f*</emphasis>streams. + The operators shown above are all defined in the parent + basic_ostream class and are therefore available with all possible + descendants. + </para> + + </sect1> + + <sect1 id="manual.io.filestreams.binary" xreflabel="Binary Input and Output"> + <title>Binary Input and Output</title> + <para> + </para> + <para>The first and most important thing to remember about binary I/O is + that opening a file with <code>ios::binary</code> is not, repeat + <emphasis>not</emphasis>, the only thing you have to do. It is not a silver + bullet, and will not allow you to use the <code><</>></code> + operators of the normal fstreams to do binary I/O. + </para> + <para>Sorry. Them's the breaks. + </para> + <para>This isn't going to try and be a complete tutorial on reading and + writing binary files (because "binary" + <ulink url="#7">covers a lot of ground)</ulink>, but we will try and clear + up a couple of misconceptions and common errors. + </para> + <para>First, <code>ios::binary</code> has exactly one defined effect, no more + and no less. Normal text mode has to be concerned with the newline + characters, and the runtime system will translate between (for + example) '\n' and the appropriate end-of-line sequence (LF on Unix, + CRLF on DOS, CR on Macintosh, etc). (There are other things that + normal mode does, but that's the most obvious.) Opening a file in + binary mode disables this conversion, so reading a CRLF sequence + under Windows won't accidentally get mapped to a '\n' character, etc. + Binary mode is not supposed to suddenly give you a bitstream, and + if it is doing so in your program then you've discovered a bug in + your vendor's compiler (or some other part of the C++ implementation, + possibly the runtime system). + </para> + <para>Second, using <code><<</code> to write and <code>>></code> to + read isn't going to work with the standard file stream classes, even + if you use <code>skipws</code> during reading. Why not? Because + ifstream and ofstream exist for the purpose of <emphasis>formatting</emphasis>, + not reading and writing. Their job is to interpret the data into + text characters, and that's exactly what you don't want to happen + during binary I/O. + </para> + <para>Third, using the <code>get()</code> and <code>put()/write()</code> member + functions still aren't guaranteed to help you. These are + "unformatted" I/O functions, but still character-based. + (This may or may not be what you want, see below.) + </para> + <para>Notice how all the problems here are due to the inappropriate use + of <emphasis>formatting</emphasis> functions and classes to perform something + which <emphasis>requires</emphasis> that formatting not be done? There are a + seemingly infinite number of solutions, and a few are listed here: + </para> + <itemizedlist> + <listitem> + <para><quote>Derive your own fstream-type classes and write your own + <</>> operators to do binary I/O on whatever data + types you're using.</quote> + </para> + <para> + This is a Bad Thing, because while + the compiler would probably be just fine with it, other humans + are going to be confused. The overloaded bitshift operators + have a well-defined meaning (formatting), and this breaks it. + </para> + </listitem> + <listitem> + <para> + <quote>Build the file structure in memory, then + <code>mmap()</code> the file and copy the + structure. + </quote> + </para> + <para> + Well, this is easy to make work, and easy to break, and is + pretty equivalent to using <code>::read()</code> and + <code>::write()</code> directly, and makes no use of the + iostream library at all... + </para> + </listitem> + <listitem> + <para> + <quote>Use streambufs, that's what they're there for.</quote> + </para> + <para> + While not trivial for the beginner, this is the best of all + solutions. The streambuf/filebuf layer is the layer that is + responsible for actual I/O. If you want to use the C++ + library for binary I/O, this is where you start. + </para> + </listitem> + </itemizedlist> + <para>How to go about using streambufs is a bit beyond the scope of this + document (at least for now), but while streambufs go a long way, + they still leave a couple of things up to you, the programmer. + As an example, byte ordering is completely between you and the + operating system, and you have to handle it yourself. + </para> + <para>Deriving a streambuf or filebuf + class from the standard ones, one that is specific to your data + types (or an abstraction thereof) is probably a good idea, and + lots of examples exist in journals and on Usenet. Using the + standard filebufs directly (either by declaring your own or by + using the pointer returned from an fstream's <code>rdbuf()</code>) + is certainly feasible as well. + </para> + <para>One area that causes problems is trying to do bit-by-bit operations + with filebufs. C++ is no different from C in this respect: I/O + must be done at the byte level. If you're trying to read or write + a few bits at a time, you're going about it the wrong way. You + must read/write an integral number of bytes and then process the + bytes. (For example, the streambuf functions take and return + variables of type <code>int_type</code>.) + </para> + <para>Another area of problems is opening text files in binary mode. + Generally, binary mode is intended for binary files, and opening + text files in binary mode means that you now have to deal with all of + those end-of-line and end-of-file problems that we mentioned before. + An instructive thread from comp.lang.c++.moderated delved off into + this topic starting more or less at + <ulink url="http://groups.google.com/groups?oi=djq&selm=an_436187505">this</ulink> + article and continuing to the end of the thread. (You'll have to + sort through some flames every couple of paragraphs, but the points + made are good ones.) + </para> + + </sect1> + + <sect1 id="manual.io.filestreams.binary2" xreflabel="Binary Input and Output"> + <title>More Binary Input and Output</title> + <para>Towards the beginning of February 2001, the subject of + "binary" I/O was brought up in a couple of places at the + same time. One notable place was Usenet, where James Kanze and + Dietmar Kühl separately posted articles on why attempting + generic binary I/O was not a good idea. (Here are copies of + <ulink url="binary_iostreams_kanze.txt">Kanze's article</ulink> and + <ulink url="binary_iostreams_kuehl.txt">Kühl's article</ulink>.) + </para> + <para>Briefly, the problems of byte ordering and type sizes mean that + the unformatted functions like <code>ostream::put()</code> and + <code>istream::get()</code> cannot safely be used to communicate + between arbitrary programs, or across a network, or from one + invocation of a program to another invocation of the same program + on a different platform, etc. + </para> + <para>The entire Usenet thread is instructive, and took place under the + subject heading "binary iostreams" on both comp.std.c++ + and comp.lang.c++.moderated in parallel. Also in that thread, + Dietmar Kühl mentioned that he had written a pair of stream + classes that would read and write XDR, which is a good step towards + a portable binary format. + </para> + + </sect1> + +</chapter> + +<!-- Chapter 03 : Interacting with C --> +<chapter id="manual.io.c" xreflabel="Interacting with C"> + <title>Interacting with C</title> + + + <sect1 id="manual.io.c.FILE" xreflabel="Using FILE* and file descriptors"> + <title>Using FILE* and file descriptors</title> + <para> + See the <link linkend="manual.ext.io">extensions</link> for using + <type>FILE</type> and <type>file descriptors</type> with + <classname>ofstream</classname> and + <classname>ifstream</classname>. + </para> + </sect1> + + <sect1 id="manual.io.c.sync" xreflabel="Performance Issues"> + <title>Performance</title> + <para> + Pathetic Performance? Ditch C. + </para> + <para>It sounds like a flame on C, but it isn't. Really. Calm down. + I'm just saying it to get your attention. + </para> + <para>Because the C++ library includes the C library, both C-style and + C++-style I/O have to work at the same time. For example: + </para> + <programlisting> + #include <iostream> + #include <cstdio> + + std::cout << "Hel"; + std::printf ("lo, worl"); + std::cout << "d!\n"; + </programlisting> + <para>This must do what you think it does. + </para> + <para>Alert members of the audience will immediately notice that buffering + is going to make a hash of the output unless special steps are taken. + </para> + <para>The special steps taken by libstdc++, at least for version 3.0, + involve doing very little buffering for the standard streams, leaving + most of the buffering to the underlying C library. (This kind of + thing is tricky to get right.) + The upside is that correctness is ensured. The downside is that + writing through <code>cout</code> can quite easily lead to awful + performance when the C++ I/O library is layered on top of the C I/O + library (as it is for 3.0 by default). Some patches have been applied + which improve the situation for 3.1. + </para> + <para>However, the C and C++ standard streams only need to be kept in sync + when both libraries' facilities are in use. If your program only uses + C++ I/O, then there's no need to sync with the C streams. The right + thing to do in this case is to call + </para> + <programlisting> + #include <emphasis>any of the I/O headers such as ios, iostream, etc</emphasis> + + std::ios::sync_with_stdio(false); + </programlisting> + <para>You must do this before performing any I/O via the C++ stream objects. + Once you call this, the C++ streams will operate independently of the + (unused) C streams. For GCC 3.x, this means that <code>cout</code> and + company will become fully buffered on their own. + </para> + <para>Note, by the way, that the synchronization requirement only applies to + the standard streams (<code>cin</code>, <code>cout</code>, + <code>cerr</code>, + <code>clog</code>, and their wide-character counterparts). File stream + objects that you declare yourself have no such requirement and are fully + buffered. + </para> + + + </sect1> +</chapter> + +</part> diff --git a/libstdc++-v3/doc/xml/manual/iterators.xml b/libstdc++-v3/doc/xml/manual/iterators.xml new file mode 100644 index 00000000000..757249d277e --- /dev/null +++ b/libstdc++-v3/doc/xml/manual/iterators.xml @@ -0,0 +1,177 @@ +<?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.iterators" xreflabel="Iterators"> +<?dbhtml filename="iterators.html"?> + +<partinfo> + <keywordset> + <keyword> + ISO C++ + </keyword> + <keyword> + library + </keyword> + </keywordset> +</partinfo> + +<title>Iterators</title> + +<!-- Chapter 01 : Predefined --> +<chapter id="manual.iterators.predefined" xreflabel="Predefined"> + <title>Predefined</title> + + <sect1 id="iterators.predefined.vs_pointers" xreflabel="Versus Pointers"> + <title>Iterators vs. Pointers</title> + <para><ulink url="../faq/index.html#5_1">FAQ 5.1</ulink> points out that iterators + are not implemented as pointers. They are a generalization of + pointers, but they are implemented in libstdc++ as separate classes. + </para> + <para>Keeping that simple fact in mind as you design your code will + prevent a whole lot of difficult-to-understand bugs. + </para> + <para>You can think of it the other way 'round, even. Since iterators + are a generalization, that means that <emphasis>pointers</emphasis> are + <emphasis>iterators</emphasis>, and that pointers can be used whenever an + iterator would be. All those functions in the Algorithms chapter + of the Standard will work just as well on plain arrays and their + pointers. + </para> + <para>That doesn't mean that when you pass in a pointer, it gets wrapped + into some special delegating iterator-to-pointer class with a layer + of overhead. (If you think that's the case anywhere, you don't + understand templates to begin with...) Oh, no; if you pass + in a pointer, then the compiler will instantiate that template + using T* as a type, and good old high-speed pointer arithmetic as + its operations, so the resulting code will be doing exactly the same + things as it would be doing if you had hand-coded it yourself (for + the 273rd time). + </para> + <para>How much overhead <emphasis>is</emphasis> there when using an iterator class? + Very little. Most of the layering classes contain nothing but + typedefs, and typedefs are "meta-information" that simply + tell the compiler some nicknames; they don't create code. That + information gets passed down through inheritance, so while the + compiler has to do work looking up all the names, your runtime code + does not. (This has been a prime concern from the beginning.) + </para> + + + </sect1> + + <sect1 id="iterators.predefined.end" xreflabel="end() Is One Past the End"> + <title>One Past the End</title> + + <para>This starts off sounding complicated, but is actually very easy, + especially towards the end. Trust me. + </para> + <para>Beginners usually have a little trouble understand the whole + 'past-the-end' thing, until they remember their early algebra classes + (see, they <emphasis>told</emphasis> you that stuff would come in handy!) and + the concept of half-open ranges. + </para> + <para>First, some history, and a reminder of some of the funkier rules in + C and C++ for builtin arrays. The following rules have always been + true for both languages: + </para> + <orderedlist> + <listitem> + <para>You can point anywhere in the array, <emphasis>or to the first element + past the end of the array</emphasis>. A pointer that points to one + past the end of the array is guaranteed to be as unique as a + pointer to somewhere inside the array, so that you can compare + such pointers safely. + </para> + </listitem> + <listitem> + <para>You can only dereference a pointer that points into an array. + If your array pointer points outside the array -- even to just + one past the end -- and you dereference it, Bad Things happen. + </para> + </listitem> + <listitem> + <para>Strictly speaking, simply pointing anywhere else invokes + undefined behavior. Most programs won't puke until such a + pointer is actually dereferenced, but the standards leave that + up to the platform. + </para> + </listitem> + </orderedlist> + <para>The reason this past-the-end addressing was allowed is to make it + easy to write a loop to go over an entire array, e.g., + while (*d++ = *s++);. + </para> + <para>So, when you think of two pointers delimiting an array, don't think + of them as indexing 0 through n-1. Think of them as <emphasis>boundary + markers</emphasis>: + </para> + <programlisting> + + beginning end + | | + | | This is bad. Always having to + | | remember to add or subtract one. + | | Off-by-one bugs very common here. + V V + array of N elements + |---|---|--...--|---|---| + | 0 | 1 | ... |N-2|N-1| + |---|---|--...--|---|---| + + ^ ^ + | | + | | This is good. This is safe. This + | | is guaranteed to work. Just don't + | | dereference 'end'. + beginning end + + </programlisting> + <para>See? Everything between the boundary markers is part of the array. + Simple. + </para> + <para>Now think back to your junior-high school algebra course, when you + were learning how to draw graphs. Remember that a graph terminating + with a solid dot meant, "Everything up through this point," + and a graph terminating with an open dot meant, "Everything up + to, but not including, this point," respectively called closed + and open ranges? Remember how closed ranges were written with + brackets, <emphasis>[a,b]</emphasis>, and open ranges were written with parentheses, + <emphasis>(a,b)</emphasis>? + </para> + <para>The boundary markers for arrays describe a <emphasis>half-open range</emphasis>, + starting with (and including) the first element, and ending with (but + not including) the last element: <emphasis>[beginning,end)</emphasis>. See, I + told you it would be simple in the end. + </para> + <para>Iterators, and everything working with iterators, follows this same + time-honored tradition. A container's <code>begin()</code> method returns + an iterator referring to the first element, and its <code>end()</code> + method returns a past-the-end iterator, which is guaranteed to be + unique and comparable against any other iterator pointing into the + middle of the container. + </para> + <para>Container constructors, container methods, and algorithms, all take + pairs of iterators describing a range of values on which to operate. + All of these ranges are half-open ranges, so you pass the beginning + iterator as the starting parameter, and the one-past-the-end iterator + as the finishing parameter. + </para> + <para>This generalizes very well. You can operate on sub-ranges quite + easily this way; functions accepting a <emphasis>[first,last)</emphasis> range + don't know or care whether they are the boundaries of an entire {array, + sequence, container, whatever}, or whether they only enclose a few + elements from the center. This approach also makes zero-length + sequences very simple to recognize: if the two endpoints compare + equal, then the {array, sequence, container, whatever} is empty. + </para> + <para>Just don't dereference <code>end()</code>. + </para> + + </sect1> +</chapter> + +<!-- Chapter 02 : Stream --> + +</part> diff --git a/libstdc++-v3/doc/xml/manual/locale.xml b/libstdc++-v3/doc/xml/manual/locale.xml new file mode 100644 index 00000000000..a4f20bd974c --- /dev/null +++ b/libstdc++-v3/doc/xml/manual/locale.xml @@ -0,0 +1,653 @@ +<sect1 id="manual.localization.locales.locale" xreflabel="locale"> +<?dbhtml filename="locale.html"?> + +<sect1info> + <keywordset> + <keyword> + ISO C++ + </keyword> + <keyword> + locale + </keyword> + </keywordset> +</sect1info> + +<title>locale</title> + +<para> +Describes the basic locale object, including nested +classes id, facet, and the reference-counted implementation object, +class _Impl. +</para> + +<sect2 id="locales.locale.req" xreflabel="locales.locale.req"> +<title>Requirements</title> + +<para> +Class locale is non-templatized and has two distinct types nested +inside of it: +</para> + +<blockquote> +<para> +<emphasis> +class facet +22.1.1.1.2 Class locale::facet +</emphasis> +</para> +</blockquote> + +<para> +Facets actually implement locale functionality. For instance, a facet +called numpunct is the data objects that can be used to query for the +thousands separator is in the German locale. +</para> + +<para> +Literally, a facet is strictly defined: +</para> + +<itemizedlist> + <listitem> + <para> + Dontaining the following public data member: + </para> + <para> + <code>static locale::id id;</code> + </para> + </listitem> + + <listitem> + <para> + Derived from another facet: + </para> + <para> + <code>class gnu_codecvt: public std::ctype<user-defined-type></code> + </para> + </listitem> +</itemizedlist> + +<para> +Of interest in this class are the memory management options explicitly +specified as an argument to facet's constructor. Each constructor of a +facet class takes a std::size_t __refs argument: if __refs == 0, the +facet is deleted when the locale containing it is destroyed. If __refs +== 1, the facet is not destroyed, even when it is no longer +referenced. +</para> + +<blockquote> +<para> +<emphasis> +class id +22.1.1.1.3 - Class locale::id +</emphasis> +</para> +</blockquote> + +<para> +Provides an index for looking up specific facets. +</para> +</sect2> + +<sect2 id="locales.locale.design" xreflabel="locales.locale.design"> +<title>Design</title> + +<para> +The major design challenge is fitting an object-orientated and +non-global locale design ontop of POSIX and other relevant stanards, +which include the Single Unix (nee X/Open.) +</para> + +<para> +Because C and earlier versions of POSIX falls down so completely, +portibility is an issue. +</para> + +</sect2> + +<sect2 id="locales.locale.impl" xreflabel="locales.locale.impl"> +<title>Implementation</title> + + <sect3 id="locale.impl.c" xreflabel="locale.impl.c"> + <title>Interacting with "C" locales</title> + +<itemizedlist> + <listitem> + <para> + <code>`locale -a`</code> displays available locales. + </para> +<blockquote> +<programlisting> +af_ZA +ar_AE +ar_AE.utf8 +ar_BH +ar_BH.utf8 +ar_DZ +ar_DZ.utf8 +ar_EG +ar_EG.utf8 +ar_IN +ar_IQ +ar_IQ.utf8 +ar_JO +ar_JO.utf8 +ar_KW +ar_KW.utf8 +ar_LB +ar_LB.utf8 +ar_LY +ar_LY.utf8 +ar_MA +ar_MA.utf8 +ar_OM +ar_OM.utf8 +ar_QA +ar_QA.utf8 +ar_SA +ar_SA.utf8 +ar_SD +ar_SD.utf8 +ar_SY +ar_SY.utf8 +ar_TN +ar_TN.utf8 +ar_YE +ar_YE.utf8 +be_BY +be_BY.utf8 +bg_BG +bg_BG.utf8 +br_FR +bs_BA +C +ca_ES +ca_ES@euro +ca_ES.utf8 +ca_ES.utf8@euro +cs_CZ +cs_CZ.utf8 +cy_GB +da_DK +da_DK.iso885915 +da_DK.utf8 +de_AT +de_AT@euro +de_AT.utf8 +de_AT.utf8@euro +de_BE +de_BE@euro +de_BE.utf8 +de_BE.utf8@euro +de_CH +de_CH.utf8 +de_DE +de_DE@euro +de_DE.utf8 +de_DE.utf8@euro +de_LU +de_LU@euro +de_LU.utf8 +de_LU.utf8@euro +el_GR +el_GR.utf8 +en_AU +en_AU.utf8 +en_BW +en_BW.utf8 +en_CA +en_CA.utf8 +en_DK +en_DK.utf8 +en_GB +en_GB.iso885915 +en_GB.utf8 +en_HK +en_HK.utf8 +en_IE +en_IE@euro +en_IE.utf8 +en_IE.utf8@euro +en_IN +en_NZ +en_NZ.utf8 +en_PH +en_PH.utf8 +en_SG +en_SG.utf8 +en_US +en_US.iso885915 +en_US.utf8 +en_ZA +en_ZA.utf8 +en_ZW +en_ZW.utf8 +es_AR +es_AR.utf8 +es_BO +es_BO.utf8 +es_CL +es_CL.utf8 +es_CO +es_CO.utf8 +es_CR +es_CR.utf8 +es_DO +es_DO.utf8 +es_EC +es_EC.utf8 +es_ES +es_ES@euro +es_ES.utf8 +es_ES.utf8@euro +es_GT +es_GT.utf8 +es_HN +es_HN.utf8 +es_MX +es_MX.utf8 +es_NI +es_NI.utf8 +es_PA +es_PA.utf8 +es_PE +es_PE.utf8 +es_PR +es_PR.utf8 +es_PY +es_PY.utf8 +es_SV +es_SV.utf8 +es_US +es_US.utf8 +es_UY +es_UY.utf8 +es_VE +es_VE.utf8 +et_EE +et_EE.utf8 +eu_ES +eu_ES@euro +eu_ES.utf8 +eu_ES.utf8@euro +fa_IR +fi_FI +fi_FI@euro +fi_FI.utf8 +fi_FI.utf8@euro +fo_FO +fo_FO.utf8 +fr_BE +fr_BE@euro +fr_BE.utf8 +fr_BE.utf8@euro +fr_CA +fr_CA.utf8 +fr_CH +fr_CH.utf8 +fr_FR +fr_FR@euro +fr_FR.utf8 +fr_FR.utf8@euro +fr_LU +fr_LU@euro +fr_LU.utf8 +fr_LU.utf8@euro +ga_IE +ga_IE@euro +ga_IE.utf8 +ga_IE.utf8@euro +gl_ES +gl_ES@euro +gl_ES.utf8 +gl_ES.utf8@euro +gv_GB +gv_GB.utf8 +he_IL +he_IL.utf8 +hi_IN +hr_HR +hr_HR.utf8 +hu_HU +hu_HU.utf8 +id_ID +id_ID.utf8 +is_IS +is_IS.utf8 +it_CH +it_CH.utf8 +it_IT +it_IT@euro +it_IT.utf8 +it_IT.utf8@euro +iw_IL +iw_IL.utf8 +ja_JP.eucjp +ja_JP.utf8 +ka_GE +kl_GL +kl_GL.utf8 +ko_KR.euckr +ko_KR.utf8 +kw_GB +kw_GB.utf8 +lt_LT +lt_LT.utf8 +lv_LV +lv_LV.utf8 +mi_NZ +mk_MK +mk_MK.utf8 +mr_IN +ms_MY +ms_MY.utf8 +mt_MT +mt_MT.utf8 +nl_BE +nl_BE@euro +nl_BE.utf8 +nl_BE.utf8@euro +nl_NL +nl_NL@euro +nl_NL.utf8 +nl_NL.utf8@euro +nn_NO +nn_NO.utf8 +no_NO +no_NO.utf8 +oc_FR +pl_PL +pl_PL.utf8 +POSIX +pt_BR +pt_BR.utf8 +pt_PT +pt_PT@euro +pt_PT.utf8 +pt_PT.utf8@euro +ro_RO +ro_RO.utf8 +ru_RU +ru_RU.koi8r +ru_RU.utf8 +ru_UA +ru_UA.utf8 +se_NO +sk_SK +sk_SK.utf8 +sl_SI +sl_SI.utf8 +sq_AL +sq_AL.utf8 +sr_YU +sr_YU@cyrillic +sr_YU.utf8 +sr_YU.utf8@cyrillic +sv_FI +sv_FI@euro +sv_FI.utf8 +sv_FI.utf8@euro +sv_SE +sv_SE.iso885915 +sv_SE.utf8 +ta_IN +te_IN +tg_TJ +th_TH +th_TH.utf8 +tl_PH +tr_TR +tr_TR.utf8 +uk_UA +uk_UA.utf8 +ur_PK +uz_UZ +vi_VN +vi_VN.tcvn +wa_BE +wa_BE@euro +yi_US +zh_CN +zh_CN.gb18030 +zh_CN.gbk +zh_CN.utf8 +zh_HK +zh_HK.utf8 +zh_TW +zh_TW.euctw +zh_TW.utf8 +</programlisting> +</blockquote> +</listitem> + + <listitem> + <para> + <code>`locale`</code> displays environmental variables that + impact how locale("") will be deduced. + </para> +<blockquote> +<programlisting> +LANG=en_US +LC_CTYPE="en_US" +LC_NUMERIC="en_US" +LC_TIME="en_US" +LC_COLLATE="en_US" +LC_MONETARY="en_US" +LC_MESSAGES="en_US" +LC_PAPER="en_US" +LC_NAME="en_US" +LC_ADDRESS="en_US" +LC_TELEPHONE="en_US" +LC_MEASUREMENT="en_US" +LC_IDENTIFICATION="en_US" +LC_ALL= +</programlisting> +</blockquote> +</listitem> +</itemizedlist> + +<para> +From Josuttis, p. 697-698, which says, that "there is only *one* +relation (of the C++ locale mechanism) to the C locale mechanism: the +global C locale is modified if a named C++ locale object is set as the +global locale" (emphasis Paolo), that is: +</para> + +<programlisting>std::locale::global(std::locale(""));</programlisting> + +<para>affects the C functions as if the following call was made:</para> + +<programlisting>std::setlocale(LC_ALL, "");</programlisting> + +<para> + On the other hand, there is *no* viceversa, that is, calling + setlocale has *no* whatsoever on the C++ locale mechanism, in + particular on the working of locale(""), which constructs the locale + object from the environment of the running program, that is, in + practice, the set of LC_ALL, LANG, etc. variable of the shell. +</para> + + </sect3> +</sect2> + +<sect2 id="locales.locale.future" xreflabel="locales.locale.future"> +<title>Future</title> + +<itemizedlist> + <listitem> + <para> + Locale initialization: at what point does _S_classic, _S_global + get initialized? Can named locales assume this initialization + has already taken place? + </para> + </listitem> + + <listitem> + <para> + Document how named locales error check when filling data + members. Ie, a fr_FR locale that doesn't have + numpunct::truename(): does it use "true"? Or is it a blank + string? What's the convention? + </para> + </listitem> + + <listitem> + <para> + Explain how locale aliasing happens. When does "de_DE" use "de" + information? What is the rule for locales composed of just an + ISO language code (say, "de") and locales with both an ISO + language code and ISO country code (say, "de_DE"). + </para> + </listitem> + + <listitem> + <para> + What should non-required facet instantiations do? If the + generic implemenation is provided, then how to end-users + provide specializations? + </para> + </listitem> +</itemizedlist> +</sect2> + +<bibliography id="locales.locale.biblio" xreflabel="locales.locale.biblio"> +<title>Bibliography</title> + + <biblioentry> + <title> + The GNU C Library + </title> + + <author> + <surname>McGrath</surname> + <firstname>Roland</firstname> + </author> + <author> + <surname>Drepper</surname> + <firstname>Ulrich</firstname> + </author> + + <copyright> + <year>2007</year> + <holder>FSF</holder> + </copyright> + <pagenums>Chapters 6 Character Set Handling and 7 Locales and Internationalization</pagenums> + + </biblioentry> + + <biblioentry> + <title> + Correspondence + </title> + + <author> + <surname>Drepper</surname> + <firstname>Ulrich</firstname> + </author> + + <copyright> + <year>2002</year> + <holder></holder> + </copyright> + </biblioentry> + + <biblioentry> + <title> + ISO/IEC 14882:1998 Programming languages - C++ + </title> + + <copyright> + <year>1998</year> + <holder>ISO</holder> + </copyright> + </biblioentry> + + <biblioentry> + <title> + ISO/IEC 9899:1999 Programming languages - C + </title> + + <copyright> + <year>1999</year> + <holder>ISO</holder> + </copyright> + </biblioentry> + + <biblioentry> + <title> + System Interface Definitions, Issue 6 (IEEE Std. 1003.1-200x) + </title> + + <copyright> + <year>1999</year> + <holder> + The Open Group/The Institute of Electrical and Electronics Engineers, Inc.</holder> + </copyright> + + <biblioid> + <ulink url="http://www.opennc.org/austin/docreg.html"> + </ulink> + </biblioid> + + </biblioentry> + + <biblioentry> + <title> + The C++ Programming Language, Special Edition + </title> + + <author> + <surname>Stroustrup</surname> + <firstname>Bjarne</firstname> + </author> + + <copyright> + <year>2000</year> + <holder>Addison Wesley, Inc.</holder> + </copyright> + <pagenums>Appendix D</pagenums> + + <publisher> + <publishername> + Addison Wesley + </publishername> + </publisher> + + </biblioentry> + + + <biblioentry> + <title> + Standard C++ IOStreams and Locales + </title> + <subtitle> + Advanced Programmer's Guide and Reference + </subtitle> + + <author> + <surname>Langer</surname> + <firstname>Angelika</firstname> + </author> + + <author> + <surname>Kreft</surname> + <firstname>Klaus</firstname> + </author> + + <copyright> + <year>2000</year> + <holder>Addison Wesley Longman, Inc.</holder> + </copyright> + + <publisher> + <publishername> + Addison Wesley Longman + </publishername> + </publisher> + + </biblioentry> + +</bibliography> + +</sect1>
\ No newline at end of file diff --git a/libstdc++-v3/doc/xml/manual/localization.xml b/libstdc++-v3/doc/xml/manual/localization.xml new file mode 100644 index 00000000000..0c6d82ea762 --- /dev/null +++ b/libstdc++-v3/doc/xml/manual/localization.xml @@ -0,0 +1,54 @@ +<?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.localization" xreflabel="Localization"> +<?dbhtml filename="localization.html"?> + +<partinfo> + <keywordset> + <keyword> + ISO C++ + </keyword> + <keyword> + library + </keyword> + </keywordset> +</partinfo> + +<title>Localization</title> + +<!-- Chapter 01 : Locale --> +<chapter id="manual.localization.locales" xreflabel="Locales"> + <title>Locales</title> + + <!-- Section 01 : locale --> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" + parse="xml" href="locale.xml"> + </xi:include> +</chapter> + +<!-- Chapter 02 : Facet --> +<chapter id="manual.localization.facet" xreflabel="facet"> + <title>Facets aka Categories</title> + + <!-- Section 01 : ctype --> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" + parse="xml" href="ctype.xml"> + </xi:include> + + <!-- Section 02 : codecvt --> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" + parse="xml" href="codecvt.xml"> + </xi:include> + + <!-- Section 03 : messages --> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" + parse="xml" href="messages.xml"> + </xi:include> +</chapter> + +<!-- Chapter 03 : Interacting with C --> + +</part> diff --git a/libstdc++-v3/doc/xml/manual/messages.xml b/libstdc++-v3/doc/xml/manual/messages.xml new file mode 100644 index 00000000000..d32620fb3ad --- /dev/null +++ b/libstdc++-v3/doc/xml/manual/messages.xml @@ -0,0 +1,604 @@ +<sect1 id="manual.localization.facet.messages" xreflabel="messages"> +<?dbhtml filename="messages.html"?> + +<sect1info> + <keywordset> + <keyword> + ISO C++ + </keyword> + <keyword> + messages + </keyword> + </keywordset> +</sect1info> + +<title>messages</title> + +<para> +The std::messages facet implements message retrieval functionality +equivalent to Java's java.text.MessageFormat .using either GNU gettext +or IEEE 1003.1-200 functions. +</para> + +<sect2 id="facet.messages.req" xreflabel="facet.messages.req"> +<title>Requirements</title> + +<para> +The std::messages facet is probably the most vaguely defined facet in +the standard library. It's assumed that this facility was built into +the standard library in order to convert string literals from one +locale to the other. For instance, converting the "C" locale's +<code>const char* c = "please"</code> to a German-localized <code>"bitte"</code> +during program execution. +</para> + +<blockquote> +<para> +22.2.7.1 - Template class messages [lib.locale.messages] +</para> +</blockquote> + +<para> +This class has three public member functions, which directly +correspond to three protected virtual member functions. +</para> + +<para> +The public member functions are: +</para> + +<para> +<code>catalog open(const string&, const locale&) const</code> +</para> + +<para> +<code>string_type get(catalog, int, int, const string_type&) const</code> +</para> + +<para> +<code>void close(catalog) const</code> +</para> + +<para> +While the virtual functions are: +</para> + +<para> +<code>catalog do_open(const string&, const locale&) const</code> +</para> +<blockquote> +<para> +<emphasis> +-1- Returns: A value that may be passed to get() to retrieve a +message, from the message catalog identified by the string name +according to an implementation-defined mapping. The result can be used +until it is passed to close(). Returns a value less than 0 if no such +catalog can be opened. +</emphasis> +</para> +</blockquote> + +<para> +<code>string_type do_get(catalog, int, int, const string_type&) const</code> +</para> +<blockquote> +<para> +<emphasis> +-3- Requires: A catalog cat obtained from open() and not yet closed. +-4- Returns: A message identified by arguments set, msgid, and dfault, +according to an implementation-defined mapping. If no such message can +be found, returns dfault. +</emphasis> +</para> +</blockquote> + +<para> +<code>void do_close(catalog) const</code> +</para> +<blockquote> +<para> +<emphasis> +-5- Requires: A catalog cat obtained from open() and not yet closed. +-6- Effects: Releases unspecified resources associated with cat. +-7- Notes: The limit on such resources, if any, is implementation-defined. +</emphasis> +</para> +</blockquote> + + +</sect2> + +<sect2 id="facet.messages.design" xreflabel="facet.messages.design"> +<title>Design</title> + +<para> +A couple of notes on the standard. +</para> + +<para> +First, why is <code>messages_base::catalog</code> specified as a typedef +to int? This makes sense for implementations that use +<code>catopen</code>, but not for others. Fortunately, it's not heavily +used and so only a minor irritant. +</para> + +<para> +Second, by making the member functions <code>const</code>, it is +impossible to save state in them. Thus, storing away information used +in the 'open' member function for use in 'get' is impossible. This is +unfortunate. +</para> + +<para> +The 'open' member function in particular seems to be oddly +designed. The signature seems quite peculiar. Why specify a <code>const +string& </code> argument, for instance, instead of just <code>const +char*</code>? Or, why specify a <code>const locale&</code> argument that is +to be used in the 'get' member function? How, exactly, is this locale +argument useful? What was the intent? It might make sense if a locale +argument was associated with a given default message string in the +'open' member function, for instance. Quite murky and unclear, on +reflection. +</para> + +<para> +Lastly, it seems odd that messages, which explicitly require code +conversion, don't use the codecvt facet. Because the messages facet +has only one template parameter, it is assumed that ctype, and not +codecvt, is to be used to convert between character sets. +</para> + +<para> +It is implicitly assumed that the locale for the default message +string in 'get' is in the "C" locale. Thus, all source code is assumed +to be written in English, so translations are always from "en_US" to +other, explicitly named locales. +</para> + +</sect2> + +<sect2 id="facet.messages.impl" xreflabel="facet.messages.impl"> +<title>Implementation</title> + + <sect3 id="messages.impl.models" xreflabel="messages.impl.models"> + <title>Models</title> + <para> + This is a relatively simple class, on the face of it. The standard + specifies very little in concrete terms, so generic + implementations that are conforming yet do very little are the + norm. Adding functionality that would be useful to programmers and + comparable to Java's java.text.MessageFormat takes a bit of work, + and is highly dependent on the capabilities of the underlying + operating system. + </para> + + <para> + Three different mechanisms have been provided, selectable via + configure flags: + </para> + +<itemizedlist> + <listitem> + <para> + generic + </para> + <para> + This model does very little, and is what is used by default. + </para> + </listitem> + + <listitem> + <para> + gnu + </para> + <para> + The gnu model is complete and fully tested. It's based on the + GNU gettext package, which is part of glibc. It uses the + functions <code>textdomain, bindtextdomain, gettext</code> to + implement full functionality. Creating message catalogs is a + relatively straight-forward process and is lightly documented + below, and fully documented in gettext's distributed + documentation. + </para> + </listitem> + + <listitem> + <para> + ieee_1003.1-200x + </para> + <para> + This is a complete, though untested, implementation based on + the IEEE standard. The functions <code>catopen, catgets, + catclose</code> are used to retrieve locale-specific messages + given the appropriate message catalogs that have been + constructed for their use. Note, the script <code> + po2msg.sed</code> that is part of the gettext distribution can + convert gettext catalogs into catalogs that + <code>catopen</code> can use. + </para> + </listitem> +</itemizedlist> + +<para> +A new, standards-conformant non-virtual member function signature was +added for 'open' so that a directory could be specified with a given +message catalog. This simplifies calling conventions for the gnu +model. +</para> + + </sect3> + + <sect3 id="messages.impl.gnu" xreflabel="messages.impl.gnu"> + <title>The GNU Model</title> + + <para> + The messages facet, because it is retrieving and converting + between characters sets, depends on the ctype and perhaps the + codecvt facet in a given locale. In addition, underlying "C" + library locale support is necessary for more than just the + <code>LC_MESSAGES</code> mask: <code>LC_CTYPE</code> is also + necessary. To avoid any unpleasantness, all bits of the "C" mask + (ie <code>LC_ALL</code>) are set before retrieving messages. + </para> + + <para> + Making the message catalogs can be initially tricky, but become + quite simple with practice. For complete info, see the gettext + documentation. Here's an idea of what is required: + </para> + +<itemizedlist> + <listitem> + <para> + Make a source file with the required string literals that need + to be translated. See <code>intl/string_literals.cc</code> for + an example. + </para> + </listitem> + + <listitem> + <para> + Make initial catalog (see "4 Making the PO Template File" from + the gettext docs).</para> + <para> + <code> xgettext --c++ --debug string_literals.cc -o libstdc++.pot </code> + </para> + </listitem> + + <listitem> + <para>Make language and country-specific locale catalogs.</para> + <para> + <code>cp libstdc++.pot fr_FR.po</code> + </para> + <para> + <code>cp libstdc++.pot de_DE.po</code> + </para> + </listitem> + + <listitem> + <para> + Edit localized catalogs in emacs so that strings are + translated. + </para> + <para> + <code>emacs fr_FR.po</code> + </para> + </listitem> + + <listitem> + <para>Make the binary mo files.</para> + <para> + <code>msgfmt fr_FR.po -o fr_FR.mo</code> + </para> + <para> + <code>msgfmt de_DE.po -o de_DE.mo</code> + </para> + </listitem> + + <listitem> + <para>Copy the binary files into the correct directory structure.</para> + <para> + <code>cp fr_FR.mo (dir)/fr_FR/LC_MESSAGES/libstdc++.mo</code> + </para> + <para> + <code>cp de_DE.mo (dir)/de_DE/LC_MESSAGES/libstdc++.mo</code> + </para> + </listitem> + + <listitem> + <para>Use the new message catalogs.</para> + <para> + <code>locale loc_de("de_DE");</code> + </para> + <para> + <code> + use_facet<messages<char> >(loc_de).open("libstdc++", locale(), dir); + </code> + </para> + </listitem> +</itemizedlist> + + </sect3> +</sect2> + +<sect2 id="facet.messages.use" xreflabel="facet.messages.use"> +<title>Use</title> + <para> + A simple example using the GNU model of message conversion. + </para> + +<programlisting> +#include <iostream> +#include <locale> +using namespace std; + +void test01() +{ + typedef messages<char>::catalog catalog; + const char* dir = + "/mnt/egcs/build/i686-pc-linux-gnu/libstdc++/po/share/locale"; + const locale loc_de("de_DE"); + const messages<char>& mssg_de = use_facet<messages<char> >(loc_de); + + catalog cat_de = mssg_de.open("libstdc++", loc_de, dir); + string s01 = mssg_de.get(cat_de, 0, 0, "please"); + string s02 = mssg_de.get(cat_de, 0, 0, "thank you"); + cout << "please in german:" << s01 << '\n'; + cout << "thank you in german:" << s02 << '\n'; + mssg_de.close(cat_de); +} +</programlisting> + +</sect2> + +<sect2 id="facet.messages.future" xreflabel="facet.messages.future"> +<title>Future</title> + +<itemizedlist> +<listitem> + <para> + Things that are sketchy, or remain unimplemented: + </para> + <itemizedlist> + <listitem> + <para> + _M_convert_from_char, _M_convert_to_char are in flux, + depending on how the library ends up doing character set + conversions. It might not be possible to do a real character + set based conversion, due to the fact that the template + parameter for messages is not enough to instantiate the + codecvt facet (1 supplied, need at least 2 but would prefer + 3). + </para> + </listitem> + + <listitem> + <para> + There are issues with gettext needing the global locale set + to extract a message. This dependence on the global locale + makes the current "gnu" model non MT-safe. Future versions + of glibc, ie glibc 2.3.x will fix this, and the C++ library + bits are already in place. + </para> + </listitem> + </itemizedlist> +</listitem> + +<listitem> + <para> + Development versions of the GNU "C" library, glibc 2.3 will allow + a more efficient, MT implementation of std::messages, and will + allow the removal of the _M_name_messages data member. If this is + done, it will change the library ABI. The C++ parts to support + glibc 2.3 have already been coded, but are not in use: once this + version of the "C" library is released, the marked parts of the + messages implementation can be switched over to the new "C" + library functionality. + </para> +</listitem> +<listitem> + <para> + At some point in the near future, std::numpunct will probably use + std::messages facilities to implement truename/falename + correctly. This is currently not done, but entries in + libstdc++.pot have already been made for "true" and "false" string + literals, so all that remains is the std::numpunct coding and the + configure/make hassles to make the installed library search its + own catalog. Currently the libstdc++.mo catalog is only searched + for the testsuite cases involving messages members. + </para> +</listitem> + +<listitem> + <para> The following member functions:</para> + + <para> + <code> + catalog + open(const basic_string<char>& __s, const locale& __loc) const + </code> + </para> + + <para> + <code> + catalog + open(const basic_string<char>&, const locale&, const char*) const; + </code> + </para> + + <para> + Don't actually return a "value less than 0 if no such catalog + can be opened" as required by the standard in the "gnu" + model. As of this writing, it is unknown how to query to see + if a specified message catalog exists using the gettext + package. + </para> +</listitem> +</itemizedlist> + +</sect2> + +<bibliography id="facet.messages.biblio" xreflabel="facet.messages.biblio"> +<title>Bibliography</title> + + <biblioentry> + <title> + The GNU C Library + </title> + + <author> + <surname>McGrath</surname> + <firstname>Roland</firstname> + </author> + <author> + <surname>Drepper</surname> + <firstname>Ulrich</firstname> + </author> + + <copyright> + <year>2007</year> + <holder>FSF</holder> + </copyright> + <pagenums>Chapters 6 Character Set Handling, and 7 Locales and Internationalization + </pagenums> + + </biblioentry> + + <biblioentry> + <title> + Correspondence + </title> + + <author> + <surname>Drepper</surname> + <firstname>Ulrich</firstname> + </author> + + <copyright> + <year>2002</year> + <holder></holder> + </copyright> + </biblioentry> + + <biblioentry> + <title> + ISO/IEC 14882:1998 Programming languages - C++ + </title> + + <copyright> + <year>1998</year> + <holder>ISO</holder> + </copyright> + </biblioentry> + + <biblioentry> + <title> + ISO/IEC 9899:1999 Programming languages - C + </title> + + <copyright> + <year>1999</year> + <holder>ISO</holder> + </copyright> + </biblioentry> + + <biblioentry> + <title> + System Interface Definitions, Issue 6 (IEEE Std. 1003.1-200x) + </title> + + <copyright> + <year>1999</year> + <holder> + The Open Group/The Institute of Electrical and Electronics Engineers, Inc.</holder> + </copyright> + + <biblioid> + <ulink url="http://www.opennc.org/austin/docreg.html"> + </ulink> + </biblioid> + + </biblioentry> + + <biblioentry> + <title> + The C++ Programming Language, Special Edition + </title> + + <author> + <surname>Stroustrup</surname> + <firstname>Bjarne</firstname> + </author> + + <copyright> + <year>2000</year> + <holder>Addison Wesley, Inc.</holder> + </copyright> + <pagenums>Appendix D</pagenums> + + <publisher> + <publishername> + Addison Wesley + </publishername> + </publisher> + + </biblioentry> + + + <biblioentry> + <title> + Standard C++ IOStreams and Locales + </title> + <subtitle> + Advanced Programmer's Guide and Reference + </subtitle> + + <author> + <surname>Langer</surname> + <firstname>Angelika</firstname> + </author> + + <author> + <surname>Kreft</surname> + <firstname>Klaus</firstname> + </author> + + <copyright> + <year>2000</year> + <holder>Addison Wesley Longman, Inc.</holder> + </copyright> + + <publisher> + <publishername> + Addison Wesley Longman + </publishername> + </publisher> + + </biblioentry> + + <biblioentry> + <title> + Java 2 Platform, Standard Edition, v 1.3.1 API Specification + </title> + <pagenums>java.util.Properties, java.text.MessageFormat, +java.util.Locale, java.util.ResourceBundle</pagenums> + <biblioid> + <ulink url="http://java.sun.com/j2se/1.3/docs/api"> + </ulink> + </biblioid> + </biblioentry> + + <biblioentry> + <title> + GNU gettext tools, version 0.10.38, Native Language Support +Library and Tools. + </title> + <biblioid> + <ulink url="http://sources.redhat.com/gettext"> + </ulink> + </biblioid> + </biblioentry> + +</bibliography> + +</sect1>
\ No newline at end of file diff --git a/libstdc++-v3/doc/xml/manual/mt_allocator.xml b/libstdc++-v3/doc/xml/manual/mt_allocator.xml new file mode 100644 index 00000000000..48f5c2fe502 --- /dev/null +++ b/libstdc++-v3/doc/xml/manual/mt_allocator.xml @@ -0,0 +1,554 @@ +<sect1 id="manual.ext.allocator.mt" xreflabel="mt allocator"> +<?dbhtml filename="mt_allocator.html"?> + +<sect1info> + <keywordset> + <keyword> + ISO C++ + </keyword> + <keyword> + allocator + </keyword> + </keywordset> +</sect1info> + +<title>mt_allocator</title> + +<para> +</para> + +<sect2 id="allocator.mt.intro" xreflabel="allocator.mt.intro"> +<title>Intro</title> + +<para> + The mt allocator [hereinafter referred to simply as "the allocator"] + is a fixed size (power of two) allocator that was initially + developed specifically to suit the needs of multi threaded + applications [hereinafter referred to as an MT application]. Over + time the allocator has evolved and been improved in many ways, in + particular it now also does a good job in single threaded + applications [hereinafter referred to as a ST application]. (Note: + In this document, when referring to single threaded applications + this also includes applications that are compiled with gcc without + thread support enabled. This is accomplished using ifdef's on + __GTHREADS). This allocator is tunable, very flexible, and capable + of high-performance. +</para> + +<para> + The aim of this document is to describe - from an application point of + view - the "inner workings" of the allocator. +</para> + +</sect2> + + +<sect2 id="allocator.mt.design_issues" xreflabel="allocator.mt.design_issues"> +<title>Design Issues</title> + +<sect3 id="allocator.mt.overview" xreflabel="allocator.mt.overview"> +<title>Overview</title> + + +<para> There are three general components to the allocator: a datum +describing the characteristics of the memory pool, a policy class +containing this pool that links instantiation types to common or +individual pools, and a class inheriting from the policy class that is +the actual allocator. +</para> + +<para>The datum describing pools characteristics is +</para> +<programlisting> + template<bool _Thread> + class __pool +</programlisting> +<para> This class is parametrized on thread support, and is explicitly +specialized for both multiple threads (with <code>bool==true</code>) +and single threads (via <code>bool==false</code>.) It is possible to +use a custom pool datum instead of the default class that is provided. +</para> + +<para> There are two distinct policy classes, each of which can be used +with either type of underlying pool datum. +</para> + +<programlisting> + template<bool _Thread> + struct __common_pool_policy + + template<typename _Tp, bool _Thread> + struct __per_type_pool_policy +</programlisting> + +<para> The first policy, <code>__common_pool_policy</code>, implements a +common pool. This means that allocators that are instantiated with +different types, say <code>char</code> and <code>long</code> will both +use the same pool. This is the default policy. +</para> + +<para> The second policy, <code>__per_type_pool_policy</code>, implements +a separate pool for each instantiating type. Thus, <code>char</code> +and <code>long</code> will use separate pools. This allows per-type +tuning, for instance. +</para> + +<para> Putting this all together, the actual allocator class is +</para> +<programlisting> + template<typename _Tp, typename _Poolp = __default_policy> + class __mt_alloc : public __mt_alloc_base<_Tp>, _Poolp +</programlisting> +<para> This class has the interface required for standard library allocator +classes, namely member functions <code>allocate</code> and +<code>deallocate</code>, plus others. +</para> + +</sect3> +</sect2> + +<sect2 id="allocator.mt.impl" xreflabel="allocator.mt.impl"> +<title>Implementation</title> + + +<sect3 id="allocator.mt.tune" xreflabel="allocator.mt.tune"> +<title>Tunable Parameters</title> + +<para>Certain allocation parameters can be modified, or tuned. There +exists a nested <code>struct __pool_base::_Tune</code> that contains all +these parameters, which include settings for +</para> + <itemizedlist> + <listitem><para>Alignment</para></listitem> + <listitem><para>Maximum bytes before calling <code>::operator new</code> directly</para></listitem> + <listitem><para>Minimum bytes</para></listitem> + <listitem><para>Size of underlying global allocations</para></listitem> + <listitem><para>Maximum number of supported threads</para></listitem> + <listitem><para>Migration of deallocations to the global free list</para></listitem> + <listitem><para>Shunt for global <code>new</code> and <code>delete</code></para></listitem> + </itemizedlist> +<para>Adjusting parameters for a given instance of an allocator can only +happen before any allocations take place, when the allocator itself is +initialized. For instance: +</para> +<programlisting> +#include <ext/mt_allocator.h> + +struct pod +{ + int i; + int j; +}; + +int main() +{ + typedef pod value_type; + typedef __gnu_cxx::__mt_alloc<value_type> allocator_type; + typedef __gnu_cxx::__pool_base::_Tune tune_type; + + tune_type t_default; + tune_type t_opt(16, 5120, 32, 5120, 20, 10, false); + tune_type t_single(16, 5120, 32, 5120, 1, 10, false); + + tune_type t; + t = allocator_type::_M_get_options(); + allocator_type::_M_set_options(t_opt); + t = allocator_type::_M_get_options(); + + allocator_type a; + allocator_type::pointer p1 = a.allocate(128); + allocator_type::pointer p2 = a.allocate(5128); + + a.deallocate(p1, 128); + a.deallocate(p2, 5128); + + return 0; +} +</programlisting> + +</sect3> + +<sect3 id="allocator.mt.init" xreflabel="allocator.mt.init"> +<title>Initialization</title> + +<para> +The static variables (pointers to freelists, tuning parameters etc) +are initialized as above, or are set to the global defaults. +</para> + +<para> +The very first allocate() call will always call the +_S_initialize_once() function. In order to make sure that this +function is called exactly once we make use of a __gthread_once call +in MT applications and check a static bool (_S_init) in ST +applications. +</para> + +<para> +The _S_initialize() function: +- If the GLIBCXX_FORCE_NEW environment variable is set, it sets the bool + _S_force_new to true and then returns. This will cause subsequent calls to + allocate() to return memory directly from a new() call, and deallocate will + only do a delete() call. +</para> + +<para> +- If the GLIBCXX_FORCE_NEW environment variable is not set, both ST and MT + applications will: + - Calculate the number of bins needed. A bin is a specific power of two size + of bytes. I.e., by default the allocator will deal with requests of up to + 128 bytes (or whatever the value of _S_max_bytes is when _S_init() is + called). This means that there will be bins of the following sizes + (in bytes): 1, 2, 4, 8, 16, 32, 64, 128. + + - Create the _S_binmap array. All requests are rounded up to the next + "large enough" bin. I.e., a request for 29 bytes will cause a block from + the "32 byte bin" to be returned to the application. The purpose of + _S_binmap is to speed up the process of finding out which bin to use. + I.e., the value of _S_binmap[ 29 ] is initialized to 5 (bin 5 = 32 bytes). +</para> +<para> + - Create the _S_bin array. This array consists of bin_records. There will be + as many bin_records in this array as the number of bins that we calculated + earlier. I.e., if _S_max_bytes = 128 there will be 8 entries. + Each bin_record is then initialized: + - bin_record->first = An array of pointers to block_records. There will be + as many block_records pointers as there are maximum number of threads + (in a ST application there is only 1 thread, in a MT application there + are _S_max_threads). + This holds the pointer to the first free block for each thread in this + bin. I.e., if we would like to know where the first free block of size 32 + for thread number 3 is we would look this up by: _S_bin[ 5 ].first[ 3 ] + + The above created block_record pointers members are now initialized to + their initial values. I.e. _S_bin[ n ].first[ n ] = NULL; +</para> + +<para> +- Additionally a MT application will: + - Create a list of free thread id's. The pointer to the first entry + is stored in _S_thread_freelist_first. The reason for this approach is + that the __gthread_self() call will not return a value that corresponds to + the maximum number of threads allowed but rather a process id number or + something else. So what we do is that we create a list of thread_records. + This list is _S_max_threads long and each entry holds a size_t thread_id + which is initialized to 1, 2, 3, 4, 5 and so on up to _S_max_threads. + Each time a thread calls allocate() or deallocate() we call + _S_get_thread_id() which looks at the value of _S_thread_key which is a + thread local storage pointer. If this is NULL we know that this is a newly + created thread and we pop the first entry from this list and saves the + pointer to this record in the _S_thread_key variable. The next time + we will get the pointer to the thread_record back and we use the + thread_record->thread_id as identification. I.e., the first thread that + calls allocate will get the first record in this list and thus be thread + number 1 and will then find the pointer to its first free 32 byte block + in _S_bin[ 5 ].first[ 1 ] + When we create the _S_thread_key we also define a destructor + (_S_thread_key_destr) which means that when the thread dies, this + thread_record is returned to the front of this list and the thread id + can then be reused if a new thread is created. + This list is protected by a mutex (_S_thread_freelist_mutex) which is only + locked when records are removed or added to the list. +</para> +<para> + - Initialize the free and used counters of each bin_record: + - bin_record->free = An array of size_t. This keeps track of the number + of blocks on a specific thread's freelist in each bin. I.e., if a thread + has 12 32-byte blocks on it's freelists and allocates one of these, this + counter would be decreased to 11. + + - bin_record->used = An array of size_t. This keeps track of the number + of blocks currently in use of this size by this thread. I.e., if a thread + has made 678 requests (and no deallocations...) of 32-byte blocks this + counter will read 678. + + The above created arrays are now initialized with their initial values. + I.e. _S_bin[ n ].free[ n ] = 0; +</para> +<para> + - Initialize the mutex of each bin_record: The bin_record->mutex + is used to protect the global freelist. This concept of a global + freelist is explained in more detail in the section "A multi + threaded example", but basically this mutex is locked whenever a + block of memory is retrieved or returned to the global freelist + for this specific bin. This only occurs when a number of blocks + are grabbed from the global list to a thread specific list or when + a thread decides to return some blocks to the global freelist. +</para> + +</sect3> + +<sect3 id="allocator.mt.deallocation" xreflabel="allocator.mt.deallocation"> +<title>Deallocation Notes</title> + +<para> Notes about deallocation. This allocator does not explicitly +release memory. Because of this, memory debugging programs like +valgrind or purify may notice leaks: sorry about this +inconvenience. Operating systems will reclaim allocated memory at +program termination anyway. If sidestepping this kind of noise is +desired, there are three options: use an allocator, like +<code>new_allocator</code> that releases memory while debugging, use +GLIBCXX_FORCE_NEW to bypass the allocator's internal pools, or use a +custom pool datum that releases resources on destruction. +</para> + +<para> + On systems with the function <code>__cxa_atexit</code>, the +allocator can be forced to free all memory allocated before program +termination with the member function +<code>__pool_type::_M_destroy</code>. However, because this member +function relies on the precise and exactly-conforming ordering of +static destructors, including those of a static local +<code>__pool</code> object, it should not be used, ever, on systems +that don't have the necessary underlying support. In addition, in +practice, forcing deallocation can be tricky, as it requires the +<code>__pool</code> object to be fully-constructed before the object +that uses it is fully constructed. For most (but not all) STL +containers, this works, as an instance of the allocator is constructed +as part of a container's constructor. However, this assumption is +implementation-specific, and subject to change. For an example of a +pool that frees memory, see the following + <ulink url="http://gcc.gnu.org/viewcvs/trunk/libstdc%2B%2B-v3/testsuite/ext/mt_allocator/deallocate_local-6.cc?view=markup"> + example.</ulink> +</para> + +</sect3> + +</sect2> + +<sect2 id="allocator.mt.example_single" xreflabel="allocator.mt.example_single"> +<title>Single Thread Example</title> + +<para> +Let's start by describing how the data on a freelist is laid out in memory. +This is the first two blocks in freelist for thread id 3 in bin 3 (8 bytes): +</para> +<programlisting> ++----------------+ +| next* ---------|--+ (_S_bin[ 3 ].first[ 3 ] points here) +| | | +| | | +| | | ++----------------+ | +| thread_id = 3 | | +| | | +| | | +| | | ++----------------+ | +| DATA | | (A pointer to here is what is returned to the +| | | the application when needed) +| | | +| | | +| | | +| | | +| | | +| | | ++----------------+ | ++----------------+ | +| next* |<-+ (If next == NULL it's the last one on the list) +| | +| | +| | ++----------------+ +| thread_id = 3 | +| | +| | +| | ++----------------+ +| DATA | +| | +| | +| | +| | +| | +| | +| | ++----------------+ +</programlisting> + +<para> +With this in mind we simplify things a bit for a while and say that there is +only one thread (a ST application). In this case all operations are made to +what is referred to as the global pool - thread id 0 (No thread may be +assigned this id since they span from 1 to _S_max_threads in a MT application). +</para> +<para> +When the application requests memory (calling allocate()) we first look at the +requested size and if this is > _S_max_bytes we call new() directly and return. +</para> +<para> +If the requested size is within limits we start by finding out from which +bin we should serve this request by looking in _S_binmap. +</para> +<para> +A quick look at _S_bin[ bin ].first[ 0 ] tells us if there are any blocks of +this size on the freelist (0). If this is not NULL - fine, just remove the +block that _S_bin[ bin ].first[ 0 ] points to from the list, +update _S_bin[ bin ].first[ 0 ] and return a pointer to that blocks data. +</para> +<para> +If the freelist is empty (the pointer is NULL) we must get memory from the +system and build us a freelist within this memory. All requests for new memory +is made in chunks of _S_chunk_size. Knowing the size of a block_record and +the bytes that this bin stores we then calculate how many blocks we can create +within this chunk, build the list, remove the first block, update the pointer +(_S_bin[ bin ].first[ 0 ]) and return a pointer to that blocks data. +</para> + +<para> +Deallocation is equally simple; the pointer is casted back to a block_record +pointer, lookup which bin to use based on the size, add the block to the front +of the global freelist and update the pointer as needed +(_S_bin[ bin ].first[ 0 ]). +</para> + +<para> +The decision to add deallocated blocks to the front of the freelist was made +after a set of performance measurements that showed that this is roughly 10% +faster than maintaining a set of "last pointers" as well. +</para> + +</sect2> + +<sect2 id="allocator.mt.example_multi" xreflabel="allocator.mt.example_multi"> +<title>Multiple Thread Example</title> + +<para> +In the ST example we never used the thread_id variable present in each block. +Let's start by explaining the purpose of this in a MT application. +</para> + +<para> +The concept of "ownership" was introduced since many MT applications +allocate and deallocate memory to shared containers from different +threads (such as a cache shared amongst all threads). This introduces +a problem if the allocator only returns memory to the current threads +freelist (I.e., there might be one thread doing all the allocation and +thus obtaining ever more memory from the system and another thread +that is getting a longer and longer freelist - this will in the end +consume all available memory). +</para> + +<para> +Each time a block is moved from the global list (where ownership is +irrelevant), to a threads freelist (or when a new freelist is built +from a chunk directly onto a threads freelist or when a deallocation +occurs on a block which was not allocated by the same thread id as the +one doing the deallocation) the thread id is set to the current one. +</para> + +<para> +What's the use? Well, when a deallocation occurs we can now look at +the thread id and find out if it was allocated by another thread id +and decrease the used counter of that thread instead, thus keeping the +free and used counters correct. And keeping the free and used counters +corrects is very important since the relationship between these two +variables decides if memory should be returned to the global pool or +not when a deallocation occurs. +</para> + +<para> +When the application requests memory (calling allocate()) we first +look at the requested size and if this is >_S_max_bytes we call new() +directly and return. +</para> + +<para> +If the requested size is within limits we start by finding out from which +bin we should serve this request by looking in _S_binmap. +</para> + +<para> +A call to _S_get_thread_id() returns the thread id for the calling thread +(and if no value has been set in _S_thread_key, a new id is assigned and +returned). +</para> + +<para> +A quick look at _S_bin[ bin ].first[ thread_id ] tells us if there are +any blocks of this size on the current threads freelist. If this is +not NULL - fine, just remove the block that _S_bin[ bin ].first[ +thread_id ] points to from the list, update _S_bin[ bin ].first[ +thread_id ], update the free and used counters and return a pointer to +that blocks data. +</para> + +<para> +If the freelist is empty (the pointer is NULL) we start by looking at +the global freelist (0). If there are blocks available on the global +freelist we lock this bins mutex and move up to block_count (the +number of blocks of this bins size that will fit into a _S_chunk_size) +or until end of list - whatever comes first - to the current threads +freelist and at the same time change the thread_id ownership and +update the counters and pointers. When the bins mutex has been +unlocked, we remove the block that _S_bin[ bin ].first[ thread_id ] +points to from the list, update _S_bin[ bin ].first[ thread_id ], +update the free and used counters, and return a pointer to that blocks +data. +</para> + +<para> +The reason that the number of blocks moved to the current threads +freelist is limited to block_count is to minimize the chance that a +subsequent deallocate() call will return the excess blocks to the +global freelist (based on the _S_freelist_headroom calculation, see +below). +</para> + +<para> +However if there isn't any memory on the global pool we need to get +memory from the system - this is done in exactly the same way as in a +single threaded application with one major difference; the list built +in the newly allocated memory (of _S_chunk_size size) is added to the +current threads freelist instead of to the global. +</para> + +<para> +The basic process of a deallocation call is simple: always add the +block to the front of the current threads freelist and update the +counters and pointers (as described earlier with the specific check of +ownership that causes the used counter of the thread that originally +allocated the block to be decreased instead of the current threads +counter). +</para> + +<para> +And here comes the free and used counters to service. Each time a +deallocation() call is made, the length of the current threads +freelist is compared to the amount memory in use by this thread. +</para> + +<para> +Let's go back to the example of an application that has one thread +that does all the allocations and one that deallocates. Both these +threads use say 516 32-byte blocks that was allocated during thread +creation for example. Their used counters will both say 516 at this +point. The allocation thread now grabs 1000 32-byte blocks and puts +them in a shared container. The used counter for this thread is now +1516. +</para> + +<para> +The deallocation thread now deallocates 500 of these blocks. For each +deallocation made the used counter of the allocating thread is +decreased and the freelist of the deallocation thread gets longer and +longer. But the calculation made in deallocate() will limit the length +of the freelist in the deallocation thread to _S_freelist_headroom % +of it's used counter. In this case, when the freelist (given that the +_S_freelist_headroom is at it's default value of 10%) exceeds 52 +(516/10) blocks will be returned to the global pool where the +allocating thread may pick them up and reuse them. +</para> + +<para> +In order to reduce lock contention (since this requires this bins +mutex to be locked) this operation is also made in chunks of blocks +(just like when chunks of blocks are moved from the global freelist to +a threads freelist mentioned above). The "formula" used can probably +be improved to further reduce the risk of blocks being "bounced back +and forth" between freelists. +</para> + +</sect2> + +</sect1>
\ No newline at end of file diff --git a/libstdc++-v3/doc/xml/manual/numerics.xml b/libstdc++-v3/doc/xml/manual/numerics.xml new file mode 100644 index 00000000000..835cd1e7454 --- /dev/null +++ b/libstdc++-v3/doc/xml/manual/numerics.xml @@ -0,0 +1,143 @@ +<?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.numerics" xreflabel="Numerics"> +<?dbhtml filename="numerics.html"?> + +<partinfo> + <keywordset> + <keyword> + ISO C++ + </keyword> + <keyword> + library + </keyword> + </keywordset> +</partinfo> + +<title>Numerics</title> + +<!-- Chapter 01 : Complex --> +<chapter id="manual.numerics.complex" xreflabel="complex"> + <title>Complex</title> + <para> + </para> + <sect1 id="numerics.complex.processing" xreflabel="complex Processing"> + <title>complex Processing</title> + <para> + </para> + <para>Using <code>complex<></code> becomes even more comple- er, sorry, + <emphasis>complicated</emphasis>, with the not-quite-gratuitously-incompatible + addition of complex types to the C language. David Tribble has + compiled a list of C++98 and C99 conflict points; his description of + C's new type versus those of C++ and how to get them playing together + nicely is +<ulink url="http://david.tribble.com/text/cdiffs.htm#C99-complex">here</ulink>. + </para> + <para><code>complex<></code> is intended to be instantiated with a + floating-point type. As long as you meet that and some other basic + requirements, then the resulting instantiation has all of the usual + math operators defined, as well as definitions of <code>op<<</code> + and <code>op>></code> that work with iostreams: <code>op<<</code> + prints <code>(u,v)</code> and <code>op>></code> can read <code>u</code>, + <code>(u)</code>, and <code>(u,v)</code>. + </para> + + </sect1> +</chapter> + +<!-- Chapter 02 : Generalized Operations --> +<chapter id="manual.numerics.generalized_ops" xreflabel="Generalized Ops"> + <title>Generalized Operations</title> + <para> + </para> + + <para>There are four generalized functions in the <numeric> header + that follow the same conventions as those in <algorithm>. Each + of them is overloaded: one signature for common default operations, + and a second for fully general operations. Their names are + self-explanatory to anyone who works with numerics on a regular basis: + </para> + <itemizedlist> + <listitem><para><code>accumulate</code></para></listitem> + <listitem><para><code>inner_product</code></para></listitem> + <listitem><para><code>partial_sum</code></para></listitem> + <listitem><para><code>adjacent_difference</code></para></listitem> + </itemizedlist> + <para>Here is a simple example of the two forms of <code>accumulate</code>. + </para> + <programlisting> + int ar[50]; + int someval = somefunction(); + + // ...initialize members of ar to something... + + int sum = std::accumulate(ar,ar+50,0); + int sum_stuff = std::accumulate(ar,ar+50,someval); + int product = std::accumulate(ar,ar+50,1,std::multiplies<int>()); + </programlisting> + <para>The first call adds all the members of the array, using zero as an + initial value for <code>sum</code>. The second does the same, but uses + <code>someval</code> as the starting value (thus, <code>sum_stuff == sum + + someval</code>). The final call uses the second of the two signatures, + and multiplies all the members of the array; here we must obviously + use 1 as a starting value instead of 0. + </para> + <para>The other three functions have similar dual-signature forms. + </para> + +</chapter> + +<!-- Chapter 03 : Interacting with C --> +<chapter id="manual.numerics.c" xreflabel="Interacting with C"> + <title>Interacting with C</title> + + <sect1 id="numerics.c.array" xreflabel="Numerics vs. Arrays"> + <title>Numerics vs. Arrays</title> + + <para>One of the major reasons why FORTRAN can chew through numbers so well + is that it is defined to be free of pointer aliasing, an assumption + that C89 is not allowed to make, and neither is C++98. C99 adds a new + keyword, <code>restrict</code>, to apply to individual pointers. The + C++ solution is contained in the library rather than the language + (although many vendors can be expected to add this to their compilers + as an extension). + </para> + <para>That library solution is a set of two classes, five template classes, + and "a whole bunch" of functions. The classes are required + to be free of pointer aliasing, so compilers can optimize the + daylights out of them the same way that they have been for FORTRAN. + They are collectively called <code>valarray</code>, although strictly + speaking this is only one of the five template classes, and they are + designed to be familiar to people who have worked with the BLAS + libraries before. + </para> + + </sect1> + + <sect1 id="numerics.c.c99" xreflabel="C99"> + <title>C99</title> + + <para>In addition to the other topics on this page, we'll note here some + of the C99 features that appear in libstdc++. + </para> + <para>The C99 features depend on the <code>--enable-c99</code> configure flag. + This flag is already on by default, but it can be disabled by the + user. Also, the configuration machinery will disable it if the + necessary support for C99 (e.g., header files) cannot be found. + </para> + <para>As of GCC 3.0, C99 support includes classification functions + such as <code>isnormal</code>, <code>isgreater</code>, + <code>isnan</code>, etc. + The functions used for 'long long' support such as <code>strtoll</code> + are supported, as is the <code>lldiv_t</code> typedef. Also supported + are the wide character functions using 'long long', like + <code>wcstoll</code>. + </para> + + </sect1> +</chapter> + +</part> diff --git a/libstdc++-v3/doc/xml/manual/parallel_mode.xml b/libstdc++-v3/doc/xml/manual/parallel_mode.xml new file mode 100644 index 00000000000..4236f63c8b1 --- /dev/null +++ b/libstdc++-v3/doc/xml/manual/parallel_mode.xml @@ -0,0 +1,674 @@ +<?xml version='1.0'?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" +[ ]> + +<chapter id="manual.ext.parallel_mode" xreflabel="Parallel Mode"> +<?dbhtml filename="parallel_mode.html"?> + +<chapterinfo> + <keywordset> + <keyword> + C++ + </keyword> + <keyword> + library + </keyword> + <keyword> + parallel + </keyword> + </keywordset> +</chapterinfo> + +<title>Parallel Mode</title> + +<para> The libstdc++ parallel mode is an experimental parallel +implementation of many algorithms the C++ Standard Library. +</para> + +<para> +Several of the standard algorithms, for instance +<code>std::sort</code>, are made parallel using OpenMP +annotations. These parallel mode constructs and can be invoked by +explicit source declaration or by compiling existing sources with a +specific compiler flag. +</para> + + +<sect1 id="manual.ext.parallel_mode.intro" xreflabel="Intro"> + <title>Intro</title> + +<para>The following library components in the include +<code><numeric></code> are included in the parallel mode:</para> +<itemizedlist> + <listitem><para><code>std::accumulate</code></para></listitem> + <listitem><para><code>std::adjacent_difference</code></para></listitem> + <listitem><para><code>std::inner_product</code></para></listitem> + <listitem><para><code>std::partial_sum</code></para></listitem> +</itemizedlist> + +<para>The following library components in the include +<code><algorithm></code> are included in the parallel mode:</para> +<itemizedlist> + <listitem><para><code>std::adjacent_find</code></para></listitem> + <listitem><para><code>std::count</code></para></listitem> + <listitem><para><code>std::count_if</code></para></listitem> + <listitem><para><code>std::equal</code></para></listitem> + <listitem><para><code>std::find</code></para></listitem> + <listitem><para><code>std::find_if</code></para></listitem> + <listitem><para><code>std::find_first_of</code></para></listitem> + <listitem><para><code>std::for_each</code></para></listitem> + <listitem><para><code>std::generate</code></para></listitem> + <listitem><para><code>std::generate_n</code></para></listitem> + <listitem><para><code>std::lexicographical_compare</code></para></listitem> + <listitem><para><code>std::mismatch</code></para></listitem> + <listitem><para><code>std::search</code></para></listitem> + <listitem><para><code>std::search_n</code></para></listitem> + <listitem><para><code>std::transform</code></para></listitem> + <listitem><para><code>std::replace</code></para></listitem> + <listitem><para><code>std::replace_if</code></para></listitem> + <listitem><para><code>std::max_element</code></para></listitem> + <listitem><para><code>std::merge</code></para></listitem> + <listitem><para><code>std::min_element</code></para></listitem> + <listitem><para><code>std::nth_element</code></para></listitem> + <listitem><para><code>std::partial_sort</code></para></listitem> + <listitem><para><code>std::partition</code></para></listitem> + <listitem><para><code>std::random_shuffle</code></para></listitem> + <listitem><para><code>std::set_union</code></para></listitem> + <listitem><para><code>std::set_intersection</code></para></listitem> + <listitem><para><code>std::set_symmetric_difference</code></para></listitem> + <listitem><para><code>std::set_difference</code></para></listitem> + <listitem><para><code>std::sort</code></para></listitem> + <listitem><para><code>std::stable_sort</code></para></listitem> + <listitem><para><code>std::unique_copy</code></para></listitem> +</itemizedlist> + +<para>The following library components in the includes +<code><set></code> and <code><map></code> are included in the parallel mode:</para> +<itemizedlist> + <listitem><para><code>std::(multi_)map/set<T>::(multi_)map/set(Iterator begin, Iterator end)</code> (bulk construction)</para></listitem> + <listitem><para><code>std::(multi_)map/set<T>::insert(Iterator begin, Iterator end)</code> (bulk insertion)</para></listitem> +</itemizedlist> + +</sect1> + +<sect1 id="manual.ext.parallel_mode.semantics" xreflabel="Semantics"> + <title>Semantics</title> + +<para> The parallel mode STL algorithms are currently not exception-safe, +i. e. user-defined functors must not throw exceptions. +</para> + +<para> Since the current GCC OpenMP implementation does not support +OpenMP parallel regions in concurrent threads, +it is not possible to call parallel STL algorithm in +concurrent threads, either. +It might work with other compilers, though.</para> + +</sect1> + +<sect1 id="manual.ext.parallel_mode.using" xreflabel="Using"> + <title>Using</title> + +<sect2 id="parallel_mode.using.parallel_mode" xreflabel="using.parallel_mode"> + <title>Using Parallel Mode</title> + +<para>To use the libstdc++ parallel mode, compile your application with + the compiler flag <code>-D_GLIBCXX_PARALLEL -fopenmp</code>. This + will link in <code>libgomp</code>, the GNU OpenMP <ulink url="http://gcc.gnu.org/onlinedocs/libgomp">implementation</ulink>, + whose presence is mandatory. In addition, hardware capable of atomic + operations is mandatory. Actually activating these atomic + operations may require explicit compiler flags on some targets + (like sparc and x86), such as <code>-march=i686</code>, + <code>-march=native</code> or <code>-mcpu=v9</code>. +</para> + +<para>Note that the <code>_GLIBCXX_PARALLEL</code> define may change the + sizes and behavior of standard class templates such as + <code>std::search</code>, and therefore one can only link code + compiled with parallel mode and code compiled without parallel mode + if no instantiation of a container is passed between the two + translation units. Parallel mode functionality has distinct linkage, + and cannot be confused with normal mode symbols.</para> +</sect2> + +<sect2 id="manual.ext.parallel_mode.usings" xreflabel="using.specific"> + <title>Using Specific Parallel Components</title> + +<para>When it is not feasible to recompile your entire application, or + only specific algorithms need to be parallel-aware, individual + parallel algorithms can be made available explicitly. These + parallel algorithms are functionally equivalent to the standard + drop-in algorithms used in parallel mode, but they are available in + a separate namespace as GNU extensions and may be used in programs + compiled with either release mode or with parallel mode. The + following table provides the names and headers of the parallel + algorithms: +</para> + +<table frame='all'> +<title>Parallel Algorithms</title> +<tgroup cols='4' align='left' colsep='1' rowsep='1'> +<colspec colname='c1'></colspec> +<colspec colname='c2'></colspec> +<colspec colname='c3'></colspec> +<colspec colname='c4'></colspec> + +<thead> + <row> + <entry>Algorithm</entry> + <entry>Header</entry> + <entry>Parallel algorithm</entry> + <entry>Parallel header</entry> + </row> +</thead> + +<tbody> + <row> + <entry><function>std::accumulate</function></entry> + <entry><filename class="headerfile">numeric</filename></entry> + <entry><function>__gnu_parallel::accumulate</function></entry> + <entry><filename class="headerfile">parallel/numeric</filename></entry> + </row> + <row> + <entry><function>std::adjacent_difference</function></entry> + <entry><filename class="headerfile">numeric</filename></entry> + <entry><function>__gnu_parallel::adjacent_difference</function></entry> + <entry><filename class="headerfile">parallel/numeric</filename></entry> + </row> + <row> + <entry><function>std::inner_product</function></entry> + <entry><filename class="headerfile">numeric</filename></entry> + <entry><function>__gnu_parallel::inner_product</function></entry> + <entry><filename class="headerfile">parallel/numeric</filename></entry> + </row> + <row> + <entry><function>std::partial_sum</function></entry> + <entry><filename class="headerfile">numeric</filename></entry> + <entry><function>__gnu_parallel::partial_sum</function></entry> + <entry><filename class="headerfile">parallel/numeric</filename></entry> + </row> + <row> + <entry><function>std::adjacent_find</function></entry> + <entry><filename class="headerfile">algorithm</filename></entry> + <entry><function>__gnu_parallel::adjacent_find</function></entry> + <entry><filename class="headerfile">parallel/algorithm</filename></entry> + </row> + + <row> + <entry><function>std::count</function></entry> + <entry><filename class="headerfile">algorithm</filename></entry> + <entry><function>__gnu_parallel::count</function></entry> + <entry><filename class="headerfile">parallel/algorithm</filename></entry> + </row> + + <row> + <entry><function>std::count_if</function></entry> + <entry><filename class="headerfile">algorithm</filename></entry> + <entry><function>__gnu_parallel::count_if</function></entry> + <entry><filename class="headerfile">parallel/algorithm</filename></entry> + </row> + + <row> + <entry><function>std::equal</function></entry> + <entry><filename class="headerfile">algorithm</filename></entry> + <entry><function>__gnu_parallel::equal</function></entry> + <entry><filename class="headerfile">parallel/algorithm</filename></entry> + </row> + + <row> + <entry><function>std::find</function></entry> + <entry><filename class="headerfile">algorithm</filename></entry> + <entry><function>__gnu_parallel::find</function></entry> + <entry><filename class="headerfile">parallel/algorithm</filename></entry> + </row> + + <row> + <entry><function>std::find_if</function></entry> + <entry><filename class="headerfile">algorithm</filename></entry> + <entry><function>__gnu_parallel::find_if</function></entry> + <entry><filename class="headerfile">parallel/algorithm</filename></entry> + </row> + + <row> + <entry><function>std::find_first_of</function></entry> + <entry><filename class="headerfile">algorithm</filename></entry> + <entry><function>__gnu_parallel::find_first_of</function></entry> + <entry><filename class="headerfile">parallel/algorithm</filename></entry> + </row> + + <row> + <entry><function>std::for_each</function></entry> + <entry><filename class="headerfile">algorithm</filename></entry> + <entry><function>__gnu_parallel::for_each</function></entry> + <entry><filename class="headerfile">parallel/algorithm</filename></entry> + </row> + + <row> + <entry><function>std::generate</function></entry> + <entry><filename class="headerfile">algorithm</filename></entry> + <entry><function>__gnu_parallel::generate</function></entry> + <entry><filename class="headerfile">parallel/algorithm</filename></entry> + </row> + + <row> + <entry><function>std::generate_n</function></entry> + <entry><filename class="headerfile">algorithm</filename></entry> + <entry><function>__gnu_parallel::generate_n</function></entry> + <entry><filename class="headerfile">parallel/algorithm</filename></entry> + </row> + + <row> + <entry><function>std::lexicographical_compare</function></entry> + <entry><filename class="headerfile">algorithm</filename></entry> + <entry><function>__gnu_parallel::lexicographical_compare</function></entry> + <entry><filename class="headerfile">parallel/algorithm</filename></entry> + </row> + + <row> + <entry><function>std::mismatch</function></entry> + <entry><filename class="headerfile">algorithm</filename></entry> + <entry><function>__gnu_parallel::mismatch</function></entry> + <entry><filename class="headerfile">parallel/algorithm</filename></entry> + </row> + + <row> + <entry><function>std::search</function></entry> + <entry><filename class="headerfile">algorithm</filename></entry> + <entry><function>__gnu_parallel::search</function></entry> + <entry><filename class="headerfile">parallel/algorithm</filename></entry> + </row> + + <row> + <entry><function>std::search_n</function></entry> + <entry><filename class="headerfile">algorithm</filename></entry> + <entry><function>__gnu_parallel::search_n</function></entry> + <entry><filename class="headerfile">parallel/algorithm</filename></entry> + </row> + + <row> + <entry><function>std::transform</function></entry> + <entry><filename class="headerfile">algorithm</filename></entry> + <entry><function>__gnu_parallel::transform</function></entry> + <entry><filename class="headerfile">parallel/algorithm</filename></entry> + </row> + + <row> + <entry><function>std::replace</function></entry> + <entry><filename class="headerfile">algorithm</filename></entry> + <entry><function>__gnu_parallel::replace</function></entry> + <entry><filename class="headerfile">parallel/algorithm</filename></entry> + </row> + + <row> + <entry><function>std::replace_if</function></entry> + <entry><filename class="headerfile">algorithm</filename></entry> + <entry><function>__gnu_parallel::replace_if</function></entry> + <entry><filename class="headerfile">parallel/algorithm</filename></entry> + </row> + + <row> + <entry><function>std::max_element</function></entry> + <entry><filename class="headerfile">algorithm</filename></entry> + <entry><function>__gnu_parallel::max_element</function></entry> + <entry><filename class="headerfile">parallel/algorithm</filename></entry> + </row> + + <row> + <entry><function>std::merge</function></entry> + <entry><filename class="headerfile">algorithm</filename></entry> + <entry><function>__gnu_parallel::merge</function></entry> + <entry><filename class="headerfile">parallel/algorithm</filename></entry> + </row> + + <row> + <entry><function>std::min_element</function></entry> + <entry><filename class="headerfile">algorithm</filename></entry> + <entry><function>__gnu_parallel::min_element</function></entry> + <entry><filename class="headerfile">parallel/algorithm</filename></entry> + </row> + + <row> + <entry><function>std::nth_element</function></entry> + <entry><filename class="headerfile">algorithm</filename></entry> + <entry><function>__gnu_parallel::nth_element</function></entry> + <entry><filename class="headerfile">parallel/algorithm</filename></entry> + </row> + + <row> + <entry><function>std::partial_sort</function></entry> + <entry><filename class="headerfile">algorithm</filename></entry> + <entry><function>__gnu_parallel::partial_sort</function></entry> + <entry><filename class="headerfile">parallel/algorithm</filename></entry> + </row> + + <row> + <entry><function>std::partition</function></entry> + <entry><filename class="headerfile">algorithm</filename></entry> + <entry><function>__gnu_parallel::partition</function></entry> + <entry><filename class="headerfile">parallel/algorithm</filename></entry> + </row> + + <row> + <entry><function>std::random_shuffle</function></entry> + <entry><filename class="headerfile">algorithm</filename></entry> + <entry><function>__gnu_parallel::random_shuffle</function></entry> + <entry><filename class="headerfile">parallel/algorithm</filename></entry> + </row> + + <row> + <entry><function>std::set_union</function></entry> + <entry><filename class="headerfile">algorithm</filename></entry> + <entry><function>__gnu_parallel::set_union</function></entry> + <entry><filename class="headerfile">parallel/algorithm</filename></entry> + </row> + + <row> + <entry><function>std::set_intersection</function></entry> + <entry><filename class="headerfile">algorithm</filename></entry> + <entry><function>__gnu_parallel::set_intersection</function></entry> + <entry><filename class="headerfile">parallel/algorithm</filename></entry> + </row> + + <row> + <entry><function>std::set_symmetric_difference</function></entry> + <entry><filename class="headerfile">algorithm</filename></entry> + <entry><function>__gnu_parallel::set_symmetric_difference</function></entry> + <entry><filename class="headerfile">parallel/algorithm</filename></entry> + </row> + + <row> + <entry><function>std::set_difference</function></entry> + <entry><filename class="headerfile">algorithm</filename></entry> + <entry><function>__gnu_parallel::set_difference</function></entry> + <entry><filename class="headerfile">parallel/algorithm</filename></entry> + </row> + + <row> + <entry><function>std::sort</function></entry> + <entry><filename class="headerfile">algorithm</filename></entry> + <entry><function>__gnu_parallel::sort</function></entry> + <entry><filename class="headerfile">parallel/algorithm</filename></entry> + </row> + + <row> + <entry><function>std::stable_sort</function></entry> + <entry><filename class="headerfile">algorithm</filename></entry> + <entry><function>__gnu_parallel::stable_sort</function></entry> + <entry><filename class="headerfile">parallel/algorithm</filename></entry> + </row> + + <row> + <entry><function>std::unique_copy</function></entry> + <entry><filename class="headerfile">algorithm</filename></entry> + <entry><function>__gnu_parallel::unique_copy</function></entry> + <entry><filename class="headerfile">parallel/algorithm</filename></entry> + </row> +</tbody> +</tgroup> +</table> + +</sect2> + +</sect1> + +<sect1 id="manual.ext.parallel_mode.design" xreflabel="Design"> + <title>Design</title> + <para> + </para> +<sect2 id="manual.ext.parallel_mode.design.intro" xreflabel="Intro"> + <title>Interface Basics</title> + + +<para>All parallel algorithms are intended to have signatures that are +equivalent to the ISO C++ algorithms replaced. For instance, the +<code>std::adjacent_find</code> function is declared as: +</para> +<programlisting> +namespace std +{ + template<typename _FIter> + _FIter + adjacent_find(_FIter, _FIter); +} +</programlisting> + +<para> +Which means that there should be something equivalent for the parallel +version. Indeed, this is the case: +</para> + +<programlisting> +namespace std +{ + namespace __parallel + { + template<typename _FIter> + _FIter + adjacent_find(_FIter, _FIter); + + ... + } +} +</programlisting> + +<para>But.... why the elipses? +</para> + +<para> The elipses in the example above represent additional overloads +required for the parallel version of the function. These additional +overloads are used to dispatch calls from the ISO C++ function +signature to the appropriate parallel function (or sequential +function, if no parallel functions are deemed worthy), based on either +compile-time or run-time conditions. +</para> + +<para> Compile-time conditions are referred to as "embarrassingly +parallel," and are denoted with the appropriate dispatch object, ie +one of <code>__gnu_parallel::sequential_tag</code>, +<code>__gnu_parallel::parallel_tag</code>, +<code>__gnu_parallel::balanced_tag</code>, +<code>__gnu_parallel::unbalanced_tag</code>, +<code>__gnu_parallel::omp_loop_tag</code>, or +<code>__gnu_parallel::omp_loop_static_tag</code>. +</para> + +<para> Run-time conditions depend on the hardware being used, the number +of threads available, etc., and are denoted by the use of the enum +<code>__gnu_parallel::parallelism</code>. Values of this enum include +<code>__gnu_parallel::sequential</code>, +<code>__gnu_parallel::parallel_unbalanced</code>, +<code>__gnu_parallel::parallel_balanced</code>, +<code>__gnu_parallel::parallel_omp_loop</code>, +<code>__gnu_parallel::parallel_omp_loop_static</code>, or +<code>__gnu_parallel::parallel_taskqueue</code>. +</para> + +<para> Putting all this together, the general view of overloads for the +parallel algorithms look like this: +</para> +<itemizedlist> + <listitem><para>ISO C++ signature</para></listitem> + <listitem><para>ISO C++ signature + sequential_tag argument</para></listitem> + <listitem><para>ISO C++ signature + parallelism argument</para></listitem> +</itemizedlist> + +<para> Please note that the implementation may use additional functions +(designated with the <code>_switch</code> suffix) to dispatch from the +ISO C++ signature to the correct parallel version. Also, some of the +algorithms do not have support for run-time conditions, so the last +overload is therefore missing. +</para> + + +</sect2> + +<sect2 id="manual.ext.parallel_mode.design.tuning" xreflabel="Tuning"> + <title>Configuration and Tuning</title> + +<para> Some algorithm variants can be enabled/disabled/selected at compile-time. +See <ulink url="latest-doxygen/compiletime__settings_8h.html"> +<code><compiletime_settings.h></code></ulink> and +See <ulink url="latest-doxygen/compiletime__settings_8h.html"> +<code><features.h></code></ulink> for details. +</para> + +<para> +To specify the number of threads to be used for an algorithm, +use <code>omp_set_num_threads</code>. +To force a function to execute sequentially, +even though parallelism is switched on in general, +add <code>__gnu_parallel::sequential_tag()</code> +to the end of the argument list. +</para> + +<para> +Parallelism always incurs some overhead. Thus, it is not +helpful to parallelize operations on very small sets of data. +There are measures to avoid parallelizing stuff that is not worth it. +For each algorithm, a minimum problem size can be stated, +usually using the variable +<code>__gnu_parallel::Settings::[algorithm]_minimal_n</code>. +Please see <ulink url="latest-doxygen/settings_8h.html"> +<code><settings.h></code></ulink> for details.</para> + + +</sect2> + +<sect2 id="manual.ext.parallel_mode.design.impl" xreflabel="Impl"> + <title>Implementation Namespaces</title> + +<para> One namespace contain versions of code that are explicitly sequential: +<code>__gnu_serial</code>. +</para> + +<para> Two namespaces contain the parallel mode: +<code>std::__parallel</code> and <code>__gnu_parallel</code>. +</para> + +<para> Parallel implementations of standard components, including +template helpers to select parallelism, are defined in <code>namespace +std::__parallel</code>. For instance, <code>std::transform</code> from +<algorithm> has a parallel counterpart in +<code>std::__parallel::transform</code> from +<parallel/algorithm>. In addition, these parallel +implementations are injected into <code>namespace +__gnu_parallel</code> with using declarations. +</para> + +<para> Support and general infrastructure is in <code>namespace +__gnu_parallel</code>. +</para> + +<para> More information, and an organized index of types and functions +related to the parallel mode on a per-namespace basis, can be found in +the generated source documentation. +</para> + +</sect2> + +</sect1> + +<sect1 id="manual.ext.parallel_mode.test" xreflabel="Testing"> + <title>Testing</title> + + <para> + Both the normal conformance and regression tests and the + supplemental performance tests work. + </para> + + <para> + To run the conformance and regression tests with the parallel mode + active, + </para> + + <screen> + <userinput>make check-parallel</userinput> + </screen> + + <para> + The log and summary files for conformance testing are in the + <code>testsuite/parallel</code> directory. + </para> + + <para> + To run the performance tests with the parallel mode active, + </para> + + <screen> + <userinput>check-performance-parallel</userinput> + </screen> + + <para> + The result file for performance testing are in the + <code>testsuite</code> directory, in the file + <code>libstdc++_performance.sum</code>. In addition, the + policy-based containers have their own visualizations, which have + additional software dependencies than the usual bare-boned text + file, and can be generated by using the <code>make + doc-performance</code> rule in the testsuite's Makefile. +</para> +</sect1> + +<bibliography id="parallel_mode.biblio" xreflabel="parallel_mode.biblio"> +<title>Bibliography</title> + + <biblioentry> + <title> + Parallelization of Bulk Operations for STL Dictionaries + </title> + + <author> + <firstname>Johannes</firstname> + <surname>Singler</surname> + </author> + <author> + <firstname>Leonor</firstname> + <surname>Frias</surname> + </author> + + <copyright> + <year>2007</year> + <holder></holder> + </copyright> + + <publisher> + <publishername> + Workshop on Highly Parallel Processing on a Chip (HPPC) 2007. (LNCS) + </publishername> + </publisher> + </biblioentry> + + <biblioentry> + <title> + The Multi-Core Standard Template Library + </title> + + <author> + <firstname>Johannes</firstname> + <surname>Singler</surname> + </author> + <author> + <firstname>Peter</firstname> + <surname>Sanders</surname> + </author> + <author> + <firstname>Felix</firstname> + <surname>Putze</surname> + </author> + + <copyright> + <year>2007</year> + <holder></holder> + </copyright> + + <publisher> + <publishername> + Euro-Par 2007: Parallel Processing. (LNCS 4641) + </publishername> + </publisher> + </biblioentry> + +</bibliography> + +</chapter> diff --git a/libstdc++-v3/doc/xml/manual/shared_ptr.xml b/libstdc++-v3/doc/xml/manual/shared_ptr.xml new file mode 100644 index 00000000000..cd517f1250a --- /dev/null +++ b/libstdc++-v3/doc/xml/manual/shared_ptr.xml @@ -0,0 +1,580 @@ +<sect1 id="manual.util.memory.shared_ptr" xreflabel="shared_ptr"> +<?dbhtml filename="shared_ptr.html"?> + +<sect1info> + <keywordset> + <keyword> + ISO C++ + </keyword> + <keyword> + shared_ptr + </keyword> + </keywordset> +</sect1info> + +<title>shared_ptr</title> + +<para> +The shared_ptr class template stores a pointer, usually obtained via new, +and implements shared ownership semantics. +</para> + +<sect2 id="shared_ptr.req" xreflabel="shared_ptr.req"> +<title>Requirements</title> + + <para> + </para> + + <para> + The standard deliberately doesn't require a reference-counted + implementation, allowing other techniques such as a + circular-linked-list. + </para> + + <para> + At the time of writing the C++0x working paper doesn't mention how + threads affect shared_ptr, but it is likely to follow the existing + practice set by <classname>boost::shared_ptr</classname>. The + shared_ptr in libstdc++ is derived from Boost's, so the same rules + apply. + </para> + + <para> + </para> +</sect2> + +<sect2 id="shared_ptr.design_issues" xreflabel="shared_ptr.design_issues"> +<title>Design Issues</title> + + + <para> +The <classname>shared_ptr</classname> code is kindly donated to GCC by the Boost +project and the original authors of the code. The basic design and +algorithms are from Boost, the notes below describe details specific to +the GCC implementation. Names have been uglified in this implementation, +but the design should be recognisable to anyone familiar with the Boost +1.32 shared_ptr. + </para> + + <para> +The basic design is an abstract base class, <code>_Sp_counted_base</code> that +does the reference-counting and calls virtual functions when the count +drops to zero. +Derived classes override those functions to destroy resources in a context +where the correct dynamic type is known. This is an application of the +technique known as type erasure. + </para> + +</sect2> + +<sect2 id="shared_ptr.impl" xreflabel="shared_ptr.impl"> +<title>Implementation</title> + + <sect3> + <title>Class Hierarchy</title> + + <para> +A <classname>shared_ptr<T></classname> contains a pointer of +type <type>T*</type> and an object of type +<classname>__shared_count</classname>. The shared_count contains a +pointer of type <type>_Sp_counted_base*</type> which points to the +object that maintains the reference-counts and destroys the managed +resource. + </para> + +<variablelist> + +<varlistentry> + <term><classname>_Sp_counted_base<Lp></classname></term> + <listitem> + <para> +The base of the hierarchy is parameterized on the lock policy alone. +_Sp_counted_base doesn't depend on the type of pointer being managed, +it only maintains the reference counts and calls virtual functions when +the counts drop to zero. The managed object is destroyed when the last +strong reference is dropped, but the _Sp_counted_base itself must exist +until the last weak reference is dropped. + </para> + </listitem> +</varlistentry> + +<varlistentry> + <term><classname>_Sp_counted_base_impl<Ptr, Deleter, Lp></classname></term> + <listitem> + <para> +Inherits from _Sp_counted_base and stores a pointer of type <type>Ptr</type> +and a deleter of type <code>Deleter</code>. <code>_Sp_deleter</code> is +used when the user doesn't supply a custom deleter. Unlike Boost's, this +default deleter is not "checked" because GCC already issues a warning if +<function>delete</function> is used with an incomplete type. +This is the only derived type used by <classname>shared_ptr<Ptr></classname> +and it is never used by <classname>shared_ptr</classname>, which uses one of +the following types, depending on how the shared_ptr is constructed. + </para> + </listitem> +</varlistentry> + +<varlistentry> + <term><classname>_Sp_counted_ptr<Ptr, Lp></classname></term> + <listitem> + <para> +Inherits from _Sp_counted_base and stores a pointer of type <type>Ptr</type>, +which is passed to <function>delete</function> when the last reference is dropped. +This is the simplest form and is used when there is no custom deleter or +allocator. + </para> + </listitem> +</varlistentry> + +<varlistentry> + <term><classname>_Sp_counted_deleter<Ptr, Deleter, Alloc></classname></term> + <listitem> + <para> +Inherits from _Sp_counted_ptr and adds support for custom deleter and +allocator. Empty Base Optimization is used for the allocator. This class +is used even when the user only provides a custom deleter, in which case +<classname>allocator</classname> is used as the allocator. + </para> + </listitem> +</varlistentry> + +<varlistentry> + <term><classname>_Sp_counted_ptr_inplace<Tp, Alloc, Lp></classname></term> + <listitem> + <para> +Used by <code>allocate_shared</code> and <code>make_shared</code>. +Contains aligned storage to hold an object of type <type>Tp</type>, +which is constructed in-place with placement <function>new</function>. +Has a variadic template constructor allowing any number of arguments to +be forwarded to <type>Tp</type>'s constructor. +Unlike the other <classname>_Sp_counted_*</classname> classes, this one is parameterized on the +type of object, not the type of pointer; this is purely a convenience +that simplifies the implementation slightly. + </para> + </listitem> +</varlistentry> + +</variablelist> + + </sect3> + + <sect3> + <title>Thread Safety</title> + + <para> +The interface of <classname>tr1::shared_ptr</classname> was extended for C++0x +with support for rvalue-references and the other features from +N2351. As with other libstdc++ headers shared by TR1 and C++0x, +boost_shared_ptr.h uses conditional compilation, based on the macros +<constant>_GLIBCXX_INCLUDE_AS_CXX0X</constant> and +<constant>_GLIBCXX_INCLUDE_AS_TR1</constant>, to enable and disable +features. + </para> + + <para> +C++0x-only features are: rvalue-ref/move support, allocator support, +aliasing constructor, make_shared & allocate_shared. Additionally, +the constructors taking <classname>auto_ptr</classname> parameters are +deprecated in C++0x mode. + </para> + +<para> +The +<ulink url="http://boost.org/libs/smart_ptr/shared_ptr.htm#ThreadSafety">Thread +Safety</ulink> section of the Boost shared_ptr documentation says "shared_ptr +objects offer the same level of thread safety as built-in types." +The implementation must ensure that concurrent updates to separate shared_ptr +instances are correct even when those instances share a reference count e.g. +</para> + +<programlisting> +shared_ptr<A> a(new A); +shared_ptr<A> b(a); + +// Thread 1 // Thread 2 + a.reset(); b.reset(); +</programlisting> + +<para> +The dynamically-allocated object must be destroyed by exactly one of the +threads. Weak references make things even more interesting. +The shared state used to implement shared_ptr must be transparent to the +user and invariants must be preserved at all times. +The key pieces of shared state are the strong and weak reference counts. +Updates to these need to be atomic and visible to all threads to ensure +correct cleanup of the managed resource (which is, after all, shared_ptr's +job!) +On multi-processor systems memory synchronisation may be needed so that +reference-count updates and the destruction of the managed resource are +race-free. +</para> + +<para> +The function <function>_Sp_counted_base::_M_add_ref_lock()</function>, called when +obtaining a shared_ptr from a weak_ptr, has to test if the managed +resource still exists and either increment the reference count or throw +<classname>bad_weak_ptr</classname>. +In a multi-threaded program there is a potential race condition if the last +reference is dropped (and the managed resource destroyed) between testing +the reference count and incrementing it, which could result in a shared_ptr +pointing to invalid memory. +</para> +<para> +The Boost shared_ptr (as used in GCC) features a clever lock-free +algorithm to avoid the race condition, but this relies on the +processor supporting an atomic <emphasis>Compare-And-Swap</emphasis> +instruction. For other platforms there are fall-backs using mutex +locks. Boost (as of version 1.35) includes several different +implementations and the preprocessor selects one based on the +compiler, standard library, platform etc. For the version of +shared_ptr in libstdc++ the compiler and library are fixed, which +makes things much simpler: we have an atomic CAS or we don't, see Lock +Policy below for details. +</para> + + </sect3> + + <sect3> + <title>Selecting Lock Policy</title> + + <para> + </para> + + <para> +There is a single <classname>_Sp_counted_base</classname> class, +which is a template parameterized on the enum +<type>__gnu_cxx::_Lock_policy</type>. The entire family of classes is +parameterized on the lock policy, right up to +<classname>__shared_ptr</classname>, <classname>__weak_ptr</classname> and +<classname>__enable_shared_from_this</classname>. The actual +<classname>std::shared_ptr</classname> class inherits from +<classname>__shared_ptr</classname> with the lock policy parameter +selected automatically based on the thread model and platform that +libstdc++ is configured for, so that the best available template +specialization will be used. This design is necessary because it would +not be conforming for <classname>shared_ptr</classname> to have an +extra template parameter, even if it had a default value. The +available policies are: + </para> + + <orderedlist> + <listitem> + <para> + <type>_S_Atomic</type> + </para> + <para> +Selected when GCC supports a builtin atomic compare-and-swap operation +on the target processor (see <ulink url="http://gcc.gnu.org/onlinedocs/gcc/Atomic-Builtins.html">Atomic +Builtins</ulink>.) The reference counts are maintained using a lock-free +algorithm and GCC's atomic builtins, which provide the required memory +synchronisation. + </para> + </listitem> + + <listitem> + <para> + <type>_S_Mutex</type> + </para> + <para> +The _Sp_counted_base specialization for this policy contains a mutex, +which is locked in add_ref_lock(). This policy is used when GCC's atomic +builtins aren't available so explicit memory barriers are needed in places. + </para> + </listitem> + + <listitem> + <para> + <type>_S_Single</type> + </para> + <para> +This policy uses a non-reentrant add_ref_lock() with no locking. It is +used when libstdc++ is built without <literal>--enable-threads</literal>. + </para> + </listitem> + + </orderedlist> + <para> + For all three policies, reference count increments and + decrements are done via the functions in + <filename>ext/atomicity.h</filename>, which detect if the program + is multi-threaded. If only one thread of execution exists in + the program then less expensive non-atomic operations are used. + </para> + </sect3> + + <sect3> + <title>Dual C++0x and TR1 Implementation</title> + +<para> +The classes derived from <classname>_Sp_counted_base</classname> (see Class Hierarchy +below) and <classname>__shared_count</classname> are implemented separately for C++0x +and TR1, in <filename>bits/boost_sp_shared_count.h</filename> and +<filename>tr1/boost_sp_shared_count.h</filename> respectively. All other classes +including <classname>_Sp_counted_base</classname> are shared by both implementations. +</para> + +<para> +The TR1 implementation is considered relatively stable, so is unlikely to +change unless bug fixes require it. If the code that is common to both +C++0x and TR1 modes needs to diverge further then it might be necessary to +duplicate additional classes and only make changes to the C++0x versions. +</para> +</sect3> + +<sect3> +<title>Related functions and classes</title> + +<variablelist> + +<varlistentry> + <term><code>dynamic_pointer_cast</code>, <code>static_pointer_cast</code>, +<code>const_pointer_cast</code></term> + <listitem> + <para> +As noted in N2351, these functions can be implemented non-intrusively using +the alias constructor. However the aliasing constructor is only available +in C++0x mode, so in TR1 mode these casts rely on three non-standard +constructors in shared_ptr and __shared_ptr. +In C++0x mode these constructors and the related tag types are not needed. + </para> + </listitem> +</varlistentry> + +<varlistentry> + <term><code>enable_shared_from_this</code></term> + <listitem> + <para> +The clever overload to detect a base class of type +<code>enable_shared_from_this</code> comes straight from Boost. +There is an extra overload for <code>__enable_shared_from_this</code> to +work smoothly with <code>__shared_ptr<Tp, Lp></code> using any lock +policy. + </para> + </listitem> +</varlistentry> + +<varlistentry> + <term><code>make_shared</code>, <code>allocate_shared</code></term> + <listitem> + <para> +<code>make_shared</code> simply forwards to <code>allocate_shared</code> +with <code>std::allocator</code> as the allocator. +Although these functions can be implemented non-intrusively using the +alias constructor, if they have access to the implementation then it is +possible to save storage and reduce the number of heap allocations. The +newly constructed object and the _Sp_counted_* can be allocated in a single +block and the standard says implementations are "encouraged, but not required," +to do so. This implementation provides additional non-standard constructors +(selected with the type <code>_Sp_make_shared_tag</code>) which create an +object of type <code>_Sp_counted_ptr_inplace</code> to hold the new object. +The returned <code>shared_ptr<A></code> needs to know the address of the +new <code>A</code> object embedded in the <code>_Sp_counted_ptr_inplace</code>, +but it has no way to access it. +This implementation uses a "covert channel" to return the address of the +embedded object when <code>get_deleter<_Sp_make_shared_tag>()</code> +is called. Users should not try to use this. +As well as the extra constructors, this implementation also needs some +members of _Sp_counted_deleter to be protected where they could otherwise +be private. + </para> + </listitem> +</varlistentry> + +</variablelist> + +</sect3> + +</sect2> + +<!--- XXX + <listitem> + <type>_Sp_counted_base<Lp></type> + <para> +The base of the hierarchy is parameterized on the lock policy alone. +_Sp_counted_base doesn't depend on the type of pointer being managed, +it only maintains the reference counts and calls virtual functions when +the counts drop to zero. The managed object is destroyed when the last +strong reference is dropped, but the _Sp_counted_base itself must exist +until the last weak reference is dropped. + </para> + </listitem> + + <listitem> + <type>_Sp_counted_base_impl<Ptr, Deleter, Lp></type> + <para> +Inherits from _Sp_counted_base and stores a pointer of type <code>Ptr</code> +and a deleter of type <code>Deleter</code>. <code>_Sp_deleter</code> is +used when the user doesn't supply a custom deleter. Unlike Boost's, this +default deleter is not "checked" because GCC already issues a warning if +<code>delete</code> is used with an incomplete type. +This is the only derived type used by <code>tr1::shared_ptr<Ptr></code> +and it is never used by <code>std::shared_ptr</code>, which uses one of +the following types, depending on how the shared_ptr is constructed. + </para> + </listitem> +--> + +<sect2 id="shared_ptr.using" xreflabel="shared_ptr.using"> +<title>Use</title> + + <sect3> + <title>Examples</title> + <para> + Examples of use can be found in the testsuite, under + <filename class="directory">testsuite/tr1/2_general_utilities/shared_ptr</filename>. + </para> + </sect3> + + <sect3> + <title>Unresolved Issues</title> + <para> + The resolution to C++ Standard Library issue <ulink url="http://www.open-std.org/jtc1/sc22/wg21/docs/lwg-active.html#674">674</ulink>, + "shared_ptr interface changes for consistency with N1856" will + need to be implemented after it is accepted into the working + paper. Issue <ulink url="http://www.open-std.org/jtc1/sc22/wg21/docs/lwg-active.html#743">743</ulink> + might also require changes. + </para> + + <para> + The <type>_S_single</type> policy uses atomics when used in MT + code, because it uses the same dispatcher functions that check + <function>__gthread_active_p()</function>. This could be + addressed by providing template specialisations for some members + of <classname>_Sp_counted_base<_S_single></classname>. + </para> + + <para> + Unlike Boost, this implementation does not use separate classes + for the pointer+deleter and pointer+deleter+allocator cases in + C++0x mode, combining both into _Sp_counted_deleter and using + <classname>allocator</classname> when the user doesn't specify + an allocator. If it was found to be beneficial an additional + class could easily be added. With the current implementation, + the _Sp_counted_deleter and __shared_count constructors taking a + custom deleter but no allocator are technically redundant and + could be removed, changing callers to always specify an + allocator. If a separate pointer+deleter class was added the + __shared_count constructor would be needed, so it has been kept + for now. + </para> + + <para> + The hack used to get the address of the managed object from + <function>_Sp_counted_ptr_inplace::_M_get_deleter()</function> + is accessible to users. This could be prevented if + <function>get_deleter<_Sp_make_shared_tag>()</function> + always returned NULL, since the hack only needs to work at a + lower level, not in the public API. This wouldn't be difficult, + but hasn't been done since there is no danger of accidental + misuse: users already know they are relying on unsupported + features if they refer to implementation details such as + _Sp_make_shared_tag. + </para> + + <para> + tr1::_Sp_deleter could be a private member of tr1::__shared_count but it + would alter the ABI. + </para> + + <para> + Exposing the alias constructor in TR1 mode could simplify the + *_pointer_cast functions. Constructor could be private in TR1 + mode, with the cast functions as friends. + </para> + </sect3> + +</sect2> + +<sect2 id="shared_ptr.ack" xreflabel="shared_ptr.ack"> +<title>Acknowledgments</title> + + <para> + The original authors of the Boost shared_ptr, which is really nice + code to work with, Peter Dimov in particular for his help and + invaluable advice on thread safety. Phillip Jordan and Paolo + Carlini for the lock policy implementation. + </para> + +</sect2> + +<bibliography id="shared_ptr.biblio" xreflabel="shared_ptr.biblio"> +<title>Bibliography</title> + + <biblioentry> + <abbrev> + n2351 + </abbrev> + + <title> + Improving shared_ptr for C++0x, Revision 2 + </title> + <subtitle> + N2351 + </subtitle> + + <biblioid> + <ulink url="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2351.htm"> + </ulink> + </biblioid> + </biblioentry> + + + <biblioentry> + <abbrev> + n2456 + </abbrev> + + <title> + C++ Standard Library Active Issues List (Revision R52) + </title> + <subtitle> + N2456 + </subtitle> + + <biblioid> + <ulink url="http://open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2456.html"> + </ulink> + </biblioid> + </biblioentry> + + + <biblioentry> + <abbrev> + n2461 + </abbrev> + + <title> + Working Draft, Standard for Programming Language C++ + </title> + <subtitle> + N2461 + </subtitle> + + <biblioid> + <ulink url="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2461.pdf"> + </ulink> + </biblioid> + </biblioentry> + + + <biblioentry> + <abbrev> + boostshared_ptr + </abbrev> + + <title> + Boost C++ Libraries documentation - shared_ptr class template + </title> + <subtitle> + N2461 + </subtitle> + + <biblioid> + <ulink url="http://boost.org/libs/smart_ptr/shared_ptr.htm">shared_ptr + </ulink> + </biblioid> + </biblioentry> + +</bibliography> + +</sect1>
\ No newline at end of file diff --git a/libstdc++-v3/doc/xml/manual/spine.xml b/libstdc++-v3/doc/xml/manual/spine.xml new file mode 100644 index 00000000000..4c9c62842a1 --- /dev/null +++ b/libstdc++-v3/doc/xml/manual/spine.xml @@ -0,0 +1,111 @@ +<?xml version='1.0'?> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" +[ ]> + +<book id="manual-index" xreflabel="manual-index"> +<?dbhtml dir="manual"?> +<?dbhtml filename="spine.html"?> +<title>The GNU C++ Library</title> + +<bookinfo> + <copyright> + <year>2008</year> + <holder> + <ulink url="http://fsf.org">FSF</ulink> + </holder> + </copyright> + <legalnotice> + <para> + <ulink url="17_intro/license.html">License</ulink> + </para> + </legalnotice> +</bookinfo> + +<!-- Part 01 : Intro --> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" + parse="xml" href="intro.xml"> +</xi:include> + +<!-- Part 02 : Support --> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" + parse="xml" href="support.xml"> +</xi:include> + +<!-- Part 03 : Diagnostics --> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" + parse="xml" href="diagnostics.xml"> +</xi:include> + +<!-- Part 04 : Utilities --> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" + parse="xml" href="utilities.xml"> +</xi:include> + +<!-- Part 05 : Strings --> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" + parse="xml" href="strings.xml"> +</xi:include> + +<!-- Part 06 : Localization --> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" + parse="xml" href="localization.xml"> +</xi:include> + +<!-- Part 07 : Containers --> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" + parse="xml" href="containers.xml"> +</xi:include> + +<!-- Part 08 : Iterators --> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" + parse="xml" href="iterators.xml"> +</xi:include> + +<!-- Part 09 : Algorithms --> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" + parse="xml" href="algorithms.xml"> +</xi:include> + +<!-- Part 10 : Numerics --> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" + parse="xml" href="numerics.xml"> +</xi:include> + +<!-- Part 11 : Input Output --> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" + parse="xml" href="io.xml"> +</xi:include> + +<!-- Part 12 : Extensions --> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" + parse="xml" href="extensions.xml"> +</xi:include> + + +<!-- Appendix A --> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" + parse="xml" href="appendix_contributing.xml"> +</xi:include> + +<!-- Appendix B --> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" + parse="xml" href="appendix_porting.xml"> +</xi:include> + +<!-- Appendix C --> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" + parse="xml" href="appendix_free.xml"> +</xi:include> + +<!-- Appendix D --> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" + parse="xml" href="../gnu/gpl-2.0.xml"> +</xi:include> + +<!-- Appendix E --> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" + parse="xml" href="../gnu/fdl-1.2.xml"> +</xi:include> + +</book> diff --git a/libstdc++-v3/doc/xml/manual/status_cxx1998.xml b/libstdc++-v3/doc/xml/manual/status_cxx1998.xml new file mode 100644 index 00000000000..fc22af00d3b --- /dev/null +++ b/libstdc++-v3/doc/xml/manual/status_cxx1998.xml @@ -0,0 +1,6153 @@ +<sect2 id="manual.intro.status.standard.1998" xreflabel="Status C++ 1998"> +<?dbhtml filename="standard_cxx1998.html"?> + +<sect2info> + <keywordset> + <keyword> + ISO C++ + </keyword> + <keyword> + 1998 + </keyword> + </keywordset> +</sect2info> + +<title>C++ 1998</title> + +<sect3 id="standard.1998" xreflabel="Status C++ 1998"> + <title>Checklist</title> + +<literallayout> + Completion Checklist for the Standard C++ Library + Updated: 2003-04-25 + + Status Code Legend: + M - Missing + S - Present as stub. + X - Partially implemented, or buggy. + T - Implemented, pending test/inspection. + V - Verified to pass all available test suites. + Q - Qualified by inspection for non-testable correctness. + P - Portability verified. + C - Certified. + + Lexical notes: + Only status codes appear in column 0. Notes relating to conformance + issues appear [in brackets]. + + Note that this checklist does not (yet) include all emendations + recommended by the ISO Library Working Group: + http://anubis.dkuug.dk/jtc1/sc22/wg21/docs/lwg-toc.html + + Detailed explanation of status codes: + + M - Missing: The name is not visible to programs that include + the specified header, either at compile or link stage. + + S - Present as stub: A program can use the name, but no implementation + is provided. Programs that use the name link correctly, but + cannot usefully be run. + + X - Partially implemented, or buggy: Some implementation has been + provided, but it is known or believed not to conform fully. + It may have an incorrect base class, wrong namespace, wrong + storage class, or simply not fully implement requirements. + However, it may be sufficiently usable to help test other + components. + + T - Implemented, pending test/inspection: Implementation believed + to be complete, and informal testing suggests it is ready for + formal verification. + + V - Verified, passes all test suites: Verified to satisfy all + generically testable conformance requirements. + + Q - Qualified by inspection for non-testable correctness: + Inspected, "implementation-defined" documentation accepted, + local usability criteria satisfied, formally inspected for + other untestable conformance. (Untestable requirements + include exception-safety, thread-safety, worst-case + complexity, memory cleanliness, usefulness.) + + P - Portability verified: Qualified on all primary target platforms. + + C - Certified: Formally certified to have passed all tests, + inspections, qualifications; approved under "signing authority" + to be used to satisfy contractual guarantees. + + ---------------------------------------------------------------------- + <algorithm> <iomanip> <list> <ostream> <streambuf> + <bitset> <ios> <locale> <queue> <string> + <complex> <iosfwd> <map> <set> <typeinfo> +X <deque> <iostream> <memory> <sstream> <utility> + <exception> <istream> <new> <stack> <valarray> + <fstream> <iterator> <numeric> <stdexcept> <vector> + <functional> <limits> + + [C header names must be in std:: to qualify. Related to shadow/ dir.] + <cassert> <ciso646> <csetjmp> <cstdio> <ctime> + <cctype> <climits> <csignal> <cstdlib> <cwchar> +X <cerrno> <clocale> <cstdarg> <cstring> <cwctype> + <cfloat> <cmath> <cstddef> + + Macro: +X errno, declared or defined in <cerrno>. + + Macro fn: +X setjmp(jmp_buf), declared or defined in <csetjmp> +X va_end(va_list), declared or defined in <cstdarg> + + Types: +X clock_t, div_t, FILE, fpos_t, lconv, ldiv_t, mbstate_t, +X ptrdiff_t, sig_atomic_t, size_t, time_t, tm, va_list, +X wctrans_t, wctype_t, and wint_t. + + 1 Which of the functions in the C++ Standard Library are not reentrant + subroutines is implementation-defined. + + 18.1 Types [lib.support.types] +X <cstddef> +X NULL +X offsetof +X ptrdiff_t +X size_t + + 18.2 Implementation properties [lib.support.limits] + + <limits>, <climits>, and <cfloat> + + 18.2.1 Numeric limits [lib.limits] + +X template<class T> class numeric_limits; + +T enum float_round_style; +T enum float_denorm_style; + +T template<> class numeric_limits<bool>; + +T template<> class numeric_limits<char>; +T template<> class numeric_limits<signed char>; +T template<> class numeric_limits<unsigned char>; +T template<> class numeric_limits<wchar_t>; + +T template<> class numeric_limits<short>; +T template<> class numeric_limits<int>; +T template<> class numeric_limits<long>; +T template<> class numeric_limits<unsigned short>; +T template<> class numeric_limits<unsigned int>; +T template<> class numeric_limits<unsigned long>; + +X template<> class numeric_limits<float>; +X template<> class numeric_limits<double>; +X template<> class numeric_limits<long double>; + + 18.2.1.1 Template class numeric_limits [lib.numeric.limits] +T template<class T> class numeric_limits { + public: +T static const bool is_specialized = false; +T static T min() throw(); +T static T max() throw(); +T static const int digits = 0; +T static const int digits10 = 0; +T static const bool is_signed = false; +T static const bool is_integer = false; +T static const bool is_exact = false; +T static const int radix = 0; +T static T epsilon() throw(); +T static T round_error() throw(); + +T static const int min_exponent = 0; +T static const int min_exponent10 = 0; +T static const int max_exponent = 0; +T static const int max_exponent10 = 0; + +T static const bool has_infinity = false; +T static const bool has_quiet_NaN = false; +T static const bool has_signaling_NaN = false; +T static const float_denorm_style has_denorm = denorm_absent; +T static const bool has_denorm_loss = false; +T static T infinity() throw(); +T static T quiet_NaN() throw(); +T static T signaling_NaN() throw(); +T static T denorm_min() throw(); + +T static const bool is_iec559 = false; +T static const bool is_bounded = false; +T static const bool is_modulo = false; + +T static const bool traps = false; +T static const bool tinyness_before = false; +T static const float_round_style round_style = round_toward_zero; + }; + + 18.2.1.3 Type float_round_style [lib.round.style] + +T enum float_round_style { +T round_indeterminate = -1, +T round_toward_zero = 0, +T round_to_nearest = 1, +T round_toward_infinity = 2, +T round_toward_neg_infinity = 3 + }; + + 18.2.1.4 Type float_denorm_style [lib.denorm.style] + +T enum float_denorm_style { +T denorm_indeterminate = -1; +T denorm_absent = 0; +T denorm present = 1; + }; + + 18.2.1.5 numeric_limits specializations [lib.numeric.special] + + [Note: see Note at 18.2.1. ] + + 18.2.2 C Library [lib.c.limits] + + 1 Header <climits> (Table 3): + CHAR_BIT INT_MAX LONG_MIN SCHAR_MIN UCHAR_MAX USHRT_MAX +X CHAR_MAX INT_MIN MB_LEN_MAX SHRT_MAX UINT_MAX + CHAR_MIN LONG_MAX SCHAR_MAX SHRT_MIN ULONG_MAX + + 3 Header <cfloat> (Table 4): + + DBL_DIG DBL_MIN_EXP FLT_MIN_10_EXP LDBL_MAX_10_EXP + DBL_EPSILON FLT_DIG FLT_MIN_EXP LDBL_MAX_EXP + DBL_MANT_DIG FLT_EPSILON FLT_RADIX LDBL_MIN +X DBL_MAX FLT_MANT_DIG FLT_ROUNDS LDBL_MIN_10_EXP + DBL_MAX_10_EXP FLT_MAX LDBL_DIG LDBL_MIN_EXP + DBL_MAX_EXP FLT_MAX_10_EXP LDBL_EPSILON + DBL_MIN FLT_MAX_EXP LDBL_MANT_DIG + DBL_MIN_10_EXP FLT_MIN LDBL_MAX + + + 1 Header <cstdlib> (partial), Table 5: +X EXIT_FAILURE EXIT_SUCCESS + abort atexit exit + +S abort(void) +S extern "C" int atexit(void (*f)(void)) +S extern "C++" int atexit(void (*f)(void)) +S exit(int status) + + 18.4 Dynamic memory management [lib.support.dynamic] + + Header <new> synopsis + +T class bad_alloc; +T struct nothrow_t {}; +T extern const nothrow_t nothrow; +T typedef void (*new_handler)(); +T new_handler set_new_handler(new_handler new_p) throw(); + +T void* operator new(std::size_t size) throw(std::bad_alloc); +T void* operator new(std::size_t size, const std::nothrow_t&) throw(); +T void operator delete(void* ptr) throw(); +T void operator delete(void* ptr, const std::nothrow_t&) throw(); +T void* operator new[](std::size_t size) throw(std::bad_alloc); +T void* operator new[](std::size_t size, const std::nothrow_t&) throw(); +T void operator delete[](void* ptr) throw(); +T void operator delete[](void* ptr, const std::nothrow_t&) throw(); +T void* operator new (std::size_t size, void* ptr) throw(); +T void* operator new[](std::size_t size, void* ptr) throw(); +T void operator delete (void* ptr, void*) throw(); +T void operator delete[](void* ptr, void*) throw(); + + 18.4.2.1 Class bad_alloc [lib.bad.alloc] + +T class bad_alloc : public exception { + public: +T bad_alloc() throw(); +T bad_alloc(const bad_alloc&) throw(); +T bad_alloc& operator=(const bad_alloc&) throw(); +T virtual ~bad_alloc() throw(); +T virtual const char* what() const throw(); + + + +T new_handler set_new_handler(new_handler new_p) throw(); + + + Header <typeinfo> synopsis + +T class type_info; +T class bad_cast; +T class bad_typeid; + + 18.5.1 - Class type_info [lib.type.info] + +T class type_info { + public: +T virtual ~type_info(); +T bool operator==(const type_info& rhs) const; +T bool operator!=(const type_info& rhs) const; +T bool before(const type_info& rhs) const; +T const char* name() const; + private: +T type_info(const type_info& rhs); +T type_info& operator=(const type_info& rhs); + }; + + 18.5.2 - Class bad_cast [lib.bad.cast] + +T bad_cast() throw(); +T virtual const char* bad_cast::what() const throw(); + + 18.5.3 Class bad_typeid [lib.bad.typeid] + +T class bad_typeid : public exception { + public: +T bad_typeid() throw(); +T bad_typeid(const bad_typeid&) throw(); +T bad_typeid& operator=(const bad_typeid&) throw(); +T virtual ~bad_typeid() throw(); +T virtual const char* what() const throw(); + }; + + 18.6 Exception handling [lib.support.exception] + +T Header <exception> synopsis + +T class exception; +T class bad_exception; + +T typedef void (*unexpected_handler)(); +T unexpected_handler set_unexpected(unexpected_handler f) throw(); +T void unexpected(); +T typedef void (*terminate_handler)(); +T terminate_handler set_terminate(terminate_handler f) throw(); +T void terminate(); +T bool uncaught_exception(); + + 18.6.1 Class exception [lib.exception] + +T class exception { + public: +T exception() throw(); +T exception(const exception&) throw(); +T exception& operator=(const exception&) throw(); +T virtual ~exception() throw(); +T virtual const char* what() const throw(); + }; + + 18.6.2.1 Class bad_exception [lib.bad.exception] +T class bad_exception : public exception { + public: +T bad_exception() throw(); +T bad_exception(const bad_exception&) throw(); +T bad_exception& operator=(const bad_exception&) throw(); +T virtual ~bad_exception() throw(); +T virtual const char* what() const throw(); + }; + + 18.7 Other runtime support [lib.support.runtime] + + 1 Headers <cstdarg> (variable arguments), <csetjmp> (nonlocal jumps), + <ctime> (system clock clock(), time()), <csignal> (signal handling), + and <cstdlib> (runtime environment getenv(), system()). + + Table 6--Header <cstdarg> synopsis + Macros: va_arg va_end va_start +X Type: va_list + + Table 7--Header <csetjmp> synopsis + + Macro: setjmp | +X Type: jmp_buf + Function: longjmp + + Table 8--Header <ctime> synopsis + + Macros: CLOCKS_PER_SEC +X Types: clock_t + Functions: clock + + Table 9--Header <csignal> synopsis + +X Macros: SIGABRT SIGILL SIGSEGV SIG_DFL + SIG_IGN SIGFPE SIGINT SIGTERM SIG_ERR + Type: sig_atomic_t + Functions: raise signal + + Table 10--Header <cstdlib> synopsis + +X Functions: getenv system + + 19.1 Exception classes [lib.std.exceptions] + + Header <stdexcept> synopsis + +T class logic_error; +T class domain_error; +T class invalid_argument; +T class length_error; +T class out_of_range; +T class runtime_error; +T class range_error; +T class overflow_error; +T class underflow_error; + + 19.1.1 Class logic_error [lib.logic.error] +T class logic_error : public exception { + public: +T explicit logic_error(const string& what_arg); + }; + + 19.1.2 Class domain_error [lib.domain.error] + +T class domain_error : public logic_error { + public: +T explicit domain_error(const string& what_arg); + }; + + 19.1.3 Class invalid_argument [lib.invalid.argument] + +T class invalid_argument : public logic_error { + public: +T explicit invalid_argument(const string& what_arg); + }; + + 19.1.4 Class length_error [lib.length.error] + +T class length_error : public logic_error { + public: +T explicit length_error(const string& what_arg); + }; + + 19.1.5 Class out_of_range [lib.out.of.range] + +T class out_of_range : public logic_error { + public: +T explicit out_of_range(const string& what_arg); + }; + + + 19.1.6 Class runtime_error [lib.runtime.error] + +T class runtime_error : public exception { + public: +T explicit runtime_error(const string& what_arg); + }; + + + 19.1.7 Class range_error [lib.range.error] + +T class range_error : public runtime_error { + public: +T explicit range_error(const string& what_arg); + }; + + 19.1.8 Class overflow_error [lib.overflow.error] + +T class overflow_error : public runtime_error { + public: +T explicit overflow_error(const string& what_arg); + }; + + + 19.1.9 Class underflow_error [lib.underflow.error] + +T class underflow_error : public runtime_error { + public: +T explicit underflow_error(const string& what_arg); + }; + + + 19.2 Assertions [lib.assertions] + + Table 2--Header <cassert> synopsis + +X Macro: assert + + 19.3 Error numbers [lib.errno] + + Table 3--Header <cerrno> synopsis + +X |Macros: EDOM ERANGE errno | + + + 20.2 Utility components [lib.utility] + + Header <utility> synopsis + + // _lib.operators_, operators: +T namespace rel_ops { +T template<class T> bool operator!=(const T&, const T&); +T template<class T> bool operator> (const T&, const T&); +T template<class T> bool operator<=(const T&, const T&); +T template<class T> bool operator>=(const T&, const T&); + } + // _lib.pairs_, pairs: +T template <class T1, class T2> struct pair; +T template <class T1, class T2> + bool operator==(const pair<T1,T2>&, const pair<T1,T2>&); +T template <class T1, class T2> + bool operator< (const pair<T1,T2>&, const pair<T1,T2>&); +T template <class T1, class T2> + bool operator!=(const pair<T1,T2>&, const pair<T1,T2>&); +T template <class T1, class T2> + bool operator> (const pair<T1,T2>&, const pair<T1,T2>&); +T template <class T1, class T2> + bool operator>=(const pair<T1,T2>&, const pair<T1,T2>&); +T template <class T1, class T2> + bool operator<=(const pair<T1,T2>&, const pair<T1,T2>&); +T template <class T1, class T2> pair<T1,T2> make_pair(const T1&, const T2&); + + + 20.2.2 Pairs [lib.pairs] + +T template <class T1, class T2> + struct pair { +T typedef T1 first_type; +T typedef T2 second_type; + +T T1 first; +T T2 second; +T pair(); +T pair(const T1& x, const T2& y); +T template<class U, class V> pair(const pair<U, V> &p); + }; + + 20.3 Function objects [lib.function.objects] + + Header <functional> synopsis + + // _lib.base_, base: +V template <class Arg, class Result> struct unary_function; +V template <class Arg1, class Arg2, class Result> struct binary_function; + + // _lib.arithmetic.operations_, arithmetic operations: +V template <class T> struct plus; +V template <class T> struct minus; +V template <class T> struct multiplies; +V template <class T> struct divides; +V template <class T> struct modulus; +V template <class T> struct negate; + // _lib.comparisons_, comparisons: +V template <class T> struct equal_to; +V template <class T> struct not_equal_to; +V template <class T> struct greater; +V template <class T> struct less; +V template <class T> struct greater_equal; +V template <class T> struct less_equal; + // _lib.logical.operations_, logical operations: +V template <class T> struct logical_and; +V template <class T> struct logical_or; +V template <class T> struct logical_not; + // _lib.negators_, negators: + template <class Predicate> struct unary_negate; +V template <class Predicate> + unary_negate<Predicate> not1(const Predicate&); +V template <class Predicate> struct binary_negate; +V template <class Predicate> + binary_negate<Predicate> not2(const Predicate&); + // _lib.binders_, binders: +V template <class Operation> class binder1st; +V template <class Operation, class T> + binder1st<Operation> bind1st(const Operation&, const T&); +V template <class Operation> class binder2nd; +V template <class Operation, class T> + binder2nd<Operation> bind2nd(const Operation&, const T&); + // _lib.function.pointer.adaptors_, adaptors: +V template <class Arg, class Result> class pointer_to_unary_function; +V template <class Arg, class Result> + pointer_to_unary_function<Arg,Result> ptr_fun(Result (*)(Arg)); +V template <class Arg1, class Arg2, class Result> + class pointer_to_binary_function; +V template <class Arg1, class Arg2, class Result> + pointer_to_binary_function<Arg1,Arg2,Result> + ptr_fun(Result (*)(Arg1,Arg2)); + + // _lib.member.pointer.adaptors_, adaptors: +V template<class S, class T> class mem_fun_t; +V template<class S, class T, class A> class mem_fun1_t; +V template<class S, class T> + mem_fun_t<S,T> mem_fun(S (T::*f)()); +V template<class S, class T, class A> + mem_fun1_t<S,T,A> mem_fun(S (T::*f)(A)); +V template<class S, class T> class mem_fun_ref_t; +V template<class S, class T, class A> class mem_fun1_ref_t; +V template<class S, class T> + mem_fun_ref_t<S,T> mem_fun_ref(S (T::*f)()); +V template<class S, class T, class A> + mem_fun1_ref_t<S,T,A> mem_fun_ref(S (T::*f)(A)); + +V template <class S, class T> class const_mem_fun_t; +V template <class S, class T, class A> class const_mem_fun1_t; +V template <class S, class T> + const_mem_fun_t<S,T> mem_fun(S (T::*f)() const); +V template <class S, class T, class A> + const_mem_fun1_t<S,T,A> mem_fun(S (T::*f)(A) const); +V template <class S, class T> class const_mem_fun_ref_t; +V template <class S, class T, class A> class const_mem_fun1_ref_t; +V template <class S, class T> + const_mem_fun_ref_t<S,T> mem_fun_ref(S (T::*f)() const); +V template <class S, class T, class A> + const_mem_fun1_ref_t<S,T,A> mem_fun_ref(S (T::*f)(A) const); + } + + 20.3.1 Base [lib.base] + +V template <class Arg, class Result> + struct unary_function { +V typedef Arg argument_type; +V typedef Result result_type; + }; +V template <class Arg1, class Arg2, class Result> + struct binary_function { +V typedef Arg1 first_argument_type; +V typedef Arg2 second_argument_type; +V typedef Result result_type; + }; + + 20.3.2 Arithmetic operations [lib.arithmetic.operations] + +T template <class T> struct plus : binary_function<T,T,T> { +V T operator()(const T& x, const T& y) const; + }; + +T template <class T> struct minus : binary_function<T,T,T> { +V T operator()(const T& x, const T& y) const; + }; + +T template <class T> struct multiplies : binary_function<T,T,T> { +V T operator()(const T& x, const T& y) const; + }; + +T template <class T> struct divides : binary_function<T,T,T> { +V T operator()(const T& x, const T& y) const; + }; + +T template <class T> struct modulus : binary_function<T,T,T> { +V T operator()(const T& x, const T& y) const; + }; + +T template <class T> struct negate : unary_function<T,T> { +V T operator()(const T& x) const; + }; + + 20.3.3 Comparisons [lib.comparisons] + +T template <class T> struct equal_to : binary_function<T,T,bool> { +V bool operator()(const T& x, const T& y) const; + }; + +T template <class T> struct not_equal_to : binary_function<T,T,bool> { +V bool operator()(const T& x, const T& y) const; + }; + +T template <class T> struct greater : binary_function<T,T,bool> { +V bool operator()(const T& x, const T& y) const; + }; + +T template <class T> struct less : binary_function<T,T,bool> { +V bool operator()(const T& x, const T& y) const; + }; + +T template <class T> struct greater_equal : binary_function<T,T,bool> { +V bool operator()(const T& x, const T& y) const; + }; + +T template <class T> struct less_equal : binary_function<T,T,bool> { +V bool operator()(const T& x, const T& y) const; + }; + + 20.3.4 Logical operations [lib.logical.operations] + +T template <class T> struct logical_and : binary_function<T,T,bool> { +V bool operator()(const T& x, const T& y) const; + }; + +T template <class T> struct logical_or : binary_function<T,T,bool> { +V bool operator()(const T& x, const T& y) const; + }; + +T template <class T> struct logical_not : unary_function<T,bool> { +V bool operator()(const T& x) const; + }; + + 20.3.5 Negators [lib.negators] + +T template <class Predicate> + class unary_negate + : public unary_function<typename Predicate::argument_type,bool> { + public: +T explicit unary_negate(const Predicate& pred); +V bool operator()(const typename Predicate::argument_type& x) const; + }; + +T template <class Predicate> + class binary_negate + : public binary_function<typename Predicate::first_argument_type, + typename Predicate::second_argument_type, bool> { + public: +T explicit binary_negate(const Predicate& pred); +V bool operator()(const typename Predicate::first_argument_type& x, + const typename Predicate::second_argument_type& y) const; + }; + + + 20.3.6 Binders [lib.binders] + + 20.3.6.1 Template class binder1st [lib.binder.1st] +T template <class Operation> + class binder1st + : public unary_function<typename Operation::second_argument_type, + typename Operation::result_type> { + protected: +T Operation op; +T typename Operation::first_argument_type value; + public: +V binder1st(const Operation& x, + const typename Operation::first_argument_type& y); +V typename Operation::result_type + operator()(const typename Operation::second_argument_type& x) const; + }; + + 20.3.6.2 bind1st [lib.bind.1st] + +V template <class Operation, class T> + binder1st<Operation> bind1st(const Operation& op, const T& x); + + 20.3.6.3 Template class binder2nd [lib.binder.2nd] +T template <class Operation> + class binder2nd + : public unary_function<typename Operation::first_argument_type, + typename Operation::result_type> { + protected: +T Operation op; +T typename Operation::second_argument_type value; + public: +V binder2nd(const Operation& x, + const typename Operation::second_argument_type& y); +V typename Operation::result_type + operator()(const typename Operation::first_argument_type& x) const; + }; + + 20.3.6.4 bind2nd [lib.bind.2nd] + +T template <class Operation, class T> + binder2nd<Operation> bind2nd(const Operation& op, const T& x); + + + 20.3.7 Adaptors for pointers to [lib.function.pointer.adaptors] + functions + + 1 To allow pointers to (unary and binary) functions to work with func- + tion adaptors the library provides: + +T template <class Arg, class Result> + class pointer_to_unary_function : public unary_function<Arg, Result> { + public: +T explicit pointer_to_unary_function(Result (*f)(Arg)); +V Result operator()(Arg x) const; + }; + +T template <class Arg, class Result> + pointer_to_unary_function<Arg, Result> ptr_fun(Result (*f)(Arg)); + +T template <class Arg1, class Arg2, class Result> + class pointer_to_binary_function : + public binary_function<Arg1,Arg2,Result> { + public: +T explicit pointer_to_binary_function(Result (*f)(Arg1, Arg2)); +V Result operator()(Arg1 x, Arg2 y) const; + }; + + + 20.3.8 Adaptors for pointers to [lib.member.pointer.adaptors] + members + +T template <class S, class T> class mem_fun_t + : public unary_function<T*, S> { + public: +T explicit mem_fun_t(S (T::*p)()); +V S operator()(T* p) const; + }; + +T template <class S, class T, class A> class mem_fun1_t + : public binary_function<T*, A, S> { + public: +T explicit mem_fun1_t(S (T::*p)(A)); +V S operator()(T* p, A x) const; + }; + +V template<class S, class T> mem_fun_t<S,T> + mem_fun(S (T::*f)()); +V template<class S, class T, class A> mem_fun1_t<S,T,A> + mem_fun(S (T::*f)(A)); + +T template <class S, class T> class mem_fun_ref_t + : public unary_function<T, S> { + public: +T explicit mem_fun_ref_t(S (T::*p)()); +V S operator()(T& p) const; + }; + +T template <class S, class T, class A> class mem_fun1_ref_t + : public binary_function<T, A, S> { + public: +T explicit mem_fun1_ref_t(S (T::*p)(A)); +V S operator()(T& p, A x) const; + }; + +T template<class S, class T> mem_fun_ref_t<S,T> + mem_fun_ref(S (T::*f)()); + +T template<class S, class T, class A> mem_fun1_ref_t<S,T,A> + mem_fun_ref(S (T::*f)(A)); + +T template <class S, class T> class const_mem_fun_t + : public unary_function<T*, S> { + public: +T explicit const_mem_fun_t(S (T::*p)() const); +V S operator()(const T* p) const; + }; + +T template <class S, class T, class A> class const_mem_fun1_t + : public binary_function<T*, A, S> { + public: +T explicit const mem_fun1_t(S (T::*p)(A) const); +V S operator()(const T* p, A x) const; + }; + +V template<class S, class T> const_mem_fun_t<S,T> + mem_fun(S (T::*f)() const); +V template<class S, class T, class A> const_mem_fun1_t<S,T,A> + mem_fun(S (T::*f)(A) const); + +T template <class S, class T> class const_mem_fun_ref_t + : public unary_function<T, S> { + public: +T explicit const_mem_fun_ref_t(S (T::*p)() const); +V S operator()(const T& p) const; + }; + +T template <class S, class T, class A> class const_mem_fun1_ref_t + : public binary_function<T, A, S> { + public: +T explicit const_mem_fun1_ref_t(S (T::*p)(A) const); +V S operator()(const T& p, A x) const; + }; + +T template<class S, class T> const_mem_fun_ref_t<S,T> + mem_fun_ref(S (T::*f)() const); + +T template<class S, class T, class A> const_mem_fun1_ref_t<S,T,A> + mem_fun_ref(S (T::*f)(A) const); + + 20.4 Memory [lib.memory] + + Header <memory> synopsis + + // _lib.default.allocator_, the default allocator: +T template <class T> class allocator; +T template <> class allocator<void>; +T template <class T, class U> + bool operator==(const allocator<T>&, const allocator<U>&) throw(); +T template <class T, class U> + bool operator!=(const allocator<T>&, const allocator<U>&) throw(); + // _lib.storage.iterator_, raw storage iterator: +T template <class OutputIterator, class T> class raw_storage_iterator; + // _lib.temporary.buffer_, temporary buffers: +T template <class T> + pair<T*,ptrdiff_t> get_temporary_buffer(ptrdiff_t n); +T template <class T> + void return_temporary_buffer(T* p); + // _lib.specialized.algorithms_, specialized algorithms: +T template <class InputIterator, class ForwardIterator> + ForwardIterator + uninitialized_copy(InputIterator first, InputIterator last, + ForwardIterator result); +T template <class ForwardIterator, class T> + void uninitialized_fill(ForwardIterator first, ForwardIterator last, + const T& x); +T template <class ForwardIterator, class Size, class T> + void uninitialized_fill_n(ForwardIterator first, Size n, const T& x); + // _lib.auto.ptr_, pointers: +X template<class X> class auto_ptr; + } + + 20.4.1 The default allocator [lib.default.allocator] + +T template <class T> class allocator; + // specialize for void: +T template <> class allocator<void> { + public: +T typedef void* pointer; +T typedef const void* const_pointer; + // reference-to-void members are impossible. +T typedef void value_type; +T template <class U> struct rebind { typedef allocator<U> other; }; + }; + +T template <class T> class allocator { + public: +T typedef size_t size_type; +T typedef ptrdiff_t difference_type; +T typedef T* pointer; +T typedef const T* const_pointer; +T typedef T& reference; +T typedef const T& const_reference; +T typedef T value_type; +T template <class U> struct rebind { typedef allocator<U> other; }; +T allocator() throw(); +T allocator(const allocator&) throw(); +T template <class U> allocator(const allocator<U>&) throw(); +T ~allocator() throw(); +T pointer address(reference x) const; +T const_pointer address(const_reference x) const; +T pointer allocate( + size_type, allocator<void>::const_pointer hint = 0); +T void deallocate(pointer p, size_type n); +T size_type max_size() const throw(); +T void construct(pointer p, const T& val); +T void destroy(pointer p); + }; + + 20.4.1.2 allocator globals [lib.allocator.globals] + +T template <class T1, class T2> + bool operator==(const allocator<T1>&, const allocator<T2>&) throw(); +T template <class T1, class T2> + bool operator!=(const allocator<T1>&, const allocator<T2>&) throw(); + + 20.4.2 Raw storage iterator [lib.storage.iterator] + +T template <class OutputIterator, class T> + class raw_storage_iterator + : public iterator<output_iterator_tag,void,void,void,void> { + public: +T explicit raw_storage_iterator(OutputIterator x); +T raw_storage_iterator<OutputIterator,T>& operator*(); +T raw_storage_iterator<OutputIterator,T>& operator=(const T& element); +T raw_storage_iterator<OutputIterator,T>& operator++(); +T raw_storage_iterator<OutputIterator,T> operator++(int); + }; + + 20.4.3 Temporary buffers [lib.temporary.buffer] + +T template <class T> + pair<T*, ptrdiff_t> get_temporary_buffer(ptrdiff_t n); + +T template <class T> void return_temporary_buffer(T* p); + + 20.4.4 Specialized algorithms [lib.specialized.algorithms] + + 20.4.4.1 uninitialized_copy [lib.uninitialized.copy] + +V template <class InputIterator, class ForwardIterator> + ForwardIterator + uninitialized_copy(InputIterator first, InputIterator last, + ForwardIterator result); + + 20.4.4.2 uninitialized_fill [lib.uninitialized.fill] + +V template <class ForwardIterator, class T> + void uninitialized_fill(ForwardIterator first, ForwardIterator last, + const T& x); + + 20.4.4.3 uninitialized_fill_n [lib.uninitialized.fill.n] + +V template <class ForwardIterator, class Size, class T> + void uninitialized_fill_n(ForwardIterator first, Size n, const T& x); + + 20.4.5 Template class auto_ptr [lib.auto.ptr] + +X template<class X> class auto_ptr { + template <class Y> struct auto_ptr_ref {}; + public: +T typedef X element_type; + // _lib.auto.ptr.cons_ construct/copy/destroy: +T explicit auto_ptr(X* p =0) throw(); +T auto_ptr(auto_ptr&) throw(); +T template<class Y> auto_ptr(auto_ptr<Y>&) throw(); +T auto_ptr& operator=(auto_ptr&) throw(); +T template<class Y> auto_ptr& operator=(auto_ptr<Y>&) throw(); +T ~auto_ptr() throw(); + // _lib.auto.ptr.members_ members: +T X& operator*() const throw(); +T X* operator->() const throw(); +T X* get() const throw(); +T X* release() throw(); +T void reset(X* p =0) throw(); + + // _lib.auto.ptr.conv_ conversions: +X auto_ptr(auto_ptr_ref<X>) throw(); +X template<class Y> operator auto_ptr_ref<Y>() throw(); +X template<class Y> operator auto_ptr<Y>() throw(); + }; + + 20.4.6 C Library [lib.c.malloc] + + Table 7--Header <cstdlib> synopsis + +X Functions: calloc malloc + free realloc + + + Table 8--Header <cstring> synopsis + +X Macro: NULL +X Type: size_t +X Functions: memchr memcmp +X memcpy memmove memset + + Table 9--Header <ctime> synopsis + +X Macros: NULL +X Types: size_t clock_t time_t +X Struct: tm + Functions: +X asctime clock difftime localtime strftime +X ctime gmtime mktime time + + 21.1.1 Character traits requirements [lib.char.traits.require] + + 2 The struct template +T template<class charT> struct char_traits; + shall be provided in the header <string> as a basis for explicit spe- + cializations. + + + 21.1.3.1 struct [lib.char.traits.specializations.char] + char_traits<char> + +T template<> + struct char_traits<char> { +T typedef char char_type; +T typedef int int_type; +T typedef streamoff off_type; +T typedef streampos pos_type; +T typedef mbstate_t state_type; + +T static void assign(char_type& c1, const char_type& c2); +T static bool eq(const char_type& c1, const char_type& c2); +T static bool lt(const char_type& c1, const char_type& c2); + +T static int compare(const char_type* s1, const char_type* s2, size_t n); +T static size_t length(const char_type* s); +T static const char_type* find(const char_type* s, size_t n, + const char_type& a); +T static char_type* move(char_type* s1, const char_type* s2, size_t n); +T static char_type* copy(char_type* s1, const char_type* s2, size_t n); +T static char_type* assign(char_type* s, size_t n, char_type a); + +T static int_type not_eof(const int_type& c); +T static char_type to_char_type(const int_type& c); +T static int_type to_int_type(const char_type& c); +T static bool eq_int_type(const int_type& c1, const int_type& c2); +T static int_type eof(); + }; + + 21.1.3.2 struct [lib.char.traits.specializations.wchar.t] + char_traits<wchar_t> + +V template<> + struct char_traits<wchar_t> { +V typedef wchar_t char_type; +V typedef wint_t int_type; +V typedef streamoff off_type; +V typedef wstreampos pos_type; +V typedef mbstate_t state_type; + +V static void assign(char_type& c1, const char_type& c2); +V static bool eq(const char_type& c1, const char_type& c2); +V static bool lt(const char_type& c1, const char_type& c2); + +V static int compare(const char_type* s1, const char_type* s2, size_t n); +V static size_t length(const char_type* s); +V static const char_type* find(const char_type* s, size_t n, + const char_type& a); +V static char_type* move(char_type* s1, const char_type* s2, size_t n); +V static char_type* copy(char_type* s1, const char_type* s2, size_t n); +V static char_type* assign(char_type* s, size_t n, char_type a); + +V static int_type not_eof(const int_type& c); +V static char_type to_char_type(const int_type& c); +V static int_type to_int_type(const char_type& c); +V static bool eq_int_type(const int_type& c1, const int_type& c2); +V static int_type eof(); + }; + + 21.2 String classes [lib.string.classes] + + // _lib.char.traits_, character traits: +V template<class charT> + struct char_traits; +V template <> struct char_traits<char>; +V template <> struct char_traits<wchar_t>; + + // _lib.basic.string_, basic_string: +V template<class charT, class traits = char_traits<charT>, + class Allocator = allocator<charT> > + class basic_string; +V template<class charT, class traits, class Allocator> + basic_string<charT,traits,Allocator> + operator+(const basic_string<charT,traits,Allocator>& lhs, + const basic_string<charT,traits,Allocator>& rhs); +V template<class charT, class traits, class Allocator> + basic_string<charT,traits,Allocator> + operator+(const charT* lhs, + const basic_string<charT,traits,Allocator>& rhs); +V template<class charT, class traits, class Allocator> + basic_string<charT,traits,Allocator> + operator+(charT lhs, const basic_string<charT,traits,Allocator>& rhs); +V template<class charT, class traits, class Allocator> + basic_string<charT,traits,Allocator> + operator+(const basic_string<charT,traits,Allocator>& lhs, + const charT* rhs); +V template<class charT, class traits, class Allocator> + basic_string<charT,traits,Allocator> + operator+(const basic_string<charT,traits,Allocator>& lhs, charT rhs); + +V template<class charT, class traits, class Allocator> + bool operator==(const basic_string<charT,traits,Allocator>& lhs, + const basic_string<charT,traits,Allocator>& rhs); +V template<class charT, class traits, class Allocator> + bool operator==(const charT* lhs, + const basic_string<charT,traits,Allocator>& rhs); +V template<class charT, class traits, class Allocator> + bool operator==(const basic_string<charT,traits,Allocator>& lhs, + const charT* rhs); +V template<class charT, class traits, class Allocator> + bool operator!=(const basic_string<charT,traits,Allocator>& lhs, + const basic_string<charT,traits,Allocator>& rhs); +V template<class charT, class traits, class Allocator> + bool operator!=(const charT* lhs, + const basic_string<charT,traits,Allocator>& rhs); +V template<class charT, class traits, class Allocator> + bool operator!=(const basic_string<charT,traits,Allocator>& lhs, + const charT* rhs); +V template<class charT, class traits, class Allocator> + bool operator< (const basic_string<charT,traits,Allocator>& lhs, + const basic_string<charT,traits,Allocator>& rhs); +V template<class charT, class traits, class Allocator> + bool operator< (const basic_string<charT,traits,Allocator>& lhs, + const charT* rhs); +V template<class charT, class traits, class Allocator> + bool operator< (const charT* lhs, + const basic_string<charT,traits,Allocator>& rhs); +V template<class charT, class traits, class Allocator> + bool operator> (const basic_string<charT,traits,Allocator>& lhs, + const basic_string<charT,traits,Allocator>& rhs); +V template<class charT, class traits, class Allocator> + bool operator> (const basic_string<charT,traits,Allocator>& lhs, + const charT* rhs); +V template<class charT, class traits, class Allocator> + bool operator> (const charT* lhs, + const basic_string<charT,traits,Allocator>& rhs); +V template<class charT, class traits, class Allocator> + bool operator<=(const basic_string<charT,traits,Allocator>& lhs, + const basic_string<charT,traits,Allocator>& rhs); +V template<class charT, class traits, class Allocator> + bool operator<=(const basic_string<charT,traits,Allocator>& lhs, + const charT* rhs); +V template<class charT, class traits, class Allocator> + bool operator<=(const charT* lhs, + const basic_string<charT,traits,Allocator>& rhs); +V template<class charT, class traits, class Allocator> + bool operator>=(const basic_string<charT,traits,Allocator>& lhs, + const basic_string<charT,traits,Allocator>& rhs); +V template<class charT, class traits, class Allocator> + bool operator>=(const basic_string<charT,traits,Allocator>& lhs, + const charT* rhs); +V template<class charT, class traits, class Allocator> + bool operator>=(const charT* lhs, + const basic_string<charT,traits,Allocator>& rhs); + + // _lib.string.special_: +V template<class charT, class traits, class Allocator> + void swap(basic_string<charT,traits,Allocator>& lhs, + basic_string<charT,traits,Allocator>& rhs); +V template<class charT, class traits, class Allocator> + basic_istream<charT,traits>& + operator>>(basic_istream<charT,traits>& is, + basic_string<charT,traits,Allocator>& str); +T template<class charT, class traits, class Allocator> + basic_ostream<charT, traits>& + operator<<(basic_ostream<charT, traits>& os, + const basic_string<charT,traits,Allocator>& str); +V template<class charT, class traits, class Allocator> + basic_istream<charT,traits>& + getline(basic_istream<charT,traits>& is, + basic_string<charT,traits,Allocator>& str, + charT delim); +V template<class charT, class traits, class Allocator> + basic_istream<charT,traits>& + getline(basic_istream<charT,traits>& is, + basic_string<charT,traits,Allocator>& str); +V typedef basic_string<char> string; +T typedef basic_string<wchar_t> wstring; + } + + 21.3 Template class basic_string [lib.basic.string] + +V namespace std { + template<class charT, class traits = char_traits<charT>, + class Allocator = allocator<charT> > + class basic_string { + public: + // types: + typedef traits traits_type; + typedef typename traits::char_type value_type; + typedef Allocator allocator_type; + typedef typename Allocator::size_type size_type; + typedef typename Allocator::difference_type difference_type; + typedef typename Allocator::reference reference; + typedef typename Allocator::const_reference const_reference; + typedef typename Allocator::pointer pointer; + typedef typename Allocator::const_pointer const_pointer; + typedef implementation defined iterator; + typedef implementation defined const_iterator; + typedef std::reverse_iterator<iterator> reverse_iterator; + typedef std::reverse_iterator<const_iterator> const_reverse_iterator; + static const size_type npos = -1; + + // _lib.string.cons_ construct/copy/destroy: +V explicit basic_string(const Allocator& a = Allocator()); +V basic_string(const basic_string& str, size_type pos = 0, + size_type n = npos, const Allocator& a = Allocator()); +V basic_string(const charT* s, + size_type n, const Allocator& a = Allocator()); +V basic_string(const charT* s, const Allocator& a = Allocator()); +V basic_string(size_type n, charT c, const Allocator& a = Allocator()); +V template<class InputIterator> + basic_string(InputIterator begin, InputIterator end, + const Allocator& a = Allocator()); +V ~basic_string(); +V basic_string& operator=(const basic_string& str); +V basic_string& operator=(const charT* s); +V basic_string& operator=(charT c); + // _lib.string.iterators_ iterators: +V iterator begin(); +V const_iterator begin() const; +V iterator end(); +V const_iterator end() const; + +V reverse_iterator rbegin(); +V const_reverse_iterator rbegin() const; +V reverse_iterator rend(); +V const_reverse_iterator rend() const; + // _lib.string.capacity_ capacity: +V size_type size() const; +V size_type length() const; +V size_type max_size() const; +V void resize(size_type n, charT c); +V void resize(size_type n); +V size_type capacity() const; +V void reserve(size_type res_arg = 0); +V void clear(); +V bool empty() const; + // _lib.string.access_ element access: +V const_reference operator[](size_type pos) const; +V reference operator[](size_type pos); +V const_reference at(size_type n) const; +V reference at(size_type n); + // _lib.string.modifiers_ modifiers: +V basic_string& operator+=(const basic_string& str); +V basic_string& operator+=(const charT* s); +V basic_string& operator+=(charT c); +V basic_string& append(const basic_string& str); +V basic_string& append(const basic_string& str, size_type pos, + size_type n); +V basic_string& append(const charT* s, size_type n); +V basic_string& append(const charT* s); +V basic_string& append(size_type n, charT c); +V template<class InputIterator> + basic_string& append(InputIterator first, InputIterator last); +V void push_back(const charT); + +V basic_string& assign(const basic_string&); +V basic_string& assign(const basic_string& str, size_type pos, + size_type n); +V basic_string& assign(const charT* s, size_type n); +V basic_string& assign(const charT* s); +V basic_string& assign(size_type n, charT c); +V template<class InputIterator> + basic_string& assign(InputIterator first, InputIterator last); +V basic_string& insert(size_type pos1, const basic_string& str); +V basic_string& insert(size_type pos1, const basic_string& str, + size_type pos2, size_type n); +V basic_string& insert(size_type pos, const charT* s, size_type n); +V basic_string& insert(size_type pos, const charT* s); +V basic_string& insert(size_type pos, size_type n, charT c); +V iterator insert(iterator p, charT c); +V void insert(iterator p, size_type n, charT c); +V template<class InputIterator> + void insert(iterator p, InputIterator first, InputIterator last); +V basic_string& erase(size_type pos = 0, size_type n = npos); +V iterator erase(iterator position); +V iterator erase(iterator first, iterator last); +V basic_string& replace(size_type pos1, size_type n1, + const basic_string& str); +V basic_string& replace(size_type pos1, size_type n1, + const basic_string& str, + size_type pos2, size_type n2); +V basic_string& replace(size_type pos, size_type n1, const charT* s, + size_type n2); +V basic_string& replace(size_type pos, size_type n1, const charT* s); +V basic_string& replace(size_type pos, size_type n1, size_type n2, + charT c); +V basic_string& replace(iterator i1, iterator i2, const basic_string& str); +V basic_string& replace(iterator i1, iterator i2, const charT* s, + size_type n); +V basic_string& replace(iterator i1, iterator i2, const charT* s); +V basic_string& replace(iterator i1, iterator i2, + size_type n, charT c); +V template<class InputIterator> + basic_string& replace(iterator i1, iterator i2, + InputIterator j1, InputIterator j2); +V size_type copy(charT* s, size_type n, size_type pos = 0) const; +V void swap(basic_string<charT,traits,Allocator>&); + // _lib.string.ops_ string operations: +V const charT* c_str() const; // explicit +V const charT* data() const; +V allocator_type get_allocator() const; +V size_type find (const basic_string& str, size_type pos = 0) const; +V size_type find (const charT* s, size_type pos, size_type n) const; +V size_type find (const charT* s, size_type pos = 0) const; +V size_type find (charT c, size_type pos = 0) const; +V size_type rfind(const basic_string& str, size_type pos = npos) const; +V size_type rfind(const charT* s, size_type pos, size_type n) const; +V size_type rfind(const charT* s, size_type pos = npos) const; +V size_type rfind(charT c, size_type pos = npos) const; + +V size_type find_first_of(const basic_string& str, + size_type pos = 0) const; +V size_type find_first_of(const charT* s, + size_type pos, size_type n) const; +V size_type find_first_of(const charT* s, size_type pos = 0) const; +V size_type find_first_of(charT c, size_type pos = 0) const; +V size_type find_last_of (const basic_string& str, + size_type pos = npos) const; +V size_type find_last_of (const charT* s, + size_type pos, size_type n) const; +V size_type find_last_of (const charT* s, size_type pos = npos) const; +V size_type find_last_of (charT c, size_type pos = npos) const; +V size_type find_first_not_of(const basic_string& str, + size_type pos = 0) const; +V size_type find_first_not_of(const charT* s, size_type pos, + size_type n) const; +V size_type find_first_not_of(const charT* s, size_type pos = 0) const; +V size_type find_first_not_of(charT c, size_type pos = 0) const; +V size_type find_last_not_of (const basic_string& str, + size_type pos = npos) const; +V size_type find_last_not_of (const charT* s, size_type pos, + size_type n) const; +V size_type find_last_not_of (const charT* s, + size_type pos = npos) const; +V size_type find_last_not_of (charT c, size_type pos = npos) const; +V basic_string substr(size_type pos = 0, size_type n = npos) const; +V int compare(const basic_string& str) const; +V int compare(size_type pos1, size_type n1, + const basic_string& str) const; +V int compare(size_type pos1, size_type n1, + const basic_string& str, + size_type pos2, size_type n2) const; +V int compare(const charT* s) const; +V int compare(size_type pos1, size_type n1, + const charT* s, size_type n2 = npos) const; + }; + } + + 21.4 Null-terminated sequence utilities [lib.c.strings] + + Table 10--Header <cctype> synopsis + + isalnum isdigit isprint isupper tolower +X isalpha isgraph ispunct isxdigit toupper + iscntrl islower isspace + + Table 11--Header <cwctype> synopsis + +X Macro: WEOF <cwctype> +X Types: wctrans_t wctype_t wint_t <cwctype> + Functions: +X iswalnum iswctype iswlower iswspace towctrans wctrans +X iswalpha iswdigit iswprint iswupper towlower wctype +X iswcntrl iswgraph iswpunct iswxdigit towupper + + Table 12--Header <cstring> synopsis + +X Macro: NULL <cstring> +X Type: size_t <cstring> + Functions: +X memchr strcat strcspn strncpy strtok +X memcmp strchr strerror strpbrk strxfrm +X memcpy strcmp strlen strrchr +X memmove strcoll strncat strspn +X memset strcpy strncmp strstr + + Table 13--Header <cwchar> synopsis + Macros: NULL <cwchar> WCHAR_MAX WCHAR_MIN WEOF <cwchar> + Types: mbstate_t wint_t <cwchar> size_t + Functions: +X btowc getwchar ungetwc wcscpy wcsrtombs wmemchr +X fgetwc mbrlen vfwprintf wcscspn wcsspn wmemcmp +X fgetws mbrtowc vswprintf wcsftime wcsstr wmemcpy +X fputwc mbsinit vwprintf wcslen wcstod wmemmove +X fputws mbsrtowcs wcrtomb wcsncat wcstok wmemset +X fwide putwc wcscat wcsncmp wcstol wprintf +X fwprintf putwchar wcschr wcsncpy wcstoul wscanf +X fwscanf swprintf wcscmp wcspbrk wcsxfrm +X getwc swscanf wcscoll wcsrchr wctob + + Table 14--Header <cstdlib> synopsis + + Macros: MB_CUR_MAX + Functions: +X atol mblen strtod wctomb +X atof mbstowcs strtol wcstombs +X atoi mbtowc strtoul + +X const char* strchr(const char* s, int c); +X char* strchr( char* s, int c); + +X const char* strpbrk(const char* s1, const char* s2); +X char* strpbrk( char* s1, const char* s2); + +X const char* strrchr(const char* s, int c); +X char* strrchr( char* s, int c); + +X const char* strstr(const char* s1, const char* s2); +X char* strstr( char* s1, const char* s2); + +X const void* memchr(const void* s, int c, size_t n); +X void* memchr( void* s, int c, size_t n); + +X const wchar_t* wcschr(const wchar_t* s, wchar_t c); +X wchar_t* wcschr( wchar_t* s, wchar_t c); + +X const wchar_t* wcspbrk(const wchar_t* s1, const wchar_t* s2); +X wchar_t* wcspbrk( wchar_t* s1, const wchar_t* s2); + +X const wchar_t* wcsrchr(const wchar_t* s, wchar_t c); +X wchar_t* wcsrchr( wchar_t* s, wchar_t c); + +X const wchar_t* wcsstr(const wchar_t* s1, const wchar_t* s2); +X wchar_t* wcsstr( wchar_t* s1, const wchar_t* s2); + +X const wchar_t* wmemchr(const wchar_t* s, wchar_t c, size_t n); +X wchar_t* wmemchr( wchar_t* s, wchar_t c, size_t n); + + [for initial efforts on the above, see shadow/string.h] + + 22.1 Locales [lib.locales] + + Header <locale> synopsis + + // _lib.locale_, locale: +T class locale; +T template <class Facet> const Facet& use_facet(const locale&); +T template <class Facet> bool has_facet(const locale&) throw(); + + // _lib.locale.convenience_, convenience interfaces: +T template <class charT> bool isspace (charT c, const locale& loc); +T template <class charT> bool isprint (charT c, const locale& loc); +T template <class charT> bool iscntrl (charT c, const locale& loc); +T template <class charT> bool isupper (charT c, const locale& loc); +T template <class charT> bool islower (charT c, const locale& loc); +T template <class charT> bool isalpha (charT c, const locale& loc); +T template <class charT> bool isdigit (charT c, const locale& loc); +T template <class charT> bool ispunct (charT c, const locale& loc); +T template <class charT> bool isxdigit(charT c, const locale& loc); +T template <class charT> bool isalnum (charT c, const locale& loc); +T template <class charT> bool isgraph (charT c, const locale& loc); +T template <class charT> charT toupper(charT c, const locale& loc); +T template <class charT> charT tolower(charT c, const locale& loc); + // _lib.category.ctype_ and _lib.facet.ctype.special_, ctype: + class ctype_base; +T template <class charT> class ctype; +T template <> class ctype<char>; // specialization +S template <class charT> class ctype_byname; +S template <> class ctype_byname<char>; // specialization +T class codecvt_base; +X template <class internT, class externT, class stateT> class codecvt; +S template <class internT, class externT, class stateT> class codecvt_byname; + // _lib.category.numeric_ and _lib.facet.numpunct_, numeric: +X template <class charT, class InputIterator> class num_get; +X template <class charT, class OutputIterator> class num_put; +T template <class charT> class numpunct; +S template <class charT> class numpunct_byname; + // _lib.category.collate_, collation: +T template <class charT> class collate; +S template <class charT> class collate_byname; + // _lib.category.time_, date and time: +T class time_base; +S template <class charT, class InputIterator> class time_get; +S template <class charT, class InputIterator> class time_get_byname; +S template <class charT, class OutputIterator> class time_put; +S template <class charT, class OutputIterator> class time_put_byname; + // _lib.category.monetary_, money: +T class money_base; +S template <class charT, class InputIterator> class money_get; +S template <class charT, class OutputIterator> class money_put; +S template <class charT, bool Intl> class moneypunct; +S template <class charT, bool Intl> class moneypunct_byname; + // _lib.category.messages_, message retrieval: +T class messages_base; +S template <class charT> class messages; +S template <class charT> class messages_byname; + + + 22.1.1 Class locale [lib.locale] + +X class locale { + public: + // types: +T class facet; +T class id; +T typedef int category; +T static const category // values assigned here are for exposition only +T none = 0, +T collate = 0x010, ctype = 0x020, +T monetary = 0x040, numeric = 0x080, +T time = 0x100, messages = 0x200, +T all = collate | ctype | monetary | numeric | time | messages; + // construct/copy/destroy: +T locale() throw() +T locale(const locale& other) throw() +X explicit locale(const char* std_name); +X locale(const locale& other, const char* std_name, category); +T template <class Facet> locale(const locale& other, Facet* f); +T locale(const locale& other, const locale& one, category); +T ~locale() throw(); // non-virtual +T const locale& operator=(const locale& other) throw(); +T template <class Facet> locale combine(const locale& other) const; + // locale operations: +X basic_string<char> name() const; +T bool operator==(const locale& other) const; +T bool operator!=(const locale& other) const; +T template <class charT, class Traits, class Allocator> + bool operator()(const basic_string<charT,Traits,Allocator>& s1, + const basic_string<charT,Traits,Allocator>& s2) const; + // global locale objects: +T static locale global(const locale&); +T static const locale& classic(); + }; + + 22.1.1.1 locale types [lib.locale.types] + + 22.1.1.1.1 Type locale::category [lib.locale.category] + +T typedef int category; + +T none, collate, ctype, monetary, numeric, time, and messages + + [required locale members] +T collate<char>, collate<wchar_t> +T ctype<char>, ctype<wchar_t> +T codecvt<char,char,mbstate_t>, +S codecvt<wchar_t,char,mbstate_t> +T moneypunct<char>, moneypunct<wchar_t> +T moneypunct<char,true>, moneypunct<wchar_t,true>, +S money_get<char>, money_get<wchar_t +S money_put<char>, money_put<wchar_t> +T numpunct<char>, numpunct<wchar_t>, +X num_get<char>, num_get<wchar_t> +X num_put<char>, num_put<wchar_t> +S time_get<char>, time_get<wchar_t>, +S time_put<char>, time_put<wchar_t> +S messages<char>, messages<wchar_t> + + [required instantiations] +S collate_byname<char>, collate_byname<wchar_t> +S ctype_byname<char>, ctype_byname<wchar_t> +S codecvt_byname<char,char,mbstate_t>, +S codecvt_byname<wchar_t,char,mbstate_t> +S moneypunct_byname<char,International>, +S moneypunct_byname<wchar_t,International>, +S money_get<C,InputIterator>, +S money_put<C,OutputIterator> +S numpunct_byname<char>, numpunct_byname<wchar_t> +X num_get<C,InputIterator>, num_put<C,OutputIterator> +S time_get<char,InputIterator>, +S time_get_byname<char,InputIterator>, +S time_get<wchar_t,OutputIterator>, +S time_get_byname<wchar_t,OutputIterator>, +S time_put<char,OutputIterator>, +S time_put_byname<char,OutputIterator>, +S time_put<wchar_t,OutputIterator> +S time_put_byname<wchar_t,OutputIterator> +S messages_byname<char>, messages_byname<wchar_t> + + + 22.1.1.1.2 Class locale::facet [lib.locale.facet] + +T class locale::facet { + protected: +T explicit facet(size_t refs = 0); +T virtual ~facet(); + private: +T facet(const facet&); // not defined +T void operator=(const facet&); // not defined + }; + } + + + 22.1.1.1.3 Class locale::id [lib.locale.id] + +T class locale::id { + public: +T id(); + private: +T void operator=(const id&); // not defined +T id(const id&); // not defined + }; + } + + + 22.2.1 The ctype category [lib.category.ctype] + +T class ctype_base { + public: +T enum mask { // numeric values are for exposition only. +T space=, print=, cntrl=, upper=, lower=, +T alpha=, digit=, punct=, xdigit=, +T alnum=, graph= + }; + }; + + + 22.2.1.1 Template class ctype [lib.locale.ctype] + +T template <class charT> + class ctype : public locale::facet, public ctype_base { + public: +T typedef charT char_type; +T explicit ctype(size_t refs = 0); +T bool is(mask m, charT c) const; +T const charT* is(const charT* low, const charT* high, mask* vec) const; +T const charT* scan_is(mask m, + const charT* low, const charT* high) const; +T const charT* scan_not(mask m, + const charT* low, const charT* high) const; +T charT toupper(charT c) const; +T const charT* toupper(charT* low, const charT* high) const; +T charT tolower(charT c) const; +T const charT* tolower(charT* low, const charT* high) const; +T charT widen(char c) const; +T const char* widen(const char* low, const char* high, charT* to) const; +T char narrow(charT c, char dfault) const; +T const charT* narrow(const charT* low, const charT*, char dfault, + char* to) const; +T static locale::id id; + + protected: +T ~ctype(); // virtual +T virtual bool do_is(mask m, charT c) const; +T virtual const charT* do_is(const charT* low, const charT* high, + mask* vec) const; +T virtual const charT* do_scan_is(mask m, + const charT* low, const charT* high) const; +T virtual const charT* do_scan_not(mask m, + const charT* low, const charT* high) const; +T virtual charT do_toupper(charT) const; +T virtual const charT* do_toupper(charT* low, const charT* high) const; +T virtual charT do_tolower(charT) const; +T virtual const charT* do_tolower(charT* low, const charT* high) const; +T virtual charT do_widen(char) const; +T virtual const char* do_widen(const char* low, const char* high, + charT* dest) const; +T virtual char do_narrow(charT, char dfault) const; +T virtual const charT* do_narrow(const charT* low, const charT* high, + char dfault, char* dest) const; + }; + + + 22.2.1.2 Template class ctype_byname [lib.locale.ctype.byname] + +X template <class charT> + class ctype_byname : public ctype<charT> { + public: +T typedef ctype<charT>::mask mask; +S explicit ctype_byname(const char*, size_t refs = 0); + protected: +S ~ctype_byname(); // virtual +S virtual bool do_is(mask m, charT c) const; +S virtual const charT* do_is(const charT* low, const charT* high, + mask* vec) const; +S virtual const char* do_scan_is(mask m, + const charT* low, const charT* high) const; +S virtual const char* do_scan_not(mask m, + const charT* low, const charT* high) const; +S virtual charT do_toupper(charT) const; +S virtual const charT* do_toupper(charT* low, const charT* high) const; +S virtual charT do_tolower(charT) const; +S virtual const charT* do_tolower(charT* low, const charT* high) const; +S virtual charT do_widen(char) const; +S virtual const char* do_widen(const char* low, const char* high, + charT* dest) const; +S virtual char do_narrow(charT, char dfault) const; +S virtual const charT* do_narrow(const charT* low, const charT* high, + char dfault, char* dest) const; + }; + + 22.2.1.3 ctype specializations [lib.facet.ctype.special] + +T template <> class ctype<char> + : public locale::facet, public ctype_base { + public: +T typedef char char_type; +T explicit ctype(const mask* tab = 0, bool del = false, + size_t refs = 0); +T bool is(mask m, char c) const; +T const char* is(const char* low, const char* high, mask* vec) const; +T const char* scan_is (mask m, + const char* low, const char* high) const; +T const char* scan_not(mask m, + const char* low, const char* high) const; +T char toupper(char c) const; +T const char* toupper(char* low, const char* high) const; +T char tolower(char c) const; +T const char* tolower(char* low, const char* high) const; +T char widen(char c) const; +T const char* widen(const char* low, const char* high, char* to) const; +T char narrow(char c, char dfault) const; +T const char* narrow(const char* low, const char* high, char dfault, + char* to) const; +T static locale::id id; +T static const size_t table_size = IMPLEMENTATION_DEFINED; + + protected: +T const mask* table() const throw(); +T static const mask* classic_table() throw(); +T ~ctype(); // virtual +T virtual char do_toupper(char c) const; +T virtual const char* do_toupper(char* low, const char* high) const; +T virtual char do_tolower(char c) const; +T virtual const char* do_tolower(char* low, const char* high) const; + +T virtual char do_widen(char c) const; +T virtual const char* do_widen(const char* low, + const char* high, + char* to) const; +T virtual char do_narrow(char c, char dfault) const; +T virtual const char* do_narrow(const char* low, + const char* high, + char dfault, char* to) const; + }; + + + 22.2.1.4 Class [lib.locale.ctype.byname.special] + ctype_byname<char> + +X template <> class ctype_byname<char> : public ctype<char> { + public: +S explicit ctype_byname(const char*, size_t refs = 0); + protected: +S ~ctype_byname(); // virtual +S virtual char do_toupper(char c) const; +S virtual const char* do_toupper(char* low, const char* high) const; +S virtual char do_tolower(char c) const; +S virtual const char* do_tolower(char* low, const char* high) const; + +S virtual char do_widen(char c) const; +S virtual const char* do_widen(char* low, + const char* high, + char* to) const; +S virtual char do_widen(char c) const; +S virtual const char* do_widen(char* low, const char* high) const; + + }; + + + + 22.2.1.5 Template class codecvt [lib.locale.codecvt] + +T class codecvt_base { + public: +T enum result { ok, partial, error, noconv }; + }; + +T template <class internT, class externT, class stateT> + class codecvt : public locale::facet, public codecvt_base { + public: +T typedef internT intern_type; +T typedef externT extern_type; +T typedef stateT state_type; +T explicit codecvt(size_t refs = 0) +T result out(stateT& state, + const internT* from, const internT* from_end, const internT*& from_next, + externT* to, externT* to_limit, externT*& to_next) const; +T result unshift(stateT& state, + externT* to, externT* to_limit, externT*& to_next) const; +T result in(stateT& state, + const externT* from, const externT* from_end, const externT*& from_next, + internT* to, internT* to_limit, internT*& to_next) const; +T int encoding() const throw(); +T bool always_noconv() const throw(); +T int length(const stateT&, const externT* from, const externT* end, + size_t max) const; +T int max_length() const throw(); +T static locale::id id; + + protected: +T ~codecvt(); // virtual +T virtual result do_out(stateT& state, + const internT* from, const internT* from_end, const internT*& from_next, + externT* to, externT* to_limit, externT*& to_next) const; +T virtual result do_in(stateT& state, +T const externT* from, const externT* from_end, const externT*& from_next, + internT* to, internT* to_limit, internT*& to_next) const; +T virtual result do_unshift(stateT& state, + externT* to, externT* to_limit, externT*& to_next) const; +T virtual int do_encoding() const throw(); +T virtual bool do_always_noconv() const throw(); +T virtual int do_length(const stateT&, const externT* from, + const externT* end, size_t max) const; +T virtual int do_max_length() const throw(); + }; + } + + + 22.2.1.6 Template class [lib.locale.codecvt.byname] + codecvt_byname + +X template <class internT, class externT, class stateT> + class codecvt_byname : public codecvt<internT, externT, stateT> { + public: +S explicit codecvt_byname(const char*, size_t refs = 0); + protected: +S ~codecvt_byname(); // virtual +S virtual result do_out(stateT& state, + const internT* from, const internT* from_end, const internT*& from_next, + externT* to, externT* to_limit, externT*& to_next) const; +S virtual result do_in(stateT& state, + const externT* from, const externT* from_end, const externT*& from_next, + internT* to, internT* to_limit, internT*& to_next) const; +S virtual result do_unshift(stateT& state, + externT* to, externT* to_limit, externT*& to_next) const; +S virtual int do_encoding() const throw(); +S virtual bool do_always_noconv() const throw(); +S virtual int do_length(const stateT&, const externT* from, + const externT* end, size_t max) const; +S virtual result do_unshift(stateT& state, + externT* to, externT* to_limit, externT*& to_next) const; +S virtual int do_max_length() const throw(); + }; + + + 22.2.2.1 Template class num_get [lib.locale.num.get] + +X template <class charT, class InputIterator = istreambuf_iterator<charT> > + class num_get : public locale::facet { + public: +T typedef charT char_type; +T typedef InputIterator iter_type; +T explicit num_get(size_t refs = 0); +T iter_type get(iter_type in, iter_type end, ios_base&, + ios_base::iostate& err, bool& v) const; +T iter_type get(iter_type in, iter_type end, ios_base& , + ios_base::iostate& err, long& v) const; +T iter_type get(iter_type in, iter_type end, ios_base&, + ios_base::iostate& err, unsigned short& v) const; +T iter_type get(iter_type in, iter_type end, ios_base&, + ios_base::iostate& err, unsigned int& v) const; +T iter_type get(iter_type in, iter_type end, ios_base&, + ios_base::iostate& err, unsigned long& v) const; +T iter_type get(iter_type in, iter_type end, ios_base&, + ios_base::iostate& err, float& v) const; +T iter_type get(iter_type in, iter_type end, ios_base&, + ios_base::iostate& err, double& v) const; +T iter_type get(iter_type in, iter_type end, ios_base&, + ios_base::iostate& err, long double& v) const; +T iter_type get(iter_type in, iter_type end, ios_base&, + ios_base::iostate& err, void*& v) const; +T static locale::id id; + + protected: +T ~num_get(); // virtual +T virtual iter_type do_get(iter_type, iter_type, ios_base&, + ios_base::iostate& err, bool& v) const; +S virtual iter_type do_get(iter_type, iter_type, ios_base&, + ios_base::iostate& err, long& v) const; +S virtual iter_type do_get(iter_type, iter_type, ios_base&, + ios_base::iostate& err, unsigned short& v) const; +S virtual iter_type do_get(iter_type, iter_type, ios_base&, + ios_base::iostate& err, unsigned int& v) const; +S virtual iter_type do_get(iter_type, iter_type, ios_base&, + ios_base::iostate& err, unsigned long& v) const; +S virtual iter_type do_get(iter_type, iter_type, ios_base&, + ios_base::iostate& err, float& v) const; +S virtual iter_type do_get(iter_type, iter_type, ios_base&, + ios_base::iostate& err, double& v) const; +S virtual iter_type do_get(iter_type, iter_type, ios_base&, + ios_base::iostate& err, long double& v) const; +S virtual iter_type do_get(iter_type, iter_type, ios_base&, + ios_base::iostate& err, void*& v) const; + }; + + + + 22.2.2.2 Template class num_put [lib.locale.nm.put] + +X template <class charT, class OutputIterator = ostreambuf_iterator<charT> > + class num_put : public locale::facet { + public: +T typedef charT char_type; +T typedef OutputIterator iter_type; +T explicit num_put(size_t refs = 0); +T iter_type put(iter_type s, ios_base& f, char_type fill, bool v) const; +T iter_type put(iter_type s, ios_base& f, char_type fill, long v) const; +T iter_type put(iter_type s, ios_base& f, char_type fill, + unsigned long v) const; +T iter_type put(iter_type s, ios_base& f, char_type fill, + double v) const; +T iter_type put(iter_type s, ios_base& f, char_type fill, + long double v) const; +T iter_type put(iter_type s, ios_base& f, char_type fill, + const void* v) const; +T static locale::id id; + protected: +T ~num_put(); // virtual +T virtual iter_type do_put(iter_type, ios_base&, char_type fill, + bool v) const; +T virtual iter_type do_put(iter_type, ios_base&, char_type fill, + long v) const; +T virtual iter_type do_put(iter_type, ios_base&, char_type fill, + unsigned long) const; +S virtual iter_type do_put(iter_type, ios_base&, char_type fill, + double v) const; +S virtual iter_type do_put(iter_type, ios_base&, char_type fill, + long double v) const; +T virtual iter_type do_put(iter_type, ios_base&, char_type fill, + const void* v) const; + }; + } + + 22.2.3.1 Template class numpunct [lib.locale.numpunct] + +T template <class charT> + class numpunct : public locale::facet { + public: +T typedef charT char_type; +T typedef basic_string<charT> string_type; +T explicit numpunct(size_t refs = 0); +T char_type decimal_point() const; +T char_type thousands_sep() const; +T string grouping() const; +T string_type truename() const; +T string_type falsename() const; +T static locale::id id; + protected: +T ~numpunct(); // virtual +T virtual char_type do_decimal_point() const; +T virtual char_type do_thousands_sep() const; +T virtual string do_grouping() const; +T virtual string_type do_truename() const; // for bool +T virtual string_type do_falsename() const; // for bool + }; + } + + + + 22.2.3.2 Template class [lib.locale.numpunct.byname] + numpunct_byname + +X template <class charT> + class numpunct_byname : public numpunct<charT> { + // this class is specialized for char and wchar_t. + public: +T typedef charT char_type; +T typedef basic_string<charT> string_type; +S explicit numpunct_byname(const char*, size_t refs = 0); + protected: +S ~numpunct_byname(); // virtual +S virtual char_type do_decimal_point() const; +S virtual char_type do_thousands_sep() const; +S virtual string do_grouping() const; +S virtual string_type do_truename() const; // for bool +S virtual string_type do_falsename() const; // for bool + }; + + + 22.2.4.1 Template class collate [lib.locale.collate] + +T template <class charT> + class collate : public locale::facet { + public: +T typedef charT char_type; +T typedef basic_string<charT> string_type; +T explicit collate(size_t refs = 0); +T int compare(const charT* low1, const charT* high1, + const charT* low2, const charT* high2) const; +T string_type transform(const charT* low, const charT* high) const; +T long hash(const charT* low, const charT* high) const; +T static locale::id id; + protected: +T ~collate(); // virtual +T virtual int do_compare(const charT* low1, const charT* high1, + const charT* low2, const charT* high2) const; +T virtual string_type do_transform + (const charT* low, const charT* high) const; +T virtual long do_hash (const charT* low, const charT* high) const; + }; + + + 22.2.4.2 Template class [lib.locale.collate.byname] + collate_byname + +X template <class charT> + class collate_byname : public collate<charT> { + public: +T typedef basic_string<charT> string_type; +T explicit collate_byname(const char*, size_t refs = 0); + protected: +S ~collate_byname(); // virtual +S virtual int do_compare(const charT* low1, const charT* high1, + const charT* low2, const charT* high2) const; +S virtual string_type do_transform + (const charT* low, const charT* high) const; +S virtual long do_hash (const charT* low, const charT* high) const; + }; + + + 22.2.5.1 Template class time_get [lib.locale.time.get] + +T class time_base { + public: +T enum dateorder { no_order, dmy, mdy, ymd, ydm }; + }; + + [Note: semantics of time_get members are implementation-defined. + To complete implementation requires documenting behavior.] + +X template <class charT, class InputIterator = istreambuf_iterator<charT> > + class time_get : public locale::facet, public time_base { + public: +T typedef charT char_type; +T typedef InputIterator iter_type; +T explicit time_get(size_t refs = 0); + +T dateorder date_order() const { return do_date_order(); } +T iter_type get_time(iter_type s, iter_type end, ios_base& f, + ios_base::iostate& err, tm* t) const; +T iter_type get_date(iter_type s, iter_type end, ios_base& f, + ios_base::iostate& err, tm* t) const; +T iter_type get_weekday(iter_type s, iter_type end, ios_base& f, + ios_base::iostate& err, tm* t) const; +T iter_type get_monthname(iter_type s, iter_type end, ios_base& f, + ios_base::iostate& err, tm* t) const; +T iter_type get_year(iter_type s, iter_type end, ios_base& f, + ios_base::iostate& err, tm* t) const; +T static locale::id id; + protected: + ~time_get(); // virtual +X virtual dateorder do_date_order() const; +S virtual iter_type do_get_time(iter_type s, iter_type end, ios_base&, + ios_base::iostate& err, tm* t) const; +S virtual iter_type do_get_date(iter_type s, iter_type end, ios_base&, + ios_base::iostate& err, tm* t) const; +S virtual iter_type do_get_weekday(iter_type s, iter_type end, ios_base&, + ios_base::iostate& err, tm* t) const; +S virtual iter_type do_get_monthname(iter_type s, ios_base&, + ios_base::iostate& err, tm* t) const; +S virtual iter_type do_get_year(iter_type s, iter_type end, ios_base&, + ios_base::iostate& err, tm* t) const; + }; + + + + 22.2.5.2 Template class [lib.locale.time.get.byname] + time_get_byname + +X template <class charT, class InputIterator = istreambuf_iterator<charT> > + class time_get_byname : public time_get<charT, InputIterator> { + public: +T typedef time_base::dateorder dateorder; +T typedef InputIterator iter_type + +S explicit time_get_byname(const char*, size_t refs = 0); + protected: +S ~time_get_byname(); // virtual +S virtual dateorder do_date_order() const; +S virtual iter_type do_get_time(iter_type s, iter_type end, ios_base&, + ios_base::iostate& err, tm* t) const; +S virtual iter_type do_get_date(iter_type s, iter_type end, ios_base&, + ios_base::iostate& err, tm* t) const; +T virtual iter_type do_get_weekday(iter_type s, iter_type end, ios_base&, + ios_base::iostate& err, tm* t) const; +T virtual iter_type do_get_monthname(iter_type s, iter_type end, ios_base&, + ios_base::iostate& err, tm* t) const; +S virtual iter_type do_get_year(iter_type s, iter_type end, ios_base&, + ios_base::iostate& err, tm* t) const; + }; + } + + 22.2.5.3 Template class time_put [lib.locale.time.put] + +X template <class charT, class OutputIterator = ostreambuf_iterator<charT> > + class time_put : public locale::facet { + public: +T typedef charT char_type; +T typedef OutputIterator iter_type; +T explicit time_put(size_t refs = 0); + // the following is implemented in terms of other member functions. +S iter_type put(iter_type s, ios_base& f, char_type fill, const tm* tmb, + const charT* pattern, const charT* pat_end) const; +T iter_type put(iter_type s, ios_base& f, char_type fill, + const tm* tmb, char format, char modifier = 0) const; +T static locale::id id; + protected: +T ~time_put(); // virtual +S virtual iter_type do_put(iter_type s, ios_base&, char_type, const tm* t, + char format, char modifier) const; + }; + + + + 22.2.5.4 Template class [lib.locale.time.put.byname] + time_put_byname + +T template <class charT, class OutputIterator = ostreambuf_iterator<charT> > + class time_put_byname : public time_put<charT, OutputIterator> + { + public: +T typedef charT char_type; +T typedef OutputIterator iter_type; + +T explicit time_put_byname(const char*, size_t refs = 0); + protected: +T ~time_put_byname(); // virtual +S virtual iter_type do_put(iter_type s, ios_base&, char_type, const tm* t, + char format, char modifier) const; + }; + + + 22.2.6.1 Template class money_get [lib.locale.money.get] + +X template <class charT, + class InputIterator = istreambuf_iterator<charT> > + class money_get : public locale::facet { + public: +T typedef charT char_type; +T typedef InputIterator iter_type; +T typedef basic_string<charT> string_type; +T explicit money_get(size_t refs = 0); +T iter_type get(iter_type s, iter_type end, bool intl, + ios_base& f, ios_base::iostate& err, + long double& units) const; +T iter_type get(iter_type s, iter_type end, bool intl, + ios_base& f, ios_base::iostate& err, + string_type& digits) const; +T static locale::id id; + protected: +T ~money_get(); // virtual +S virtual iter_type do_get(iter_type, iter_type, bool, ios_base&, + ios_base::iostate& err, long double& units) const; +S virtual iter_type do_get(iter_type, iter_type, bool, ios_base&, + ios_base::iostate& err, string_type& digits) const; + }; + + 22.2.6.2 Template class money_put [lib.locale.money.put] + +X template <class charT, + class OutputIterator = ostreambuf_iterator<charT> > + class money_put : public locale::facet { + public: +T typedef charT char_type; +T typedef OutputIterator iter_type; +T typedef basic_string<charT> string_type; +T explicit money_put(size_t refs = 0); +T iter_type put(iter_type s, bool intl, ios_base& f, + char_type fill, long double units) const; +T iter_type put(iter_type s, bool intl, ios_base& f, + char_type fill, const string_type& digits) const; +T static locale::id id; + + protected: +T ~money_put(); // virtual +S virtual iter_type + do_put(iter_type, bool, ios_base&, char_type fill, + long double units) const; +S virtual iter_type + do_put(iter_type, bool, ios_base&, char_type fill, + const string_type& digits) const; + }; + + + 22.2.6.3 Template class moneypunct [lib.locale.moneypunct] + +T class money_base { + public: +T enum part { none, space, symbol, sign, value }; +T struct pattern { char field[4]; }; + }; + +X template <class charT, bool International = false> + class moneypunct : public locale::facet, public money_base { + public: +T typedef charT char_type; +T typedef basic_string<charT> string_type; +T explicit moneypunct(size_t refs = 0); +T charT decimal_point() const; +T charT thousands_sep() const; +T string grouping() const; +T string_type curr_symbol() const; +T string_type positive_sign() const; +T string_type negative_sign() const; +T int frac_digits() const; +T pattern pos_format() const; +T pattern neg_format() const; +T static locale::id id; +T static const bool intl = International; + protected: +T ~moneypunct(); // virtual +S virtual charT do_decimal_point() const; +S virtual charT do_thousands_sep() const; +S virtual string do_grouping() const; +S virtual string_type do_curr_symbol() const; +S virtual string_type do_positive_sign() const; +S virtual string_type do_negative_sign() const; +S virtual int do_frac_digits() const; +T virtual pattern do_pos_format() const; +T virtual pattern do_neg_format() const; + }; + } + + 22.2.6.4 Template class [lib.locale.moneypunct.byname] + moneypunct_byname + +X template <class charT, bool Intl = false> + class moneypunct_byname : public moneypunct<charT, Intl> { + public: +T typedef money_base::pattern pattern; +T typedef basic_string<charT> string_type; + +T explicit moneypunct_byname(const char*, size_t refs = 0); + protected: +T ~moneypunct_byname(); // virtual +S virtual charT do_decimal_point() const; +S virtual charT do_thousands_sep() const; +S virtual string do_grouping() const; +S virtual string_type do_curr_symbol() const; +S virtual string_type do_positive_sign() const; +S virtual string_type do_negative_sign() const; +S virtual int do_frac_digits() const; +S virtual pattern do_pos_format() const; +S virtual pattern do_neg_format() const; + }; + + 22.2.7.1 Template class messages [lib.locale.messages] + +T class messages_base { + public: +T typedef int catalog; + }; + +X template <class charT> + class messages : public locale::facet, public messages_base { + public: +T typedef charT char_type; +T typedef basic_string<charT> string_type; +T explicit messages(size_t refs = 0); +T catalog open(const basic_string<char>& fn, const locale&) const; +T string_type get(catalog c, int set, int msgid, + const string_type& dfault) const; +T void close(catalog c) const; +T static locale::id id; + protected: +T ~messages(); // virtual +S virtual catalog do_open(const basic_string<char>&, const locale&) const; +S virtual string_type do_get(catalog, int set, int msgid, + const string_type& dfault) const; +S virtual void do_close(catalog) const; + }; + + 22.2.7.2 Template class [lib.locale.messages.byname] + messages_byname + + +X template <class charT> + class messages_byname : public messages<charT> { + public: +T typedef messages_base::catalog catalog; +T typedef basic_string<charT> string_type; + +T explicit messages_byname(const char*, size_t refs = 0); + protected: +T ~messages_byname(); // virtual +S virtual catalog do_open(const basic_string<char>&, const locale&) const; +S virtual string_type do_get(catalog, int set, int msgid, + const string_type& dfault) const; +S virtual void do_close(catalog) const; + }; + + + 22.3 C Library Locales [lib.c.locales] + + + Table 13--Header <clocale> synopsis + Macros: +X LC_ALL LC_COLLATE LC_CTYPE +X LC_MONETARY LC_NUMERIC LC_TIME +X NULL +X Struct: lconv +X Functions: localeconv setlocale + + + 23.2 Sequences [lib.sequences] + + <deque>, <list>, <queue>, <stack>, and <vector>. + + Header <deque> synopsis + +T template <class T, class Allocator = allocator<T> > class deque; +T template <class T, class Allocator> + bool operator==(const deque<T,Allocator>& x, const deque<T,Allocator>& y); +T template <class T, class Allocator> + bool operator< (const deque<T,Allocator>& x, const deque<T,Allocator>& y); +T template <class T, class Allocator> + bool operator!=(const deque<T,Allocator>& x, const deque<T,Allocator>& y); +T template <class T, class Allocator> + bool operator> (const deque<T,Allocator>& x, const deque<T,Allocator>& y); +T template <class T, class Allocator> + bool operator>=(const deque<T,Allocator>& x, const deque<T,Allocator>& y); +T template <class T, class Allocator> + bool operator<=(const deque<T,Allocator>& x, const deque<T,Allocator>& y); +T template <class T, class Allocator> + void swap(deque<T,Allocator>& x, deque<T,Allocator>& y); + } + + Header <list> synopsis + +T template <class T, class Allocator = allocator<T> > class list; +T template <class T, class Allocator> + bool operator==(const list<T,Allocator>& x, const list<T,Allocator>& y); +T template <class T, class Allocator> + bool operator< (const list<T,Allocator>& x, const list<T,Allocator>& y); +T template <class T, class Allocator> + bool operator!=(const list<T,Allocator>& x, const list<T,Allocator>& y); +T template <class T, class Allocator> + bool operator> (const list<T,Allocator>& x, const list<T,Allocator>& y); +T template <class T, class Allocator> + bool operator>=(const list<T,Allocator>& x, const list<T,Allocator>& y); +T template <class T, class Allocator> + bool operator<=(const list<T,Allocator>& x, const list<T,Allocator>& y); +T template <class T, class Allocator> + void swap(list<T,Allocator>& x, list<T,Allocator>& y); + } + + Header <queue> synopsis + + namespace std { +T template <class T, class Container = deque<T> > class queue; +T template <class T, class Container> + bool operator==(const queue<T, Container>& x, + const queue<T, Container>& y); +T template <class T, class Container> + bool operator< (const queue<T, Container>& x, + const queue<T, Container>& y); +T template <class T, class Container> + bool operator!=(const queue<T, Container>& x, + const queue<T, Container>& y); +T template <class T, class Container> + bool operator> (const queue<T, Container>& x, + const queue<T, Container>& y); +T template <class T, class Container> + bool operator>=(const queue<T, Container>& x, + const queue<T, Container>& y); +T template <class T, class Container> + bool operator<=(const queue<T, Container>& x, + const queue<T, Container>& y); +T template <class T, class Container = vector<T>, + class Compare = less<typename Container::value_type> > +T class priority_queue; + } + + Header <stack> synopsis + + namespace std { +T template <class T, class Container = deque<T> > class stack; +T template <class T, class Container> + bool operator==(const stack<T, Container>& x, + const stack<T, Container>& y); +T template <class T, class Container> + bool operator< (const stack<T, Container>& x, + const stack<T, Container>& y); +T template <class T, class Container> + bool operator!=(const stack<T, Container>& x, + const stack<T, Container>& y); +T template <class T, class Container> + bool operator> (const stack<T, Container>& x, + const stack<T, Container>& y); +T template <class T, class Container> + bool operator>=(const stack<T, Container>& x, + const stack<T, Container>& y); +T template <class T, class Container> + bool operator<=(const stack<T, Container>& x, + const stack<T, Container>& y); + } + + Header <vector> synopsis + +T template <class T, class Allocator = allocator<T> > class vector; + +T template <class T, class Allocator> + bool operator==(const vector<T,Allocator>& x, + const vector<T,Allocator>& y); +T template <class T, class Allocator> + bool operator< (const vector<T,Allocator>& x, + const vector<T,Allocator>& y); +T template <class T, class Allocator> + bool operator!=(const vector<T,Allocator>& x, + const vector<T,Allocator>& y); +T template <class T, class Allocator> + bool operator> (const vector<T,Allocator>& x, + const vector<T,Allocator>& y); +T template <class T, class Allocator> + bool operator>=(const vector<T,Allocator>& x, + const vector<T,Allocator>& y); +T template <class T, class Allocator> + bool operator<=(const vector<T,Allocator>& x, + const vector<T,Allocator>& y); +T template <class T, class Allocator> + void swap(vector<T,Allocator>& x, vector<T,Allocator>& y); + +T template <class Allocator> class vector<bool,Allocator>; +T template <class Allocator> + bool operator==(const vector<bool,Allocator>& x, + const vector<bool,Allocator>& y); +T template <class Allocator> + bool operator< (const vector<bool,Allocator>& x, + const vector<bool,Allocator>& y); +T template <class Allocator> + bool operator!=(const vector<bool,Allocator>& x, + const vector<bool,Allocator>& y); +T template <class Allocator> + bool operator> (const vector<bool,Allocator>& x, + const vector<bool,Allocator>& y); +T template <class Allocator> + bool operator>=(const vector<bool,Allocator>& x, + const vector<bool,Allocator>& y); +T template <class Allocator> + bool operator<=(const vector<bool,Allocator>& x, + const vector<bool,Allocator>& y); +T template <class Allocator> + void swap(vector<bool,Allocator>& x, vector<bool,Allocator>& y); + } + + 23.2.1 Template class deque [lib.deque] + + template <class T, class Allocator = allocator<T> > +T class deque { + public: + // types: +T typedef typename Allocator::reference reference; +T typedef typename Allocator::const_reference const_reference; +T typedef implementation defined iterator; +T typedef implementation defined const_iterator; +T typedef implementation defined size_type; +T typedef implementation defined difference_type; +T typedef T value_type; +T typedef Allocator allocator_type; +T typedef typename Allocator::pointer pointer; +T typedef typename Allocator::const_pointer const_pointer; +T typedef std::reverse_iterator<iterator> reverse_iterator; +T typedef std::reverse_iterator<const_iterator> const_reverse_iterator; + // _lib.deque.cons_ construct/copy/destroy: +T explicit deque(const Allocator& = Allocator()); +T explicit deque(size_type n, const T& value = T(), + const Allocator& = Allocator()); +T template <class InputIterator> + deque(InputIterator first, InputIterator last, + const Allocator& = Allocator()); +T deque(const deque<T,Allocator>& x); +T ~deque(); +T deque<T,Allocator>& operator=(const deque<T,Allocator>& x); +T template <class InputIterator> + void assign(InputIterator first, InputIterator last); +T void assign(size_type n, const T& t); +T allocator_type get_allocator() const; + // iterators: +T iterator begin(); +T const_iterator begin() const; +T iterator end(); +T const_iterator end() const; +T reverse_iterator rbegin(); +T const_reverse_iterator rbegin() const; +T reverse_iterator rend(); +T const_reverse_iterator rend() const; + // _lib.deque.capacity_ capacity: +T size_type size() const; +T size_type max_size() const; +T void resize(size_type sz, T c = T()); +T bool empty() const; + + // element access: +T reference operator[](size_type n); +T const_reference operator[](size_type n) const; +T reference at(size_type n); +T const_reference at(size_type n) const; +T reference front(); +T const_reference front() const; +T reference back(); +T const_reference back() const; + // _lib.deque.modifiers_ modifiers: +T void push_front(const T& x); +T void push_back(const T& x); +T iterator insert(iterator position, const T& x); +T void insert(iterator position, size_type n, const T& x); +T template <class InputIterator> + void insert (iterator position, + InputIterator first, InputIterator last); +T void pop_front(); +T void pop_back(); +T iterator erase(iterator position); +T iterator erase(iterator first, iterator last); +T void swap(deque<T,Allocator>&); +T void clear(); + }; +T template <class T, class Allocator> + bool operator==(const deque<T,Allocator>& x, + const deque<T,Allocator>& y); +T template <class T, class Allocator> + bool operator< (const deque<T,Allocator>& x, + const deque<T,Allocator>& y); +T template <class T, class Allocator> + bool operator!=(const deque<T,Allocator>& x, + const deque<T,Allocator>& y); +T template <class T, class Allocator> + bool operator> (const deque<T,Allocator>& x, + const deque<T,Allocator>& y); +T template <class T, class Allocator> + bool operator>=(const deque<T,Allocator>& x, + const deque<T,Allocator>& y); +T template <class T, class Allocator> + bool operator<=(const deque<T,Allocator>& x, + const deque<T,Allocator>& y); + // specialized algorithms: +T template <class T, class Allocator> + void swap(deque<T,Allocator>& x, deque<T,Allocator>& y); + + + 23.2.2 Template class list [lib.list] + +T template <class T, class Allocator = allocator<T> > + class list { + public: + // types: +T typedef typename Allocator::reference reference; +T typedef typename Allocator::const_reference const_reference; +T typedef implementation defined iterator; +T typedef implementation defined const_iterator; +T typedef implementation defined size_type; +T typedef implementation defined difference_type; +T typedef T value_type; +T typedef Allocator allocator_type; +T typedef typename Allocator::pointer pointer; +T typedef typename Allocator::const_pointer const_pointer; +T typedef std::reverse_iterator<iterator> reverse_iterator; +T typedef std::reverse_iterator<const_iterator> const_reverse_iterator; + + // _lib.list.cons_ construct/copy/destroy: +T explicit list(const Allocator& = Allocator()); +T explicit list(size_type n, const T& value = T(), + const Allocator& = Allocator()); +T template <class InputIterator> + list(InputIterator first, InputIterator last, + const Allocator& = Allocator()); +T list(const list<T,Allocator>& x); +T ~list(); +T list<T,Allocator>& operator=(const list<T,Allocator>& x); +T template <class InputIterator> + void assign(InputIterator first, InputIterator last); +T void assign(size_type n, const T& t); +T allocator_type get_allocator() const; + // iterators: +T iterator begin(); +T const_iterator begin() const; +T iterator end(); +T const_iterator end() const; +T reverse_iterator rbegin(); +T const_reverse_iterator rbegin() const; +T reverse_iterator rend(); +T const_reverse_iterator rend() const; + // _lib.list.capacity_ capacity: +T bool empty() const; +T size_type size() const; +T size_type max_size() const; +T void resize(size_type sz, T c = T()); + // element access: +T reference front(); +T const_reference front() const; +T reference back(); +T const_reference back() const; + // _lib.list.modifiers_ modifiers: +T void push_front(const T& x); +T void pop_front(); +T void push_back(const T& x); +T void pop_back(); +T iterator insert(iterator position, const T& x); +T void insert(iterator position, size_type n, const T& x); +T template <class InputIterator> + void insert(iterator position, InputIterator first, + InputIterator last); +T iterator erase(iterator position); +T iterator erase(iterator position, iterator last); +T void swap(list<T,Allocator>&); +T void clear(); + // _lib.list.ops_ list operations: +T void splice(iterator position, list<T,Allocator>& x); +T void splice(iterator position, list<T,Allocator>& x, iterator i); +T void splice(iterator position, list<T,Allocator>& x, iterator first, + iterator last); +T void remove(const T& value); +T template <class Predicate> void remove_if(Predicate pred); + +T void unique(); +T template <class BinaryPredicate> + void unique(BinaryPredicate binary_pred); +T void merge(list<T,Allocator>& x); +T template <class Compare> void merge(list<T,Allocator>& x, Compare comp); + void sort(); +T template <class Compare> void sort(Compare comp); + void reverse(); + }; +T template <class T, class Allocator> + bool operator==(const list<T,Allocator>& x, const list<T,Allocator>& y); +T template <class T, class Allocator> + bool operator< (const list<T,Allocator>& x, const list<T,Allocator>& y); +T template <class T, class Allocator> + bool operator!=(const list<T,Allocator>& x, const list<T,Allocator>& y); +T template <class T, class Allocator> + bool operator> (const list<T,Allocator>& x, const list<T,Allocator>& y); +T template <class T, class Allocator> + bool operator>=(const list<T,Allocator>& x, const list<T,Allocator>& y); +T template <class T, class Allocator> + bool operator<=(const list<T,Allocator>& x, const list<T,Allocator>& y); + // specialized algorithms: +T template <class T, class Allocator> + void swap(list<T,Allocator>& x, list<T,Allocator>& y); + + + 23.2.3.1 Template class queue [lib.queue] + +T template <class T, class Container = deque<T> > + class queue { + public: +T typedef typename Container::value_type value_type; +T typedef typename Container::size_type size_type; +T typedef Container container_type; + protected: +T Container c; + public: +T explicit queue(const Container& = Container()); + +T bool empty() const { return c.empty(); } +T size_type size() const { return c.size(); } +T value_type& front() { return c.front(); } +T const value_type& front() const { return c.front(); } +T value_type& back() { return c.back(); } +T const value_type& back() const { return c.back(); } +T void push(const value_type& x) { c.push_back(x); } +T void pop() { c.pop_front(); } + }; + +T template <class T, class Container> + bool operator==(const queue<T, Container>& x, + const queue<T, Container>& y); +T template <class T, class Container> + bool operator< (const queue<T, Container>& x, + const queue<T, Container>& y); +T template <class T, class Container> + bool operator!=(const queue<T, Container>& x, + const queue<T, Container>& y); +T template <class T, class Container> + bool operator> (const queue<T, Container>& x, + const queue<T, Container>& y); +T template <class T, class Container> + bool operator>=(const queue<T, Container>& x, + const queue<T, Container>& y); +T template <class T, class Container> + bool operator<=(const queue<T, Container>& x, + const queue<T, Container>& y); + + 23.2.3.2 Template class priority_queue [lib.priority.queue] + +T template <class T, class Container = vector<T>, + class Compare = less<typename Container::value_type> > + class priority_queue { + public: +T typedef typename Container::value_type value_type; +T typedef typename Container::size_type size_type; +T typedef Container container_type; + protected: +T Container c; +T Compare comp; + public: +T explicit priority_queue(const Compare& x = Compare(), + const Container& = Container()); +T template <class InputIterator> + priority_queue(InputIterator first, InputIterator last, + const Compare& x = Compare(), + const Container& = Container()); + +T bool empty() const { return c.empty(); } +T size_type size() const { return c.size(); } +T const value_type& top() const { return c.front(); } +T void push(const value_type& x); +T void pop(); + }; + + 23.2.3.3 Template class stack [lib.stack] + +T template <class T, class Container = deque<T> > + class stack { + public: +T typedef typename Container::value_type value_type; +T typedef typename Container::size_type size_type; +T typedef Container container_type; + protected: +T Container c; + public: +T explicit stack(const Container& = Container()); + +T bool empty() const { return c.empty(); } +T size_type size() const { return c.size(); } +T value_type& top() { return c.back(); } +T const value_type& top() const { return c.back(); } +T void push(const value_type& x) { c.push_back(x); } +T void pop() { c.pop_back(); } + }; +T template <class T, class Container> + bool operator==(const stack<T, Container>& x, + const stack<T, Container>& y); +T template <class T, class Container> + bool operator< (const stack<T, Container>& x, + const stack<T, Container>& y); +T template <class T, class Container> + bool operator!=(const stack<T, Container>& x, + const stack<T, Container>& y); +T template <class T, class Container> + bool operator> (const stack<T, Container>& x, + const stack<T, Container>& y); +T template <class T, class Container> + bool operator>=(const stack<T, Container>& x, + const stack<T, Container>& y); +T template <class T, class Container> + bool operator<=(const stack<T, Container>& x, + const stack<T, Container>& y); + + 23.2.4 Template class vector [lib.vector] + + template <class T, class Allocator = allocator<T> > +T class vector { + public: + // types: +T typedef typename Allocator::reference reference; +T typedef typename Allocator::const_reference const_reference; +T typedef implementation defined iterator; +T typedef implementation defined const_iterator; +T typedef implementation defined size_type; +T typedef implementation defined difference_type; +T typedef T value_type; +T typedef Allocator allocator_type; +T typedef typename Allocator::pointer pointer; +T typedef typename Allocator::const_pointer const_pointer +T typedef std::reverse_iterator<iterator> reverse_iterator; +T typedef std::reverse_iterator<const_iterator> const_reverse_iterator; + // _lib.vector.cons_ construct/copy/destroy: +T explicit vector(const Allocator& = Allocator()); +T explicit vector(size_type n, const T& value = T(), + const Allocator& = Allocator()); +T template <class InputIterator> + vector(InputIterator first, InputIterator last, + const Allocator& = Allocator()); +T vector(const vector<T,Allocator>& x); +T ~vector(); +T vector<T,Allocator>& operator=(const vector<T,Allocator>& x); +T template <class InputIterator> + void assign(InputIterator first, InputIterator last); +T void assign(size_type n, const T& u); +T allocator_type get_allocator() const; + // iterators: +T iterator begin(); +T const_iterator begin() const; +T iterator end(); +T const_iterator end() const; +T reverse_iterator rbegin(); +T const_reverse_iterator rbegin() const; +T reverse_iterator rend(); +T const_reverse_iterator rend() const; + // _lib.vector.capacity_ capacity: +T size_type size() const; +T size_type max_size() const; +T void resize(size_type sz, T c = T()); +T size_type capacity() const; +T bool empty() const; +T void reserve(size_type n); + + // element access: +T reference operator[](size_type n); +T const_reference operator[](size_type n) const; +T const_reference at(size_type n) const; +T reference at(size_type n); +T reference front(); +T const_reference front() const; +T reference back(); +T const_reference back() const; + // _lib.vector.modifiers_ modifiers: +T void push_back(const T& x); +T void pop_back(); +T iterator insert(iterator position, const T& x); +T void insert(iterator position, size_type n, const T& x); +T template <class InputIterator> + void insert(iterator position, + InputIterator first, InputIterator last); +T iterator erase(iterator position); +T iterator erase(iterator first, iterator last); +T void swap(vector<T,Allocator>&); +T void clear(); + }; + +T template <class T, class Allocator> + bool operator==(const vector<T,Allocator>& x, + const vector<T,Allocator>& y); +T template <class T, class Allocator> + bool operator< (const vector<T,Allocator>& x, + const vector<T,Allocator>& y); +T template <class T, class Allocator> + bool operator!=(const vector<T,Allocator>& x, + const vector<T,Allocator>& y); +T template <class T, class Allocator> + bool operator> (const vector<T,Allocator>& x, + const vector<T,Allocator>& y); +T template <class T, class Allocator> + bool operator>=(const vector<T,Allocator>& x, + const vector<T,Allocator>& y); +T template <class T, class Allocator> + bool operator<=(const vector<T,Allocator>& x, + const vector<T,Allocator>& y); + // specialized algorithms: +T template <class T, class Allocator> + void swap(vector<T,Allocator>& x, vector<T,Allocator>& y); + + + 23.2.5 Class vector<bool> [lib.vector.bool] + +T template <class Allocator> class vector<bool, Allocator> { + public: + // types: +T typedef bool const_reference; +T typedef implementation defined iterator; +T typedef implementation defined const_iterator; +T typedef implementation defined size_type; +T typedef implementation defined difference_type; +T typedef bool value_type; +T typedef Allocator allocator_type; +T typedef implementation defined pointer; +T typedef implementation defined const_pointer +T typedef std::reverse_iterator<iterator> reverse_iterator; +T typedef std::reverse_iterator<const_iterator> const_reverse_iterator; + // bit reference: +T class reference { + friend class vector; +T reference(); + public: +T ~reference(); +T operator bool() const; +T reference& operator=(const bool x); +T reference& operator=(const reference& x); +T void flip(); // flips the bit + }; + + // construct/copy/destroy: +T explicit vector(const Allocator& = Allocator()); +T explicit vector(size_type n, const bool& value = bool(), + const Allocator& = Allocator()); +T template <class InputIterator> + vector(InputIterator first, InputIterator last, + const Allocator& = Allocator()); +T vector(const vector<bool,Allocator>& x); +T ~vector(); +T vector<bool,Allocator>& operator=(const vector<bool,Allocator>& x); +T template <class InputIterator> + void assign(InputIterator first, InputIterator last); +T void assign(size_type n, const T& t); +T allocator_type get_allocator() const; + // iterators: +T iterator begin(); +T const_iterator begin() const; +T iterator end(); +T const_iterator end() const; +T reverse_iterator rbegin(); +T const_reverse_iterator rbegin() const; +T reverse_iterator rend(); +T const_reverse_iterator rend() const; + // capacity: +T size_type size() const; +T size_type max_size() const; +T void resize(size_type sz, bool c = false); +T size_type capacity() const; +T bool empty() const; +T void reserve(size_type n); + // element access: +T reference operator[](size_type n); +T const_reference operator[](size_type n) const; +T const_reference at(size_type n) const; +T reference at(size_type n); +T reference front(); +T const_reference front() const; +T reference back(); +T const_reference back() const; + // modifiers: +T void push_back(const bool& x); +T void pop_back(); +T iterator insert(iterator position, const bool& x); +T void insert (iterator position, size_type n, const bool& x); +T template <class InputIterator> + void insert(iterator position, + InputIterator first, InputIterator last); +T iterator erase(iterator position); +T iterator erase(iterator first, iterator last); +T void swap(vector<bool,Allocator>&); +T static void swap(reference x, reference y); +T void flip(); // flips all bits +T void clear(); + }; + +T template <class Allocator> + bool operator==(const vector<bool,Allocator>& x, + const vector<bool,Allocator>& y); +T template <class Allocator> + bool operator< (const vector<bool,Allocator>& x, + const vector<bool,Allocator>& y); +T template <class Allocator> + bool operator!=(const vector<bool,Allocator>& x, + const vector<bool,Allocator>& y); +T template <class Allocator> + bool operator> (const vector<bool,Allocator>& x, + const vector<bool,Allocator>& y); +T template <class Allocator> + bool operator>=(const vector<bool,Allocator>& x, + const vector<bool,Allocator>& y); +T template <class Allocator> + bool operator<=(const vector<bool,Allocator>& x, + const vector<bool,Allocator>& y); + // specialized algorithms: +T template <class Allocator> + void swap(vector<bool,Allocator>& x, vector<bool,Allocator>& y); + + 23.3 Associative containers [lib.associative] + + <map> and <set>: + + Header <map> synopsis + + template <class Key, class T, class Compare = less<Key>, + class Allocator = allocator<pair<const Key, T> > > +T class map; + +T template <class Key, class T, class Compare, class Allocator> + bool operator==(const map<Key,T,Compare,Allocator>& x, + const map<Key,T,Compare,Allocator>& y); +T template <class Key, class T, class Compare, class Allocator> + bool operator< (const map<Key,T,Compare,Allocator>& x, + const map<Key,T,Compare,Allocator>& y); +T template <class Key, class T, class Compare, class Allocator> + bool operator!=(const map<Key,T,Compare,Allocator>& x, + const map<Key,T,Compare,Allocator>& y); +T template <class Key, class T, class Compare, class Allocator> + bool operator> (const map<Key,T,Compare,Allocator>& x, + const map<Key,T,Compare,Allocator>& y); +T template <class Key, class T, class Compare, class Allocator> + bool operator>=(const map<Key,T,Compare,Allocator>& x, + const map<Key,T,Compare,Allocator>& y); +T template <class Key, class T, class Compare, class Allocator> + bool operator<=(const map<Key,T,Compare,Allocator>& x, + const map<Key,T,Compare,Allocator>& y); +T template <class Key, class T, class Compare, class Allocator> + void swap(map<Key,T,Compare,Allocator>& x, + map<Key,T,Compare,Allocator>& y); +T template <class Key, class T, class Compare = less<Key>, + class Allocator = allocator<pair<const Key, T> > > + class multimap; +T template <class Key, class T, class Compare, class Allocator> + bool operator==(const multimap<Key,T,Compare,Allocator>& x, + const multimap<Key,T,Compare,Allocator>& y); +T template <class Key, class T, class Compare, class Allocator> + bool operator< (const multimap<Key,T,Compare,Allocator>& x, + const multimap<Key,T,Compare,Allocator>& y); +T template <class Key, class T, class Compare, class Allocator> + bool operator!=(const multimap<Key,T,Compare,Allocator>& x, + const multimap<Key,T,Compare,Allocator>& y); +T template <class Key, class T, class Compare, class Allocator> + bool operator> (const multimap<Key,T,Compare,Allocator>& x, + const multimap<Key,T,Compare,Allocator>& y); +T template <class Key, class T, class Compare, class Allocator> + bool operator>=(const multimap<Key,T,Compare,Allocator>& x, + const multimap<Key,T,Compare,Allocator>& y); +T template <class Key, class T, class Compare, class Allocator> + bool operator<=(const multimap<Key,T,Compare,Allocator>& x, + const multimap<Key,T,Compare,Allocator>& y); +T template <class Key, class T, class Compare, class Allocator> + void swap(multimap<Key,T,Compare,Allocator>& x, + multimap<Key,T,Compare,Allocator>& y); + } + + Header <set> synopsis + + template <class Key, class Compare = less<Key>, + class Allocator = allocator<Key> > +T class set; + +T template <class Key, class Compare, class Allocator> + bool operator==(const set<Key,Compare,Allocator>& x, + const set<Key,Compare,Allocator>& y); +T template <class Key, class Compare, class Allocator> + bool operator< (const set<Key,Compare,Allocator>& x, + const set<Key,Compare,Allocator>& y); +T template <class Key, class Compare, class Allocator> + bool operator!=(const set<Key,Compare,Allocator>& x, + const set<Key,Compare,Allocator>& y); +T template <class Key, class Compare, class Allocator> + bool operator> (const set<Key,Compare,Allocator>& x, + const set<Key,Compare,Allocator>& y); +T template <class Key, class Compare, class Allocator> + bool operator>=(const set<Key,Compare,Allocator>& x, + const set<Key,Compare,Allocator>& y); +T template <class Key, class Compare, class Allocator> + bool operator<=(const set<Key,Compare,Allocator>& x, + const set<Key,Compare,Allocator>& y); +T template <class Key, class Compare, class Allocator> + void swap(set<Key,Compare,Allocator>& x, + set<Key,Compare,Allocator>& y); +T template <class Key, class Compare = less<Key>, + class Allocator = allocator<Key> > + class multiset; +T template <class Key, class Compare, class Allocator> + bool operator==(const multiset<Key,Compare,Allocator>& x, + const multiset<Key,Compare,Allocator>& y); +T template <class Key, class Compare, class Allocator> + bool operator< (const multiset<Key,Compare,Allocator>& x, + const multiset<Key,Compare,Allocator>& y); +T template <class Key, class Compare, class Allocator> + bool operator!=(const multiset<Key,Compare,Allocator>& x, + const multiset<Key,Compare,Allocator>& y); +T template <class Key, class Compare, class Allocator> + bool operator> (const multiset<Key,Compare,Allocator>& x, + const multiset<Key,Compare,Allocator>& y); +T template <class Key, class Compare, class Allocator> + bool operator>=(const multiset<Key,Compare,Allocator>& x, + const multiset<Key,Compare,Allocator>& y); +T template <class Key, class Compare, class Allocator> + bool operator<=(const multiset<Key,Compare,Allocator>& x, + const multiset<Key,Compare,Allocator>& y); +T template <class Key, class Compare, class Allocator> + void swap(multiset<Key,Compare,Allocator>& x, + multiset<Key,Compare,Allocator>& y); + } + + 23.3.1 Template class map [lib.map] + + template <class Key, class T, class Compare = less<Key>, + class Allocator = allocator<pair<const Key, T> > > +T class map { + public: + // types: +T typedef Key key_type; +T typedef T mapped_type; +T typedef pair<const Key, T> value_type; +T typedef Compare key_compare; +T typedef Allocator allocator_type; +T typedef typename Allocator::reference reference; +T typedef typename Allocator::const_reference const_reference; +T typedef implementation defined iterator; +T typedef implementation defined const_iterator; +T typedef implementation defined size_type; +T typedef implementation defined difference_type; +T typedef typename Allocator::pointer pointer; +T typedef typename Allocator::const_pointer const_pointer; +T typedef std::reverse_iterator<iterator> reverse_iterator; +T typedef std::reverse_iterator<const_iterator> const_reverse_iterator; +T class value_compare + : public binary_function<value_type,value_type,bool> { + friend class map; + protected: +T Compare comp; +T value_compare(Compare c) : comp(c) {} + public: +T bool operator()(const value_type& x, const value_type& y) const { + return comp(x.first, y.first); + } + }; + + // _lib.map.cons_ construct/copy/destroy: +T explicit map(const Compare& comp = Compare(), + const Allocator& = Allocator()); +T template <class InputIterator> + map(InputIterator first, InputIterator last, + const Compare& comp = Compare(), const Allocator& = Allocator()); +T map(const map<Key,T,Compare,Allocator>& x); +T ~map(); +T map<Key,T,Compare,Allocator>& + operator=(const map<Key,T,Compare,Allocator>& x); + // iterators: +T iterator begin(); +T const_iterator begin() const; +T iterator end(); +T const_iterator end() const; +T reverse_iterator rbegin(); +T const_reverse_iterator rbegin() const; +T reverse_iterator rend(); +T const_reverse_iterator rend() const; + // capacity: +T bool empty() const; +T size_type size() const; +T size_type max_size() const; + // _lib.map.access_ element access: +T T& operator[](const key_type& x); + // modifiers: +T pair<iterator, bool> insert(const value_type& x); +T iterator insert(iterator position, const value_type& x); +T template <class InputIterator> + void insert(InputIterator first, InputIterator last); +T void erase(iterator position); +T size_type erase(const key_type& x); +T void erase(iterator first, iterator last); +T void swap(map<Key,T,Compare,Allocator>&); +T void clear(); + // observers: +T key_compare key_comp() const; +T value_compare value_comp() const; + // _lib.map.ops_ map operations: +T iterator find(const key_type& x); +T const_iterator find(const key_type& x) const; +T size_type count(const key_type& x) const; +T iterator lower_bound(const key_type& x); +T const_iterator lower_bound(const key_type& x) const; +T iterator upper_bound(const key_type& x); +T const_iterator upper_bound(const key_type& x) const; +T pair<iterator,iterator> + equal_range(const key_type& x); +T pair<const_iterator,const_iterator> + equal_range(const key_type& x) const; + }; + +T template <class Key, class T, class Compare, class Allocator> + bool operator==(const map<Key,T,Compare,Allocator>& x, + const map<Key,T,Compare,Allocator>& y); +T template <class Key, class T, class Compare, class Allocator> + bool operator< (const map<Key,T,Compare,Allocator>& x, + const map<Key,T,Compare,Allocator>& y); +T template <class Key, class T, class Compare, class Allocator> + bool operator!=(const map<Key,T,Compare,Allocator>& x, + const map<Key,T,Compare,Allocator>& y); +T template <class Key, class T, class Compare, class Allocator> + bool operator> (const map<Key,T,Compare,Allocator>& x, + const map<Key,T,Compare,Allocator>& y); +T template <class Key, class T, class Compare, class Allocator> + bool operator>=(const map<Key,T,Compare,Allocator>& x, + const map<Key,T,Compare,Allocator>& y); +T template <class Key, class T, class Compare, class Allocator> + bool operator<=(const map<Key,T,Compare,Allocator>& x, + const map<Key,T,Compare,Allocator>& y); + // specialized algorithms: +T template <class Key, class T, class Compare, class Allocator> + void swap(map<Key,T,Compare,Allocator>& x, + map<Key,T,Compare,Allocator>& y); + + 23.3.2 Template class multimap [lib.multimap] + + template <class Key, class T, class Compare = less<Key>, + class Allocator = allocator<pair<const Key, T> > > +T class multimap { + public: + // types: +T typedef Key key_type; +T typedef T mapped_type; +T typedef pair<const Key,T> value_type; +T typedef Compare key_compare; +T typedef Allocator allocator_type; +T typedef typename Allocator::reference reference; +T typedef typename Allocator::const_reference const_reference; +T typedef implementation defined iterator; +T typedef implementation defined const_iterator; +T typedef implementation defined size_type; +T typedef implementation defined difference_type +T typedef typename Allocator::pointer pointer; +T typedef typename Allocator::const_pointer const_pointer; +T typedef std::reverse_iterator<iterator> reverse_iterator; +T typedef std::reverse_iterator<const_iterator> const_reverse_iterator; +T class value_compare + : public binary_function<value_type,value_type,bool> { + friend class multimap; + protected: +T Compare comp; +T value_compare(Compare c) : comp(c) {} + public: +T bool operator()(const value_type& x, const value_type& y) const { + return comp(x.first, y.first); + } + }; + // construct/copy/destroy: +T explicit multimap(const Compare& comp = Compare(), + const Allocator& = Allocator()); +T template <class InputIterator> + multimap(InputIterator first, InputIterator last, + const Compare& comp = Compare(), + const Allocator& = Allocator()); +T multimap(const multimap<Key,T,Compare,Allocator>& x); +T ~multimap(); +T multimap<Key,T,Compare,Allocator>& + operator=(const multimap<Key,T,Compare,Allocator>& x); +T allocator_type get_allocator() const; + + // iterators: +T iterator begin(); +T const_iterator begin() const; +T iterator end(); +T const_iterator end() const; +T reverse_iterator rbegin(); +T const_reverse_iterator rbegin() const; +T reverse_iterator rend(); +T const_reverse_iterator rend() const; + // capacity: +T bool empty() const; +T size_type size() const; +T size_type max_size() const; + // modifiers: +T iterator insert(const value_type& x); +T iterator insert(iterator position, const value_type& x); +T template <class InputIterator> + void insert(InputIterator first, InputIterator last); +T void erase(iterator position); +T size_type erase(const key_type& x); +T void erase(iterator first, iterator last); +T void swap(multimap<Key,T,Compare,Allocator>&); +T void clear(); + // observers: +T key_compare key_comp() const; +T value_compare value_comp() const; + // map operations: +T iterator find(const key_type& x); +T const_iterator find(const key_type& x) const; +T size_type count(const key_type& x) const; +T iterator lower_bound(const key_type& x); +T const_iterator lower_bound(const key_type& x) const; +T iterator upper_bound(const key_type& x); +T const_iterator upper_bound(const key_type& x) const; +T pair<iterator,iterator> equal_range(const key_type& x); +T pair<const_iterator,const_iterator> equal_range(const key_type& x) const; + }; + +T template <class Key, class T, class Compare, class Allocator> + bool operator==(const multimap<Key,T,Compare,Allocator>& x, + const multimap<Key,T,Compare,Allocator>& y); +T template <class Key, class T, class Compare, class Allocator> + bool operator< (const multimap<Key,T,Compare,Allocator>& x, + const multimap<Key,T,Compare,Allocator>& y); +T template <class Key, class T, class Compare, class Allocator> + bool operator!=(const multimap<Key,T,Compare,Allocator>& x, + const multimap<Key,T,Compare,Allocator>& y); +T template <class Key, class T, class Compare, class Allocator> + bool operator> (const multimap<Key,T,Compare,Allocator>& x, + const multimap<Key,T,Compare,Allocator>& y); +T template <class Key, class T, class Compare, class Allocator> + bool operator>=(const multimap<Key,T,Compare,Allocator>& x, + const multimap<Key,T,Compare,Allocator>& y); +T template <class Key, class T, class Compare, class Allocator> + bool operator<=(const multimap<Key,T,Compare,Allocator>& x, + const multimap<Key,T,Compare,Allocator>& y); + // specialized algorithms: +T template <class Key, class T, class Compare, class Allocator> + void swap(multimap<Key,T,Compare,Allocator>& x, + multimap<Key,T,Compare,Allocator>& y); + + + 23.3.3 Template class set [lib.set] + + template <class Key, class Compare = less<Key>, + class Allocator = allocator<Key> > +T class set { + public: + // types: +T typedef Key key_type; +T typedef Key value_type; +T typedef Compare key_compare; +T typedef Compare value_compare; +T typedef Allocator allocator_type; +T typedef typename Allocator::reference reference; +T typedef typename Allocator::const_reference const_reference; +T typedef implementation defined iterator; +T typedef implementation defined const_iterator; +T typedef implementation defined size_type; +T typedef implementation defined difference_type; +T typedef typename Allocator::pointer pointer; +T typedef typename Allocator::const_pointer const_pointer; +T typedef std::reverse_iterator<iterator> reverse_iterator; +T typedef std::reverse_iterator<const_iterator> const_reverse_iterator; + // _lib.set.cons_ construct/copy/destroy: +T explicit set(const Compare& comp = Compare(), + const Allocator& = Allocator()); +T template <class InputIterator> + set(InputIterator first, InputIterator last, + const Compare& comp = Compare(), const Allocator& = Allocator()); +T set(const set<Key,Compare,Allocator>& x); +T ~set(); +T set<Key,Compare,Allocator>& + operator=(const set<Key,Compare,Allocator>& x); +T allocator_type get_allocator() const; + // iterators: +T iterator begin(); +T const_iterator begin() const; +T iterator end(); +T const_iterator end() const; +T reverse_iterator rbegin(); +T const_reverse_iterator rbegin() const; +T reverse_iterator rend(); +T const_reverse_iterator rend() const; + // capacity: +T bool empty() const; +T size_type size() const; +T size_type max_size() const; + // modifiers: +T pair<iterator,bool> insert(const value_type& x); +T iterator insert(iterator position, const value_type& x); +T template <class InputIterator> +T void insert(InputIterator first, InputIterator last); +T void erase(iterator position); +T size_type erase(const key_type& x); +T void erase(iterator first, iterator last); +T void swap(set<Key,Compare,Allocator>&); +T void clear(); + + // observers: +T key_compare key_comp() const; +T value_compare value_comp() const; + // set operations: +T iterator find(const key_type& x) const; +T size_type count(const key_type& x) const; +T iterator lower_bound(const key_type& x) const; +T iterator upper_bound(const key_type& x) const; +T pair<iterator,iterator> equal_range(const key_type& x) const; + }; +T template <class Key, class Compare, class Allocator> + bool operator==(const set<Key,Compare,Allocator>& x, + const set<Key,Compare,Allocator>& y); +T template <class Key, class Compare, class Allocator> + bool operator< (const set<Key,Compare,Allocator>& x, + const set<Key,Compare,Allocator>& y); +T template <class Key, class Compare, class Allocator> + bool operator!=(const set<Key,Compare,Allocator>& x, + const set<Key,Compare,Allocator>& y); +T template <class Key, class Compare, class Allocator> + bool operator> (const set<Key,Compare,Allocator>& x, + const set<Key,Compare,Allocator>& y); +T template <class Key, class Compare, class Allocator> + bool operator>=(const set<Key,Compare,Allocator>& x, + const set<Key,Compare,Allocator>& y); +T template <class Key, class Compare, class Allocator> + bool operator<=(const set<Key,Compare,Allocator>& x, + const set<Key,Compare,Allocator>& y); + // specialized algorithms: +T template <class Key, class Compare, class Allocator> + void swap(set<Key,Compare,Allocator>& x, + set<Key,Compare,Allocator>& y); + + 23.3.4 Template class multiset [lib.multiset] + + template <class Key, class Compare = less<Key>, + class Allocator = allocator<Key> > +T class multiset { + public: + // types: +T typedef Key key_type; +T typedef Key value_type; +T typedef Compare key_compare; +T typedef Compare value_compare; +T typedef Allocator allocator_type; +T typedef typename Allocator::reference reference; +T typedef typename Allocator::const_reference const_reference; +T typedef implementation defined iterator; +T typedef implementation defined const_iterator; +T typedef implementation defined size_type; +T typedef implementation defined difference_type +T typedef typename Allocator::pointer pointer; +T typedef typename Allocator::const_pointer const_pointer; +T typedef std::reverse_iterator<iterator> reverse_iterator; +T typedef std::reverse_iterator<const_iterator> const_reverse_iterator; + + // construct/copy/destroy: +T explicit multiset(const Compare& comp = Compare(), + const Allocator& = Allocator()); +T template <class InputIterator> + multiset(InputIterator first, InputIterator last, + const Compare& comp = Compare(), + const Allocator& = Allocator()); +T multiset(const multiset<Key,Compare,Allocator>& x); +T ~multiset(); +T multiset<Key,Compare,Allocator>& + operator=(const multiset<Key,Compare,Allocator>& x); +T allocator_type get_allocator() const; + // iterators: +T iterator begin(); +T const_iterator begin() const; +T iterator end(); +T const_iterator end() const; +T reverse_iterator rbegin(); +T const_reverse_iterator rbegin() const; +T reverse_iterator rend(); +T const_reverse_iterator rend() const; + // capacity: +T bool empty() const; +T size_type size() const; +T size_type max_size() const; + // modifiers: +T iterator insert(const value_type& x); +T iterator insert(iterator position, const value_type& x); +T template <class InputIterator> + void insert(InputIterator first, InputIterator last); +T void erase(iterator position); +T size_type erase(const key_type& x); +T void erase(iterator first, iterator last); +T void swap(multiset<Key,Compare,Allocator>&); +T void clear(); + // observers: +T key_compare key_comp() const; +T value_compare value_comp() const; + // set operations: +T iterator find(const key_type& x) const; +T size_type count(const key_type& x) const; +T iterator lower_bound(const key_type& x) const; +T iterator upper_bound(const key_type& x) const; +T pair<iterator,iterator> equal_range(const key_type& x) const; + }; + +T template <class Key, class Compare, class Allocator> + bool operator==(const multiset<Key,Compare,Allocator>& x, + const multiset<Key,Compare,Allocator>& y); +T template <class Key, class Compare, class Allocator> + bool operator< (const multiset<Key,Compare,Allocator>& x, + const multiset<Key,Compare,Allocator>& y); +T template <class Key, class Compare, class Allocator> + bool operator!=(const multiset<Key,Compare,Allocator>& x, + const multiset<Key,Compare,Allocator>& y); +T template <class Key, class Compare, class Allocator> + bool operator> (const multiset<Key,Compare,Allocator>& x, + const multiset<Key,Compare,Allocator>& y); +T template <class Key, class Compare, class Allocator> + bool operator>=(const multiset<Key,Compare,Allocator>& x, + const multiset<Key,Compare,Allocator>& y); +T template <class Key, class Compare, class Allocator> + bool operator<=(const multiset<Key,Compare,Allocator>& x, + const multiset<Key,Compare,Allocator>& y); + // specialized algorithms: +T template <class Key, class Compare, class Allocator> + void swap(multiset<Key,Compare,Allocator>& x, + multiset<Key,Compare,Allocator>& y); + + 23.3.5 Template class bitset [lib.template.bitset] + + Header <bitset> synopsis + +T template <size_t N> class bitset; + // _lib.bitset.operators_ bitset operations: +T template <size_t N> + bitset<N> operator&(const bitset<N>&, const bitset<N>&); +T template <size_t N> + bitset<N> operator|(const bitset<N>&, const bitset<N>&); +T template <size_t N> + bitset<N> operator^(const bitset<N>&, const bitset<N>&); +T template <class charT, class traits, size_t N> + basic_istream<charT, traits>& + operator>>(basic_istream<charT, traits>& is, bitset<N>& x); +T template <class charT, class traits, size_t N> + basic_ostream<charT, traits>& + operator<<(basic_ostream<charT, traits>& os, const bitset<N>& x); + +T template<size_t N> class bitset { + public: + // bit reference: +T class reference { + friend class bitset; +T reference(); + public: +T ~reference(); +T reference& operator=(bool x); // for b[i] = x; +T reference& operator=(const reference&); // for b[i] = b[j]; +T bool operator~() const; // flips the bit +T operator bool() const; // for x = b[i]; +T reference& flip(); // for b[i].flip(); + }; + + // _lib.bitset.cons_ constructors: +T bitset(); +T bitset(unsigned long val); +T template<class charT, class traits, class Allocator> + explicit bitset( + const basic_string<charT,traits,Allocator>& str, + typename basic_string<charT,traits,Allocator>::size_type pos = 0, + typename basic_string<charT,traits,Allocator>::size_type n = + basic_string<charT,traits,Allocator>::npos); + // _lib.bitset.members_ bitset operations: +T bitset<N>& operator&=(const bitset<N>& rhs); +T bitset<N>& operator|=(const bitset<N>& rhs); +T bitset<N>& operator^=(const bitset<N>& rhs); +T bitset<N>& operator<<=(size_t pos); +T bitset<N>& operator>>=(size_t pos); +T bitset<N>& set(); +T bitset<N>& set(size_t pos, int val = true); +T bitset<N>& reset(); +T bitset<N>& reset(size_t pos); +T bitset<N> operator~() const; +T bitset<N>& flip(); +T bitset<N>& flip(size_t pos); + // element access: +T reference operator[](size_t pos); // for b[i]; +T unsigned long to_ulong() const; +T template <class charT, class traits, class Allocator> + basic_string<charT, traits, Allocator> to_string() const; +T size_t count() const; +T size_t size() const; +T bool operator==(const bitset<N>& rhs) const; +T bool operator!=(const bitset<N>& rhs) const; +T bool test(size_t pos) const; +T bool any() const; +T bool none() const; +T bitset<N> operator<<(size_t pos) const; +T bitset<N> operator>>(size_t pos) const; + }; + + + + + 24.2 Header <iterator> synopsis [lib.iterator.synopsis] + + // _lib.iterator.primitives_, primitives: +T template<class Iterator> struct iterator_traits; +T template<class T> struct iterator_traits<T*>; + +X template<class Category, class T, class Distance = ptrdiff_t, + class Pointer = T*, class Reference = T&> struct iterator; +T struct input_iterator_tag {}; +T struct output_iterator_tag {}; +T struct forward_iterator_tag: public input_iterator_tag {}; +T struct bidirectional_iterator_tag: public forward_iterator_tag {}; +T struct random_access_iterator_tag: public bidirectional_iterator_tag {}; + // _lib.iterator.operations_, iterator operations: +T template <class InputIterator, class Distance> + void advance(InputIterator& i, Distance n); +T template <class InputIterator> + typename iterator_traits<InputIterator>::difference_type + distance(InputIterator first, InputIterator last); + // _lib.predef.iterators_, predefined iterators: +X template <class Iterator> class reverse_iterator; +T template <class Iterator> + bool operator==( + const reverse_iterator<Iterator>& x, + const reverse_iterator<Iterator>& y); +T template <class Iterator> + bool operator<( + const reverse_iterator<Iterator>& x, + const reverse_iterator<Iterator>& y); +T template <class Iterator> + bool operator!=( + const reverse_iterator<Iterator>& x, + const reverse_iterator<Iterator>& y); +T template <class Iterator> + bool operator>( + const reverse_iterator<Iterator>& x, + const reverse_iterator<Iterator>& y); +T template <class Iterator> + bool operator>=( + const reverse_iterator<Iterator>& x, + const reverse_iterator<Iterator>& y); +T template <class Iterator> + bool operator<=( + const reverse_iterator<Iterator>& x, + const reverse_iterator<Iterator>& y); +T template <class Iterator> + typename reverse_iterator<Iterator>::difference_type operator-( + const reverse_iterator<Iterator>& x, + const reverse_iterator<Iterator>& y); +T template <class Iterator> + reverse_iterator<Iterator> + operator+( + typename reverse_iterator<Iterator>::difference_type n, + const reverse_iterator<Iterator>& x); + +X template <class Container> class back_insert_iterator; +T template <class Container> + back_insert_iterator<Container> back_inserter(Container& x); +X template <class Container> class front_insert_iterator; +T template <class Container> + front_insert_iterator<Container> front_inserter(Container& x); +X template <class Container> class insert_iterator; +T template <class Container, class Iterator> + insert_iterator<Container> inserter(Container& x, Iterator i); + // _lib.stream.iterators_, stream iterators: +X template <class T, class charT = char, class traits = char_traits<charT>, + class Distance = ptrdiff_t> + class istream_iterator; + template <class T, class charT, class traits, class Distance> +X bool operator==(const istream_iterator<T,charT,traits,Distance>& x, + const istream_iterator<T,charT,traits,Distance>& y); + template <class T, class charT, class traits, class Distance> +X bool operator!=(const istream_iterator<T,charT,traits,Distance>& x, + const istream_iterator<T,charT,traits,Distance>& y); +X template <class T, class charT = char, class traits = char_traits<charT> > + class ostream_iterator; +X template<class charT, class traits = char_traits<charT> > + class istreambuf_iterator; +X template <class charT, class traits> + bool operator==(const istreambuf_iterator<charT,traits>& a, + const istreambuf_iterator<charT,traits>& b); +X template <class charT, class traits> + bool operator!=(const istreambuf_iterator<charT,traits>& a, + const istreambuf_iterator<charT,traits>& b); +T template <class charT, class traits = char_traits<charT> > + class ostreambuf_iterator; + + 24.3 Iterator primitives [lib.iterator.primitives] + +T template<class Iterator> struct iterator_traits { +T typedef typename Iterator::difference_type difference_type; +T typedef typename Iterator::value_type value_type; +T typedef typename Iterator::pointer pointer; +T typedef typename Iterator::reference reference; +T typedef typename Iterator::iterator_category iterator_category; + }; + +T template<class T> struct iterator_traits<T*> { +T typedef ptrdiff_t difference_type; +T typedef T value_type; +T typedef T* pointer; +T typedef T& reference; +T typedef random_access_iterator_tag iterator_category; + }; + +T template<class T> struct iterator_traits<const T*> { +T typedef ptrdiff_t difference_type; +T typedef T value_type; +T typedef const T* pointer; +T typedef const T& reference; +T typedef random_access_iterator_tag iterator_category; + }; + + 24.3.2 Basic iterator [lib.iterator.basic] + + template<class Category, class T, class Distance = ptrdiff_t, + class Pointer = T*, class Reference = T&> +X struct iterator { +T typedef T value_type; +T typedef Distance difference_type; +T typedef Pointer pointer; +T typedef Reference reference; +T typedef Category iterator_category; + }; + + 24.3.3 Standard iterator tags [lib.std.iterator.tags] + +T struct input_iterator_tag {}; +T struct output_iterator_tag {}; +T struct forward_iterator_tag: public input_iterator_tag {}; +T struct bidirectional_iterator_tag: public forward_iterator_tag {}; +T struct random_access_iterator_tag: public bidirectional_iterator_tag {}; + + + 24.4.1 Reverse iterators [lib.reverse.iterators] + + template <class Iterator> +X class reverse_iterator : public + iterator<typename iterator_traits<Iterator>::iterator_category, + typename iterator_traits<Iterator>::value_type, + typename iterator_traits<Iterator>::difference_type, + typename iterator_traits<Iterator>::pointer, + typename iterator_traits<Iterator>::reference> { + protected: +T Iterator current; + public: +T typedef Iterator + iterator_type; +T typedef typename iterator_traits<Iterator>::difference_type + difference_type; +T typedef typename iterator_traits<Iterator>::reference + reference; +T typedef typename iterator_traits<Iterator>::pointer + pointer; + +T reverse_iterator(); +T explicit reverse_iterator(Iterator x); +T template <class U> reverse_iterator(const reverse_iterator<U>& u); +T Iterator base() const; // explicit +T reference operator*() const; +T pointer operator->() const; +T reverse_iterator& operator++(); +T reverse_iterator operator++(int); +T reverse_iterator& operator--(); +T reverse_iterator operator--(int); + +T reverse_iterator operator+ (difference_type n) const; +T reverse_iterator& operator+=(difference_type n); +T reverse_iterator operator- (difference_type n) const; +T reverse_iterator& operator-=(difference_type n); +T reference operator[](difference_type n) const; + }; +T template <class Iterator> + bool operator==( + const reverse_iterator<Iterator>& x, + const reverse_iterator<Iterator>& y); +T template <class Iterator> + bool operator<( + const reverse_iterator<Iterator>& x, + const reverse_iterator<Iterator>& y); +T template <class Iterator> + bool operator!=( + const reverse_iterator<Iterator>& x, + const reverse_iterator<Iterator>& y); +T template <class Iterator> + bool operator>( + const reverse_iterator<Iterator>& x, + const reverse_iterator<Iterator>& y); +T template <class Iterator> + bool operator>=( + const reverse_iterator<Iterator>& x, + const reverse_iterator<Iterator>& y); +T template <class Iterator> + bool operator<=( + const reverse_iterator<Iterator>& x, + const reverse_iterator<Iterator>& y); +T template <class Iterator> + typename reverse_iterator<Iterator>::difference_type operator-( + const reverse_iterator<Iterator>& x, + const reverse_iterator<Iterator>& y); +T template <class Iterator> + reverse_iterator<Iterator> operator+( + typename reverse_iterator<Iterator>::difference_type n, + const reverse_iterator<Iterator>& x); + + + 24.4.2.1 Template class [lib.back.insert.iterator] + back_insert_iterator + + template <class Container> +X class back_insert_iterator : + public iterator<output_iterator_tag,void,void,void,void> { + protected: +T Container* container; + public: +T typedef Container container_type; +T explicit back_insert_iterator(Container& x); +T back_insert_iterator<Container>& + operator=(typename Container::const_reference value); + +T back_insert_iterator<Container>& operator*(); +T back_insert_iterator<Container>& operator++(); +T back_insert_iterator<Container> operator++(int); + }; +T template <class Container> + back_insert_iterator<Container> back_inserter(Container& x); + + + + 24.4.2.3 Template class [lib.front.insert.iterator] + front_insert_iterator + + template <class Container> +X class front_insert_iterator : + public iterator<output_iterator_tag,void,void,void,void> { + protected: +T Container* container; + public: +T typedef Container container_type; +T explicit front_insert_iterator(Container& x); +T front_insert_iterator<Container>& + operator=(typename Container::const_reference value); +T front_insert_iterator<Container>& operator*(); +T front_insert_iterator<Container>& operator++(); +T front_insert_iterator<Container> operator++(int); + }; +T template <class Container> + front_insert_iterator<Container> front_inserter(Container& x); + + + 24.4.2.5 Template class insert_iterator [lib.insert.iterator] + + template <class Container> +X class insert_iterator : + public iterator<output_iterator_tag,void,void,void,void> { + protected: +T Container* container; +T typename Container::iterator iter; + public: +T typedef Container container_type; +T insert_iterator(Container& x, typename Container::iterator i); +T insert_iterator<Container>& + operator=(typename Container::const_reference value); +T insert_iterator<Container>& operator*(); +T insert_iterator<Container>& operator++(); +T insert_iterator<Container>& operator++(int); + }; +T template <class Container, class Iterator> + insert_iterator<Container> inserter(Container& x, Iterator i); + + 24.5.1 Template class istream_iterator [lib.istream.iterator] + + template <class T, class charT = char, class traits = char_traits<charT>, + class Distance = ptrdiff_t> +X class istream_iterator: + public iterator<input_iterator_tag, T, Distance, const T*, const T&> { + public: +T typedef charT char_type +T typedef traits traits_type; +T typedef basic_istream<charT,traits> istream_type; +T istream_iterator(); +T istream_iterator(istream_type& s); +T istream_iterator(const istream_iterator<T,charT,traits,Distance>& x); +T ~istream_iterator(); + +T const T& operator*() const; +T const T* operator->() const; +T istream_iterator<T,charT,traits,Distance>& operator++(); +T istream_iterator<T,charT,traits,Distance> operator++(int); + }; + +T template <class T, class charT, class traits, class Distance> + bool operator==(const istream_iterator<T,charT,traits,Distance>& x, + const istream_iterator<T,charT,traits,Distance>& y); +T template <class T, class charT, class traits, class Distance> + bool operator!=(const istream_iterator<T,charT,traits,Distance>& x, + const istream_iterator<T,charT,traits,Distance>& y); + + + 24.5.2 Template class ostream_iterator [lib.ostream.iterator] + + template <class T, class charT = char, class traits = char_traits<charT> > +X class ostream_iterator: + public iterator<output_iterator_tag, void, void, void, void> { + public: +T typedef charT char_type; +T typedef traits traits_type; +T typedef basic_ostream<charT,traits> ostream_type; +T ostream_iterator(ostream_type& s); +T ostream_iterator(ostream_type& s, const charT* delimiter); +T ostream_iterator(const ostream_iterator<T,charT,traits>& x); +T ~ostream_iterator(); +T ostream_iterator<T,charT,traits>& operator=(const T& value); + +T ostream_iterator<T,charT,traits>& operator*(); +T ostream_iterator<T,charT,traits>& operator++(); +T ostream_iterator<T,charT,traits>& operator++(int); + }; + + + 24.5.3 Template class [lib.istreambuf.iterator] + istreambuf_iterator + + template<class charT, class traits = char_traits<charT> > +X class istreambuf_iterator + : public iterator<input_iterator_tag, charT, + typename traits::off_type, charT*, charT&> { + public: +T typedef charT char_type; +T typedef traits traits_type; +T typedef typename traits::int_type int_type; +T typedef basic_streambuf<charT,traits> streambuf_type; +T typedef basic_istream<charT,traits> istream_type; +T class proxy; // exposition only +T istreambuf_iterator() throw(); +T istreambuf_iterator(istream_type& s) throw(); +T istreambuf_iterator(streambuf_type* s) throw(); +T istreambuf_iterator(const proxy& p) throw(); +T charT operator*() const; +T istreambuf_iterator<charT,traits>& operator++(); +T proxy operator++(int); +X bool equal(istreambuf_iterator& b); + }; + +T template <class charT, class traits> + bool operator==(const istreambuf_iterator<charT,traits>& a, + const istreambuf_iterator<charT,traits>& b); + +T template <class charT, class traits> + bool operator!=(const istreambuf_iterator<charT,traits>& a, + const istreambuf_iterator<charT,traits>& b); + + 24.5.3.1 Template class [lib.istreambuf.iterator::proxy] + istreambuf_iterator::proxy + + template <class charT, class traits = char_traits<charT> > +T class istreambuf_iterator<charT, traits>::proxy + { +T charT keep_; +T basic_streambuf<charT,traits>* sbuf_; +T proxy(charT c, + basic_streambuf<charT,traits>* sbuf); + : keep_(c), sbuf_(sbuf) {} + public: +T charT operator*() { return keep_; } + }; + + + + 24.5.4 Template class [lib.ostreambuf.iterator] + ostreambuf_iterator + + template <class charT, class traits = char_traits<charT> > +T class ostreambuf_iterator: + public iterator<output_iterator_tag, void, void, void, void> { + public: +T typedef charT char_type; +T typedef traits traits_type; +T typedef basic_streambuf<charT,traits> streambuf_type; +T typedef basic_ostream<charT,traits> ostream_type; + public: +T ostreambuf_iterator(ostream_type& s) throw(); +T ostreambuf_iterator(streambuf_type* s) throw(); +T ostreambuf_iterator& operator=(charT c); +T ostreambuf_iterator& operator*(); +T ostreambuf_iterator& operator++(); +T ostreambuf_iterator& operator++(int); +T bool failed() const throw(); + }; + + + Header <algorithm> synopsis + + + // _lib.alg.nonmodifying_, non-modifying sequence operations: +T template<class InputIterator, class Function> + Function for_each(InputIterator first, InputIterator last, Function f); +T template<class InputIterator, class T> + InputIterator find(InputIterator first, InputIterator last, + const T& value); +T template<class InputIterator, class Predicate> + InputIterator find_if(InputIterator first, InputIterator last, + Predicate pred); +T template<class ForwardIterator1, class ForwardIterator2> + ForwardIterator1 + find_end(ForwardIterator1 first1, ForwardIterator1 last1, + ForwardIterator2 first2, ForwardIterator2 last2); +T template<class ForwardIterator1, class ForwardIterator2, + class BinaryPredicate> + ForwardIterator1 + find_end(ForwardIterator1 first1, ForwardIterator1 last1, + ForwardIterator2 first2, ForwardIterator2 last2, + BinaryPredicate pred); +T template<class ForwardIterator1, class ForwardIterator2> + ForwardIterator1 + find_first_of(ForwardIterator1 first1, ForwardIterator1 last1, + ForwardIterator2 first2, ForwardIterator2 last2); +T template<class ForwardIterator1, class ForwardIterator2, + class BinaryPredicate> + ForwardIterator1 + find_first_of(ForwardIterator1 first1, ForwardIterator1 last1, + ForwardIterator2 first2, ForwardIterator2 last2, + BinaryPredicate pred); +T template<class ForwardIterator> + ForwardIterator adjacent_find(ForwardIterator first, + ForwardIterator last); +T template<class ForwardIterator, class BinaryPredicate> + ForwardIterator adjacent_find(ForwardIterator first, + ForwardIterator last, BinaryPredicate pred); +T template<class InputIterator, class T> + typename iterator_traits<InputIterator>::difference_type + count(InputIterator first, InputIterator last, const T& value); +T template<class InputIterator, class Predicate> + typename iterator_traits<InputIterator>::difference_type + count_if(InputIterator first, InputIterator last, Predicate pred); +T template<class InputIterator1, class InputIterator2> + pair<InputIterator1, InputIterator2> + mismatch(InputIterator1 first1, InputIterator1 last1, + InputIterator2 first2); +T template<class InputIterator1, class InputIterator2, class BinaryPredicate> + pair<InputIterator1, InputIterator2> + mismatch(InputIterator1 first1, InputIterator1 last1, + InputIterator2 first2, BinaryPredicate pred); + +T template<class InputIterator1, class InputIterator2> + bool equal(InputIterator1 first1, InputIterator1 last1, + InputIterator2 first2); +T template<class InputIterator1, class InputIterator2, class BinaryPredicate> + bool equal(InputIterator1 first1, InputIterator1 last1, + InputIterator2 first2, BinaryPredicate pred); +T template<class ForwardIterator1, class ForwardIterator2> + ForwardIterator1 search(ForwardIterator1 first1, ForwardIterator1 last1, + ForwardIterator2 first2, ForwardIterator2 last2); +T template<class ForwardIterator1, class ForwardIterator2, + class BinaryPredicate> + ForwardIterator1 search(ForwardIterator1 first1, ForwardIterator1 last1, + ForwardIterator2 first2, ForwardIterator2 last2, + BinaryPredicate pred); +T template<class ForwardIterator, class Size, class T> + ForwardIterator search_n(ForwardIterator first, ForwardIterator last, + Size count, const T& value); +T template<class ForwardIterator, class Size, class T, class BinaryPredicate> + ForwardIterator1 search_n(ForwardIterator first, ForwardIterator last, + Size count, const T& value, + BinaryPredicate pred); + // _lib.alg.modifying.operations_, modifying sequence operations: + // _lib.alg.copy_, copy: +T template<class InputIterator, class OutputIterator> + OutputIterator copy(InputIterator first, InputIterator last, + OutputIterator result); +T template<class BidirectionalIterator1, class BidirectionalIterator2> + BidirectionalIterator2 + copy_backward(BidirectionalIterator1 first, BidirectionalIterator1 last, + BidirectionalIterator2 result); + // _lib.alg.swap_, swap: +T template<class T> void swap(T& a, T& b); +T template<class ForwardIterator1, class ForwardIterator2> + ForwardIterator2 swap_ranges(ForwardIterator1 first1, + ForwardIterator1 last1, ForwardIterator2 first2); +T template<class ForwardIterator1, class ForwardIterator2> + void iter_swap(ForwardIterator1 a, ForwardIterator2 b); +T template<class InputIterator, class OutputIterator, class UnaryOperation> + OutputIterator transform(InputIterator first, InputIterator last, + OutputIterator result, UnaryOperation op); +T template<class InputIterator1, class InputIterator2, class OutputIterator, + class BinaryOperation> + OutputIterator transform(InputIterator1 first1, InputIterator1 last1, + InputIterator2 first2, OutputIterator result, + BinaryOperation binary_op); + +T template<class ForwardIterator, class T> + void replace(ForwardIterator first, ForwardIterator last, + const T& old_value, const T& new_value); +T template<class ForwardIterator, class Predicate, class T> + void replace_if(ForwardIterator first, ForwardIterator last, + Predicate pred, const T& new_value); +T template<class InputIterator, class OutputIterator, class T> + OutputIterator replace_copy(InputIterator first, InputIterator last, + OutputIterator result, + const T& old_value, const T& new_value); +T template<class Iterator, class OutputIterator, class Predicate, class T> + OutputIterator replace_copy_if(Iterator first, Iterator last, + OutputIterator result, + Predicate pred, const T& new_value); +T template<class ForwardIterator, class T> + void fill(ForwardIterator first, ForwardIterator last, const T& value); +T template<class OutputIterator, class Size, class T> + void fill_n(OutputIterator first, Size n, const T& value); +T template<class ForwardIterator, class Generator> + void generate(ForwardIterator first, ForwardIterator last, Generator gen); +T template<class OutputIterator, class Size, class Generator> + void generate_n(OutputIterator first, Size n, Generator gen); +T template<class ForwardIterator, class T> + ForwardIterator remove(ForwardIterator first, ForwardIterator last, + const T& value); +T template<class ForwardIterator, class Predicate> + ForwardIterator remove_if(ForwardIterator first, ForwardIterator last, + Predicate pred); +T template<class InputIterator, class OutputIterator, class T> + OutputIterator remove_copy(InputIterator first, InputIterator last, + OutputIterator result, const T& value); +T template<class InputIterator, class OutputIterator, class Predicate> + OutputIterator remove_copy_if(InputIterator first, InputIterator last, + OutputIterator result, Predicate pred); +T template<class ForwardIterator> + ForwardIterator unique(ForwardIterator first, ForwardIterator last); +T template<class ForwardIterator, class BinaryPredicate> + ForwardIterator unique(ForwardIterator first, ForwardIterator last, + BinaryPredicate pred); +T template<class InputIterator, class OutputIterator> + OutputIterator unique_copy(InputIterator first, InputIterator last, + OutputIterator result); +T template<class InputIterator, class OutputIterator, class BinaryPredicate> + OutputIterator unique_copy(InputIterator first, InputIterator last, + OutputIterator result, BinaryPredicate pred); +T template<class BidirectionalIterator> + void reverse(BidirectionalIterator first, BidirectionalIterator last); +T template<class BidirectionalIterator, class OutputIterator> + OutputIterator reverse_copy(BidirectionalIterator first, + BidirectionalIterator last, + OutputIterator result); + +T template<class ForwardIterator> + void rotate(ForwardIterator first, ForwardIterator middle, + ForwardIterator last); +T template<class ForwardIterator, class OutputIterator> + OutputIterator rotate_copy(ForwardIterator first, ForwardIterator middle, + ForwardIterator last, OutputIterator result); +T template<class RandomAccessIterator> + void random_shuffle(RandomAccessIterator first, + RandomAccessIterator last); +T template<class RandomAccessIterator, class RandomNumberGenerator> + void random_shuffle(RandomAccessIterator first, + RandomAccessIterator last, + RandomNumberGenerator& rand); + // _lib.alg.partitions_, partitions: +T template<class BidirectionalIterator, class Predicate> + BidirectionalIterator partition(BidirectionalIterator first, + BidirectionalIterator last, + Predicate pred); +T template<class BidirectionalIterator, class Predicate> + BidirectionalIterator stable_partition(BidirectionalIterator first, + BidirectionalIterator last, + Predicate pred); + // _lib.alg.sorting_, sorting and related operations: + // _lib.alg.sort_, sorting: +T template<class RandomAccessIterator> + void sort(RandomAccessIterator first, RandomAccessIterator last); +T template<class RandomAccessIterator, class Compare> + void sort(RandomAccessIterator first, RandomAccessIterator last, + Compare comp); +T template<class RandomAccessIterator> + void stable_sort(RandomAccessIterator first, RandomAccessIterator last); +T template<class RandomAccessIterator, class Compare> + void stable_sort(RandomAccessIterator first, RandomAccessIterator last, + Compare comp); +T template<class RandomAccessIterator> + void partial_sort(RandomAccessIterator first, + RandomAccessIterator middle, + RandomAccessIterator last); +T template<class RandomAccessIterator, class Compare> + void partial_sort(RandomAccessIterator first, + RandomAccessIterator middle, + RandomAccessIterator last, Compare comp); +T template<class InputIterator, class RandomAccessIterator> + RandomAccessIterator + partial_sort_copy(InputIterator first, InputIterator last, + RandomAccessIterator result_first, + RandomAccessIterator result_last); +T template<class InputIterator, class RandomAccessIterator, class Compare> + RandomAccessIterator + partial_sort_copy(InputIterator first, InputIterator last, + RandomAccessIterator result_first, + RandomAccessIterator result_last, + Compare comp); + +T template<class RandomAccessIterator> + void nth_element(RandomAccessIterator first, RandomAccessIterator nth, + RandomAccessIterator last); +T template<class RandomAccessIterator, class Compare> + void nth_element(RandomAccessIterator first, RandomAccessIterator nth, + RandomAccessIterator last, Compare comp); + // _lib.alg.binary.search_, binary search: +T template<class ForwardIterator, class T> + ForwardIterator lower_bound(ForwardIterator first, ForwardIterator last, + const T& value); +T template<class ForwardIterator, class T, class Compare> + ForwardIterator lower_bound(ForwardIterator first, ForwardIterator last, + const T& value, Compare comp); +T template<class ForwardIterator, class T> + ForwardIterator upper_bound(ForwardIterator first, ForwardIterator last, + const T& value); +T template<class ForwardIterator, class T, class Compare> + ForwardIterator upper_bound(ForwardIterator first, ForwardIterator last, + const T& value, Compare comp); +T template<class ForwardIterator, class T> + pair<ForwardIterator, ForwardIterator> + equal_range(ForwardIterator first, ForwardIterator last, + const T& value); +T template<class ForwardIterator, class T, class Compare> + pair<ForwardIterator, ForwardIterator> + equal_range(ForwardIterator first, ForwardIterator last, + const T& value, Compare comp); +T template<class ForwardIterator, class T> + bool binary_search(ForwardIterator first, ForwardIterator last, + const T& value); +T template<class ForwardIterator, class T, class Compare> + bool binary_search(ForwardIterator first, ForwardIterator last, + const T& value, Compare comp); + // _lib.alg.merge_, merge: +T template<class InputIterator1, class InputIterator2, class OutputIterator> + OutputIterator merge(InputIterator1 first1, InputIterator1 last1, + InputIterator2 first2, InputIterator2 last2, + OutputIterator result); +T template<class InputIterator1, class InputIterator2, class OutputIterator, + class Compare> + OutputIterator merge(InputIterator1 first1, InputIterator1 last1, + InputIterator2 first2, InputIterator2 last2, + OutputIterator result, Compare comp); +T template<class BidirectionalIterator> + void inplace_merge(BidirectionalIterator first, + BidirectionalIterator middle, + BidirectionalIterator last); +T template<class BidirectionalIterator, class Compare> + void inplace_merge(BidirectionalIterator first, + BidirectionalIterator middle, + BidirectionalIterator last, Compare comp); + + // _lib.alg.set.operations_, set operations: +T template<class InputIterator1, class InputIterator2> + bool includes(InputIterator1 first1, InputIterator1 last1, + InputIterator2 first2, InputIterator2 last2); +T template<class InputIterator1, class InputIterator2, class Compare> + bool includes(InputIterator1 first1, InputIterator1 last1, + InputIterator2 first2, InputIterator2 last2, Compare comp); +T template<class InputIterator1, class InputIterator2, class OutputIterator> + OutputIterator set_union(InputIterator1 first1, InputIterator1 last1, + InputIterator2 first2, InputIterator2 last2, + OutputIterator result); +T template<class InputIterator1, class InputIterator2, class OutputIterator, + class Compare> + OutputIterator set_union(InputIterator1 first1, InputIterator1 last1, + InputIterator2 first2, InputIterator2 last2, + OutputIterator result, Compare comp); +T template<class InputIterator1, class InputIterator2, class OutputIterator> + OutputIterator set_intersection + (InputIterator1 first1, InputIterator1 last1, + InputIterator2 first2, InputIterator2 last2, + OutputIterator result); +T template<class InputIterator1, class InputIterator2, class OutputIterator, + class Compare> + OutputIterator set_intersection + (InputIterator1 first1, InputIterator1 last1, + InputIterator2 first2, InputIterator2 last2, + OutputIterator result, Compare comp); +T template<class InputIterator1, class InputIterator2, class OutputIterator> + OutputIterator set_difference + (InputIterator1 first1, InputIterator1 last1, + InputIterator2 first2, InputIterator2 last2, + OutputIterator result); +T template<class InputIterator1, class InputIterator2, class OutputIterator, + class Compare> + OutputIterator set_difference(InputIterator1 first1, InputIterator1 last1, + InputIterator2 first2, InputIterator2 last2, + OutputIterator result, Compare comp); +T template<class InputIterator1, class InputIterator2, class OutputIterator> + OutputIterator + set_symmetric_difference(InputIterator1 first1, InputIterator1 last1, + InputIterator2 first2, InputIterator2 last2, + OutputIterator result); +T template<class InputIterator1, class InputIterator2, class OutputIterator, + class Compare> + OutputIterator + set_symmetric_difference(InputIterator1 first1, InputIterator1 last1, + InputIterator2 first2, InputIterator2 last2, + OutputIterator result, Compare comp); + // _lib.alg.heap.operations_, heap operations: +T template<class RandomAccessIterator> + void push_heap(RandomAccessIterator first, RandomAccessIterator last); +T template<class RandomAccessIterator, class Compare> + void push_heap(RandomAccessIterator first, RandomAccessIterator last, + Compare comp); + +T template<class RandomAccessIterator> + void pop_heap(RandomAccessIterator first, RandomAccessIterator last); +T template<class RandomAccessIterator, class Compare> + void pop_heap(RandomAccessIterator first, RandomAccessIterator last, + Compare comp); +T template<class RandomAccessIterator> + void make_heap(RandomAccessIterator first, RandomAccessIterator last); +T template<class RandomAccessIterator, class Compare> + void make_heap(RandomAccessIterator first, RandomAccessIterator last, + Compare comp); +T template<class RandomAccessIterator> + void sort_heap(RandomAccessIterator first, RandomAccessIterator last); +T template<class RandomAccessIterator, class Compare> + void sort_heap(RandomAccessIterator first, RandomAccessIterator last, + Compare comp); + // _lib.alg.min.max_, minimum and maximum: +T template<class T> const T& min(const T& a, const T& b); +T template<class T, class Compare> + const T& min(const T& a, const T& b, Compare comp); +T template<class T> const T& max(const T& a, const T& b); +T template<class T, class Compare> + const T& max(const T& a, const T& b, Compare comp); +T template<class ForwardIterator> + ForwardIterator min_element(ForwardIterator first, ForwardIterator last); +T template<class ForwardIterator, class Compare> + ForwardIterator min_element(ForwardIterator first, ForwardIterator last, + Compare comp); +T template<class ForwardIterator> + ForwardIterator max_element(ForwardIterator first, ForwardIterator last); +T template<class ForwardIterator, class Compare> + ForwardIterator max_element(ForwardIterator first, ForwardIterator last, + Compare comp); +T template<class InputIterator1, class InputIterator2> + bool lexicographical_compare + (InputIterator1 first1, InputIterator1 last1, + InputIterator2 first2, InputIterator2 last2); +T template<class InputIterator1, class InputIterator2, class Compare> + bool lexicographical_compare + (InputIterator1 first1, InputIterator1 last1, + InputIterator2 first2, InputIterator2 last2, + Compare comp); + + // _lib.alg.permutation.generators_, permutations +T template<class BidirectionalIterator> + bool next_permutation(BidirectionalIterator first, + BidirectionalIterator last); +T template<class BidirectionalIterator, class Compare> + bool next_permutation(BidirectionalIterator first, + BidirectionalIterator last, Compare comp); +T template<class BidirectionalIterator> + bool prev_permutation(BidirectionalIterator first, + BidirectionalIterator last); +T template<class BidirectionalIterator, class Compare> + bool prev_permutation(BidirectionalIterator first, + BidirectionalIterator last, Compare comp); + + + 25.4 C library algorithms [lib.alg.c.library] + + 1 Header <cstdlib> (partial, Table 2): + + Table 2--Header <cstdlib> synopsis + + Functions: bsearch qsort + + +X extern "C" void *bsearch(const void *key, const void *base, + size_t nmemb, size_t size, + int (*compar)(const void *, const void *)); +X extern "C++" void *bsearch(const void *key, const void *base, + size_t nmemb, size_t size, + int (*compar)(const void *, const void *)); + +X extern "C" void qsort(void* base, size_t nmemb, size_t size, + int (*compar)(const void*, const void*)); +X extern "C++" void qsort(void* base, size_t nmemb, size_t size, + int (*compar)(const void*, const void*)); + + + + 26.2 Complex numbers [lib.complex.numbers] + + + 26.2.1 Header <complex> synopsis [lib.complex.synopsis] + +T template<class T> class complex; +T template<> class complex<float>; +T template<> class complex<double>; +T template<> class complex<long double>; + // _lib.complex.ops_ operators: +T template<class T> + complex<T> operator+(const complex<T>&, const complex<T>&); +T template<class T> complex<T> operator+(const complex<T>&, const T&); +T template<class T> complex<T> operator+(const T&, const complex<T>&); +T template<class T> complex<T> operator- + (const complex<T>&, const complex<T>&); +T template<class T> complex<T> operator-(const complex<T>&, const T&); +T template<class T> complex<T> operator-(const T&, const complex<T>&); +T template<class T> complex<T> operator* + (const complex<T>&, const complex<T>&); +T template<class T> complex<T> operator*(const complex<T>&, const T&); +T template<class T> complex<T> operator*(const T&, const complex<T>&); +T template<class T> complex<T> operator/ + (const complex<T>&, const complex<T>&); +T template<class T> complex<T> operator/(const complex<T>&, const T&); +T template<class T> complex<T> operator/(const T&, const complex<T>&); +T template<class T> complex<T> operator+(const complex<T>&); +T template<class T> complex<T> operator-(const complex<T>&); +T template<class T> bool operator== + (const complex<T>&, const complex<T>&); +T template<class T> bool operator==(const complex<T>&, const T&); +T template<class T> bool operator==(const T&, const complex<T>&); +T template<class T> bool operator!=(const complex<T>&, const complex<T>&); +T template<class T> bool operator!=(const complex<T>&, const T&); +T template<class T> bool operator!=(const T&, const complex<T>&); +T template<class T, class charT, class traits> + basic_istream<charT, traits>& + operator>>(basic_istream<charT, traits>&, complex<T>&); + +T template<class T, class charT, class traits> + basic_ostream<charT, traits>& + operator<<(basic_ostream<charT, traits>&, const complex<T>&); + // _lib.complex.value.ops_ values: +T template<class T> T real(const complex<T>&); +T template<class T> T imag(const complex<T>&); + +T template<class T> T abs(const complex<T>&); +T template<class T> T arg(const complex<T>&); +T template<class T> T norm(const complex<T>&); +T template<class T> complex<T> conj(const complex<T>&); +T template<class T> complex<T> polar(const T&, const T&); + // _lib.complex.transcendentals_ transcendentals: +T template<class T> complex<T> cos (const complex<T>&); +T template<class T> complex<T> cosh (const complex<T>&); +T template<class T> complex<T> exp (const complex<T>&); +T template<class T> complex<T> log (const complex<T>&); +T template<class T> complex<T> log10(const complex<T>&); +T template<class T> complex<T> pow(const complex<T>&, int); +T template<class T> complex<T> pow(const complex<T>&, const T&); +T template<class T> complex<T> pow(const complex<T>&, const complex<T>&); +T template<class T> complex<T> pow(const T&, const complex<T>&); +T template<class T> complex<T> sin (const complex<T>&); +T template<class T> complex<T> sinh (const complex<T>&); +T template<class T> complex<T> sqrt (const complex<T>&); +T template<class T> complex<T> tan (const complex<T>&); +T template<class T> complex<T> tanh (const complex<T>&); + } + + 26.2.2 Template class complex [lib.complex] + + template<class T> +T class complex { + public: +T typedef T value_type; + +T complex(const T& re = T(), const T& im = T()); +T complex(const complex&); +T template<class X> complex(const complex<X>&); + +T T real() const; +T T imag() const; + +T complex<T>& operator= (const T&); +T complex<T>& operator+=(const T&); +T complex<T>& operator-=(const T&); +T complex<T>& operator*=(const T&); +T complex<T>& operator/=(const T&); + +T complex& operator=(const complex&); +T template<class X> complex<T>& operator= (const complex<X>&); +T template<class X> complex<T>& operator+=(const complex<X>&); +T template<class X> complex<T>& operator-=(const complex<X>&); +T template<class X> complex<T>& operator*=(const complex<X>&); +T template<class X> complex<T>& operator/=(const complex<X>&); + }; + +T template<class T> complex<T> operator+ + (const complex<T>&, const complex<T>&); +T template<class T> complex<T> operator+(const complex<T>&, const T&); +T template<class T> complex<T> operator+(const T&, const complex<T>&); + +T template<class T> complex<T> operator- + (const complex<T>&, const complex<T>&); +T template<class T> complex<T> operator-(const complex<T>&, const T&); +T template<class T> complex<T> operator-(const T&, const complex<T>&); + +T template<class T> complex<T> operator* + (const complex<T>&, const complex<T>&); +T template<class T> complex<T> operator*(const complex<T>&, const T&); +T template<class T> complex<T> operator*(const T&, const complex<T>&); + +T template<class T> complex<T> operator/ + (const complex<T>&, const complex<T>&); +T template<class T> complex<T> operator/(const complex<T>&, const T&); +T template<class T> complex<T> operator/(const T&, const complex<T>&); + +T template<class T> complex<T> operator+(const complex<T>&); +T template<class T> complex<T> operator-(const complex<T>&); + +T template<class T> bool operator==(const complex<T>&, const complex<T>&); +T template<class T> bool operator==(const complex<T>&, const T&); +T template<class T> bool operator==(const T&, const complex<T>&); + +T template<class T> bool operator!=(const complex<T>&, const complex<T>&); +T template<class T> bool operator!=(const complex<T>&, const T&); +T template<class T> bool operator!=(const T&, const complex<T>&); + +T template<class T, class charT, class traits> + basic_istream<charT, traits>& + operator>>(basic_istream<charT, traits>&, complex<T>&); + +T template<class T, class charT, class traits> + basic_ostream<charT, traits>& + operator<<(basic_ostream<charT, traits>&, const complex<T>&); + + + 26.2.3 complex specializations [lib.complex.special] + +T template<> class complex<float> { + public: +T typedef float value_type; + +T complex(float re = 0.0f, float im = 0.0f); +T explicit complex(const complex<double>&); +T explicit complex(const complex<long double>&); +T float real() const; +T float imag() const; + +T complex<float>& operator= (float); +T complex<float>& operator+=(float); +T complex<float>& operator-=(float); +T complex<float>& operator*=(float); +T complex<float>& operator/=(float); + +T complex<float>& operator=(const complex<float>&); +T template<class X> complex<float>& operator= (const complex<X>&); +T template<class X> complex<float>& operator+=(const complex<X>&); +T template<class X> complex<float>& operator-=(const complex<X>&); +T template<class X> complex<float>& operator*=(const complex<X>&); +T template<class X> complex<float>& operator/=(const complex<X>&); + }; +T template<> class complex<double> { + public: +T typedef double value_type; + +T complex(double re = 0.0, double im = 0.0); +T complex(const complex<float>&); +T explicit complex(const complex<long double>&); +T double real() const; +T double imag() const; + +T complex<double>& operator= (double); +T complex<double>& operator+=(double); +T complex<double>& operator-=(double); +T complex<double>& operator*=(double); +T complex<double>& operator/=(double); + +T complex<double>& operator=(const complex<double>&); +T template<class X> complex<double>& operator= (const complex<X>&); +T template<class X> complex<double>& operator+=(const complex<X>&); +T template<class X> complex<double>& operator-=(const complex<X>&); +T template<class X> complex<double>& operator*=(const complex<X>&); +T template<class X> complex<double>& operator/=(const complex<X>&); + }; + +T template<> class complex<long double> { + public: +T typedef long double value_type; + +T complex(long double re = 0.0L, long double im = 0.0L); +T complex(const complex<float>&); +T complex(const complex<double>&); +T long double real() const; +T long double imag() const; + +T complex<long double>& operator=(const complex<long double>&); +T complex<long double>& operator= (long double); +T complex<long double>& operator+=(long double); +T complex<long double>& operator-=(long double); +T complex<long double>& operator*=(long double); +T complex<long double>& operator/=(long double); + +T template<class X> complex<long double>& operator= (const complex<X>&); +T template<class X> complex<long double>& operator+=(const complex<X>&); +T template<class X> complex<long double>& operator-=(const complex<X>&); +T template<class X> complex<long double>& operator*=(const complex<X>&); +T template<class X> complex<long double>& operator/=(const complex<X>&); + }; + + 26.3 Numeric arrays [lib.numarray] + + 26.3.1 Header <valarray> synopsis [lib.valarray.synopsis] + +T template<class T> class valarray; // An array of type T +T class slice; +T template<class T> class slice_array; +T class gslice; +T template<class T> class gslice_array; +T template<class T> class mask_array; // a masked array +T template<class T> class indirect_array; // an indirected array + +T template<class T> valarray<T> operator* + (const valarray<T>&, const valarray<T>&); +T template<class T> valarray<T> operator* (const valarray<T>&, const T&); +T template<class T> valarray<T> operator* (const T&, const valarray<T>&); +T template<class T> valarray<T> operator/ + (const valarray<T>&, const valarray<T>&); +T template<class T> valarray<T> operator/ (const valarray<T>&, const T&); +T template<class T> valarray<T> operator/ (const T&, const valarray<T>&); +T template<class T> valarray<T> operator% + (const valarray<T>&, const valarray<T>&); +T template<class T> valarray<T> operator% (const valarray<T>&, const T&); +T template<class T> valarray<T> operator% (const T&, const valarray<T>&); +T template<class T> valarray<T> operator+ + (const valarray<T>&, const valarray<T>&); +T template<class T> valarray<T> operator+ (const valarray<T>&, const T&); +T template<class T> valarray<T> operator+ (const T&, const valarray<T>&); +T template<class T> valarray<T> operator- + (const valarray<T>&, const valarray<T>&); +T template<class T> valarray<T> operator- (const valarray<T>&, const T&); +T template<class T> valarray<T> operator- (const T&, const valarray<T>&); +T template<class T> valarray<T> operator^ + (const valarray<T>&, const valarray<T>&); +T template<class T> valarray<T> operator^ (const valarray<T>&, const T&); +T template<class T> valarray<T> operator^ (const T&, const valarray<T>&); +T template<class T> valarray<T> operator& + (const valarray<T>&, const valarray<T>&); +T template<class T> valarray<T> operator& (const valarray<T>&, const T&); +T template<class T> valarray<T> operator& (const T&, const valarray<T>&); +T template<class T> valarray<T> operator| + (const valarray<T>&, const valarray<T>&); +T template<class T> valarray<T> operator| (const valarray<T>&, const T&); +T template<class T> valarray<T> operator| (const T&, const valarray<T>&); +T template<class T> valarray<T> operator<< + (const valarray<T>&, const valarray<T>&); +T template<class T> valarray<T> operator<<(const valarray<T>&, const T&); +T template<class T> valarray<T> operator<<(const T&, const valarray<T>&); +T template<class T> valarray<T> operator>> + (const valarray<T>&, const valarray<T>&); +T template<class T> valarray<T> operator>>(const valarray<T>&, const T&); +T template<class T> valarray<T> operator>>(const T&, const valarray<T>&); +T template<class T> valarray<bool> operator&& + (const valarray<T>&, const valarray<T>&); +T template<class T> valarray<bool> operator&&(const valarray<T>&, const T&); +T template<class T> valarray<bool> operator&&(const T&, const valarray<T>&); +T template<class T> valarray<bool> operator|| + (const valarray<T>&, const valarray<T>&); +T template<class T> valarray<bool> operator||(const valarray<T>&, const T&); +T template<class T> valarray<bool> operator||(const T&, const valarray<T>&); + +T template<class T> + valarray<bool> operator==(const valarray<T>&, const valarray<T>&); +T template<class T> valarray<bool> operator==(const valarray<T>&, const T&); +T template<class T> valarray<bool> operator==(const T&, const valarray<T>&); +T template<class T> + valarray<bool> operator!=(const valarray<T>&, const valarray<T>&); +T template<class T> valarray<bool> operator!=(const valarray<T>&, const T&); +T template<class T> valarray<bool> operator!=(const T&, const valarray<T>&); +T template<class T> + valarray<bool> operator< (const valarray<T>&, const valarray<T>&); +T template<class T> valarray<bool> operator< (const valarray<T>&, const T&); +T template<class T> valarray<bool> operator< (const T&, const valarray<T>&); +T template<class T> + valarray<bool> operator> (const valarray<T>&, const valarray<T>&); +T template<class T> valarray<bool> operator> (const valarray<T>&, const T&); +T template<class T> valarray<bool> operator> (const T&, const valarray<T>&); +T template<class T> + valarray<bool> operator<=(const valarray<T>&, const valarray<T>&); +T template<class T> valarray<bool> operator<=(const valarray<T>&, const T&); +T template<class T> valarray<bool> operator<=(const T&, const valarray<T>&); +T template<class T> + valarray<bool> operator>=(const valarray<T>&, const valarray<T>&); +T template<class T> valarray<bool> operator>=(const valarray<T>&, const T&); +T template<class T> valarray<bool> operator>=(const T&, const valarray<T>&); +T template<class T> valarray<T> abs (const valarray<T>&); +T template<class T> valarray<T> acos (const valarray<T>&); +T template<class T> valarray<T> asin (const valarray<T>&); +T template<class T> valarray<T> atan (const valarray<T>&); +T template<class T> valarray<T> atan2 + (const valarray<T>&, const valarray<T>&); +T template<class T> valarray<T> atan2(const valarray<T>&, const T&); +T template<class T> valarray<T> atan2(const T&, const valarray<T>&); +T template<class T> valarray<T> cos (const valarray<T>&); +T template<class T> valarray<T> cosh (const valarray<T>&); +T template<class T> valarray<T> exp (const valarray<T>&); +T template<class T> valarray<T> log (const valarray<T>&); +T template<class T> valarray<T> log10(const valarray<T>&); +T template<class T> valarray<T> pow(const valarray<T>&, const valarray<T>&); +T template<class T> valarray<T> pow(const valarray<T>&, const T&); +T template<class T> valarray<T> pow(const T&, const valarray<T>&); +T template<class T> valarray<T> sin (const valarray<T>&); +T template<class T> valarray<T> sinh (const valarray<T>&); +T template<class T> valarray<T> sqrt (const valarray<T>&); +T template<class T> valarray<T> tan (const valarray<T>&); +T template<class T> valarray<T> tanh (const valarray<T>&); + } + + + 26.3.2 Template class valarray [lib.template.valarray] + +T template<class T> class valarray { + public: +T typedef T value_type; + + // _lib.valarray.cons_ construct/destroy: +T valarray(); +T explicit valarray(size_t); +T valarray(const T&, size_t); +T valarray(const T*, size_t); +T valarray(const valarray&); +T valarray(const slice_array<T>&); +T valarray(const gslice_array<T>&); +T valarray(const mask_array<T>&); +T valarray(const indirect_array<T>&); +T ~valarray(); + + // _lib.valarray.assign_ assignment: +T valarray<T>& operator=(const valarray<T>&); +T valarray<T>& operator=(const T&); +T valarray<T>& operator=(const slice_array<T>&); +T valarray<T>& operator=(const gslice_array<T>&); +T valarray<T>& operator=(const mask_array<T>&); +T valarray<T>& operator=(const indirect_array<T>&); + // _lib.valarray.access_ element access: +T T operator[](size_t) const; +T T& operator[](size_t); + // _lib.valarray.sub_ subset operations: +T valarray<T> operator[](slice) const; +T slice_array<T> operator[](slice); +T valarray<T> operator[](const gslice&) const; +T gslice_array<T> operator[](const gslice&); +T valarray<T> operator[](const valarray<bool>&) const; +T mask_array<T> operator[](const valarray<bool>&); +T valarray<T> operator[](const valarray<size_t>&) const; +T indirect_array<T> operator[](const valarray<size_t>&); + // _lib.valarray.unary_ unary operators: +T valarray<T> operator+() const; +T valarray<T> operator-() const; +T valarray<T> operator~() const; +T valarray<T> operator!() const; + // _lib.valarray.cassign_ computed assignment: +T valarray<T>& operator*= (const T&); +T valarray<T>& operator/= (const T&); +T valarray<T>& operator%= (const T&); +T valarray<T>& operator+= (const T&); +T valarray<T>& operator-= (const T&); +T valarray<T>& operator^= (const T&); +T valarray<T>& operator&= (const T&); +T valarray<T>& operator|= (const T&); +T valarray<T>& operator<<=(const T&); +T valarray<T>& operator>>=(const T&); +T valarray<T>& operator*= (const valarray<T>&); +T valarray<T>& operator/= (const valarray<T>&); +T valarray<T>& operator%= (const valarray<T>&); +T valarray<T>& operator+= (const valarray<T>&); +T valarray<T>& operator-= (const valarray<T>&); +T valarray<T>& operator^= (const valarray<T>&); +T valarray<T>& operator|= (const valarray<T>&); +T valarray<T>& operator&= (const valarray<T>&); +T valarray<T>& operator<<=(const valarray<T>&); +T valarray<T>& operator>>=(const valarray<T>&); + // _lib.valarray.members_ member functions: +T size_t size() const; +T T sum() const; +T T min() const; +T T max() const; + +T valarray<T> shift (int) const; +T valarray<T> cshift(int) const; +T valarray<T> apply(T func(T)) const; +T valarray<T> apply(T func(const T&)) const; +T void resize(size_t sz, T c = T()); + }; + } + + + + 26.3.4 Class slice [lib.class.slice] + +T class slice { + public: +T slice(); +T slice(size_t, size_t, size_t); + +T size_t start() const; +T size_t size() const; +T size_t stride() const; + }; + } + + + + 26.3.5 Template class slice_array [lib.template.slice.array] + +T template <class T> class slice_array { + public: +T typedef T value_type; + +T void operator= (const valarray<T>&) const; +T void operator*= (const valarray<T>&) const; +T void operator/= (const valarray<T>&) const; +T void operator%= (const valarray<T>&) const; +T void operator+= (const valarray<T>&) const; +T void operator-= (const valarray<T>&) const; +T void operator^= (const valarray<T>&) const; +T void operator&= (const valarray<T>&) const; +T void operator|= (const valarray<T>&) const; +T void operator<<=(const valarray<T>&) const; +T void operator>>=(const valarray<T>&) const; +T void operator=(const T&); +T ~slice_array(); + private: +T slice_array(); +T slice_array(const slice_array&); +T slice_array& operator=(const slice_array&); + }; + } + + + + 26.3.6 The gslice class [lib.class.gslice] + +T class gslice { + public: +T gslice(); +T gslice(size_t s, const valarray<size_t>& l, const valarray<size_t>& d); + +T size_t start() const; +T valarray<size_t> size() const; +T valarray<size_t> stride() const; + }; + + + 26.3.7 Template class gslice_array [lib.template.gslice.array] + +T template <class T> class gslice_array { + public: +T typedef T value_type; + +T void operator= (const valarray<T>&) const; +T void operator*= (const valarray<T>&) const; +T void operator/= (const valarray<T>&) const; +T void operator%= (const valarray<T>&) const; +T void operator+= (const valarray<T>&) const; +T void operator-= (const valarray<T>&) const; +T void operator^= (const valarray<T>&) const; +T void operator&= (const valarray<T>&) const; +T void operator|= (const valarray<T>&) const; +T void operator<<=(const valarray<T>&) const; +T void operator>>=(const valarray<T>&) const; +T void operator=(const T&); +T ~gslice_array(); + private: +T gslice_array(); +T gslice_array(const gslice_array&); +T gslice_array& operator=(const gslice_array&); + }; + + + 26.3.8 Template class mask_array [lib.template.mask.array] + +T template <class T> class mask_array { + public: +T typedef T value_type; + +T void operator= (const valarray<T>&) const; +T void operator*= (const valarray<T>&) const; +T void operator/= (const valarray<T>&) const; +T void operator%= (const valarray<T>&) const; +T void operator+= (const valarray<T>&) const; +T void operator-= (const valarray<T>&) const; +T void operator^= (const valarray<T>&) const; +T void operator&= (const valarray<T>&) const; +T void operator|= (const valarray<T>&) const; +T void operator<<=(const valarray<T>&) const; +T void operator>>=(const valarray<T>&) const; +T void operator=(const T&); +T ~mask_array(); + private: +T mask_array(); +T mask_array(const mask_array&); +T mask_array& operator=(const mask_array&); + // remainder implementation defined + }; + + + 26.3.9 Template class [lib.template.indirect.array] + indirect_array + +T template <class T> class indirect_array { + public: +T typedef T value_type; + +T void operator= (const valarray<T>&) const; +T void operator*= (const valarray<T>&) const; +T void operator/= (const valarray<T>&) const; +T void operator%= (const valarray<T>&) const; +T void operator+= (const valarray<T>&) const; +T void operator-= (const valarray<T>&) const; +T void operator^= (const valarray<T>&) const; +T void operator&= (const valarray<T>&) const; +T void operator|= (const valarray<T>&) const; +T void operator<<=(const valarray<T>&) const; +T void operator>>=(const valarray<T>&) const; +T void operator=(const T&); +T ~indirect_array(); + private: +T indirect_array(); +T indirect_array(const indirect_array&); +T indirect_array& operator=(const indirect_array&); + // remainder implementation defined + }; + + 26.4 Generalized numeric operations [lib.numeric.ops] + + Header <numeric> synopsis + +T template <class InputIterator, class T> + T accumulate(InputIterator first, InputIterator last, T init); + +T template <class InputIterator, class T, class BinaryOperation> + T accumulate(InputIterator first, InputIterator last, T init, + BinaryOperation binary_op); + +T template <class InputIterator1, class InputIterator2, class T> + T inner_product(InputIterator1 first1, InputIterator1 last1, + InputIterator2 first2, T init); + +T template <class InputIterator1, class InputIterator2, class T, + class BinaryOperation1, class BinaryOperation2> + T inner_product(InputIterator1 first1, InputIterator1 last1, + InputIterator2 first2, T init, + BinaryOperation1 binary_op1, + BinaryOperation2 binary_op2); + +T template <class InputIterator, class OutputIterator> + OutputIterator partial_sum(InputIterator first, + InputIterator last, + OutputIterator result); + +T template <class InputIterator, class OutputIterator, + class BinaryOperation> + OutputIterator partial_sum(InputIterator first, + InputIterator last, + OutputIterator result, + BinaryOperation binary_op); + +T template <class InputIterator, class OutputIterator> + OutputIterator adjacent_difference(InputIterator first, + InputIterator last, + OutputIterator result); + +T template <class InputIterator, class OutputIterator, + class BinaryOperation> + OutputIterator adjacent_difference(InputIterator first, + InputIterator last, + OutputIterator result, + BinaryOperation binary_op); + + + 26.5 C Library [lib.c.math] + + Table 2--Header <cmath> synopsis +X Macro: HUGE_VAL + Functions: +X acos cos fmod modf tan +X asin cosh frexp pow tanh +X atan exp ldexp sin +X atan2 fabs log sinh +X ceil floor log10 sqrt + + Table 3--Header <cstdlib> synopsis +X Macros: RAND_MAX +X Types: div_t ldiv_t + Functions: +X abs labs srand +X div ldiv rand + +X long abs(long); // labs() +X ldiv_t div(long, long); // ldiv() + +X float abs (float); +X float acos (float); +X float asin (float); +X float atan (float); +X float atan2(float, float); +X float ceil (float); +X float cos (float); +X float cosh (float); +X float exp (float); +X float fabs (float); +X float floor(float); +X float fmod (float, float); +X float frexp(float, int*); +X float ldexp(float, int); +X float log (float); +X float log10(float); +X float modf (float, float*); +X float pow (float, float); +X float pow (float, int); +X float sin (float); +X float sinh (float); +X float sqrt (float); +X float tan (float); +X float tanh (float); + +X double abs(double); // fabs() +X double pow(double, int); + +X long double abs (long double); +X long double acos (long double); +X long double asin (long double); +X long double atan (long double); +X long double atan2(long double, long double); +X long double ceil (long double); +X long double cos (long double); +X long double cosh (long double); +X long double exp (long double); +X long double fabs (long double); +X long double floor(long double); +X long double fmod (long double, long double); +X long double frexp(long double, int*); +X long double ldexp(long double, int); +X long double log (long double); +X long double log10(long double); +X long double modf (long double, long double*); +X long double pow (long double, long double); +X long double pow (long double, int); +X long double sin (long double); +X long double sinh (long double); +X long double sqrt (long double); +X long double tan (long double); +X long double tanh (long double); + + Header <iosfwd> synopsis + +X template<class charT> class char_traits; +X template<> class char_traits<char>; +X template<> class char_traits<wchar_t>; +X template<class T> class allocator; +X template <class charT, class traits = char_traits<charT> > + class basic_ios; + +X template <class charT, class traits = char_traits<charT> > + class basic_streambuf; + +X template <class charT, class traits = char_traits<charT> > + class basic_istream; + +X template <class charT, class traits = char_traits<charT> > + class basic_ostream; + +X template <class charT, class traits = char_traits<charT> > + class basic_iostream; + +X template <class charT, class traits = char_traits<charT>, + class Allocator = allocator<charT> > + class basic_stringbuf; + +X template <class charT, class traits = char_traits<charT>, + class Allocator = allocator<charT> > + class basic_istringstream; + +X template <class charT, class traits = char_traits<charT>, + class Allocator = allocator<charT> > + class basic_ostringstream; + +X template <class charT, class traits = char_traits<charT>, + class Allocator = allocator<charT> > + class basic_stringstream; + +X template <class charT, class traits = char_traits<charT> > + class basic_filebuf; + +X template <class charT, class traits = char_traits<charT> > + class basic_ifstream; + +X template <class charT, class traits = char_traits<charT> > + class basic_ofstream; + +X template <class charT, class traits = char_traits<charT> > + class basic_fstream; +X template <class charT, class traits = char_traits<charT> > + class istreambuf_iterator; + +X template <class charT, class traits = char_traits<charT> > + class ostreambuf_iterator; +X typedef basic_ios<char> ios; +X typedef basic_ios<wchar_t> wios; +X typedef basic_streambuf<char> streambuf; +X typedef basic_istream<char> istream; +X typedef basic_ostream<char> ostream; +X typedef basic_iostream<char> iostream; +X typedef basic_stringbuf<char> stringbuf; +X typedef basic_istringstream<char> istringstream; +X typedef basic_ostringstream<char> ostringstream; +X typedef basic_stringstream<char> stringstream; +X typedef basic_filebuf<char> filebuf; +X typedef basic_ifstream<char> ifstream; +X typedef basic_ofstream<char> ofstream; +X typedef basic_fstream<char> fstream; +X typedef basic_streambuf<wchar_t> wstreambuf; +X typedef basic_istream<wchar_t> wistream; +X typedef basic_ostream<wchar_t> wostream; +X typedef basic_iostream<wchar_t> wiostream; +X typedef basic_stringbuf<wchar_t> wstringbuf; +X typedef basic_istringstream<wchar_t> wistringstream; +X typedef basic_ostringstream<wchar_t> wostringstream; +X typedef basic_stringstream<wchar_t> wstringstream; + +X typedef basic_filebuf<wchar_t> wfilebuf; +X typedef basic_ifstream<wchar_t> wifstream; +X typedef basic_ofstream<wchar_t> wofstream; +X typedef basic_fstream<wchar_t> wfstream; +X template <class state> class fpos; +X typedef fpos<char_traits<char>::state_type> streampos; +X typedef fpos<char_traits<wchar_t>::state_type> wstreampos; + + 27.3 Standard iostream objects [lib.iostream.objects] + + Header <iostream> synopsis + +T [must also include <istream> and <ostream>] +T extern istream cin; +T extern ostream cout; +T extern ostream cerr; +T extern ostream clog; + +T extern wistream wcin; +T extern wostream wcout; +T extern wostream wcerr; +T extern wostream wclog; + + 27.4 Iostreams base classes [lib.iostreams.base] + + Header <ios> synopsis + + #include <iosfwd> + +T typedef OFF_T streamoff; +T typedef SZ_T streamsize; +T template <class stateT> class fpos; + + class ios_base; + template <class charT, class traits = char_traits<charT> > + class basic_ios; + // _lib.std.ios.manip_, manipulators: +T ios_base& boolalpha (ios_base& str); +T ios_base& noboolalpha(ios_base& str); +T ios_base& showbase (ios_base& str); +T ios_base& noshowbase (ios_base& str); +T ios_base& showpoint (ios_base& str); +T ios_base& noshowpoint(ios_base& str); +T ios_base& showpos (ios_base& str); +T ios_base& noshowpos (ios_base& str); +T ios_base& skipws (ios_base& str); +T ios_base& noskipws (ios_base& str); +T ios_base& nouppercase(ios_base& str); +T ios_base& uppercase (ios_base& str); +M ios_base& unitbuf (ios_base& str); +M ios_base& nounitbuf (ios_base& str); + // _lib.adjustfield.manip_ adjustfield: +T ios_base& internal (ios_base& str); +T ios_base& left (ios_base& str); +T ios_base& right (ios_base& str); + // _lib.basefield.manip_ basefield: +T ios_base& dec (ios_base& str); +T ios_base& hex (ios_base& str); +T ios_base& oct (ios_base& str); + + // _lib.floatfield.manip_ floatfield: +T ios_base& fixed (ios_base& str); +T ios_base& scientific (ios_base& str); + + + 27.4.2 Class ios_base [lib.ios.base] + +T class ios_base { + public: + class failure; +T typedef T1 fmtflags; +T static const fmtflags boolalpha; +T static const fmtflags dec; +T static const fmtflags fixed; +T static const fmtflags hex; +T static const fmtflags internal; +T static const fmtflags left; +T static const fmtflags oct; +T static const fmtflags right; +T static const fmtflags scientific; +T static const fmtflags showbase; +T static const fmtflags showpoint; +T static const fmtflags showpos; +T static const fmtflags skipws; +X static const fmtflags unitbuf; +T static const fmtflags uppercase; +T static const fmtflags adjustfield; +T static const fmtflags basefield; +T static const fmtflags floatfield; + + typedef T2 iostate; +T static const iostate badbit; +T static const iostate eofbit; +T static const iostate failbit; +T static const iostate goodbit; +T typedef T3 openmode; +T static const openmode app; +T static const openmode ate; +T static const openmode binary; +T static const openmode in; +T static const openmode out; +T static const openmode trunc; +T typedef T4 seekdir; +T static const seekdir beg; +T static const seekdir cur; +T static const seekdir end; +T class Init; + // _lib.fmtflags.state_ fmtflags state: +T fmtflags flags() const; +T fmtflags flags(fmtflags fmtfl); +T fmtflags setf(fmtflags fmtfl); +T fmtflags setf(fmtflags fmtfl, fmtflags mask); +T void unsetf(fmtflags mask); +T streamsize precision() const; +T streamsize precision(streamsize prec); +T streamsize width() const; +T streamsize width(streamsize wide); + // _lib.ios.base.locales_ locales: +T locale imbue(const locale& loc); +T locale getloc() const; + // _lib.ios.base.storage_ storage: +T static int xalloc(); +T long& iword(int index); +T void*& pword(int index); + // destructor +T virtual ~ios_base(); + // _lib.ios.base.callback_ callbacks; +T enum event { erase_event, imbue_event, copyfmt_event }; +T typedef void (*event_callback)(event, ios_base&, int index); +T void register_callback(event_call_back fn, int index); +T static bool sync_with_stdio(bool sync = true); + protected: +T ios_base(); + }; + + 27.4.2.1.1 Class ios_base::failure [lib.ios::failure] + +T class ios_base::failure : public exception { + public: +T explicit failure(const string& msg); +T virtual ~failure(); +T virtual const char* what() const throw(); + }; + + + 27.4.2.1.6 Class ios_base::Init [lib.ios::Init] + +T class ios_base::Init { + public: +T Init(); +T ~Init(); + }; + + + 27.4.3 Template class fpos [lib.fpos] + +X template <class stateT> class fpos { + public: + // _lib.fpos.members_ Members +T stateT state() const; +T void state(stateT); + private; +T stateT st; // exposition only + }; + + + 27.4.5 Template class basic_ios [lib.ios] + + template <class charT, class traits = char_traits<charT> > +X class basic_ios : public ios_base { + public: + + // Types: +T typedef charT char_type; +T typedef typename traits::int_type int_type; +T typedef typename traits::pos_type pos_type; +T typedef typename traits::off_type off_type; +T typedef traits traits_type; +T operator void*() const +T bool operator!() const +T iostate rdstate() const; +T void clear(iostate state = goodbit); +T void setstate(iostate state); +T bool good() const; +T bool eof() const; +T bool fail() const; +T bool bad() const; +T iostate exceptions() const; +T void exceptions(iostate except); + // _lib.basic.ios.cons_ Constructor/destructor: +T explicit basic_ios(basic_streambuf<charT,traits>* sb); +T virtual ~basic_ios(); + // _lib.basic.ios.members_ Members: +T basic_ostream<charT,traits>* tie() const; +T basic_ostream<charT,traits>* tie(basic_ostream<charT,traits>* tiestr); +T basic_streambuf<charT,traits>* rdbuf() const; +T basic_streambuf<charT,traits>* rdbuf(basic_streambuf<charT,traits>* sb); +X basic_ios& copyfmt(const basic_ios& rhs); +T char_type fill() const; +T char_type fill(char_type ch); + // _lib.ios.base.locales_ locales: +T locale imbue(const locale& loc); +X char narrow(char_type c, char dfault) const; +X char_type widen(char c) const; + protected: + basic_ios(); +T void init(basic_streambuf<charT,traits>* sb); + private: +T basic_ios(const basic_ios& ); // not defined +T basic_ios& operator=(const basic_ios&); // not defined + }; + + + 27.5 Stream buffers [lib.stream.buffers] + + Header <streambuf> synopsis + +X template <class charT, class traits = char_traits<charT> > + class basic_streambuf; +T typedef basic_streambuf<char> streambuf; +T typedef basic_streambuf<wchar_t> wstreambuf; + + 27.5.2 Template class [lib.streambuf] + basic_streambuf<charT,traits> + + template <class charT, class traits = char_traits<charT> > +X class basic_streambuf { + public: + + // Types: +T typedef charT char_type; +T typedef typename traits::int_type int_type; +T typedef typename traits::pos_type pos_type; +T typedef typename traits::off_type off_type; +T typedef traits traits_type; +T virtual ~basic_streambuf(); + // _lib.streambuf.locales_ locales: +T locale pubimbue(const locale &loc); +T locale getloc() const; + // _lib.streambuf.buffer_ buffer and positioning: +T basic_streambuf<char_type,traits>* + pubsetbuf(char_type* s, streamsize n); +T pos_type pubseekoff(off_type off, ios_base::seekdir way, + ios_base::openmode which = + ios_base::in | ios_base::out); +T pos_type pubseekpos(pos_type sp, + ios_base::openmode which = + ios_base::in | ios_base::out); +T int pubsync(); + + // Get and put areas: + // _lib.streambuf.pub.get_ Get area: +T streamsize in_avail(); +T int_type snextc(); +T int_type sbumpc(); +T int_type sgetc(); +T streamsize sgetn(char_type* s, streamsize n); + // _lib.streambuf.pub.pback_ Putback: +X int_type sputbackc(char_type c); +X int_type sungetc(); + // _lib.streambuf.pub.put_ Put area: +T int_type sputc(char_type c); +X streamsize sputn(const char_type* s, streamsize n); + protected: +T basic_streambuf(); + // _lib.streambuf.get.area_ Get area: +T char_type* eback() const; +T char_type* gptr() const; +T char_type* egptr() const; +T void gbump(int n); +T void setg(char_type* gbeg, char_type* gnext, char_type* gend); + // _lib.streambuf.put.area_ Put area: +T char_type* pbase() const; +T char_type* pptr() const; +T char_type* epptr() const; +T void pbump(int n); +T void setp(char_type* pbeg, char_type* pend); + // _lib.streambuf.virtuals_ virtual functions: + // _lib.streambuf.virt.locales_ Locales: +T virtual void imbue(const locale &loc); + // _lib.streambuf.virt.buffer_ Buffer management and positioning: +T virtual basic_streambuf<char_type,traits>* + setbuf(char_type* s, streamsize n); +T virtual pos_type seekoff(off_type off, ios_base::seekdir way, + ios_base::openmode which = ios_base::in | ios_base::out); +T virtual pos_type seekpos(pos_type sp, + ios_base::openmode which = ios_base::in | ios_base::out); +T virtual int sync(); + // _lib.streambuf.virt.get_ Get area: +T virtual int showmanyc(); +T virtual streamsize xsgetn(char_type* s, streamsize n); +T virtual int_type underflow(); +T virtual int_type uflow(); + // _lib.streambuf.virt.pback_ Putback: +T virtual int_type pbackfail(int_type c = traits::eof()); + // _lib.streambuf.virt.put_ Put area: +X virtual streamsize xsputn(const char_type* s, streamsize n); +T virtual int_type overflow (int_type c = traits::eof()); + }; + + 27.6 Formatting and manipulators [lib.iostream.format] + + Header <istream> synopsis + +T template <class charT, class traits = char_traits<charT> > + class basic_istream; +T typedef basic_istream<char> istream; +T typedef basic_istream<wchar_t> wistream; + +T template <class charT, class traits = char_traits<charT> > + class basic_iostream; +T typedef basic_iostream<char> iostream; +T typedef basic_iostream<wchar_t> wiostream; + +X template <class charT, class traits> + basic_istream<charT,traits>& ws(basic_istream<charT,traits>& is); + + Header <ostream> synopsis + +X template <class charT, class traits = char_traits<charT> > + class basic_ostream; +T typedef basic_ostream<char> ostream; +T typedef basic_ostream<wchar_t> wostream; + +T template <class charT, class traits> + basic_ostream<charT,traits>& endl(basic_ostream<charT,traits>& os); +T template <class charT, class traits> + basic_ostream<charT,traits>& ends(basic_ostream<charT,traits>& os); +T template <class charT, class traits> + basic_ostream<charT,traits>& flush(basic_ostream<charT,traits>& os); + + Header <iomanip> synopsis + + // Types T1, T2, ... are unspecified implementation types +T T1 resetiosflags(ios_base::fmtflags mask); +T T2 setiosflags (ios_base::fmtflags mask); +T T3 setbase(int base); +T template<charT> T4 setfill(charT c); +T T5 setprecision(int n); +T T6 setw(int n); + + + 27.6.1.1 Template class basic_istream [lib.istream] + + template <class charT, class traits = char_traits<charT> > +T class basic_istream : virtual public basic_ios<charT,traits> { + public: + // Types (inherited from basic_ios (_lib.ios_)): +T typedef charT char_type; +T typedef typename traits::int_type int_type; +T typedef typename traits::pos_type pos_type; +T typedef typename traits::off_type off_type; +T typedef traits traits_type; + // _lib.istream.cons_ Constructor/destructor: +T explicit basic_istream(basic_streambuf<charT,traits>* sb); +T virtual ~basic_istream(); + // _lib.istream::sentry_ Prefix/suffix: +T class sentry; + + // _lib.istream.formatted_ Formatted input: +T basic_istream<charT,traits>& operator>> + (basic_istream<charT,traits>& (*pf)(basic_istream<charT,traits>&)) +T basic_istream<charT,traits>& operator>> + (basic_ios<charT,traits>& (*pf)(basic_ios<charT,traits>&)) +T basic_istream<charT,traits>& operator>> + (ios_base& (*pf)(ios_base&)) +S basic_istream<charT,traits>& operator>>(bool& n); +S basic_istream<charT,traits>& operator>>(short& n); +S basic_istream<charT,traits>& operator>>(unsigned short& n); +S basic_istream<charT,traits>& operator>>(int& n); +S basic_istream<charT,traits>& operator>>(unsigned int& n); +S basic_istream<charT,traits>& operator>>(long& n); +S basic_istream<charT,traits>& operator>>(unsigned long& n); +S basic_istream<charT,traits>& operator>>(float& f); +S basic_istream<charT,traits>& operator>>(double& f); +S basic_istream<charT,traits>& operator>>(long double& f); +S basic_istream<charT,traits>& operator>>(void*& p); +S basic_istream<charT,traits>& operator>> + (basic_streambuf<char_type,traits>* sb); + // _lib.istream.unformatted_ Unformatted input: +T streamsize gcount() const; +S int_type get(); +S basic_istream<charT,traits>& get(char_type& c); +S basic_istream<charT,traits>& get(char_type* s, streamsize n); +S basic_istream<charT,traits>& get(char_type* s, streamsize n, + char_type delim); +S basic_istream<charT,traits>& get(basic_streambuf<char_type,traits>& sb); +S basic_istream<charT,traits>& get(basic_streambuf<char_type,traits>& sb, + char_type delim); +S basic_istream<charT,traits>& getline(char_type* s, streamsize n); +S basic_istream<charT,traits>& getline(char_type* s, streamsize n, + char_type delim); +S basic_istream<charT,traits>& ignore + (streamsize n = 1, int_type delim = traits::eof()); +S int_type peek(); +S basic_istream<charT,traits>& read (char_type* s, streamsize n); +S streamsize readsome(char_type* s, streamsize n); +S basic_istream<charT,traits>& putback(char_type c); +S basic_istream<charT,traits>& unget(); +S int sync(); + +S pos_type tellg(); +S basic_istream<charT,traits>& seekg(pos_type); +S basic_istream<charT,traits>& seekg(off_type, ios_base::seekdir); + }; + + // _lib.istream::extractors_ character extraction templates: +S template<class charT, class traits> + basic_istream<charT,traits>& operator>>(basic_istream<charT,traits>&, + charT&); +S template<class traits> + basic_istream<char,traits>& operator>>(basic_istream<char,traits>&, + unsigned char&); +S template<class traits> + basic_istream<char,traits>& operator>>(basic_istream<char,traits>&, + signed char&); + +S template<class charT, class traits> + basic_istream<charT,traits>& operator>>(basic_istream<charT,traits>&, + charT*); +S template<class traits> + basic_istream<char,traits>& operator>>(basic_istream<char,traits>&, + unsigned char*); +S template<class traits> + basic_istream<char,traits>& operator>>(basic_istream<char,traits>&, + signed char*); + + 27.6.1.1.2 Class basic_istream::sentry [lib.istream::sentry] + + + template <class charT,class traits = char_traits<charT> > +S class basic_istream<charT,traits>::sentry { + typedef traits traits_type; +S bool ok_; // exposition only + public: +S explicit sentry(basic_istream<charT,traits>& is, bool noskipws = false); +S ~sentry(); +S operator bool() const { return ok_; } + private: +T sentry(const sentry&); // not defined +T sentry& operator=(const sentry&); // not defined + }; + + + 27.6.1.5 Template class basic_iostream [lib.iostreamclass] + + template <class charT, class traits = char_traits<charT> > +T class basic_iostream : + public basic_istream<charT,traits>, + public basic_ostream<charT,traits> { + public: + // constructor/destructor +T explicit basic_iostream(basic_streambuf<charT,traits>* sb); +T virtual ~basic_iostream(); + }; + + + 27.6.2.1 Template class basic_ostream [lib.ostream] + + template <class charT, class traits = char_traits<charT> > +X class basic_ostream : virtual public basic_ios<charT,traits> { + public: + // Types (inherited from basic_ios (_lib.ios_)): +T typedef charT char_type; +T typedef typename traits::int_type int_type; +T typedef typename traits::pos_type pos_type; +T typedef typename traits::off_type off_type; +T typedef traits traits_type; + // _lib.ostream.cons_ Constructor/destructor: +T explicit basic_ostream(basic_streambuf<char_type,traits>* sb); +T virtual ~basic_ostream(); + // _lib.ostream::sentry_ Prefix/suffix: +T class sentry; + // _lib.ostream.formatted_ Formatted output: +T basic_ostream<charT,traits>& operator<< + (basic_ostream<charT,traits>& (*pf)(basic_ostream<charT,traits>&)); +T basic_ostream<charT,traits>& operator<< + (basic_ios<charT,traits>& (*pf)(basic_ios<charT,traits>&)); +T basic_ostream<charT,traits>& operator<< + (ios_base& (*pf)(ios_base&)); +T basic_ostream<charT,traits>& operator<<(bool n); +T basic_ostream<charT,traits>& operator<<(short n); +T basic_ostream<charT,traits>& operator<<(unsigned short n); +T basic_ostream<charT,traits>& operator<<(int n); +T basic_ostream<charT,traits>& operator<<(unsigned int n); +T basic_ostream<charT,traits>& operator<<(long n); +T basic_ostream<charT,traits>& operator<<(unsigned long n); +S basic_ostream<charT,traits>& operator<<(float f); +S basic_ostream<charT,traits>& operator<<(double f); +S basic_ostream<charT,traits>& operator<<(long double f); +T basic_ostream<charT,traits>& operator<<(const void* p); +X basic_ostream<charT,traits>& operator<< + (basic_streambuf<char_type,traits>* sb); + // _lib.ostream.unformatted_ Unformatted output: +T basic_ostream<charT,traits>& put(char_type c); +T basic_ostream<charT,traits>& write(const char_type* s, streamsize n); +X basic_ostream<charT,traits>& flush(); + + // _lib.ostream.seeks_ seeks: +S pos_type tellp(); +S basic_ostream<charT,traits>& seekp(pos_type); +S basic_ostream<charT,traits>& seekp(off_type, ios_base::seekdir); + }; + // _lib.ostream.inserters.character_ character inserters +X template<class charT, class traits> + basic_ostream<charT,traits>& operator<<(basic_ostream<charT,traits>&, + charT); +X template<class charT, class traits> + basic_ostream<charT,traits>& operator<<(basic_ostream<charT,traits>&, + char); + // specialization +X template<class traits> + basic_ostream<char,traits>& operator<<(basic_ostream<char,traits>&, + char); + // signed and unsigned +X template<class traits> + basic_ostream<char,traits>& operator<<(basic_ostream<char,traits>&, + signed char); +X template<class traits> + basic_ostream<char,traits>& operator<<(basic_ostream<char,traits>&, + unsigned char) +X template<class charT, class traits> + basic_ostream<charT,traits>& operator<<(basic_ostream<charT,traits>&, + const charT*); +X template<class charT, class traits> + basic_ostream<charT,traits>& operator<<(basic_ostream<charT,traits>&, + const char*); + // partial specializationss +X template<class traits> + basic_ostream<char,traits>& operator<<(basic_ostream<char,traits>&, + const char*); + // signed and unsigned +X template<class traits> + basic_ostream<char,traits>& operator<<(basic_ostream<char,traits>&, + const signed char*); +X template<class traits> + basic_ostream<char,traits>& operator<<(basic_ostream<char,traits>&, + const unsigned char*); + + + 27.6.2.3 Class basic_ostream::sentry [lib.ostream::sentry] + + template <class charT,class traits = char_traits<charT> > +X class basic_ostream<charT,traits>::sentry { + bool ok_; // exposition only + public: +X explicit sentry(basic_ostream<charT,traits>& os); +X ~sentry(); +X operator bool() const { return ok_; } + private +X sentry(const sentry&); // not defined +X sentry& operator=(const sentry&); // not defined + }; + + 27.7 String-based streams [lib.string.streams] + + Header <sstream> synopsis + +X template <class charT, class traits = char_traits<charT>, + class Allocator = allocator<charT> > + class basic_stringbuf; + +T typedef basic_stringbuf<char> stringbuf; +T typedef basic_stringbuf<wchar_t> wstringbuf; + + template <class charT, class traits = char_traits<charT>, + class Allocator = allocator<charT> > +X class basic_istringstream; + +T typedef basic_istringstream<char> istringstream; +T typedef basic_istringstream<wchar_t> wistringstream; + + template <class charT, class traits = char_traits<charT>, + class Allocator = allocator<charT> > +X class basic_ostringstream; +T typedef basic_ostringstream<char> ostringstream; +T typedef basic_ostringstream<wchar_t> wostringstream; + + template <class charT, class traits = char_traits<charT>, + class Allocator = allocator<charT> > +X class basic_stringstream; +T typedef basic_stringstream<char> stringstream; +T typedef basic_stringstream<wchar_t> wstringstream; + + 27.7.1 Template class basic_stringbuf [lib.stringbuf] + + template <class charT, class traits = char_traits<charT>, + class Allocator = allocator<charT> > +X class basic_stringbuf : public basic_streambuf<charT,traits> { + public: +T typedef charT char_type; +T typedef typename traits::int_type int_type; +T typedef typename traits::pos_type pos_type; +T typedef typename traits::off_type off_type; +T typedef traits traits_type; + // _lib.stringbuf.cons_ Constructors: +S explicit basic_stringbuf(ios_base::openmode which + = ios_base::in | ios_base::out); +S explicit basic_stringbuf + (const basic_string<charT,traits,Allocator>& str, + ios_base::openmode which = ios_base::in | ios_base::out); + // _lib.stringbuf.members_ Get and set: +S basic_string<charT,traits,Allocator> str() const; +S void str(const basic_string<charT,traits,Allocator>& s); + + protected: + // _lib.stringbuf.virtuals_ Overridden virtual functions: +S virtual int_type underflow(); +S virtual int_type pbackfail(int_type c = traits::eof()); +S virtual int_type overflow (int_type c = traits::eof()); +S virtual basic_streambuf<charT,traits>* setbuf(charT*, streamsize); + +S virtual pos_type seekoff(off_type off, ios_base::seekdir way, + ios_base::openmode which + = ios_base::in | ios_base::out); +S virtual pos_type seekpos(pos_type sp, + ios_base::openmode which + = ios_base::in | ios_base::out); + }; + + + 27.7.2 Template class basic_istringstream [lib.istringstream] + + template <class charT, class traits = char_traits<charT>, + class Allocator = allocator<charT> > +X class basic_istringstream : public basic_istream<charT,traits> { + public: +T typedef charT char_type; +T typedef typename traits::int_type int_type; +T typedef typename traits::pos_type pos_type; +T typedef typename traits::off_type off_type; +T typedef traits traits_type; + // _lib.istringstream.cons_ Constructors: +S explicit basic_istringstream(ios_base::openmode which = ios_base::in); +S explicit basic_istringstream( + const basic_string<charT,traits,Allocator>& str, + ios_base::openmode which = ios_base::in); + + // _lib.istringstream.members_ Members: +S basic_stringbuf<charT,traits,Allocator>* rdbuf() const; +S basic_string<charT,traits,Allocator> str() const; +S void str(const basic_string<charT,traits,Allocator>& s); + private: + // basic_stringbuf<charT,traits,Allocator> sb; exposition only + }; + + 27.7.3 Class basic_ostringstream [lib.ostringstream] + + template <class charT, class traits = char_traits<charT>, + class Allocator = allocator<charT> > +X class basic_ostringstream : public basic_ostream<charT,traits> { + public: + + // Types: +T typedef charT char_type; +T typedef typename traits::int_type int_type; +T typedef typename traits::pos_type pos_type; +T typedef typename traits::off_type off_type; + // _lib.ostringstream.cons_ Constructors/destructor: +S explicit basic_ostringstream(ios_base::openmode which = ios_base::out); +S explicit basic_ostringstream( + const basic_string<charT,traits,Allocator>& str, + ios_base::openmode which = ios_base::out); + // _lib.ostringstream.members_ Members: +S basic_stringbuf<charT,traits,Allocator>* rdbuf() const; +S basic_string<charT,traits,Allocator> str() const; +S void str(const basic_string<charT,traits,Allocator>& s); + }; + + + 27.7.4 Template class basic_stringstream [lib.stringstream] + + template <class charT, class traits = char_traits<charT>, + class Allocator = allocator<charT> > +X class basic_stringstream + : public basic_iostream<charT,traits> { + public: + // Types +T typedef charT char_type; +T typedef typename traits::int_type int_type; +T typedef typename traits::pos_type pos_type; +T typedef typename traits::off_type off_type; + // constructors/destructors +S explicit basic_stringstream( + ios_base::openmode which = ios_base::out|ios_base::in); +S explicit basic_stringstream( + const basic_string<charT,traits,Allocator>& str, + ios_base::openmode which = ios_base::out|ios_base::in); + // Members: +S basic_stringbuf<charT,traits,Allocator>* rdbuf() const; +S basic_string<charT,traits,Allocator> str() const; +S void str(const basic_string<charT,traits,Allocator>& str); + }; + + + + 27.8.1 File streams [lib.fstreams] + + + Header <fstream> synopsis + +X template <class charT, class traits = char_traits<charT> > + class basic_filebuf; +T typedef basic_filebuf<char> filebuf; +T typedef basic_filebuf<wchar_t> wfilebuf; + +X template <class charT, class traits = char_traits<charT> > + class basic_ifstream; +T typedef basic_ifstream<char> ifstream; +T typedef basic_ifstream<wchar_t> wifstream; + +X template <class charT, class traits = char_traits<charT> > + class basic_ofstream; +T typedef basic_ofstream<char> ofstream; +T typedef basic_ofstream<wchar_t> wofstream; + +X template <class charT, class traits = char_traits<charT> > + class basic_fstream; +T typedef basic_fstream<char> fstream; +T typedef basic_fstream<wchar_t> wfstream; + + 27.8.1.1 Template class basic_filebuf [lib.filebuf] + + template <class charT, class traits = char_traits<charT> > +X class basic_filebuf : public basic_streambuf<charT,traits> { + public: +T typedef charT char_type; +T typedef typename traits::int_type int_type; +T typedef typename traits::pos_type pos_type; +T typedef typename traits::off_type off_type; +T typedef traits traits_type; + // _lib.filebuf.cons_ Constructors/destructor: +X basic_filebuf(); +X virtual ~basic_filebuf(); + // _lib.filebuf.members_ Members: +T bool is_open() const; +X basic_filebuf<charT,traits>* open + (const char* s, ios_base::openmode mode); +X basic_filebuf<charT,traits>* close(); + protected: + // _lib.filebuf.virtuals_ Overridden virtual functions: +X virtual streamsize showmanyc(); +X virtual int_type underflow(); +X virtual int_type uflow(); +X virtual int_type pbackfail(int_type c = traits::eof()); +X virtual int_type overflow (int_type c = traits::eof()); +S virtual basic_streambuf<charT,traits>* + setbuf(char_type* s, streamsize n); +S virtual pos_type seekoff(off_type off, ios_base::seekdir way, + ios_base::openmode which + = ios_base::in | ios_base::out); +S virtual pos_type seekpos(pos_type sp, ios_base::openmode which + = ios_base::in | ios_base::out); +S virtual int sync(); +S virtual void imbue(const locale& loc); + }; + + + + 27.8.1.5 Template class basic_ifstream [lib.ifstream] + + template <class charT, class traits = char_traits<charT> > +X class basic_ifstream : public basic_istream<charT,traits> { + public: +T typedef charT char_type; +T typedef typename traits::int_type int_type; +T typedef typename traits::pos_type pos_type; +T typedef typename traits::off_type off_type; +T typedef traits traits_type; + // _lib.ifstream.cons_ Constructors: +S basic_ifstream(); +S explicit basic_ifstream(const char* s, + ios_base::openmode mode = ios_base::in); + // _lib.ifstream.members_ Members: +S basic_filebuf<charT,traits>* rdbuf() const; +S bool is_open(); +S void open(const char* s, ios_base::openmode mode = ios_base::in); +S void close(); + }; + + + 27.8.1.8 Template class basic_ofstream [lib.ofstream] + + template <class charT, class traits = char_traits<charT> > +X class basic_ofstream : public basic_ostream<charT,traits> { + public: +T typedef charT char_type; +T typedef typename traits::int_type int_type; +T typedef typename traits::pos_type pos_type; +T typedef typename traits::off_type off_type; +T typedef traits traits_type; + // _lib.ofstream.cons_ Constructors: +X basic_ofstream(); +X explicit basic_ofstream(const char* s, + ios_base::openmode mode + = ios_base::out); + // _lib.ofstream.members_ Members: +X basic_filebuf<charT,traits>* rdbuf() const; +T bool is_open(); +X void open(const char* s, ios_base::openmode mode = ios_base::out); +X void close(); + }; + + + 27.8.1.11 Template class basic_fstream [lib.fstream] + + template <class charT, class traits=char_traits<charT> > +X class basic_fstream + : public basic_iostream<charT,traits> { + public: +T typedef charT char_type; +T typedef typename traits::int_type int_type; +T typedef typename traits::pos_type pos_type; +T typedef typename traits::off_type off_type; +T typedef traits traits_type; + // constructors/destructor +S basic_fstream(); +S explicit basic_fstream( + const char* s, + ios_base::openmode mode = ios_base::in|ios_base::out); + + // Members: +S basic_filebuf<charT,traits>* rdbuf() const; +S bool is_open(); +S void open( + const char* s, + ios_base::openmode mode = ios_base::in|ios_base::out); +S void close(); + }; + + + + 27.8.2 C Library files [lib.c.files] + + + Table 13--Header <cstdio> synopsis + Macros: +X BUFSIZ L_tmpnam SEEK_SET TMP_MAX +X EOF NULL <cstdio> stderr _IOFBF +X FILENAME_MAX SEEK_CUR stdin _IOLBF +X FOPEN_MAX SEEK_END stdout _IONBF + +X Types: FILE fpos_t size_t <cstdio> + Functions: +X clearerr fgets fscanf gets rewind +X fclose fopen fseek perror scanf tmpnam +X feof fprintf fsetpos printf setbuf ungetc +X ferror fputc ftell putc setvbuf vprintf +X fflush fputs fwrite puts sprintf vfprintf +X fgetc fread getc remove sscanf vsprintf +X fgetpos freopen getchar putchar rename tmpfile + + + + + 1.5 Standard C library headers [depr.c.headers] + +X <assert.h> <iso646.h> <setjmp.h> <stdio.h> <wchar.h> + <ctype.h> <limits.h> <signal.h> <stdlib.h> <wctype.h> + <errno.h> <locale.h> <stdarg.h> <string.h> + <float.h> <math.h> <stddef.h> <time.h> + + 1.6 Old iostreams members [depr.ios.members] + + [Note: these should be #ifdef'd to permit diagnostics if used.] + namespace std { + class ios_base { + public: +T typedef T1 io_state; +T typedef T2 open_mode; +T typedef T3 seek_dir; +T typedef OFF_T streamoff; +T typedef OFF_T streampos; + // remainder unchanged + }; + } + + [Note: these should be #ifdef'd to permit diagnostics if used.] + namespace std { + template<class charT, class traits = char_traits<charT> > + class basic_streambuf { + public: +T void stossc(); + // remainder unchanged + }; + } + + 8 An implementation may provide the following member functions that + overload signatures specified in clause _lib.iostreams_: + + [Note: the following overloads should be #ifdef'd to permit + diagnostics to be emitted, by default, if used.] + + template<class charT, class Traits> class basic_ios { + public: +M void clear(io_state state); +M void setstate(io_state state); + // remainder unchanged + }; + class ios_base { + public: +M void exceptions(io_state); + // remainder unchanged + }; + template<class charT, class traits = char_traits<charT> > + class basic_streambuf { + public: +M pos_type pubseekoff(off_type off, ios_base::seek_dir way, + ios_base::open_mode which = ios_base::in | ios_base::out); +M pos_type pubseekpos(pos_type sp, + ios_base::open_mode which = ios_base::in | ios_base::out); + // remainder unchanged + }; + template <class charT, class traits = char_traits<charT> > + class basic_filebuf : public basic_streambuf<charT,traits> { + public: +M basic_filebuf<charT,traits>* open + (const char* s, ios_base::open_mode mode); + // remainder unchanged + }; + template <class charT, class traits = char_traits<charT> > + class basic_ifstream : public basic_istream<charT,traits> { + public: +M void open(const char* s, ios_base::open_mode mode = in); + // remainder unchanged + }; + template <class charT, class traits = char_traits<charT> > + class basic_ofstream : public basic_ostream<charT,traits> { + public: +M void open(const char* s, ios_base::open_mode mode = out | trunc); + // remainder unchanged + }; + } + + + + 1.7.1 Class strstreambuf [depr.strstreambuf] + + [Note: It should be possible to adopt these components with only + minor changes from the 2.8 version of the library.] + +M class strstreambuf : public basic_streambuf<char> { + public: +M explicit strstreambuf(streamsize alsize_arg = 0); +M strstreambuf(void* (*palloc_arg)(size_t), void (*pfree_arg)(void*)); +M strstreambuf(char* gnext_arg, streamsize n, char* pbeg_arg = 0); +M strstreambuf(const char* gnext_arg, streamsize n); +M strstreambuf(signed char* gnext_arg, streamsize n, + signed char* pbeg_arg = 0); +M strstreambuf(const signed char* gnext_arg, streamsize n); +M strstreambuf(unsigned char* gnext_arg, streamsize n, + unsigned char* pbeg_arg = 0); +M strstreambuf(const unsigned char* gnext_arg, streamsize n); +M virtual ~strstreambuf(); +M void freeze(bool freezefl = true); +M char* str(); +M int pcount(); + protected: +M virtual int_type overflow (int_type c = EOF); +M virtual int_type pbackfail(int_type c = EOF); +M virtual int_type underflow(); +M virtual pos_type seekoff(off_type off, ios_base::seekdir way, + ios_base::openmode which + = ios_base::in | ios_base::out); +M virtual pos_type seekpos(pos_type sp, ios_base::openmode which + = ios_base::in | ios_base::out); +M virtual streambuf<char>* setbuf(char* s, streamsize n); + } + + 1.7.4 Class strstream [depr.strstream] + +M class strstream + : public basic_iostream<char> { + public: + // Types +M typedef char char_type; +M typedef typename char_traits<char>::int_type int_type +M typedef typename char_traits<char>::pos_type pos_type; +M typedef typename char_traits<char>::off_type off_type; + // consturctors/destructor +M strstream(); +M strstream(char* s, int n, + ios_base::openmode mode = ios_base::in|ios_base::out); +M virtual ~strstream(); + // Members: +M strstreambuf* rdbuf() const; +M void freeze(bool freezefl = true); +M int pcount() const; +M char* str(); + }; +</literallayout> + +</sect3> + + +<sect3 id="standard.1998.specific" xreflabel="Implementation Specific"> + <title>Implementation Specific Behavior</title> + + <para> + The ISO standard defines the following phrase: + </para> + <blockquote> + <variablelist> + <varlistentry> + <term> + <code>[1.3.5] implementation-defined behavior</code> + </term> + <listitem> + <para> + Behavior, for a well-formed program construct and correct data, that + depends on the implementation <emphasis>and that each implementation + shall document</emphasis>. + </para> + </listitem> + </varlistentry> + </variablelist> + </blockquote> + <para> + We do so here, for the C++ library only. Behavior of the + compiler, linker, runtime loader, and other elements of "the + implementation" are documented elsewhere. Everything listed + in Annex B, Implementation Qualities, are also part of the + compiler, not the library. + </para> + <para> + For each entry, we give the section number of the standard, when + applicable. This list is probably incomplet and inkorrekt. + </para> + <para> + <emphasis>[1.9]/11 #3</emphasis> If <code>isatty(3)</code> is true, then + interactive stream support is implied. + </para> + <para> + <emphasis>[17.4.4.5]</emphasis> Non-reentrant functions are probably best + discussed in the various sections on multithreading (see above). + </para> + <!-- [17.4.4.8]/3 says any function that doesn't have an exception-spec + can throw whatever we want; see also its footnote. Let's list those + in the sections where the function itself occurs. + --> + <para><emphasis>[18.1]/4</emphasis> The type of <code>NULL</code> is described + <ulink url="../18_support/howto.html#1">here</ulink>. + </para> + <para><emphasis>[18.3]/8</emphasis> Even though it's listed in the library + sections, libstdc++ has zero control over what the cleanup code hands + back to the runtime loader. Talk to the compiler people. :-) + </para> + <para><emphasis>[18.4.2.1]/5</emphasis> (bad_alloc), + <emphasis>[18.5.2]/5</emphasis> (bad_cast), + <emphasis>[18.5.3]/5</emphasis> (bad_typeid), + <emphasis>[18.6.1]/8</emphasis> (exception), + <emphasis>[18.6.2.1]/5</emphasis> (bad_exception): The <code>what()</code> + member function of class <code>std::exception</code>, and these other + classes publicly derived from it, simply returns the name of the + class. But they are the <emphasis>mangled</emphasis> names; you will need to call + <code>c++filt</code> and pass the names as command-line parameters to + demangle them, or call a + <ulink url="../18_support/howto.html#5">runtime demangler function</ulink>. + (The classes in <code><stdexcept></code> have constructors which + require an argument to use later for <code>what()</code> calls, so the + problem of <code>what()</code>'s value does not arise in most + user-defined exceptions.) + </para> + <para><emphasis>[18.5.1]/7</emphasis> The return value of + <code>std::type_info::name()</code> is the mangled type name (see the + previous entry for more). + </para> + <para><emphasis>[20.1.5]/5</emphasis> <emphasis>"Implementors are encouraged to + supply libraries that can accept allocators that encapsulate more + general memory models and that support non-equal instances. In such + implementations, any requirements imposed on allocators by containers + beyond those requirements that appear in Table 32, and the semantics + of containers and algorithms when allocator instances compare + non-equal, are implementation-defined."</emphasis> As yet we don't + have any allocators which compare non-equal, so we can't describe how + they behave. + </para> + <para><emphasis>[21.1.3.1]/3,4</emphasis>, + <emphasis>[21.1.3.2]/2</emphasis>, + <emphasis>[23.*]'s foo::iterator</emphasis>, + <emphasis>[27.*]'s foo::*_type</emphasis>, + <emphasis>others...</emphasis> + Nope, these types are called implementation-defined because you + shouldn't be taking advantage of their underlying types. Listing them + here would defeat the purpose. :-) + </para> + <para><emphasis>[21.1.3.1]/5</emphasis> I don't really know about the mbstate_t + stuff... see the <ulink url="../22_locale/howto.html">chapter 22 notes</ulink> + for what does exist. + </para> + <para><emphasis>[22.*]</emphasis> Anything and everything we have on locale + implementation will be described + <ulink url="../22_locale/howto.html">over here</ulink>. + </para> + <para><emphasis>[26.2.8]/9</emphasis> I have no idea what + <code>complex<T></code>'s pow(0,0) returns. + </para> + <para><emphasis>[27.4.2.4]/2</emphasis> Calling + <code>std::ios_base::sync_with_stdio</code> after I/O has already been + performed on the standard stream objects will + flush the buffers, and <!-- this line might go away --> + destroy and recreate the underlying buffer instances. Whether or not + the previously-written I/O is destroyed in this process depends mostly + on the --enable-libio choice: for stdio, if the written data is + already in the stdio buffer, the data may be completely safe! + </para> + <para><emphasis>[27.6.1.1.2]</emphasis>, + <emphasis>[27.6.2.3]</emphasis> The I/O sentry ctor and dtor can perform + additional work than the minimum required. We are not currently taking + advantage of this yet. + </para> + <para><emphasis>[27.7.1.3]/16</emphasis>, + <emphasis>[27.8.1.4]/10</emphasis> + The effects of <code>pubsetbuf/setbuf</code> are described + <ulink url="../27_io/howto.html#2">in this chapter</ulink>. + </para> + <para><emphasis>[27.8.1.4]/16</emphasis> Calling <code>fstream::sync</code> when + a get area exists will... whatever <code>fflush()</code> does, I think. + </para> + +</sect3> + +</sect2> diff --git a/libstdc++-v3/doc/xml/manual/status_cxx200x.xml b/libstdc++-v3/doc/xml/manual/status_cxx200x.xml new file mode 100644 index 00000000000..1c6460a5544 --- /dev/null +++ b/libstdc++-v3/doc/xml/manual/status_cxx200x.xml @@ -0,0 +1,2241 @@ +<sect2 id="manual.intro.status.standard.200x" xreflabel="Status C++ 200x"> +<?dbhtml filename="standard_cxx200x.html"?> + +<sect2info> + <keywordset> + <keyword> + ISO C++ + </keyword> + <keyword> + 200x + </keyword> + </keywordset> +</sect2info> + +<title>C++ 200x</title> + +<para> +This table is based on the table of contents of ISO/IEC +Doc No: N2461=07-0331 Date: 2007-10-22 +Working Draft, Standard for Programming Language C++ +</para> + +<para> +In this implementation <literal>-std=gnu++0x</literal> or +<literal>-std=c++0x</literal> flags must be used to enable language and +library features. The pre-defined symbol +<constant>__GXX_EXPERIMENTAL_CXX0X__</constant> is used to check for the +presence of the required flag. +</para> + +<para> +This page describes the C++0x support in mainline GCC SVN, not in any +particular release. +</para> + +<table frame='all'> +<title>C++ 200x Implementation Status</title> +<tgroup cols='6' align='left' colsep='1' rowsep='1'> +<colspec colname='c1'></colspec> +<colspec colname='c2'></colspec> +<colspec colname='c3'></colspec> +<colspec colname='c4'></colspec> +<colspec colname='c5'></colspec> +<colspec colname='c6'></colspec> + + <thead> + <row> + <entry>Section</entry> + <entry>Description</entry> + <entry>Done</entry> + <entry>Broken</entry> + <entry>Missing</entry> + <entry>Comments</entry> + </row> + </thead> + + <tbody> + <row> + <entry><emphasis>20</emphasis></entry> + <entry namest="c2" nameend="c6" align="left"><emphasis>General Utilities</emphasis></entry> + </row> + <row> + <entry>20.2</entry> + <entry>Utility Components</entry> + <entry></entry> + <entry></entry> + <entry>incomplete</entry> + <entry></entry> + </row> + <row> + <entry>20.2.1</entry> + <entry>Operators</entry> + <entry></entry> + <entry></entry> + <entry>partial</entry> + <entry></entry> + </row> + <row> + <entry>20.2.2</entry> + <entry>forward/move helpers</entry> + <entry></entry> + <entry></entry> + <entry>partial</entry> + <entry></entry> + </row> + <row> + <entry>20.2.3</entry> + <entry>Pairs</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + + <row> + <entry>20.3</entry> + <entry>Header <code><tuple></code> synopsis</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>20.3.1</entry> + <entry>Class template <code>tuple</code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>20.3.1.1</entry> + <entry>Construction</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>20.3.1.2</entry> + <entry>Tuple creation functions</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>20.3.1.3</entry> + <entry>Tuple helper classes</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>20.3.1.4</entry> + <entry>Element access</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>20.3.1.5</entry> + <entry>Relational operators</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + + <row> + <entry>20.4</entry> + <entry namest="c2" nameend="c6" align="left"><emphasis>Metaprogramming and type traits</emphasis></entry> + </row> + <row> + <entry>20.4.1</entry> + <entry>Requirements</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>20.4.2</entry> + <entry>Header <code><type_traits></code> synopsis</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>20.4.3</entry> + <entry>Helper classes</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>20.4.4</entry> + <entry>General Requirements</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>20.4.5</entry> + <entry>Unary Type Traits</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>20.4.5.1</entry> + <entry>Primary Type Categories</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>20.4.5.2</entry> + <entry>Composite type traits</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>20.4.5.3</entry> + <entry>Type properties</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>20.4.6</entry> + <entry>Relationships between types</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>20.4.7</entry> + <entry>Transformations between types</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>20.4.7.1</entry> + <entry>Const-volatile modifications</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>20.4.7.2</entry> + <entry>Reference modifications</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>20.4.7.3</entry> + <entry>Array modifications</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>20.4.7.4</entry> + <entry>Pointer modifications</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>20.4.8</entry> + <entry>Other transformations</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>20.4.9</entry> + <entry>Implementation requirements</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>20.5 </entry> + <entry>Function Objects</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>20.5</entry> + <entry>Additions to header <code><functional></code> synopsis</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>20.5.1</entry> + <entry>Definitions</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>20.5.2</entry> + <entry>Requirements</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>20.5.3</entry> + <entry>Base</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>20.5.4</entry> + <entry>Function return types</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>20.5.5</entry> + <entry>Class template <code>reference_wrapper</code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>20.5.5.1</entry> + <entry><code>reference_wrapper</code> construct/copy/destroy</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>20.5.5.2</entry> + <entry><code>reference_wrapper</code> assignment</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>20.5.5.3</entry> + <entry><code>reference_wrapper</code> access</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>20.5.5.4</entry> + <entry><code>reference_wrapper</code> invocation</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>20.5.5.5</entry> + <entry><code>reference_wrapper</code> helper functions</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>20.5.14</entry> + <entry>Function template <code>mem_fn</code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>20.5.11</entry> + <entry>Template function bind</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + + <row> + <entry>20.5.11.1</entry> + <entry>Function object binders</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>20.5.11.1.1</entry> + <entry>Class template <code>is_bind_expression</code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>20.5.11.1.2</entry> + <entry>Class template <code>is_placeholder</code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>20.5.11.1.3</entry> + <entry>Function template <code>bind</code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>20.5.11.1.4</entry> + <entry>Placeholders</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>20.5.15</entry> + <entry>Polymorphic function wrappers</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>20.5.15.1</entry> + <entry>Class <code>bad_function_call<code></code></code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>20.5.15.1.1</entry> + <entry><code>bad_function_call</code> constructor</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>20.5.15.2</entry> + <entry>Class template <code>function</code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>20.5.15.2.1</entry> + <entry><code>function</code> construct/copy/destroy</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>20.5.15.2.2</entry> + <entry><code>function</code> modifiers</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>20.5.15.2.3</entry> + <entry><code>function</code> capacity</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>20.5.15.2.4</entry> + <entry><code>function</code> invocation</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>20.5.15.2.5</entry> + <entry><code>function</code> target access</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>20.5.15.2.7</entry> + <entry>null pointer comparison operators</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>20.5.15.2.8</entry> + <entry>specialized algorithms</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>20.5.16</entry> + <entry>Class template <code>hash</code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>20.6</entry> + <entry>Additions to header <code><memory></code> synopsis</entry> + <entry></entry> + <entry></entry> + <entry>partial</entry> + <entry>missing <code>unique_ptr</code></entry> + </row> + <row> + <entry>20.6.5</entry> + <entry>Class template <code>unique_ptr</code></entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>20.6.6</entry> + <entry>Smart pointers</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>20.6.6.1</entry> + <entry>Class <code>bad_weak_ptr</code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>20.6.6.2</entry> + <entry>Class template <code>shared_ptr</code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry>See Footnotes.</entry> + </row> + <row> + <entry>20.6.6.2.1</entry> + <entry><code>shared_ptr</code> constructors</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>20.6.6.2.2</entry> + <entry><code>shared_ptr</code> destructor</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>20.6.6.2.3</entry> + <entry><code>shared_ptr</code> assignment</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>20.6.6.2.4</entry> + <entry><code>shared_ptr</code> modifiers</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>20.6.6.2.5</entry> + <entry><code>shared_ptr</code> observers</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>20.6.6.2.6</entry> + <entry><code>shared_ptr</code> creation</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry> + <ulink url="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2351.htm">N2351</ulink> + </entry> + </row> + <row> + <entry>20.6.6.2.7</entry> + <entry><code>shared_ptr</code> comparison</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>20.6.6.2.8</entry> + <entry><code>shared_ptr</code> I/O</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>20.6.6.2.9</entry> + <entry><code>shared_ptr</code> specialized algorithms</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>20.6.6.2.10</entry> + <entry><code>shared_ptr</code> casts</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>20.6.6.2.11</entry> + <entry><code>get_deleter</code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>20.6.6.3</entry> + <entry>Class template <code>weak_ptr</code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>20.6.6.3.1</entry> + <entry><code>weak_ptr</code> constructors</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>20.6.6.3.2</entry> + <entry><code>weak_ptr</code> destructor</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>20.6.6.3.3</entry> + <entry><code>weak_ptr</code> assignment</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>20.6.6.3.4</entry> + <entry><code>weak_ptr</code> modifiers</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>20.6.6.3.5</entry> + <entry><code>weak_ptr</code> observers</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>20.6.6.3.6</entry> + <entry><code>weak_ptr</code> comparison</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>20.6.6.3.7</entry> + <entry><code>weak_ptr</code> specialized algorithms</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>20.6.6.4</entry> + <entry>Class template <code>enable_shared_from_this</code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + + + + <row> + <entry><emphasis>23</emphasis></entry> + <entry namest="c2" nameend="c6" align="left"><emphasis>Containers</emphasis></entry> + </row> + <row> + <entry>23.2.1</entry> + <entry>Header <code><array></code> synopsis</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>23.2.1</entry> + <entry>Class template array</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>23.2.1.1</entry> + <entry><code>array</code> constructors, copy, and assignment</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>23.2.1.2</entry> + <entry><code>array</code> specialized algorithms</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>23.2.1.3</entry> + <entry><code>array </code>size</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>23.2.1.4</entry> + <entry><code>array </code>data</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>23.2.1.5</entry> + <entry>Zero sized <code>array</code>s</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>23.2.1.6</entry> + <entry>Tuple interface to class template <code>array</code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + + <row> + <entry>23.4</entry> + <entry>Unordered associative containers</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>23.4.1</entry> + <entry>Class template <code>unordered_map</code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>23.4.1.1</entry> + <entry><code>unordered_map</code> constructors</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>23.4.1.2</entry> + <entry><code>unordered_map</code> element access</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>23.4.1.3</entry> + <entry><code>unordered_map</code> swap</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>23.4.2</entry> + <entry>Class template <code>unordered_multimap</code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>23.4.2.1</entry> + <entry><code>unordered_multimap</code> constructors</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>23.4.2.2</entry> + <entry><code>unordered_multimap</code> swap</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>23.4.3</entry> + <entry>Class template <code>unordered_set</code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>23.4.3.1</entry> + <entry><code>unordered_set</code> constructors</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>23.4.3.2</entry> + <entry><code>unordered_set</code> swap</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>23.4.4</entry> + <entry>Class template <code>unordered_multiset<code></code></code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>23.4.4.1</entry> + <entry><code>unordered_multiset</code> constructors</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>23.4.4.2</entry> + <entry><code>unordered_multiset</code> swap</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + + <row> + <entry><emphasis>26</emphasis></entry> + <entry namest="c2" nameend="c6" align="left"><emphasis>Numerics</emphasis></entry> + </row> + <row> + <entry>26.4</entry> + <entry>Random number generation</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>26.4.1</entry> + <entry>Requirements</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>26.4.2</entry> + <entry>Header <code><random></code> synopsis</entry> + <entry></entry> + <entry></entry> + <entry>partial</entry> + <entry></entry> + </row> + <row> + <entry>26.4.3</entry> + <entry>Random number engine class templates</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>26.4.3.1</entry> + <entry>Class template <code>linear_congruential_engine</code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>26.4.3.2</entry> + <entry>Class template <code>mersenne_twister_engine</code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>26.4.3.3</entry> + <entry>Class template <code>subtract_with_carry_engine</code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>26.4.4</entry> + <entry>Random number engine adaptor class templates</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + + <row> + <entry>26.4.4.1</entry> + <entry>Class template <code>discard_block_engine</code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>26.4.4.2</entry> + <entry>Class template <code>independent_bits_engine</code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>26.4.4.3</entry> + <entry>Class template <code>shuffle_order_engine</code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>26.4.4.4</entry> + <entry>Class template <code>xor_combine_engine</code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry>operator()() per N2079</entry> + </row> + <row> + <entry>26.4.5</entry> + <entry>Engines and engine adaptors with predefined parameters</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>26.4.6</entry> + <entry>Class <code>random_device</code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>26.4.7</entry> + <entry>Utilities</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>26.4.7.1</entry> + <entry>Class <code>seed_seq</code></entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>26.4.7.2</entry> + <entry>Function template <code>generate_cannonical</code></entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>26.4.8</entry> + <entry>Random number generation class templates</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>26.4.8.1</entry> + <entry>Uniform distributions</entry> + <entry></entry> + <entry></entry> + <entry>partial</entry> + <entry></entry> + </row> + <row> + <entry>26.4.8.1</entry> + <entry>Class template <code>uniform_int_distribution</code></entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>26.4.8.1</entry> + <entry>Class template <code>uniform_real_distribution</code></entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>26.4.8.2</entry> + <entry>Bernoulli distributions</entry> + <entry></entry> + <entry></entry> + <entry>partial</entry> + <entry></entry> + </row> + + <row> + <entry>26.4.8.2.1</entry> + <entry>Class <code>bernoulli_distribution</code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>26.4.8.2.2</entry> + <entry>Class template <code>binomial_distribution</code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>26.4.8.2.3</entry> + <entry>Class template <code>geometric_distribution</code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>26.4.8.2.4</entry> + <entry>Class template <code>negative_binomial_distribution</code></entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>26.4.8.3</entry> + <entry>Poisson distributions</entry> + <entry></entry> + <entry></entry> + <entry>partial</entry> + <entry></entry> + </row> + <row> + <entry>26.4.8.3.1</entry> + <entry>Class template <code>poisson_distribution</code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>26.4.8.3.2</entry> + <entry>Class template <code>exponential_distribution</code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>26.4.8.3.3</entry> + <entry>Class template <code>gamma_distribution</code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>26.4.8.3.4</entry> + <entry>Class template <code>weibull_distribution</code></entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>26.4.8.3.5</entry> + <entry>Class template <code>extreme_value_distribution</code></entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>26.4.8.4</entry> + <entry>Normal distributions</entry> + <entry></entry> + <entry></entry> + <entry>partial</entry> + <entry></entry> + </row> + <row> + <entry>26.4.8.4.1</entry> + <entry>Class template <code>normal_distribution</code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>26.4.8.4.2</entry> + <entry>Class template <code>lognormal_distribution</code></entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>26.4.8.4.3</entry> + <entry>Class template <code>chi_squared_distribution</code></entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>26.4.8.4.4</entry> + <entry>Class template <code>cauchy_distribution</code></entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>26.4.8.4.5</entry> + <entry>Class template <code>fisher_f_distribution</code></entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>26.4.8.4.6</entry> + <entry>Class template <code>student_t_distribution</code></entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>26.4.8.5</entry> + <entry>Sampling distributions</entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>26.4.8.5.1</entry> + <entry>Class template <code>discrete_distribution</code></entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>26.4.8.5.1</entry> + <entry>Class template <code>piecewise_constant_distribution</code></entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>26.4.8.5.1</entry> + <entry>Class template <code>general_pdf_distribution</code></entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + + <row> + <entry><emphasis>28</emphasis></entry> + <entry namest="c2" nameend="c6" align="left"><emphasis>Regular Expressions</emphasis></entry> + </row> + <row> + <entry>28.1</entry> + <entry>Definitions</entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>28.2</entry> + <entry>Requirements</entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>28.3</entry> + <entry>Regular expressions summary</entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>28.4</entry> + <entry>Header <code><regex></code> synopsis</entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>28.5</entry> + <entry>Namespace <code>tr1::regex_constants</code></entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>28.5.1</entry> + <entry>Bitmask Type <code>syntax_option_type</code></entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>28.5.2</entry> + <entry>Bitmask Type <code>regex_constants::match_flag_type</code></entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>28.5.3</entry> + <entry>Implementation defined <code>error_type</code></entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>28.6</entry> + <entry>Class <code>regex_error</code></entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>28.7</entry> + <entry>Class template <code>regex_traits</code></entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>28.8</entry> + <entry>Class template <code>basic_regex</code></entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>28.8.1</entry> + <entry><code>basic_regex</code> constants</entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>28.8.2</entry> + <entry><code>basic_regex</code> constructors</entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>28.8.3</entry> + <entry><code>basic_regex</code> assign</entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>28.8.4</entry> + <entry><code>basic_regex</code> constant operations</entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>28.8.5</entry> + <entry><code>basic_regex</code> locale</entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>28.8.6</entry> + <entry><code>basic_regex</code> swap</entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>28.8.7</entry> + <entry><code>basic_regex</code> non-member functions</entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>28.8.7.1</entry> + <entry><code>basic_regex</code> non-member swap</entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>28.9</entry> + <entry>Class template <code>sub_match</code></entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>28.9.1</entry> + <entry><code>sub_match</code> members</entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>28.9.2</entry> + <entry><code>sub_match</code> non-member operators</entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>28.10</entry> + <entry>Class template <code>match_results</code></entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>28.10.1</entry> + <entry><code>match_results</code> constructors</entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>28.10.2</entry> + <entry><code>match_results</code> size</entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>28.10.3</entry> + <entry><code>match_results</code> element access</entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>28.10.4</entry> + <entry><code>match_results</code> formatting</entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>28.10.5</entry> + <entry><code>match_results</code> allocator</entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>28.10.6</entry> + <entry><code>match_results</code> swap</entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>28.11</entry> + <entry>Regular expression algorithms</entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>28.11.1</entry> + <entry>exceptions</entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>28.11.2</entry> + <entry><code>regex_match</code></entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>28.11.3</entry> + <entry><code>regex_search</code></entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>28.11.4</entry> + <entry><code>regex_replace</code></entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>28.12</entry> + <entry>Regular expression Iterators</entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>28.12.1</entry> + <entry>Class template <code>regex_iterator</code></entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>28.12.1.1</entry> + <entry><code>regex_iterator</code> constructors</entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>28.12.1.2</entry> + <entry><code>regex_iterator</code> comparisons</entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>28.12.1.3</entry> + <entry><code>regex_iterator</code> dereference</entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>28.12.1.4</entry> + <entry><code>regex_iterator</code> increment</entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>28.12.2</entry> + <entry>Class template <code>regex_token_iterator</code></entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>28.12.2.1</entry> + <entry><code>regex_token_iterator</code> constructors</entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>28.12.2.2</entry> + <entry><code>regex_token_iterator</code> comparisons</entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>28.12.2.3</entry> + <entry><code>regex_token_iterator</code> dereference</entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>28.12.2.4</entry> + <entry><code>regex_token_iterator</code> increment</entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>28.13</entry> + <entry>Modified ECMAScript regular expression grammar</entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry><emphasis>C</emphasis></entry> + <entry namest="c2" nameend="c6" align="left"><emphasis>C Compatibility</emphasis></entry> + </row> + <row> + <entry>C2.1</entry> + <entry>Additions to header <code><complex></code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>C2.1.1</entry> + <entry>Synopsis</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>C2.1.2</entry> + <entry>Function <code>acos</code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>C2.1.3</entry> + <entry>Function <code>asin</code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>C2.1.4</entry> + <entry>Function <code>atan</code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>C2.1.5</entry> + <entry>Function <code>acosh</code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>C2.1.6</entry> + <entry>Function <code>asinh</code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>C2.1.7</entry> + <entry>Function <code>atanh</code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>C2.1.8</entry> + <entry>Function <code>fabs</code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>C2.1.9</entry> + <entry>Additional Overloads</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>C2.2</entry> + <entry>Header <code><ccomplex></code></entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry>DR 551</entry> + </row> + <row> + <entry>C2.3</entry> + <entry>Header <code><complex.h></code></entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry>DR 551</entry> + </row> + <row> + <entry>C2.4</entry> + <entry>Additions to header <code><cctype></code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>C2.4.1</entry> + <entry>Synopsis</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>C2.4.2</entry> + <entry>Function <code>isblank</code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>C2.5</entry> + <entry>Additions to header <code><ctype.h></code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>C2.6</entry> + <entry>Header <code><cfenv></code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>C2.6.1</entry> + <entry>Synopsis</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>C2.6.2</entry> + <entry>Definitions</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>C2.7</entry> + <entry>Header <code><fenv.h></code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>C2.8</entry> + <entry>Additions to header <code><cfloat></code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>C2.9</entry> + <entry>Additions to header <code><float.h></code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>C2.10</entry> + <entry>Additions to header <code><ios></code></entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>C2.10.1</entry> + <entry>Synopsis</entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>C2.10.2</entry> + <entry>Function <code>hexfloat</code></entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>C2.11</entry> + <entry>Header <code><cinttypes></code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>C2.11.1</entry> + <entry>Synopsis</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry>DR 557</entry> + </row> + <row> + <entry>C2.11.2</entry> + <entry>Definitions</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>C2.12</entry> + <entry>Header <code><inttypes.h></code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>C2.13</entry> + <entry>Additions to header <code><climits></code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>C2.14</entry> + <entry>Additions to header <code><limits.h></code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>C2.15</entry> + <entry>Additions to header <code><locale></code></entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>C2.16</entry> + <entry>Additions to header <code><cmath></code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>C2.16.1</entry> + <entry>Synopsis</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>C2.16.2</entry> + <entry>Definitions</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>C2.16.3</entry> + <entry>Function template definitions</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>C2.16.4</entry> + <entry>Additional overloads</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry>DR 568; DR 550</entry> + </row> + <row> + <entry>C2.17</entry> + <entry>Additions to header <code><math.h></code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>C2.18</entry> + <entry>Additions to header <code><cstdarg></code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>C2.19</entry> + <entry>Additions to header <code><stdarg.h></code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>C2.20</entry> + <entry>The header <code><cstdbool></code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>C2.21</entry> + <entry>The header <code><stdbool.h></code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>C2.22</entry> + <entry>The header <code><cstdint></code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>C2.22.1</entry> + <entry>Synopsis</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>C2.22.2</entry> + <entry>Definitions</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>C2.23</entry> + <entry>The header <code><stdint.h></code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>C2.24</entry> + <entry>Additions to header <code><cstdio></code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>C2.24.1</entry> + <entry>Synopsis</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>C2.24.2</entry> + <entry>Definitions</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>C2.24.3</entry> + <entry>Additional format specifiers</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry>C library responsibility</entry> + </row> + <row> + <entry>C2.24.4</entry> + <entry>Additions to header <code><stdio.h></code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>C2.25</entry> + <entry>Additions to header <code><cstdlib></code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>C2.25.1</entry> + <entry>Synopsis</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>C2.25.2</entry> + <entry>Definitions</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>C2.25.3</entry> + <entry>Function <code>abs</code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>C2.25.4</entry> + <entry>Function <code>div</code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>C2.26</entry> + <entry>Additions to header <code><stdlib.h></code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>C2.27</entry> + <entry>Header <code><ctgmath></code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry>DR 551</entry> + </row> + <row> + <entry>C2.28</entry> + <entry>Header <code><tgmath.h></code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry>DR 551</entry> + </row> + <row> + <entry>C2.29</entry> + <entry>Additions to header <code><ctime></code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry>C library responsibility</entry> + </row> + <row> + <entry>C2.30</entry> + <entry>Additions to header <code><cwchar></code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>C2.30.1</entry> + <entry>Synopsis</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>C2.30.2</entry> + <entry>Definitions</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>C2.30.3</entry> + <entry>Additional wide format specifiers</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry>C library responsibility</entry> + </row> + <row> + <entry>C2.31</entry> + <entry>Additions to header <code><wchar.h></code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>C2.32</entry> + <entry>Additions to header <code><cwctype></code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>C2.32.1</entry> + <entry>Synopsis</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>C2.32.2</entry> + <entry>Function <code>iswblank</code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>C2.33</entry> + <entry>Additions to header <code><wctype.h></code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry><emphasis>D</emphasis></entry> + <entry namest="c2" nameend="c6" align="left"><emphasis>Compatibility Features</emphasis></entry> + </row> + <row> + <entry>D.6</entry> + <entry>Old iostream members</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>D.8</entry> + <entry>Binders</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry><ulink url="http://gcc.gnu.org/PR33911">33911</ulink></entry> + </row> + <row> + <entry>D.9</entry> + <entry>Class template <code>auto_ptr</code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry><ulink url="http://gcc.gnu.org/PR33911">33911</ulink></entry> + </row> + </tbody> +</tgroup> +</table> + +<para> +Footnotes +</para> + +<para> + The shared_ptr implementation uses some code from the + <ulink url="http://www.boost.org/libs/smart_ptr/shared_ptr.htm">Boost + shared_ptr</ulink> library. +</para> + +</sect2>
\ No newline at end of file diff --git a/libstdc++-v3/doc/xml/manual/status_cxxtr1.xml b/libstdc++-v3/doc/xml/manual/status_cxxtr1.xml new file mode 100644 index 00000000000..092a78af458 --- /dev/null +++ b/libstdc++-v3/doc/xml/manual/status_cxxtr1.xml @@ -0,0 +1,2273 @@ +<sect2 id="manual.intro.status.standard.tr1" xreflabel="Status C++ TR1"> +<?dbhtml filename="standard_cxxtr1.html"?> + +<sect2info> + <keywordset> + <keyword> + ISO C++ + </keyword> + <keyword> + tr1 + </keyword> + </keywordset> +</sect2info> + +<title>C++ TR1</title> + +<para> +This table is based on the table of contents of ISO/IEC DTR 19768 +Doc No: N1836=05-0096 Date: 2005-06-24 +Draft Technical Report on C++ Library Extensions +</para> + +<para> +In this implementation the header names are prefixed by +<code>tr1/</code>, for instance <code><tr1/functional></code>, +<code><tr1/memory></code>, and so on. +</para> + +<para> +This page describes the TR1 support in mainline GCC SVN, not in any particular +release. +</para> + +<table frame='all'> +<title>C++ TR1 Implementation Status</title> +<tgroup cols='6' align='left' colsep='1' rowsep='1'> +<colspec colname='c1'></colspec> +<colspec colname='c2'></colspec> +<colspec colname='c3'></colspec> +<colspec colname='c4'></colspec> +<colspec colname='c5'></colspec> +<colspec colname='c6'></colspec> + + <thead> + <row> + <entry>Section</entry> + <entry>Description</entry> + <entry>Done</entry> + <entry>Broken</entry> + <entry>Missing</entry> + <entry>Comments</entry> + </row> + </thead> + <tbody> + <row> + <entry><emphasis>2</emphasis></entry> + <entry namest="c2" nameend="c6" align="left"><emphasis>General Utilities</emphasis></entry> + </row> + <row> + <entry>2.1</entry> + <entry>Reference wrappers</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>2.1.1</entry> + <entry>Additions to header <code><functional></code> synopsis</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>2.1.2</entry> + <entry>Class template <code>reference_wrapper</code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>2.1.2.1</entry> + <entry><code>reference_wrapper</code> construct/copy/destroy</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>2.1.2.2</entry> + <entry><code>reference_wrapper</code> assignment</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>2.1.2.3</entry> + <entry><code>reference_wrapper</code> access</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>2.1.2.4</entry> + <entry><code>reference_wrapper</code> invocation</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>2.1.2.5</entry> + <entry><code>reference_wrapper</code> helper functions</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>2.2</entry> + <entry>Smart pointers</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>2.2.1</entry> + <entry>Additions to header <code><memory></code> synopsis</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>2.2.2</entry> + <entry>Class <code>bad_weak_ptr</code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>2.2.3</entry> + <entry>Class template <code>shared_ptr</code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry>See Footnotes</entry> + </row> + <row> + <entry>2.2.3.1</entry> + <entry><code>shared_ptr</code> constructors</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>2.2.3.2</entry> + <entry><code>shared_ptr</code> destructor</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>2.2.3.3</entry> + <entry><code>shared_ptr</code> assignment</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>2.2.3.4</entry> + <entry><code>shared_ptr</code> modifiers</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>2.2.3.5</entry> + <entry><code>shared_ptr</code> observers</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>2.2.3.6</entry> + <entry><code>shared_ptr</code> comparison</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>2.2.3.7</entry> + <entry><code>shared_ptr</code> I/O</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>2.2.3.8</entry> + <entry><code>shared_ptr</code> specialized algorithms</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>2.2.3.9</entry> + <entry><code>shared_ptr</code> casts</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>2.2.3.10</entry> + <entry><code>get_deleter</code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>2.2.4</entry> + <entry>Class template <code>weak_ptr</code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>2.2.4.1</entry> + <entry><code>weak_ptr</code> constructors</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>2.2.4.2</entry> + <entry><code>weak_ptr</code> destructor</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>2.2.4.3</entry> + <entry><code>weak_ptr</code> assignment</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>2.2.4.4</entry> + <entry><code>weak_ptr</code> modifiers</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>2.2.4.5</entry> + <entry><code>weak_ptr</code> observers</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>2.2.4.6</entry> + <entry><code>weak_ptr</code> comparison</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>2.2.4.7</entry> + <entry><code>weak_ptr</code> specialized algorithms</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>2.2.5</entry> + <entry>Class template <code>enable_shared_from_this</code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry><emphasis>3</emphasis></entry> + <entry namest="c2" nameend="c6" align="left"><emphasis>Function Objects</emphasis></entry> + </row> + <row> + <entry>3.1</entry> + <entry>Definitions</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>3.2</entry> + <entry>Additions to <code><functional> synopsis</code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>3.3</entry> + <entry>Requirements</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>3.4</entry> + <entry>Function return types</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>3.5</entry> + <entry>Function template <code>mem_fn</code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>3.6</entry> + <entry>Function object binders</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>3.6.1</entry> + <entry>Class template <code>is_bind_expression</code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>3.6.2</entry> + <entry>Class template <code>is_placeholder</code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>3.6.3</entry> + <entry>Function template <code>bind</code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>3.6.4</entry> + <entry>Placeholders</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>3.7</entry> + <entry>Polymorphic function wrappers</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>3.7.1</entry> + <entry>Class <code>bad_function_call<code></code></code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>3.7.1.1</entry> + <entry><code>bad_function_call</code> constructor</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>3.7.2</entry> + <entry>Class template <code>function</code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>3.7.2.1</entry> + <entry><code>function</code> construct/copy/destroy</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>3.7.2.2</entry> + <entry><code>function</code> modifiers</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>3.7.2.3</entry> + <entry><code>function</code> capacity</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>3.7.2.4</entry> + <entry><code>function</code> invocation</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>3.7.2.5</entry> + <entry><code>function</code> target access</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>3.7.2.6</entry> + <entry>undefined operators</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>3.7.2.7</entry> + <entry>null pointer comparison operators</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>3.7.2.8</entry> + <entry>specialized algorithms</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry><emphasis>4</emphasis></entry> + <entry namest="c2" nameend="c6" align="left"><emphasis>Metaprogramming and type traits</emphasis></entry> + </row> + <row> + <entry>4.1</entry> + <entry>Requirements</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>4.2</entry> + <entry>Header <code><type_traits></code> synopsis</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>4.3</entry> + <entry>Helper classes</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>4.4</entry> + <entry>General Requirements</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>4.5</entry> + <entry>Unary Type Traits</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>4.5.1</entry> + <entry>Primary Type Categories</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>4.5.2</entry> + <entry>Composite type traits</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>4.5.3</entry> + <entry>Type properties</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>4.6</entry> + <entry>Relationships between types</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>4.7</entry> + <entry>Transformations between types</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>4.7.1</entry> + <entry>Const-volatile modifications</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>4.7.2</entry> + <entry>Reference modifications</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>4.7.3</entry> + <entry>Array modifications</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>4.7.4</entry> + <entry>Pointer modifications</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>4.8</entry> + <entry>Other transformations</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>4.9</entry> + <entry>Implementation requirements</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry><emphasis>5</emphasis></entry> + <entry namest="c2" nameend="c6" align="left"><emphasis>Numerical Facilities</emphasis></entry> + </row> + <row> + <entry>5.1</entry> + <entry>Random number generation</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>5.1.1</entry> + <entry>Requirements</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>5.1.2</entry> + <entry>Header <code><random></code> synopsis</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>5.1.3</entry> + <entry>Class template <code>variate_generator</code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>5.1.4</entry> + <entry>Random number engine class templates</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>5.1.4.1</entry> + <entry>Class template <code>linear_congruential</code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>5.1.4.2</entry> + <entry>Class template <code>mersenne_twister</code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>5.1.4.3</entry> + <entry>Class template <code>subtract_with_carry</code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>5.1.4.4</entry> + <entry>Class template <code>subtract_with_carry_01</code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>5.1.4.5</entry> + <entry>Class template <code>discard_block</code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>5.1.4.6</entry> + <entry>Class template <code>xor_combine</code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry>operator()() per N2079</entry> + </row> + <row> + <entry>5.1.5</entry> + <entry>Engines with predefined parameters</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>5.1.6</entry> + <entry>Class <code>random_device</code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>5.1.7</entry> + <entry>Random distribution class templates</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>5.1.7.1</entry> + <entry>Class template <code>uniform_int</code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>5.1.7.2</entry> + <entry>Class <code>bernoulli_distribution</code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>5.1.7.3</entry> + <entry>Class template <code>geometric_distribution</code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>5.1.7.4</entry> + <entry>Class template <code>poisson_distribution</code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>5.1.7.5</entry> + <entry>Class template <code>binomial_distribution</code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>5.1.7.6</entry> + <entry>Class template <code>uniform_real</code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>5.1.7.7</entry> + <entry>Class template <code>exponential_distribution</code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>5.1.7.8</entry> + <entry>Class template <code>normal_distribution</code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>5.1.7.9</entry> + <entry>Class template <code>gamma_distribution</code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>5.2</entry> + <entry>Mathematical special functions</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>5.2.1</entry> + <entry>Additions to header <code><cmath></code> synopsis</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>5.2.1.1</entry> + <entry>associated Laguerre polynomials</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>5.2.1.2</entry> + <entry>associated Legendre functions</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>5.2.1.3</entry> + <entry>beta function</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>5.2.1.4</entry> + <entry>(complete) elliptic integral of the first kind</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>5.2.1.5</entry> + <entry>(complete) elliptic integral of the second kind</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>5.2.1.6</entry> + <entry>(complete) elliptic integral of the third kind</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>5.2.1.7</entry> + <entry>confluent hypergeometric functions</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>5.2.1.8</entry> + <entry>regular modified cylindrical Bessel functions</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>5.2.1.9</entry> + <entry>cylindrical Bessel functions (of the first kind)</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>5.2.1.10</entry> + <entry>irregular modified cylindrical Bessel functions</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>5.2.1.11</entry> + <entry>cylindrical Neumann functions</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>5.2.1.12</entry> + <entry>(incomplete) elliptic integral of the first kind</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>5.2.1.13</entry> + <entry>(incomplete) elliptic integral of the second kind</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>5.2.1.14</entry> + <entry>(incomplete) elliptic integral of the third kind</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>5.2.1.15</entry> + <entry>exponential integral</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>5.2.1.16</entry> + <entry>Hermite polynomials</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>5.2.1.17</entry> + <entry>hypergeometric functions</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>5.2.1.18</entry> + <entry>Laguerre polynomials</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>5.2.1.19</entry> + <entry>Legendre polynomials</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>5.2.1.20</entry> + <entry>Riemann zeta function</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>5.2.1.21</entry> + <entry>spherical Bessel functions (of the first kind)</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>5.2.1.22</entry> + <entry>spherical associated Legendre functions</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>5.2.1.23</entry> + <entry>spherical Neumann functions</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>5.2.2</entry> + <entry>Additions to header <code><math.h></code> synopsis</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry><emphasis>6</emphasis></entry> + <entry namest="c2" nameend="c6" align="left"><emphasis>Containers</emphasis></entry> + </row> + <row> + <entry>6.1</entry> + <entry>Tuple types</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>6.1.1</entry> + <entry>Header <code><tuple></code> synopsis</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>6.1.2</entry> + <entry>Additions to header <code><utility></code> synopsis</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>6.1.3</entry> + <entry>Class template <code>tuple</code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>6.1.3.1</entry> + <entry>Construction</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>6.1.3.2</entry> + <entry>Tuple creation functions</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>6.1.3.3</entry> + <entry>Tuple helper classes</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>6.1.3.4</entry> + <entry>Element access</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>6.1.3.5</entry> + <entry>Relational operators</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>6.1.4</entry> + <entry>Pairs</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>6.2</entry> + <entry>Fixed size array</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>6.2.1</entry> + <entry>Header <code><array></code> synopsis</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>6.2.2</entry> + <entry>Class template <code>array</code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>6.2.2.1</entry> + <entry><code>array</code> constructors, copy, and assignment</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>6.2.2.2</entry> + <entry><code>array</code> specialized algorithms</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>6.2.2.3</entry> + <entry><code>array</code> size</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>6.2.2.4</entry> + <entry>Zero sized <code>array</code>s</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>6.2.2.5</entry> + <entry>Tuple interface to class template <code>array</code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>6.3</entry> + <entry>Unordered associative containers</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>6.3.1</entry> + <entry>Unordered associative container requirements</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>6.3.1.1</entry> + <entry>Exception safety guarantees</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>6.3.2</entry> + <entry>Additions to header <code><functional></code> synopsis</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>6.3.3</entry> + <entry>Class template <code>hash</code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>6.3.4</entry> + <entry>Unordered associative container classes</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>6.3.4.1</entry> + <entry>Header <code><unordered_set></code> synopsis</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>6.3.4.2</entry> + <entry>Header <code><unordered_map></code> synopsis</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>6.3.4.3</entry> + <entry>Class template <code>unordered_set</code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>6.3.4.3.1</entry> + <entry><code>unordered_set</code> constructors</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>6.3.4.3.2</entry> + <entry><code>unordered_set</code> swap</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>6.3.4.4</entry> + <entry>Class template <code>unordered_map</code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>6.3.4.4.1</entry> + <entry><code>unordered_map</code> constructors</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>6.3.4.4.2</entry> + <entry><code>unordered_map</code> element access</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>6.3.4.4.3</entry> + <entry><code>unordered_map</code> swap</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>6.3.4.5</entry> + <entry>Class template <code>unordered_multiset<code></code></code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>6.3.4.5.1</entry> + <entry><code>unordered_multiset</code> constructors</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>6.3.4.5.2</entry> + <entry><code>unordered_multiset</code> swap</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>6.3.4.6</entry> + <entry>Class template <code>unordered_multimap</code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>6.3.4.6.1</entry> + <entry><code>unordered_multimap</code> constructors</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>6.3.4.6.2</entry> + <entry><code>unordered_multimap</code> swap</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry><emphasis>7</emphasis></entry> + <entry namest="c2" nameend="c6" align="left"><emphasis>Regular Expressions</emphasis></entry> + </row> + <row> + <entry>7.1</entry> + <entry>Definitions</entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>7.2</entry> + <entry>Requirements</entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>7.3</entry> + <entry>Regular expressions summary</entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>7.4</entry> + <entry>Header <code><regex></code> synopsis</entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>7.5</entry> + <entry>Namespace <code>tr1::regex_constants</code></entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>7.5.1</entry> + <entry>Bitmask Type <code>syntax_option_type</code></entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>7.5.2</entry> + <entry>Bitmask Type <code>regex_constants::match_flag_type</code></entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>7.5.3</entry> + <entry>Implementation defined <code>error_type</code></entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>7.6</entry> + <entry>Class <code>regex_error</code></entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>7.7</entry> + <entry>Class template <code>regex_traits</code></entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>7.8</entry> + <entry>Class template <code>basic_regex</code></entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>7.8.1</entry> + <entry><code>basic_regex</code> constants</entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>7.8.2</entry> + <entry><code>basic_regex</code> constructors</entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>7.8.3</entry> + <entry><code>basic_regex</code> assign</entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>7.8.4</entry> + <entry><code>basic_regex</code> constant operations</entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>7.8.5</entry> + <entry><code>basic_regex</code> locale</entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>7.8.6</entry> + <entry><code>basic_regex</code> swap</entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>7.8.7</entry> + <entry><code>basic_regex</code> non-member functions</entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>7.8.7.1</entry> + <entry><code>basic_regex</code> non-member swap</entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>7.9</entry> + <entry>Class template <code>sub_match</code></entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>7.9.1</entry> + <entry><code>sub_match</code> members</entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>7.9.2</entry> + <entry><code>sub_match</code> non-member operators</entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>7.10</entry> + <entry>Class template <code>match_results</code></entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>7.10.1</entry> + <entry><code>match_results</code> constructors</entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>7.10.2</entry> + <entry><code>match_results</code> size</entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>7.10.3</entry> + <entry><code>match_results</code> element access</entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>7.10.4</entry> + <entry><code>match_results</code> formatting</entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>7.10.5</entry> + <entry><code>match_results</code> allocator</entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>7.10.6</entry> + <entry><code>match_results</code> swap</entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>7.11</entry> + <entry>Regular expression algorithms</entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>7.11.1</entry> + <entry>exceptions</entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>7.11.2</entry> + <entry><code>regex_match</code></entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>7.11.3</entry> + <entry><code>regex_search</code></entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>7.11.4</entry> + <entry><code>regex_replace</code></entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>7.12</entry> + <entry>Regular expression Iterators</entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>7.12.1</entry> + <entry>Class template <code>regex_iterator</code></entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>7.12.1.1</entry> + <entry><code>regex_iterator</code> constructors</entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>7.12.1.2</entry> + <entry><code>regex_iterator</code> comparisons</entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>7.12.1.3</entry> + <entry><code>regex_iterator</code> dereference</entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>7.12.1.4</entry> + <entry><code>regex_iterator</code> increment</entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>7.12.2</entry> + <entry>Class template <code>regex_token_iterator</code></entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>7.12.2.1</entry> + <entry><code>regex_token_iterator</code> constructors</entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>7.12.2.2</entry> + <entry><code>regex_token_iterator</code> comparisons</entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>7.12.2.3</entry> + <entry><code>regex_token_iterator</code> dereference</entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>7.12.2.4</entry> + <entry><code>regex_token_iterator</code> increment</entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>7.13</entry> + <entry>Modified ECMAScript regular expression grammar</entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry><emphasis>8</emphasis></entry> + <entry namest="c2" nameend="c6" align="left"><emphasis>C Compatibility</emphasis></entry> + </row> + <row> + <entry>8.1</entry> + <entry>Additions to header <code><complex></code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>8.1.1</entry> + <entry>Synopsis</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>8.1.2</entry> + <entry>Function <code>acos</code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>8.1.3</entry> + <entry>Function <code>asin</code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>8.1.4</entry> + <entry>Function <code>atan</code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>8.1.5</entry> + <entry>Function <code>acosh</code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>8.1.6</entry> + <entry>Function <code>asinh</code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>8.1.7</entry> + <entry>Function <code>atanh</code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>8.1.8</entry> + <entry>Function <code>fabs</code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>8.1.9</entry> + <entry>Additional Overloads</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>8.2</entry> + <entry>Header <code><ccomplex></code></entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry>DR 551</entry> + </row> + <row> + <entry>8.3</entry> + <entry>Header <code><complex.h></code></entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry>DR 551</entry> + </row> + <row> + <entry>8.4</entry> + <entry>Additions to header <code><cctype></code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>8.4.1</entry> + <entry>Synopsis</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>8.4.2</entry> + <entry>Function <code>isblank</code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>8.5</entry> + <entry>Additions to header <code><ctype.h></code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>8.6</entry> + <entry>Header <code><cfenv></code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>8.6.1</entry> + <entry>Synopsis</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>8.6.2</entry> + <entry>Definitions</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>8.7</entry> + <entry>Header <code><fenv.h></code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>8.8</entry> + <entry>Additions to header <code><cfloat></code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>8.9</entry> + <entry>Additions to header <code><float.h></code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>8.10</entry> + <entry>Additions to header <code><ios></code></entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>8.10.1</entry> + <entry>Synopsis</entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>8.10.2</entry> + <entry>Function <code>hexfloat</code></entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>8.11</entry> + <entry>Header <code><cinttypes></code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>8.11.1</entry> + <entry>Synopsis</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry>DR 557</entry> + </row> + <row> + <entry>8.11.2</entry> + <entry>Definitions</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>8.12</entry> + <entry>Header <code><inttypes.h></code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>8.13</entry> + <entry>Additions to header <code><climits></code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>8.14</entry> + <entry>Additions to header <code><limits.h></code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>8.15</entry> + <entry>Additions to header <code><locale></code></entry> + <entry></entry> + <entry></entry> + <entry>missing</entry> + <entry></entry> + </row> + <row> + <entry>8.16</entry> + <entry>Additions to header <code><cmath></code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>8.16.1</entry> + <entry>Synopsis</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>8.16.2</entry> + <entry>Definitions</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>8.16.3</entry> + <entry>Function template definitions</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>8.16.4</entry> + <entry>Additional overloads</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry>DR 568; DR 550</entry> + </row> + <row> + <entry>8.17</entry> + <entry>Additions to header <code><math.h></code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>8.18</entry> + <entry>Additions to header <code><cstdarg></code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>8.19</entry> + <entry>Additions to header <code><stdarg.h></code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>8.20</entry> + <entry>The header <code><cstdbool></code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>8.21</entry> + <entry>The header <code><stdbool.h></code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>8.22</entry> + <entry>The header <code><cstdint></code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>8.22.1</entry> + <entry>Synopsis</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>8.22.2</entry> + <entry>Definitions</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>8.23</entry> + <entry>The header <code><stdint.h></code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>8.24</entry> + <entry>Additions to header <code><cstdio></code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>8.24.1</entry> + <entry>Synopsis</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>8.24.2</entry> + <entry>Definitions</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>8.24.3</entry> + <entry>Additional format specifiers</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry>C library responsibility</entry> + </row> + <row> + <entry>8.24.4</entry> + <entry>Additions to header <code><stdio.h></code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>8.25</entry> + <entry>Additions to header <code><cstdlib></code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>8.25.1</entry> + <entry>Synopsis</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>8.25.2</entry> + <entry>Definitions</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>8.25.3</entry> + <entry>Function <code>abs</code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>8.25.4</entry> + <entry>Function <code>div</code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>8.26</entry> + <entry>Additions to header <code><stdlib.h></code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>8.27</entry> + <entry>Header <code><ctgmath></code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry>DR 551</entry> + </row> + <row> + <entry>8.28</entry> + <entry>Header <code><tgmath.h></code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry>DR 551</entry> + </row> + <row> + <entry>8.29</entry> + <entry>Additions to header <code><ctime></code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry>C library responsibility</entry> + </row> + <row> + <entry>8.30</entry> + <entry>Additions to header <code><cwchar></code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>8.30.1</entry> + <entry>Synopsis</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>8.30.2</entry> + <entry>Definitions</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>8.30.3</entry> + <entry>Additional wide format specifiers</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry>C library responsibility</entry> + </row> + <row> + <entry>8.31</entry> + <entry>Additions to header <code><wchar.h></code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>8.32</entry> + <entry>Additions to header <code><cwctype></code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>8.32.1</entry> + <entry>Synopsis</entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>8.32.2</entry> + <entry>Function <code>iswblank</code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>8.33</entry> + <entry>Additions to header <code><wctype.h></code></entry> + <entry>done</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + </tbody> +</tgroup> +</table> + +<para> +Footnotes +</para> + +<para> + The shared_ptr implementation uses some code from the + <ulink url="http://www.boost.org/libs/smart_ptr/shared_ptr.htm">Boost + shared_ptr</ulink> library. +</para> + +</sect2>
\ No newline at end of file diff --git a/libstdc++-v3/doc/xml/manual/strings.xml b/libstdc++-v3/doc/xml/manual/strings.xml new file mode 100644 index 00000000000..d8f2035cb6d --- /dev/null +++ b/libstdc++-v3/doc/xml/manual/strings.xml @@ -0,0 +1,495 @@ +<?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.strings" xreflabel="Strings"> +<?dbhtml filename="strings.html"?> + +<partinfo> + <keywordset> + <keyword> + ISO C++ + </keyword> + <keyword> + library + </keyword> + </keywordset> +</partinfo> + +<title>Strings</title> + +<!-- Chapter 01 : Character Traits --> + +<!-- Chapter 02 : String Classes --> +<chapter id="manual.strings.string" xreflabel="string"> + <title>String Classes</title> + + <sect1 id="strings.string.simple" xreflabel="Simple Transformations"> + <title>Simple Transformations</title> + <para> + Here are Standard, simple, and portable ways to perform common + transformations on a <code>string</code> instance, such as + "convert to all upper case." The word transformations + is especially apt, because the standard template function + <code>transform<></code> is used. + </para> + <para> + This code will go through some iterations. Here's a simiple + version: + </para> + <programlisting> + #include <string> + #include <algorithm> + #include <cctype> // old <ctype.h> + + struct ToLower + { + char operator() (char c) const { return std::tolower(c); } + }; + + struct ToUpper + { + char operator() (char c) const { return std::toupper(c); } + }; + + int main() + { + std::string s ("Some Kind Of Initial Input Goes Here"); + + // Change everything into upper case + std::transform (s.begin(), s.end(), s.begin(), ToUpper()); + + // Change everything into lower case + std::transform (s.begin(), s.end(), s.begin(), ToLower()); + + // Change everything back into upper case, but store the + // result in a different string + std::string capital_s; + capital_s.resize(s.size()); + std::transform (s.begin(), s.end(), capital_s.begin(), ToUpper()); + } + </programlisting> + <para> + <emphasis>Note</emphasis> that these calls all + involve the global C locale through the use of the C functions + <code>toupper/tolower</code>. This is absolutely guaranteed to work -- + but <emphasis>only</emphasis> if the string contains <emphasis>only</emphasis> characters + from the basic source character set, and there are <emphasis>only</emphasis> + 96 of those. Which means that not even all English text can be + represented (certain British spellings, proper names, and so forth). + So, if all your input forevermore consists of only those 96 + characters (hahahahahaha), then you're done. + </para> + <para><emphasis>Note</emphasis> that the + <code>ToUpper</code> and <code>ToLower</code> function objects + are needed because <code>toupper</code> and <code>tolower</code> + are overloaded names (declared in <code><cctype></code> and + <code><locale></code>) so the template-arguments for + <code>transform<></code> cannot be deduced, as explained in + <ulink url="http://gcc.gnu.org/ml/libstdc++/2002-11/msg00180.html">this + message</ulink>. + <!-- section 14.8.2.4 clause 16 in ISO 14882:1998 --> + At minimum, you can write short wrappers like + </para> + <programlisting> + char toLower (char c) + { + return std::tolower(c); + } </programlisting> + <para>The correct method is to use a facet for a particular locale + and call its conversion functions. These are discussed more in + Chapter 22; the specific part is + <ulink url="../22_locale/howto.html#7">Correct Transformations</ulink>, + which shows the final version of this code. (Thanks to James Kanze + for assistance and suggestions on all of this.) + </para> + <para>Another common operation is trimming off excess whitespace. Much + like transformations, this task is trivial with the use of string's + <code>find</code> family. These examples are broken into multiple + statements for readability: + </para> + <programlisting> + std::string str (" \t blah blah blah \n "); + + // trim leading whitespace + string::size_type notwhite = str.find_first_not_of(" \t\n"); + str.erase(0,notwhite); + + // trim trailing whitespace + notwhite = str.find_last_not_of(" \t\n"); + str.erase(notwhite+1); </programlisting> + <para>Obviously, the calls to <code>find</code> could be inserted directly + into the calls to <code>erase</code>, in case your compiler does not + optimize named temporaries out of existence. + </para> + + </sect1> + <sect1 id="strings.string.case" xreflabel="Case Sensitivity"> + <title>Case Sensivitity</title> + <para> + </para> + + <para>The well-known-and-if-it-isn't-well-known-it-ought-to-be + <ulink url="http://www.gotw.ca/gotw/">Guru of the Week</ulink> + discussions held on Usenet covered this topic in January of 1998. + Briefly, the challenge was, <quote>write a 'ci_string' class which + is identical to the standard 'string' class, but is + case-insensitive in the same way as the (common but nonstandard) + C function stricmp()</quote>. + </para> + <programlisting> + ci_string s( "AbCdE" ); + + // case insensitive + assert( s == "abcde" ); + assert( s == "ABCDE" ); + + // still case-preserving, of course + assert( strcmp( s.c_str(), "AbCdE" ) == 0 ); + assert( strcmp( s.c_str(), "abcde" ) != 0 ); </programlisting> + + <para>The solution is surprisingly easy. The original answer was + posted on Usenet, and a revised version appears in Herb Sutter's + book <emphasis>Exceptional C++</emphasis> and on his website as <ulink url="http://www.gotw.ca/gotw/029.htm">GotW 29</ulink>. + </para> + <para>See? Told you it was easy!</para> + <para> + <emphasis>Added June 2000:</emphasis> The May 2000 issue of C++ + Report contains a fascinating <ulink + url="http://lafstern.org/matt/col2_new.pdf"> article</ulink> by + Matt Austern (yes, <emphasis>the</emphasis> Matt Austern) on why + case-insensitive comparisons are not as easy as they seem, and + why creating a class is the <emphasis>wrong</emphasis> way to go + about it in production code. (The GotW answer mentions one of + the principle difficulties; his article mentions more.) + </para> + <para>Basically, this is "easy" only if you ignore some things, + things which may be too important to your program to ignore. (I chose + to ignore them when originally writing this entry, and am surprised + that nobody ever called me on it...) The GotW question and answer + remain useful instructional tools, however. + </para> + <para><emphasis>Added September 2000:</emphasis> James Kanze provided a link to a + <ulink url="http://www.unicode.org/unicode/reports/tr21/">Unicode + Technical Report discussing case handling</ulink>, which provides some + very good information. + </para> + + </sect1> + <sect1 id="strings.string.character_types" xreflabel="Arbitrary Characters"> + <title>Arbitrary Character Types</title> + <para> + </para> + + <para>The <code>std::basic_string</code> is tantalizingly general, in that + it is parameterized on the type of the characters which it holds. + In theory, you could whip up a Unicode character class and instantiate + <code>std::basic_string<my_unicode_char></code>, or assuming + that integers are wider than characters on your platform, maybe just + declare variables of type <code>std::basic_string<int></code>. + </para> + <para>That's the theory. Remember however that basic_string has additional + type parameters, which take default arguments based on the character + type (called <code>CharT</code> here): + </para> + <programlisting> + template <typename CharT, + typename Traits = char_traits<CharT>, + typename Alloc = allocator<CharT> > + class basic_string { .... };</programlisting> + <para>Now, <code>allocator<CharT></code> will probably Do The Right + Thing by default, unless you need to implement your own allocator + for your characters. + </para> + <para>But <code>char_traits</code> takes more work. The char_traits + template is <emphasis>declared</emphasis> but not <emphasis>defined</emphasis>. + That means there is only + </para> + <programlisting> + template <typename CharT> + struct char_traits + { + static void foo (type1 x, type2 y); + ... + };</programlisting> + <para>and functions such as char_traits<CharT>::foo() are not + actually defined anywhere for the general case. The C++ standard + permits this, because writing such a definition to fit all possible + CharT's cannot be done. + </para> + <para>The C++ standard also requires that char_traits be specialized for + instantiations of <code>char</code> and <code>wchar_t</code>, and it + is these template specializations that permit entities like + <code>basic_string<char,char_traits<char>></code> to work. + </para> + <para>If you want to use character types other than char and wchar_t, + such as <code>unsigned char</code> and <code>int</code>, you will + need suitable specializations for them. For a time, in earlier + versions of GCC, there was a mostly-correct implementation that + let programmers be lazy but it broke under many situations, so it + was removed. GCC 3.4 introduced a new implementation that mostly + works and can be specialized even for <code>int</code> and other + built-in types. + </para> + <para>If you want to use your own special character class, then you have + <ulink url="http://gcc.gnu.org/ml/libstdc++/2002-08/msg00163.html">a lot + of work to do</ulink>, especially if you with to use i18n features + (facets require traits information but don't have a traits argument). + </para> + <para>Another example of how to specialize char_traits was given <ulink url="http://gcc.gnu.org/ml/libstdc++/2002-08/msg00260.html">on the + mailing list</ulink> and at a later date was put into the file <code> + include/ext/pod_char_traits.h</code>. We agree + that the way it's used with basic_string (scroll down to main()) + doesn't look nice, but that's because <ulink url="http://gcc.gnu.org/ml/libstdc++/2002-08/msg00236.html">the + nice-looking first attempt</ulink> turned out to <ulink url="http://gcc.gnu.org/ml/libstdc++/2002-08/msg00242.html">not + be conforming C++</ulink>, due to the rule that CharT must be a POD. + (See how tricky this is?) + </para> + + </sect1> + + <sect1 id="strings.string.token" xreflabel="Tokenizing"> + <title>Tokenizing</title> + <para> + </para> + <para>The Standard C (and C++) function <code>strtok()</code> leaves a lot to + be desired in terms of user-friendliness. It's unintuitive, it + destroys the character string on which it operates, and it requires + you to handle all the memory problems. But it does let the client + code decide what to use to break the string into pieces; it allows + you to choose the "whitespace," so to speak. + </para> + <para>A C++ implementation lets us keep the good things and fix those + annoyances. The implementation here is more intuitive (you only + call it once, not in a loop with varying argument), it does not + affect the original string at all, and all the memory allocation + is handled for you. + </para> + <para>It's called stringtok, and it's a template function. Sources are + as below, in a less-portable form than it could be, to keep this + example simple (for example, see the comments on what kind of + string it will accept). + </para> + +<programlisting> +#include <string> +template <typename Container> +void +stringtok(Container &container, string const &in, + const char * const delimiters = " \t\n") +{ + const string::size_type len = in.length(); + string::size_type i = 0; + + while (i < len) + { + // Eat leading whitespace + i = in.find_first_not_of(delimiters, i); + if (i == string::npos) + return; // Nothing left but white space + + // Find the end of the token + string::size_type j = in.find_first_of(delimiters, i); + + // Push token + if (j == string::npos) + { + container.push_back(in.substr(i)); + return; + } + else + container.push_back(in.substr(i, j-i)); + + // Set up for next loop + i = j + 1; + } +} +</programlisting> + + + <para> + The author uses a more general (but less readable) form of it for + parsing command strings and the like. If you compiled and ran this + code using it: + </para> + + + <programlisting> + std::list<string> ls; + stringtok (ls, " this \t is\t\n a test "); + for (std::list<string>const_iterator i = ls.begin(); + i != ls.end(); ++i) + { + std::cerr << ':' << (*i) << ":\n"; + } </programlisting> + <para>You would see this as output: + </para> + <programlisting> + :this: + :is: + :a: + :test: </programlisting> + <para>with all the whitespace removed. The original <code>s</code> is still + available for use, <code>ls</code> will clean up after itself, and + <code>ls.size()</code> will return how many tokens there were. + </para> + <para>As always, there is a price paid here, in that stringtok is not + as fast as strtok. The other benefits usually outweigh that, however. + <ulink url="stringtok_std_h.txt">Another version of stringtok is given + here</ulink>, suggested by Chris King and tweaked by Petr Prikryl, + and this one uses the + transformation functions mentioned below. If you are comfortable + with reading the new function names, this version is recommended + as an example. + </para> + <para><emphasis>Added February 2001:</emphasis> Mark Wilden pointed out that the + standard <code>std::getline()</code> function can be used with standard + <ulink url="../27_io/howto.html">istringstreams</ulink> to perform + tokenizing as well. Build an istringstream from the input text, + and then use std::getline with varying delimiters (the three-argument + signature) to extract tokens into a string. + </para> + + + </sect1> + <sect1 id="strings.string.shrink" xreflabel="Shrink to Fit"> + <title>Shrink to Fit</title> + <para> + </para> + <para>From GCC 3.4 calling <code>s.reserve(res)</code> on a + <code>string s</code> with <code>res < s.capacity()</code> will + reduce the string's capacity to <code>std::max(s.size(), res)</code>. + </para> + <para>This behaviour is suggested, but not required by the standard. Prior + to GCC 3.4 the following alternative can be used instead + </para> + <programlisting> + std::string(str.data(), str.size()).swap(str); + </programlisting> + <para>This is similar to the idiom for reducing a <code>vector</code>'s + memory usage (see <ulink url='../faq/index.html#5_9'>FAQ 5.9</ulink>) but + the regular copy constructor cannot be used because libstdc++'s + <code>string</code> is Copy-On-Write. + </para> + + + </sect1> + + <sect1 id="strings.string.Cstring" xreflabel="CString (MFC)"> + <title>CString (MFC)</title> + <para> + </para> + + <para>A common lament seen in various newsgroups deals with the Standard + string class as opposed to the Microsoft Foundation Class called + CString. Often programmers realize that a standard portable + answer is better than a proprietary nonportable one, but in porting + their application from a Win32 platform, they discover that they + are relying on special functions offered by the CString class. + </para> + <para>Things are not as bad as they seem. In + <ulink url="http://gcc.gnu.org/ml/gcc/1999-04n/msg00236.html">this + message</ulink>, Joe Buck points out a few very important things: + </para> + <itemizedlist> + <listitem><para>The Standard <code>string</code> supports all the operations + that CString does, with three exceptions. + </para></listitem> + <listitem><para>Two of those exceptions (whitespace trimming and case + conversion) are trivial to implement. In fact, we do so + on this page. + </para></listitem> + <listitem><para>The third is <code>CString::Format</code>, which allows formatting + in the style of <code>sprintf</code>. This deserves some mention: + </para></listitem> + </itemizedlist> + <para> + The old libg++ library had a function called form(), which did much + the same thing. But for a Standard solution, you should use the + stringstream classes. These are the bridge between the iostream + hierarchy and the string class, and they operate with regular + streams seamlessly because they inherit from the iostream + hierarchy. An quick example: + </para> + <programlisting> + #include <iostream> + #include <string> + #include <sstream> + + string f (string& incoming) // incoming is "foo N" + { + istringstream incoming_stream(incoming); + string the_word; + int the_number; + + incoming_stream >> the_word // extract "foo" + >> the_number; // extract N + + ostringstream output_stream; + output_stream << "The word was " << the_word + << " and 3*N was " << (3*the_number); + + return output_stream.str(); + } </programlisting> + <para>A serious problem with CString is a design bug in its memory + allocation. Specifically, quoting from that same message: + </para> + <programlisting> + CString suffers from a common programming error that results in + poor performance. Consider the following code: + + CString n_copies_of (const CString& foo, unsigned n) + { + CString tmp; + for (unsigned i = 0; i < n; i++) + tmp += foo; + return tmp; + } + + This function is O(n^2), not O(n). The reason is that each += + causes a reallocation and copy of the existing string. Microsoft + applications are full of this kind of thing (quadratic performance + on tasks that can be done in linear time) -- on the other hand, + we should be thankful, as it's created such a big market for high-end + ix86 hardware. :-) + + If you replace CString with string in the above function, the + performance is O(n). + </programlisting> + <para>Joe Buck also pointed out some other things to keep in mind when + comparing CString and the Standard string class: + </para> + <itemizedlist> + <listitem><para>CString permits access to its internal representation; coders + who exploited that may have problems moving to <code>string</code>. + </para></listitem> + <listitem><para>Microsoft ships the source to CString (in the files + MFC\SRC\Str{core,ex}.cpp), so you could fix the allocation + bug and rebuild your MFC libraries. + <emphasis><emphasis>Note:</emphasis> It looks like the CString shipped + with VC++6.0 has fixed this, although it may in fact have been + one of the VC++ SPs that did it.</emphasis> + </para></listitem> + <listitem><para><code>string</code> operations like this have O(n) complexity + <emphasis>if the implementors do it correctly</emphasis>. The libstdc++ + implementors did it correctly. Other vendors might not. + </para></listitem> + <listitem><para>While parts of the SGI STL are used in libstdc++, their + string class is not. The SGI <code>string</code> is essentially + <code>vector<char></code> and does not do any reference + counting like libstdc++'s does. (It is O(n), though.) + So if you're thinking about SGI's string or rope classes, + you're now looking at four possibilities: CString, the + libstdc++ string, the SGI string, and the SGI rope, and this + is all before any allocator or traits customizations! (More + choices than you can shake a stick at -- want fries with that?) + </para></listitem> + </itemizedlist> + + </sect1> +</chapter> + +<!-- Chapter 03 : Interacting with C --> + +</part> diff --git a/libstdc++-v3/doc/xml/manual/support.xml b/libstdc++-v3/doc/xml/manual/support.xml new file mode 100644 index 00000000000..55169590028 --- /dev/null +++ b/libstdc++-v3/doc/xml/manual/support.xml @@ -0,0 +1,448 @@ +<?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.support" xreflabel="Support"> +<?dbhtml filename="support.html"?> + +<partinfo> + <keywordset> + <keyword> + ISO C++ + </keyword> + <keyword> + library + </keyword> + </keywordset> +</partinfo> + +<title>Support</title> + +<preface> + <title></title> + <para> + This part deals with the functions called and objects created + automatically during the course of a program's existence. + </para> + + <para> + While we can't reproduce the contents of the Standard here (you + need to get your own copy from your nation's member body; see our + homepage for help), we can mention a couple of changes in what + kind of support a C++ program gets from the Standard Library. + </para> +</preface> + +<chapter id="manual.support.types" xreflabel="Types"> + <title>Types</title> + <sect1 id="manual.support.types.fundamental" xreflabel="Fundamental Types"> + <title>Fundamental Types</title> + <para> + C++ has the following builtin types: + </para> + <itemizedlist> + <listitem><para> + char + </para></listitem> + <listitem><para> + signed char + </para></listitem> + <listitem><para> + unsigned char + </para></listitem> + <listitem><para> + signed short + </para></listitem> + <listitem><para> + signed int + </para></listitem> + <listitem><para> + signed long + </para></listitem> + <listitem><para> + unsigned short + </para></listitem> + <listitem><para> + unsigned int + </para></listitem> + <listitem><para> + unsigned long + </para></listitem> + <listitem><para> + bool + </para></listitem> + <listitem><para> + wchar_t + </para></listitem> + <listitem><para> + float + </para></listitem> + <listitem><para> + double + </para></listitem> + <listitem><para> + long double + </para></listitem> + </itemizedlist> + + <para> + These fundamental types are always available, without having to + include a header file. These types are exactly the same in + either C++ or in C. + </para> + + <para> + Specializing parts of the library on these types is prohibited: + instead, use a POD. + </para> + + </sect1> + <sect1 id="manual.support.types.numeric_limits" xreflabel="Numeric Properites"> + <title>Numeric Properties</title> + + + <para> + The header <filename class="headerfile">limits</filename> defines + traits classes to give access to various implementation + defined-aspects of the fundamental types. The traits classes -- + fourteen in total -- are all specializations of the template class + <classname>numeric_limits</classname>, documented <ulink + url="http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/structstd_1_1numeric__limits.html">here</ulink> + and defined as follows: + </para> + + <programlisting> + template<typename T> + struct class + { + static const bool is_specialized; + static T max() throw(); + static T min() throw(); + + static const int digits; + static const int digits10; + static const bool is_signed; + static const bool is_integer; + static const bool is_exact; + static const int radix; + static T epsilon() throw(); + static T round_error() throw(); + + static const int min_exponent; + static const int min_exponent10; + static const int max_exponent; + static const int max_exponent10; + + static const bool has_infinity; + static const bool has_quiet_NaN; + static const bool has_signaling_NaN; + static const float_denorm_style has_denorm; + static const bool has_denorm_loss; + static T infinity() throw(); + static T quiet_NaN() throw(); + static T denorm_min() throw(); + + static const bool is_iec559; + static const bool is_bounded; + static const bool is_modulo; + + static const bool traps; + static const bool tinyness_before; + static const float_round_style round_style; + }; + </programlisting> + </sect1> + + <sect1 id="manual.support.types.null" xreflabel="NULL"> + <title>NULL</title> + <para> + The only change that might affect people is the type of + <constant>NULL</constant>: while it is required to be a macro, + the definition of that macro is <emphasis>not</emphasis> allowed + to be <constant>(void*)0</constant>, which is often used in C. + </para> + + <para> + For <command>g++</command>, <constant>NULL</constant> is + <programlisting>#define</programlisting>'d to be + <constant>__null</constant>, a magic keyword extension of + <command>g++</command>. + </para> + + <para> + The biggest problem of #defining <constant>NULL</constant> to be + something like <quote>0L</quote> is that the compiler will view + that as a long integer before it views it as a pointer, so + overloading won't do what you expect. (This is why + <command>g++</command> has a magic extension, so that + <constant>NULL</constant> is always a pointer.) + </para> + + <para>In his book <ulink + url="http://www.awprofessional.com/titles/0-201-92488-9/"><emphasis>Effective + C++</emphasis></ulink>, Scott Meyers points out that the best way + to solve this problem is to not overload on pointer-vs-integer + types to begin with. He also offers a way to make your own magic + <constant>NULL</constant> that will match pointers before it + matches integers. + </para> + <para>See + <ulink url="http://www.awprofessional.com/titles/0-201-31015-5/">the + Effective C++ CD example</ulink> + </para> + </sect1> + +</chapter> + +<chapter id="manual.support.memory" xreflabel="Dynamic Memory"> + <title>Dynamic Memory</title> + <para> + There are six flavors each of <function>new</function> and + <function>delete</function>, so make certain that you're using the right + ones. Here are quickie descriptions of <function>new</function>: + </para> + <itemizedlist> + <listitem><para> + single object form, throwing a + <classname>bad_alloc</classname> on errors; this is what most + people are used to using + </para></listitem> + <listitem><para> + Single object "nothrow" form, returning NULL on errors + </para></listitem> + <listitem><para> + Array <function>new</function>, throwing + <classname>bad_alloc</classname> on errors + </para></listitem> + <listitem><para> + Array nothrow <function>new</function>, returning + <constant>NULL</constant> on errors + </para></listitem> + <listitem><para> + Placement <function>new</function>, which does nothing (like + it's supposed to) + </para></listitem> + <listitem><para> + Placement array <function>new</function>, which also does + nothing + </para></listitem> + </itemizedlist> + <para> + They are distinguished by the parameters that you pass to them, like + any other overloaded function. The six flavors of <function>delete</function> + are distinguished the same way, but none of them are allowed to throw + an exception under any circumstances anyhow. (They match up for + completeness' sake.) + </para> + <para> + Remember that it is perfectly okay to call <function>delete</function> on a + NULL pointer! Nothing happens, by definition. That is not the + same thing as deleting a pointer twice. + </para> + <para> + By default, if one of the <quote>throwing <function>new</function>s</quote> can't + allocate the memory requested, it tosses an instance of a + <classname>bad_alloc</classname> exception (or, technically, some class derived + from it). You can change this by writing your own function (called a + new-handler) and then registering it with <function>set_new_handler()</function>: + </para> + <programlisting> + typedef void (*PFV)(void); + + static char* safety; + static PFV old_handler; + + void my_new_handler () + { + delete[] safety; + popup_window ("Dude, you are running low on heap memory. You + should, like, close some windows, or something. + The next time you run out, we're gonna burn!"); + set_new_handler (old_handler); + return; + } + + int main () + { + safety = new char[500000]; + old_handler = set_new_handler (&my_new_handler); + ... + } + </programlisting> + <para> + <classname>bad_alloc</classname> is derived from the base <classname>exception</classname> + class defined in Chapter 19. + </para> +</chapter> + +<chapter id="manual.support.termination" xreflabel="Termination"> + <title>Termination</title> + <sect1 id="support.termination.handlers" xreflabel="Termination Handlers"> + <title>Termination Handlers</title> + <para> + Not many changes here to <filename + class="headerfile">cstdlib</filename>. You should note that the + <function>abort()</function> function does not call the + destructors of automatic nor static objects, so if you're + depending on those to do cleanup, it isn't going to happen. + (The functions registered with <function>atexit()</function> + don't get called either, so you can forget about that + possibility, too.) + </para> + <para> + The good old <function>exit()</function> function can be a bit + funky, too, until you look closer. Basically, three points to + remember are: + </para> + <orderedlist> + <listitem> + <para> + Static objects are destroyed in reverse order of their creation. + </para> + </listitem> + <listitem> + <para> + Functions registered with <function>atexit()</function> are called in + reverse order of registration, once per registration call. + (This isn't actually new.) + </para> + </listitem> + <listitem> + <para> + The previous two actions are <quote>interleaved,</quote> that is, + given this pseudocode: + </para> +<programlisting> + extern "C or C++" void f1 (void); + extern "C or C++" void f2 (void); + + static Thing obj1; + atexit(f1); + static Thing obj2; + atexit(f2); +</programlisting> + <para> + then at a call of <function>exit()</function>, + <varname>f2</varname> will be called, then + <varname>obj2</varname> will be destroyed, then + <varname>f1</varname> will be called, and finally + <varname>obj1</varname> will be destroyed. If + <varname>f1</varname> or <varname>f2</varname> allow an + exception to propagate out of them, Bad Things happen. + </para> + </listitem> + </orderedlist> + <para> + Note also that <function>atexit()</function> is only required to store 32 + functions, and the compiler/library might already be using some of + those slots. If you think you may run out, we recommend using + the <function>xatexit</function>/<function>xexit</function> combination from <literal>libiberty</literal>, which has no such limit. + </para> + </sect1> + + <sect1 id="support.termination.verbose" xreflabel="Verbose Terminate Handler"> + <title>Verbose Terminate Handler</title> + <para> + If you are having difficulty with uncaught exceptions and want a + little bit of help debugging the causes of the core dumps, you can + make use of a GNU extension, the verbose terminate handler. + </para> + +<programlisting> +#include <exception> + +int main() +{ + std::set_terminate(__gnu_cxx::__verbose_terminate_handler); + ... + + throw <replaceable>anything</replaceable>; +} +</programlisting> + + <para> + The <function>__verbose_terminate_handler</function> function + obtains the name of the current exception, attempts to demangle + it, and prints it to stderr. If the exception is derived from + <classname>exception</classname> then the output from + <function>what()</function> will be included. + </para> + + <para> + Any replacement termination function is required to kill the + program without returning; this one calls abort. + </para> + + <para> + For example: + </para> + +<programlisting> +#include <exception> +#include <stdexcept> + +struct argument_error : public std::runtime_error +{ + argument_error(const std::string& s): std::runtime_error(s) { } +}; + +int main(int argc) +{ + std::set_terminate(__gnu_cxx::__verbose_terminate_handler); + if (argc > 5) + throw argument_error(<quote>argc is greater than 5!</quote>); + else + throw argc; +} +</programlisting> + + <para> + With the verbose terminate handler active, this gives: + </para> + + <screen> + <computeroutput> + % ./a.out + terminate called after throwing a `int' + Aborted + % ./a.out f f f f f f f f f f f + terminate called after throwing an instance of `argument_error' + what(): argc is greater than 5! + Aborted + </computeroutput> + </screen> + + <para> + The 'Aborted' line comes from the call to + <function>abort()</function>, of course. + </para> + + <para> + This is the default termination handler; nothing need be done to + use it. To go back to the previous <quote>silent death</quote> + method, simply include <filename>exception</filename> and + <filename>cstdlib</filename>, and call + </para> + + <programlisting> + std::set_terminate(std::abort); + </programlisting> + + <para> + After this, all calls to <function>terminate</function> will use + <function>abort</function> as the terminate handler. + </para> + + <para> + Note: the verbose terminate handler will attempt to write to + stderr. If your application closes stderr or redirects it to an + inappropriate location, + <function>__verbose_terminate_handler</function> will behave in + an unspecified manner. + </para> + + </sect1> +</chapter> + +</part> diff --git a/libstdc++-v3/doc/xml/manual/test.xml b/libstdc++-v3/doc/xml/manual/test.xml new file mode 100644 index 00000000000..076138d10da --- /dev/null +++ b/libstdc++-v3/doc/xml/manual/test.xml @@ -0,0 +1,823 @@ +<sect1 id="manual.intro.setup.test" xreflabel="Testing"> +<?dbhtml filename="test.html"?> + +<sect1info> + <keywordset> + <keyword> + ISO C++ + </keyword> + <keyword> + test + </keyword> + <keyword> + testsuite + </keyword> + </keywordset> +</sect1info> + +<title>Test</title> + +<sect2 id="test.organization" xreflabel="test.organization"> +<title>Organization</title> +<para> + The directory <emphasis>libsrcdir/testsuite</emphasis> contains the + individual test cases organized in sub-directories corresponding to + chapters of the C++ standard (detailed below), the dejagnu test + harness support files, and sources to various testsuite utilities + that are packaged in a separate testing library. +</para> + +<para> + All test cases for functionality required by the runtime components + of the C++ standard (ISO 14882) are files within the following + directories. +</para> + + <programlisting> +17_intro +18_support +19_diagnostics +20_util +21_strings +22_locale +23_containers +25_algorithms +26_numerics +27_io + </programlisting> + + <para> + In addition, the following directories include test files: + </para> + + <programlisting> +tr1 Tests for components as described by the Technical Report on Standard Library Extensions (TR1). +backward Tests for backwards compatibility and deprecated features. +demangle Tests for __cxa_demangle, the IA 64 C++ ABI demangler +ext Tests for extensions. +performance Tests for performance analysis, and performance regressions. +thread Tests for threads. + </programlisting> + + <para> + Some directories don't have test files, but instead contain + auxiliary information (<ulink url="#internals">more information</ulink>): + </para> + + <programlisting> +config Files for the dejagnu test harness. +lib Files for the dejagnu test harness. +libstdc++* Files for the dejagnu test harness. +data Sample text files for testing input and output. +util Files for libtestc++, utilities and testing routines. + </programlisting> + + <para> + Within a directory that includes test files, there may be + additional subdirectories, or files. Originally, test cases + were appended to one file that represented a particular section + of the chapter under test, and was named accordingly. For + instance, to test items related to <code> 21.3.6.1 - + basic_string::find [lib.string::find]</code> in the standard, + the following was used: + </para> + <programlisting> +21_strings/find.cc + </programlisting> + <para> + However, that practice soon became a liability as the test cases + became huge and unwieldy, and testing new or extended + functionality (like wide characters or named locales) became + frustrating, leading to aggressive pruning of test cases on some + platforms that covered up implementation errors. Now, the test + suite has a policy of one file, one test case, which solves the + above issues and gives finer grained results and more manageable + error debugging. As an example, the test case quoted above + becomes: + </para> + <programlisting> +21_strings/basic_string/find/char/1.cc +21_strings/basic_string/find/char/2.cc +21_strings/basic_string/find/char/3.cc +21_strings/basic_string/find/wchar_t/1.cc +21_strings/basic_string/find/wchar_t/2.cc +21_strings/basic_string/find/wchar_t/3.cc + </programlisting> + + <para> + All new tests should be written with the policy of one test + case, one file in mind. + </para> + +</sect2> + +<sect2 id="test.naming" xreflabel="test.naming"> +<title>Naming Conventions</title> + <para> + </para> + + <para> + In addition, there are some special names and suffixes that are + used within the testsuite to designate particular kinds of + tests. + </para> + +<itemizedlist> +<listitem> + <para> + <emphasis>_xin.cc</emphasis> + </para> + <para> + This test case expects some kind of interactive input in order + to finish or pass. At the moment, the interactive tests are not + run by default. Instead, they are run by hand, like: + </para> + <programlisting> +g++ 27_io/objects/char/3_xin.cc +cat 27_io/objects/char/3_xin.in | a.out + </programlisting> +</listitem> +<listitem> + <para> + <emphasis>.in</emphasis> + </para> + <para> + This file contains the expected input for the corresponding <emphasis> + _xin.cc</emphasis> test case. + </para> +</listitem> +<listitem> + <para> + <emphasis>_neg.cc</emphasis> + </para> + <para> + This test case is expected to fail: it's a negative test. At the + moment, these are almost always compile time errors. + </para> +</listitem> +<listitem> + <para> + <emphasis>char</emphasis> + </para> + <para> + This can either be a directory name or part of a longer file + name, and indicates that this file, or the files within this + directory are testing the <code>char</code> instantiation of a + template. + </para> +</listitem> +<listitem> + <para> + <emphasis>wchar_t</emphasis> + </para> + <para> + This can either be a directory name or part of a longer file + name, and indicates that this file, or the files within this + directory are testing the <code>wchar_t</code> instantiation of + a template. Some hosts do not support <code>wchar_t</code> + functionality, so for these targets, all of these tests will not + be run. + </para> +</listitem> +<listitem> + <para> + <emphasis>thread</emphasis> + </para> + <para> + This can either be a directory name or part of a longer file + name, and indicates that this file, or the files within this + directory are testing situations where multiple threads are + being used. + </para> +</listitem> +<listitem> + <para> + <emphasis>performance</emphasis> + </para> + <para> + This can either be an enclosing directory name or part of a + specific file name. This indicates a test that is used to + analyze runtime performance, for performance regression testing, + or for other optimization related analysis. At the moment, these + test cases are not run by default. + </para> +</listitem> +</itemizedlist> + +</sect2> + +<sect2 id="test.utils" xreflabel="test.utils"> +<title>Utilities</title> + <para> + </para> + <para> + The testsuite directory also contains some files that implement + functionality that is intended to make writing test cases easier, + or to avoid duplication, or to provide error checking in a way that + is consistent across platforms and test harnesses. A stand-alone + executable, called <emphasis>abi_check</emphasis>, and a static + library called <emphasis>libtestc++</emphasis> are + constructed. Both of these items are not installed, and only used + during testing. + </para> + + <para> + These files include the following functionality: + </para> + + <itemizedlist> + <listitem> + <para> + <emphasis>testsuite_abi.h</emphasis>, + <emphasis>testsuite_abi.cc</emphasis>, + <emphasis>testsuite_abi_check.cc</emphasis> + </para> + <para> + Creates the executable <emphasis>abi_check</emphasis>. + Used to check correctness of symbol versioning, visibility of + exported symbols, and compatibility on symbols in the shared + library, for hosts that support this feature. More information + can be found in the ABI documentation <ulink url="abi.html">here</ulink> + </para> + </listitem> + <listitem> + <para> + <emphasis>testsuite_allocator.h</emphasis>, + <emphasis>testsuite_allocator.cc</emphasis> + </para> + <para> + Contains specialized allocators that keep track of construction + and destruction. Also, support for overriding global new and + delete operators, including verification that new and delete + are called during execution, and that allocation over max_size + fails. + </para> + </listitem> + <listitem> + <para> + <emphasis>testsuite_character.h</emphasis> + </para> + <para> + Contains <code>std::char_traits</code> and + <code>std::codecvt</code> specializations for a user-defined + POD. + </para> + </listitem> + <listitem> + <para> + <emphasis>testsuite_hooks.h</emphasis>, + <emphasis>testsuite_hooks.cc</emphasis> + </para> + <para> + A large number of utilities, including: + </para> + <itemizedlist> + <listitem><para>VERIFY</para></listitem> + <listitem><para>set_memory_limits</para></listitem> + <listitem><para>verify_demangle</para></listitem> + <listitem><para>run_tests_wrapped_locale</para></listitem> + <listitem><para>run_tests_wrapped_env</para></listitem> + <listitem><para>try_named_locale</para></listitem> + <listitem><para>try_mkfifo</para></listitem> + <listitem><para>func_callback</para></listitem> + <listitem><para>counter</para></listitem> + <listitem><para>copy_tracker</para></listitem> + <listitem><para>copy_constructor</para></listitem> + <listitem><para>assignment_operator</para></listitem> + <listitem><para>destructor</para></listitem> + <listitem> + <para>pod_char, pod_int and associated char_traits specializations</para> + </listitem> + </itemizedlist> + </listitem> + <listitem> + <para> + <emphasis>testsuite_io.h</emphasis> + </para> + <para> + Error, exception, and constraint checking for + <code>std::streambuf, std::basic_stringbuf, std::basic_filebuf</code>. + </para> + </listitem> + <listitem> + <para> + <emphasis>testsuite_iterators.h</emphasis> + </para> + <para> + Wrappers for various iterators. + </para> + </listitem> + <listitem> + <para> + <emphasis>testsuite_performance.h</emphasis> + </para> + <para> + A number of class abstractions for performance counters, and + reporting functions including: + </para> + <itemizedlist> + <listitem><para>time_counter</para></listitem> + <listitem><para>resource_counter</para></listitem> + <listitem><para>report_performance</para></listitem> + </itemizedlist> + </listitem> + </itemizedlist> + +</sect2> + +<sect2 id="test.run" xreflabel="test.run"> +<title>Running the Testsuite</title> + + <sect3 id="test.run.basic" xreflabel="test.run.basic"> + <title>Basic Results</title> + <para> + There are several options for running tests, including testing + the regression tests, testing a subset of the regression tests, + testing the performance tests, testing just compilation, testing + installed tools, etc. In addition, there is a special rule for + checking the exported symbols of the shared library. + </para> + + <para> + You can check the status of the build without installing it + using the dejagnu harness, much like the rest of the gcc + tools.</para> + <programlisting> make check</programlisting> + <para>in the <emphasis>libbuilddir</emphasis> directory.</para> + <para>or</para> + <programlisting> make check-target-libstdc++-v3</programlisting> + <para>in the <emphasis>gccbuilddir</emphasis> directory. + </para> + + <para> + These commands are functionally equivalent and will create a + 'testsuite' directory underneath + <emphasis>libbuilddir</emphasis> containing the results of the + tests. Two results files will be generated: <emphasis> + libstdc++.sum</emphasis>, which is a PASS/FAIL summary for each + test, and <emphasis>libstdc++.log</emphasis> which is a log of + the exact command line passed to the compiler, the compiler + output, and the executable output (if any). + </para> + + <para> + Archives of test results for various versions and platforms are + available on the GCC website in the <ulink + url="http://gcc.gnu.org/gcc-4.1/buildstat.html">build + status</ulink> section of each individual release, and are also + archived on a daily basis on the <ulink + url="http://gcc.gnu.org/ml/gcc-testresults/current">gcc-testresults</ulink> + mailing list. Please check either of these places for a similar + combination of source version, operating system, and host CPU. + </para> + </sect3> + + <sect3 id="test.run.options" xreflabel="test.run.options"> + <title>Options</title> + <para> + To debug the dejagnu test harness during runs, try invoking with a + specific argument to the variable RUNTESTFLAGS, as below. + </para> + +<programlisting> +make check-target-libstdc++-v3 RUNTESTFLAGS="-v" +</programlisting> + + <para> + or + </para> + +<programlisting> +make check-target-libstdc++-v3 RUNTESTFLAGS="-v -v" +</programlisting> + + <para> + To run a subset of the library tests, you will need to generate + the <emphasis>testsuite_files</emphasis> file by running + <command>make testsuite_files</command> in the + <emphasis>libbuilddir/testsuite</emphasis> directory, described + below. Edit the file to remove the tests you don't want and + then run the testsuite as normal. + </para> + + <para> + There are two ways to run on a simulator: set up DEJAGNU to point to a + specially crafted site.exp, or pass down --target_board flags. + </para> + + <para> + Example flags to pass down for various embedded builds are as follows: + </para> + +<programlisting> + --target=powerpc-eabism (libgloss/sim) +make check-target-libstdc++-v3 RUNTESTFLAGS="--target_board=powerpc-sim" + +--target=calmrisc32 (libgloss/sid) +make check-target-libstdc++-v3 RUNTESTFLAGS="--target_board=calmrisc32-sid" + +--target=xscale-elf (newlib/sim) +make check-target-libstdc++-v3 RUNTESTFLAGS="--target_board=arm-sim" +</programlisting> + + <para> + Also, here is an example of how to run the libstdc++ testsuite + for a multilibed build directory with different ABI settings: + </para> + + <programlisting> +make check-target-libstdc++-v3 RUNTESTFLAGS='--target_board \"unix{-mabi=32,,-mabi=64}\"' +</programlisting> + + <para> + You can run the tests with a compiler and library that have + already been installed. Make sure that the compiler (e.g., + <code>g++</code>) is in your <code>PATH</code>. If you are + using shared libraries, then you must also ensure that the + directory containing the shared version of libstdc++ is in your + <code>LD_LIBRARY_PATH</code>, or equivalent. If your GCC source + tree is at <code>/path/to/gcc</code>, then you can run the tests + as follows: + </para> + +<programlisting> +runtest --tool libstdc++ --srcdir=/path/to/gcc/libstdc++-v3/testsuite +</programlisting> + + <para> + The testsuite will create a number of files in the directory in + which you run this command,. Some of those files might use the + same name as files created by other testsuites (like the ones + for GCC and G++), so you should not try to run all the + testsuites in parallel from the same directory. + </para> + + <para> + In addition, there are some testing options that are mostly of + interest to library maintainers and system integrators. As such, + these tests may not work on all cpu and host combinations, and + may need to be executed in the + <emphasis>libbuilddir/testsuite</emphasis> directory. These + options include, but are not necessarily limited to, the + following: + </para> + + <programlisting> + make testsuite_files + </programlisting> + + <para> + Five files are generated that determine what test files + are run. These files are: + </para> + + <itemizedlist> + <listitem> + <para> + <emphasis>testsuite_files</emphasis> + </para> + <para> + This is a list of all the test cases that will be run. Each + test case is on a separate line, given with an absolute path + from the <emphasis>libsrcdir/testsuite</emphasis> directory. + </para> + </listitem> + + <listitem> + <para> + <emphasis>testsuite_files_interactive</emphasis> + </para> + <para> + This is a list of all the interactive test cases, using the + same format as the file list above. These tests are not run + by default. + </para> + </listitem> + + <listitem> + <para> + <emphasis>testsuite_files_performance</emphasis> + </para> + <para> + This is a list of all the performance test cases, using the + same format as the file list above. These tests are not run + by default. + </para> + </listitem> + + <listitem> + <para> + <emphasis>testsuite_thread</emphasis> + </para> + <para> + This file indicates that the host system can run tests which + incolved multiple threads. + </para> + </listitem> + + <listitem> + <para> + <emphasis>testsuite_wchar_t</emphasis> + </para> + <para> + This file indicates that the host system can run the wchar_t + tests, and corresponds to the macro definition <code> + _GLIBCXX_USE_WCHAR_T</code> in the file c++config.h. + </para> + </listitem> + </itemizedlist> + + <programlisting> + make check-abi + </programlisting> + + <para> + The library ABI can be tested. This involves testing the shared + library against an ABI-defining previous version of symbol + exports. + </para> + + <programlisting> + make check-compile + </programlisting> + + <para> + This rule compiles, but does not link or execute, the + <emphasis>testsuite_files</emphasis> test cases and displays the + output on stdout. + </para> + + <programlisting> + make check-performance + </programlisting> + + <para> + This rule runs through the + <emphasis>testsuite_files_performance</emphasis> test cases and + collects information for performance analysis and can be used to + spot performance regressions. Various timing information is + collected, as well as number of hard page faults, and memory + used. This is not run by default, and the implementation is in + flux. + </para> + + <para> + We are interested in any strange failures of the testsuite; + please email the main libstdc++ mainling list if you see + something odd or have questions. + </para> + </sect3> + + <sect3 id="test.run.permutations" xreflabel="test.run.permutations"> + <title>Test Permutations</title> + <para> + To run the libstdc++ test suite under the <link + linkend="manual.ext.debug_mode">debug mode</link>, edit + <filename>libstdc++-v3/scripts/testsuite_flags</filename> to add the + compile-time flag <constant>-D_GLIBCXX_DEBUG</constant> to the + result printed by the <literal>--build-cxx</literal> + option. Additionally, add the + <constant>-D_GLIBCXX_DEBUG_PEDANTIC</constant> flag to turn on + pedantic checking. The libstdc++ test suite should produce + precisely the same results under debug mode that it does under + release mode: any deviation indicates an error in either the + library or the test suite. + </para> + + <para> + Or, just run the testsuites with <constant>CXXFLAGS</constant> + set to <constant>-D_GLIBCXX_DEBUG</constant>. + </para> + </sect3> +</sect2> + +<sect2 id="test.new_tests" xreflabel="test.new_tests"> +<title>New Test Cases</title> + + <para> + The first step in making a new test case is to choose the correct + directory and file name, given the organization as previously + described. + </para> + + <para> + All files are copyright the FSF, and GPL'd: this is very + important. The first copyright year should correspond to the date + the file was checked in to SVN. + </para> + + <para> + As per the dejagnu instructions, always return 0 from main to + indicate success. + </para> + + <para> + A bunch of utility functions and classes have already been + abstracted out into the testsuite utility library, <code> + libtestc++</code>. To use this functionality, just include the + appropriate header file: the library or specific object files will + automatically be linked in as part of the testsuite run. + </para> + + <para> + For a test that needs to take advantage of the dejagnu test + harness, what follows below is a list of special keyword that + harness uses. Basically, a test case contains dg-keywords (see + dg.exp) indicating what to do and what kinds of behavior are to be + expected. New test cases should be written with the new style + DejaGnu framework in mind. + </para> + + <para> + To ease transition, here is the list of dg-keyword documentation + lifted from dg.exp. + </para> + +<programlisting> +# The currently supported options are: +# +# dg-prms-id N +# set prms_id to N +# +# dg-options "options ..." [{ target selector }] +# specify special options to pass to the tool (eg: compiler) +# +# dg-do do-what-keyword [{ target/xfail selector }] +# `do-what-keyword' is tool specific and is passed unchanged to +# ${tool}-dg-test. An example is gcc where `keyword' can be any of: +# preprocess|compile|assemble|link|run +# and will do one of: produce a .i, produce a .s, produce a .o, +# produce an a.out, or produce an a.out and run it (the default is +# compile). +# +# dg-error regexp comment [{ target/xfail selector } [{.|0|linenum}]] +# indicate an error message <regexp> is expected on this line +# (the test fails if it doesn't occur) +# Linenum=0 for general tool messages (eg: -V arg missing). +# "." means the current line. +# +# dg-warning regexp comment [{ target/xfail selector } [{.|0|linenum}]] +# indicate a warning message <regexp> is expected on this line +# (the test fails if it doesn't occur) +# +# dg-bogus regexp comment [{ target/xfail selector } [{.|0|linenum}]] +# indicate a bogus error message <regexp> use to occur here +# (the test fails if it does occur) +# +# dg-build regexp comment [{ target/xfail selector }] +# indicate the build use to fail for some reason +# (errors covered here include bad assembler generated, tool crashes, +# and link failures) +# (the test fails if it does occur) +# +# dg-excess-errors comment [{ target/xfail selector }] +# indicate excess errors are expected (any line) +# (this should only be used sparingly and temporarily) +# +# dg-output regexp [{ target selector }] +# indicate the expected output of the program is <regexp> +# (there may be multiple occurrences of this, they are concatenated) +# +# dg-final { tcl code } +# add some tcl code to be run at the end +# (there may be multiple occurrences of this, they are concatenated) +# (unbalanced braces must be \-escaped) +# +# "{ target selector }" is a list of expressions that determine whether the +# test succeeds or fails for a particular target, or in some cases whether the +# option applies for a particular target. If the case of `dg-do' it specifies +# whether the test case is even attempted on the specified target. +# +# The target selector is always optional. The format is one of: +# +# { xfail *-*-* ... } - the test is expected to fail for the given targets +# { target *-*-* ... } - the option only applies to the given targets +# +# At least one target must be specified, use *-*-* for "all targets". +# At present it is not possible to specify both `xfail' and `target'. +# "native" may be used in place of "*-*-*". + +Example 1: Testing compilation only +// { dg-do compile } + +Example 2: Testing for expected warnings on line 36, which all targets fail +// { dg-warning "string literals" "" { xfail *-*-* } 36 + +Example 3: Testing for expected warnings on line 36 +// { dg-warning "string literals" "" { target *-*-* } 36 + +Example 4: Testing for compilation errors on line 41 +// { dg-do compile } +// { dg-error "no match for" "" { target *-*-* } 41 } + +Example 5: Testing with special command line settings, or without the +use of pre-compiled headers, in particular the stdc++.h.gch file. Any +options here will override the DEFAULT_CXXFLAGS and PCH_CXXFLAGS set +up in the normal.exp file. +// { dg-options "-O0" { target *-*-* } } +</programlisting> + + <para> + More examples can be found in the libstdc++-v3/testsuite/*/*.cc files. + </para> + + +</sect2> + +<sect2 id="test.dejagnu" xreflabel="test.dejagnu"> +<title>Test Harness Details</title> + <para> + Underlying details of testing are abstracted via the GNU Dejagnu package. + </para> + + +<para>This is information for those looking at making changes to the testsuite +structure, and/or needing to trace dejagnu's actions with --verbose. This +will not be useful to people who are "merely" adding new tests to the existing +structure. +</para> + +<para>The first key point when working with dejagnu is the idea of a "tool". +Files, directories, and functions are all implicitly used when they are +named after the tool in use. Here, the tool will always be "libstdc++". +</para> + +<para>The <code>lib</code> subdir contains support routines. The +<code>lib/libstdc++.exp</code> file ("support library") is loaded +automagically, and must explicitly load the others. For example, files can +be copied from the core compiler's support directory into <code>lib</code>. +</para> + +<para>Some routines in <code>lib/libstdc++.exp</code> are callbacks, some are +our own. Callbacks must be prefixed with the name of the tool. To easily +distinguish the others, by convention our own routines are named "v3-*". +</para> + +<para>The next key point when working with dejagnu is "test files". Any +directory whose name starts with the tool name will be searched for test files. +(We have only one.) In those directories, any <code>.exp</code> file is +considered a test file, and will be run in turn. Our main test file is called +<code>normal.exp</code>; it runs all the tests in testsuite_files using the +callbacks loaded from the support library. +</para> + +<para>The <code>config</code> directory is searched for any particular "target +board" information unique to this library. This is currently unused and sets +only default variables. +</para> + +</sect2> + +<sect2 id="test.future" xreflabel="test.future"> +<title>Future</title> + <para> + </para> + + +<para> +Shared runs need to be implemented, for targets that support shared libraries. +</para> + +<para> +Diffing of expected output to standard streams needs to be finished off. +</para> + +<para> +The V3 testing framework supports, or will eventually support, +additional keywords for the purpose of easing the job of writing +test cases. All V3-keywords are of the form <code>@xxx@</code>. +Currently plans for supported keywords include: +</para> + +<variablelist> +<varlistentry><term> <code> @require@ <files> </code> </term> +<listitem> + <para> + The existence of <files> is essential for the test to complete + successfully. For example, a test case foo.C using bar.baz as + input file could say + </para> + <programlisting> + // @require@ bar.baz</programlisting> + <para> + The special variable % stands for the rootname, e.g. the + file-name without its `.C' extension. Example of use (taken + verbatim from 27_io/filebuf.cc) + </para> + <programlisting> + // @require@ %-*.tst %-*.txt</programlisting> +</listitem></varlistentry> +<varlistentry><term> <code> @diff@ <first-list> <second-list> </code> </term> +<listitem> + <para> + After the test case compiles and ran successfully, diff + <first-list> against <second-list>, these lists should + have the same length. The test fails if diff returns non-zero a + pair of files. + </para> +</listitem></varlistentry> +</variablelist> + +</sect2> + +</sect1>
\ No newline at end of file diff --git a/libstdc++-v3/doc/xml/manual/using.xml b/libstdc++-v3/doc/xml/manual/using.xml new file mode 100644 index 00000000000..2782596201f --- /dev/null +++ b/libstdc++-v3/doc/xml/manual/using.xml @@ -0,0 +1,1024 @@ +<?xml version='1.0'?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" +[ ]> + +<chapter id="manual.intro.using" xreflabel="Using"> +<?dbhtml filename="using.html"?> + +<title>Using</title> + + <sect1 id="manual.intro.using.lib" xreflabel="Lib"> + <title>Linking Library Binary Files</title> + + <para> + If you only built a static library (libstdc++.a), or if you + specified static linking, you don't have to worry about this. + But if you built a shared library (libstdc++.so) and linked + against it, then you will need to find that library when you run + the executable. + </para> + <para> + Methods vary for different platforms and different styles, but + the usual ones are printed to the screen during installation. + They include: + </para> + <itemizedlist> + <listitem> + <para> + At runtime set LD_LIBRARY_PATH in your environment + correctly, so that the shared library for libstdc++ can be + found and loaded. Be certain that you understand all of the + other implications and behavior of LD_LIBRARY_PATH first + (few people do, and they get into trouble). + </para> + </listitem> + <listitem> + <para> + Compile the path to find the library at runtime into the + program. This can be done by passing certain options to + g++, which will in turn pass them on to the linker. The + exact format of the options is dependent on which linker you + use: + </para> + <itemizedlist> + <listitem> + <para> + GNU ld (default on Linux):<literal>-Wl,--rpath,<filename class="directory">destdir</filename>/lib</literal> + </para> + </listitem> + <listitem> + <para> + IRIX ld:<literal> + -Wl,-rpath,<filename class="directory">destdir</filename>/lib</literal> + </para> + </listitem> + <listitem> + <para> + Solaris ld:<literal>-Wl,-R<filename class="directory">destdir</filename>/lib</literal> + </para> + </listitem> + <listitem> + <para> + More...? Let us know! + </para> + </listitem> + </itemizedlist> + </listitem> + </itemizedlist> + <para> + Use the <command>ldd</command> utility to show which library the + system thinks it will get at runtime. + </para> + <para> + A libstdc++.la file is also installed, for use with Libtool. If + you use Libtool to create your executables, these details are + taken care of for you. + </para> + </sect1> + + <sect1 id="manual.intro.using.headers" xreflabel="Headers"> + <title>Headers</title> + + <sect2 id="manual.intro.using.headers.all" xreflabel="Header Files"> + <title>Header Files</title> + + <para> + The C++ standard specifies the entire set of header files that + must be available to all hosted implementations. Actually, the + word "files" is a misnomer, since the contents of the + headers don't necessarily have to be in any kind of external + file. The only rule is that when one <code>#include</code>'s a + header, the contents of that header become available, no matter + how. + </para> + + <para> + That said, in practice files are used. + </para> + + <para> + There are two main types of include files: header files related + to a specific version of the ISO C++ standard (called Standard + Headers), and all others (TR1, C++ ABI, and Extensions). + </para> + + <para> + Two dialects of standard headers are supported, corresponding to + the 1998 standard as updated for 2003, and the draft of the + upcoming 200x standard. + </para> + + <para> + C++98/03 include files. These are available in the default compilation mode, ie <code>-std=c++98</code> or <code>-std=gnu++98</code>. + </para> + +<table frame='all'> +<title>C++ 1998 Library Headers</title> +<tgroup cols='5' align='left' colsep='1' rowsep='1'> +<colspec colname='c1'></colspec> +<colspec colname='c2'></colspec> +<colspec colname='c3'></colspec> +<colspec colname='c4'></colspec> +<tbody> +<row><entry><filename class="headerfile">algorithm</filename></entry><entry><filename class="headerfile">iomanip</filename></entry><entry><filename class="headerfile">list</filename></entry><entry><filename class="headerfile">ostream</filename></entry><entry><filename class="headerfile">streambuf</filename></entry></row> +<row><entry><filename class="headerfile">bitset</filename></entry><entry><filename class="headerfile">ios</filename></entry><entry><filename class="headerfile">locale</filename></entry><entry><filename class="headerfile">queue</filename></entry><entry><filename class="headerfile">string</filename></entry></row> +<row><entry><filename class="headerfile">complex</filename></entry><entry><filename class="headerfile">iosfwd</filename></entry><entry><filename class="headerfile">map</filename></entry><entry><filename class="headerfile">set</filename></entry><entry><filename class="headerfile">typeinfo</filename></entry></row> +<row><entry><filename class="headerfile">deque</filename></entry><entry><filename class="headerfile">iostream</filename></entry><entry><filename class="headerfile">memory</filename></entry><entry><filename class="headerfile">sstream</filename></entry><entry><filename class="headerfile">utility</filename></entry></row> +<row><entry><filename class="headerfile">exception</filename></entry><entry><filename class="headerfile">istream</filename></entry><entry><filename class="headerfile">new</filename></entry><entry><filename class="headerfile">stack</filename></entry><entry><filename class="headerfile">valarray</filename></entry></row> +<row><entry><filename class="headerfile">fstream</filename></entry><entry><filename class="headerfile">iterator</filename></entry><entry><filename class="headerfile">numeric</filename></entry><entry><filename class="headerfile">stdexcept</filename></entry><entry><filename class="headerfile">vector</filename></entry></row> +<row><entry><filename class="headerfile">functional</filename></entry><entry><filename class="headerfile">limits</filename></entry></row> +</tbody> +</tgroup> +</table> + +<para></para> +<table frame='all'> +<title>C++ 1998 Library Headers for C Library Facilities</title> +<tgroup cols='5' align='left' colsep='1' rowsep='1'> +<colspec colname='c1'></colspec> +<colspec colname='c2'></colspec> +<colspec colname='c3'></colspec> +<colspec colname='c4'></colspec> +<tbody> +<row><entry><filename class="headerfile">cassert</filename></entry><entry><filename class="headerfile">ciso646</filename></entry><entry><filename class="headerfile">csetjmp</filename></entry><entry><filename class="headerfile">cstdio</filename></entry><entry><filename class="headerfile">ctime</filename></entry></row> +<row><entry><filename class="headerfile">cctype</filename></entry><entry><filename class="headerfile">climits</filename></entry><entry><filename class="headerfile">csignal</filename></entry><entry><filename class="headerfile">cstdlib</filename></entry><entry><filename class="headerfile">cwchar</filename></entry></row> +<row><entry><filename class="headerfile">cerrno</filename></entry><entry><filename class="headerfile">clocale</filename></entry><entry><filename class="headerfile">cstdarg</filename></entry><entry><filename class="headerfile">cstring</filename></entry><entry><filename class="headerfile">cwctype</filename></entry></row> +<row><entry><filename class="headerfile">cfloat</filename></entry><entry><filename class="headerfile">cmath</filename></entry><entry><filename class="headerfile">cstddef</filename></entry></row> +</tbody> +</tgroup> +</table> + +<para>C++0x include files. These are only available in C++0x compilation mode, ie <code>-std=c++0x</code> or <code>-std=gnu++0x</code>. +</para> + +<para></para> +<table frame='all'> +<title>C++ 200x Library Headers</title> +<tgroup cols='5' align='left' colsep='1' rowsep='1'> +<colspec colname='c1'></colspec> +<colspec colname='c2'></colspec> +<colspec colname='c3'></colspec> +<colspec colname='c4'></colspec> +<tbody> +<row><entry><filename class="headerfile">algorithm</filename></entry><entry><filename class="headerfile">iomanip</filename></entry><entry><filename class="headerfile">locale</filename></entry><entry><filename class="headerfile">regex</filename></entry><entry><filename class="headerfile">tuple</filename></entry></row> +<row><entry><filename class="headerfile">array</filename></entry><entry><filename class="headerfile">ios</filename></entry><entry><filename class="headerfile">map</filename></entry><entry><filename class="headerfile">set</filename></entry><entry><filename class="headerfile">typeinfo</filename></entry></row> +<row><entry><filename class="headerfile">bitset</filename></entry><entry><filename class="headerfile">iosfwd</filename></entry><entry><filename class="headerfile">memory</filename></entry><entry><filename class="headerfile">sstream</filename></entry><entry><filename class="headerfile">type_traits</filename></entry></row> +<row><entry><filename class="headerfile">complex</filename></entry><entry><filename class="headerfile">iostream</filename></entry><entry><filename class="headerfile">new</filename></entry><entry><filename class="headerfile">stack</filename></entry><entry><filename class="headerfile">unordered_map</filename></entry></row> +<row><entry><filename class="headerfile">deque</filename></entry><entry><filename class="headerfile">istream</filename></entry><entry><filename class="headerfile">numeric</filename></entry><entry><filename class="headerfile">stdexcept</filename></entry><entry><filename class="headerfile">unordered_set</filename></entry></row> +<row><entry><filename class="headerfile">exception</filename></entry><entry><filename class="headerfile">iterator</filename></entry><entry><filename class="headerfile">ostream</filename></entry><entry><filename class="headerfile">streambuf</filename></entry><entry><filename class="headerfile">utility</filename></entry></row> +<row><entry><filename class="headerfile">fstream</filename></entry><entry><filename class="headerfile">limits</filename></entry><entry><filename class="headerfile">queue</filename></entry><entry><filename class="headerfile">string</filename></entry><entry><filename class="headerfile">valarray</filename></entry></row> +<row><entry><filename class="headerfile">functional</filename></entry><entry><filename class="headerfile">list</filename></entry><entry><filename class="headerfile">random</filename></entry><entry><filename class="headerfile">system_error</filename></entry><entry><filename class="headerfile">vector</filename></entry></row> +</tbody> +</tgroup> +</table> + +<para></para> + +<table frame='all'> +<title>C++ 200x Library Headers for C Library Facilities</title> +<tgroup cols='5' align='left' colsep='1' rowsep='1'> +<colspec colname='c1'></colspec> +<colspec colname='c2'></colspec> +<colspec colname='c3'></colspec> +<colspec colname='c4'></colspec> +<colspec colname='c5'></colspec> +<tbody> +<row><entry><filename class="headerfile">cassert</filename></entry><entry><filename class="headerfile">cfloat</filename></entry><entry><filename class="headerfile">cmath</filename></entry><entry><filename class="headerfile">cstddef</filename></entry><entry><filename class="headerfile">ctgmath</filename></entry></row> +<row><entry><filename class="headerfile">ccomplex</filename></entry><entry><filename class="headerfile">cinttypes</filename></entry><entry><filename class="headerfile">csetjmp</filename></entry><entry><filename class="headerfile">cstdint</filename></entry><entry><filename class="headerfile">ctime</filename></entry></row> +<row><entry><filename class="headerfile">cctype</filename></entry><entry><filename class="headerfile">ciso646</filename></entry><entry><filename class="headerfile">csignal</filename></entry><entry><filename class="headerfile">cstdio</filename></entry><entry><filename class="headerfile">cuchar</filename></entry></row> +<row><entry><filename class="headerfile">cerrno</filename></entry><entry><filename class="headerfile">climits</filename></entry><entry><filename class="headerfile">cstdarg</filename></entry><entry><filename class="headerfile">cstdlib</filename></entry><entry><filename class="headerfile">cwchar</filename></entry></row> +<row><entry><filename class="headerfile">cfenv</filename></entry><entry><filename class="headerfile">clocale</filename></entry><entry><filename class="headerfile">cstdbool</filename></entry><entry><filename class="headerfile">cstring</filename></entry><entry><filename class="headerfile">cwctype</filename></entry></row> +</tbody> +</tgroup> +</table> + + +<para> + In addition, TR1 includes as: +</para> + +<table frame='all'> +<title>C++ TR1 Library Headers</title> +<tgroup cols='5' align='left' colsep='1' rowsep='1'> +<colspec colname='c1'></colspec> +<colspec colname='c2'></colspec> +<colspec colname='c3'></colspec> +<colspec colname='c4'></colspec> +<colspec colname='c5'></colspec> +<tbody> + +<row><entry><filename class="headerfile">tr1/array</filename></entry><entry><filename class="headerfile">tr1/memory</filename></entry><entry><filename class="headerfile">tr1/regex</filename></entry><entry><filename class="headerfile">tr1/type_traits</filename></entry><entry><filename class="headerfile">tr1/unordered_set</filename></entry></row> +<row><entry><filename class="headerfile">tr1/complex</filename></entry><entry><filename class="headerfile">tr1/random</filename></entry><entry><filename class="headerfile">tr1/tuple</filename></entry><entry><filename class="headerfile">tr1/unordered_map</filename></entry><entry><filename class="headerfile">tr1/utility</filename></entry></row> +<row><entry><filename class="headerfile">tr1/functional</filename></entry></row> +</tbody> +</tgroup> +</table> + +<para></para> + + +<table frame='all'> +<title>C++ TR1 Library Headers for C Library Facilities</title> +<tgroup cols='5' align='left' colsep='1' rowsep='1'> +<colspec colname='c1'></colspec> +<colspec colname='c2'></colspec> +<colspec colname='c3'></colspec> +<colspec colname='c4'></colspec> +<colspec colname='c5'></colspec> +<tbody> + +<row><entry><filename class="headerfile">tr1/cmath</filename></entry><entry><filename class="headerfile">tr1/cfloat</filename></entry><entry><filename class="headerfile">tr1/cstdarg</filename></entry><entry><filename class="headerfile">tr1/cstdio</filename></entry><entry><filename class="headerfile">tr1/ctime</filename></entry></row> +<row><entry><filename class="headerfile">tr1/ccomplex</filename></entry><entry><filename class="headerfile">tr1/cinttypes</filename></entry><entry><filename class="headerfile">tr1/cstdbool</filename></entry><entry><filename class="headerfile">tr1/cstdlib</filename></entry><entry><filename class="headerfile">tr1/cwchar</filename></entry></row> +<row><entry><filename class="headerfile">tr1/cfenv</filename></entry><entry><filename class="headerfile">tr1/climits</filename></entry><entry><filename class="headerfile">tr1/cstdint</filename></entry><entry><filename class="headerfile">tr1/ctgmath</filename></entry><entry><filename class="headerfile">tr1/cwctype</filename></entry></row> +</tbody> +</tgroup> +</table> + +<para> + Also included are files for the C++ ABI interface: +</para> + +<table frame='all'> +<title>C++ ABI Headers</title> +<tgroup cols='2' align='left' colsep='1' rowsep='1'> +<colspec colname='c1'></colspec> +<colspec colname='c2'></colspec> +<tbody> +<row><entry><filename class="headerfile">cxxabi.h</filename></entry><entry><filename class="headerfile">cxxabi_forced.h</filename></entry></row> +</tbody> +</tgroup> +</table> + +<para> + And a large variety of extensions. +</para> + +<table frame='all'> +<title>Extension Headers</title> +<tgroup cols='5' align='left' colsep='1' rowsep='1'> +<colspec colname='c1'></colspec> +<colspec colname='c2'></colspec> +<colspec colname='c3'></colspec> +<colspec colname='c4'></colspec> +<colspec colname='c5'></colspec> +<tbody> + +<row><entry><filename class="headerfile">ext/algorithm</filename></entry><entry><filename class="headerfile">ext/debug_allocator.h</filename></entry><entry><filename class="headerfile">ext/mt_allocator.h</filename></entry><entry><filename class="headerfile">ext/pod_char_traits.h</filename></entry><entry><filename class="headerfile">ext/stdio_sync_filebuf.h</filename></entry></row> +<row><entry><filename class="headerfile">ext/array_allocator.h</filename></entry><entry><filename class="headerfile">ext/enc_filebuf.h</filename></entry><entry><filename class="headerfile">ext/new_allocator.h</filename></entry><entry><filename class="headerfile">ext/pool_allocator.h</filename></entry><entry><filename class="headerfile">ext/throw_allocator.h</filename></entry></row> +<row><entry><filename class="headerfile">ext/atomicity.h</filename></entry><entry><filename class="headerfile">ext/functional</filename></entry><entry><filename class="headerfile">ext/numeric</filename></entry><entry><filename class="headerfile">ext/rb_tree</filename></entry><entry><filename class="headerfile">ext/typelist.h</filename></entry></row> +<row><entry><filename class="headerfile">ext/bitmap_allocator.h</filename></entry><entry><filename class="headerfile">ext/iterator</filename></entry><entry><filename class="headerfile">ext/numeric_traits.h</filename></entry><entry><filename class="headerfile">ext/rope</filename></entry><entry><filename class="headerfile">ext/type_traits.h</filename></entry></row> +<row><entry><filename class="headerfile">ext/codecvt_specializations.h</filename></entry><entry><filename class="headerfile">ext/malloc_allocator.h</filename></entry><entry><filename class="headerfile">ext/pb_ds/assoc_container.h</filename></entry><entry><filename class="headerfile">ext/slist</filename></entry><entry><filename class="headerfile">ext/vstring.h</filename></entry></row> +<row><entry><filename class="headerfile">ext/concurrence.h</filename></entry><entry><filename class="headerfile">ext/memory</filename></entry><entry><filename class="headerfile">ext/pb_ds/priority_queue.h</filename></entry><entry><filename class="headerfile">ext/stdio_filebuf.h</filename></entry></row> +</tbody> +</tgroup> +</table> + +<para></para> + +<table frame='all'> +<title>Extension Debug Headers</title> +<tgroup cols='5' align='left' colsep='1' rowsep='1'> +<colspec colname='c1'></colspec> +<colspec colname='c2'></colspec> +<colspec colname='c3'></colspec> +<colspec colname='c4'></colspec> +<colspec colname='c5'></colspec> +<tbody> + +<row><entry><filename class="headerfile">debug/bitset</filename></entry><entry><filename class="headerfile">debug/list</filename></entry><entry><filename class="headerfile">debug/set</filename></entry><entry><filename class="headerfile">debug/unordered_map</filename></entry><entry><filename class="headerfile">debug/vector</filename></entry></row> +<row><entry><filename class="headerfile">debug/deque</filename></entry><entry><filename class="headerfile">debug/map</filename></entry><entry><filename class="headerfile">debug/string</filename></entry><entry><filename class="headerfile">debug/unordered_set</filename></entry></row> +</tbody> +</tgroup> +</table> + +<para></para> + +<table frame='all'> +<title>Extension Parallel Headers</title> +<tgroup cols='2' align='left' colsep='1' rowsep='1'> +<colspec colname='c1'></colspec> +<colspec colname='c2'></colspec> +<tbody> +<row><entry><filename class="headerfile">parallel/algorithm</filename></entry><entry><filename class="headerfile">parallel/numeric</filename></entry></row> +</tbody> +</tgroup> +</table> + + </sect2> + + <sect2 id="manual.intro.using.headers.mixing" xreflabel="Mixing Headers"> + <title>Mixing Headers</title> + +<para> A few simple rules. +</para> + +<para>First, mixing different dialects of the standard headers is not +possible. It's an all-or-nothing affair. Thus, code like +</para> + +<programlisting> +#include <array> +#include <functional> +</programlisting> + +<para>Implies C++0x mode. To use the entities in <array>, the C++0x +compilation mode must be used, which implies the C++0x functionality +(and deprecations) in <functional> will be present. +</para> + +<para>Second, the other headers can be included with either dialect of +the standard headers, although features and types specific to C++0x +are still only enabled when in C++0x compilation mode. So, to use +rvalue references with <code>__gnu_cxx::vstring</code>, or to use the +debug-mode versions of <code>std::unordered_map</code>, one must use +the <code>std=gnu++0x</code> compiler flag. (Or <code>std=c++0x</code>, of course.) +</para> + +<para>A special case of the second rule is the mixing of TR1 and C++0x +facilities. It is possible (although not especially prudent) to +include both the TR1 version and the C++0x version of header in the +same translation unit: +</para> + +<programlisting> +#include <tr1/type_traits> +#include <type_traits> +</programlisting> + +<para> Several parts of C++0x diverge quite substantially from TR1 predecessors. +</para> + </sect2> + + <sect2 id="manual.intro.using.headers.cheaders" xreflabel="C Headers and"> + <title>The C Headers and <code>namespace std</code></title> + +<para> + The standard specifies that if one includes the C-style header + (<math.h> in this case), the symbols will be available + in the global namespace and perhaps in + namespace <code>std::</code> (but this is no longer a firm + requirement.) One the other hand, including the C++-style + header (<cmath>) guarantees that the entities will be + found in namespace std and perhaps in the global namespace. + </para> + +<para> +Usage of C++-style headers is recommended, as then +C-linkage names can be disambiguated by explicit qualification, such +as by <code>std::abort</code>. In addition, the C++-style headers can +use function overloading to provide a simpler interface to certain +families of C-functions. For instance in <cmath>, the +function <code>std::sin</code> has overloads for all the builtin +floating-point types. This means that <code>std::sin</code> can be +used uniformly, instead of a combination +of <code>std::sinf</code>, <code>std::sin</code>, +and <code>std::sinl</code>. +</para> + </sect2> + + <sect2 id="manual.intro.using.headers.pre" xreflabel="Precompiled Headers"> + <title>Precompiled Headers</title> + + +<para>There are three base header files that are provided. They can be +used to precompile the standard headers and extensions into binary +files that may the be used to speed compiles that use these headers. +</para> + + +<itemizedlist> +<listitem> + <para>stdc++.h</para> +<para>Includes all standard headers. Actual content varies depending on +language dialect. +</para> +</listitem> + +<listitem> + <para>stdtr1c++.h</para> +<para>Includes all of <stdc++.h>, and adds all the TR1 headers. +</para> +</listitem> + +<listitem><para>extc++.h</para> +<para>Includes all of <stdtr1c++.h>, and adds all the Extension headers. +</para></listitem> +</itemizedlist> + +<para>How to construct a .gch file from one of these base header files.</para> + +<para>First, find the include directory for the compiler. One way to do +this is:</para> + +<programlisting> +g++ -v hello.cc + +#include <...> search starts here: + /mnt/share/bld/H-x86-gcc.20071201/include/c++/4.3.0 +... +End of search list. +</programlisting> + + +<para>Then, create a precompiled header file with the same flags that +will be used to compile other projects.</para> + +<programlisting> +g++ -Winvalid-pch -x c++-header -g -O2 -o ./stdc++.h.gch /mnt/share/bld/H-x86-gcc.20071201/include/c++/4.3.0/x86_64-unknown-linux-gnu/bits/stdc++.h +</programlisting> + +<para>The resulting file will be quite large: the current size is around +thirty megabytes. </para> + +<para>How to use the resulting file.</para> + +<programlisting> +g++ -I. -include stdc++.h -H -g -O2 hello.cc +</programlisting> + +<para>Verification that the PCH file is being used is easy:</para> + +<programlisting> +g++ -Winvalid-pch -I. -include stdc++.h -H -g -O2 hello.cc -o test.exe +! ./stdc++.h.gch +. /mnt/share/bld/H-x86-gcc.20071201/include/c++/4.3.0/iostream +. /mnt/share/bld/H-x86-gcc.20071201include/c++/4.3.0/string +</programlisting> + +<para>The exclamation point to the left of the <code>stdc++.h.gch</code> listing means that the generated PCH file was used, and thus the </para> +<para></para> + +<para> Detailed information about creating precompiled header files can be found in the GCC <ulink url="http://gcc.gnu.org/onlinedocs/gcc/Precompiled-Headers.html">documentation</ulink>. +</para> + + + </sect2> + </sect1> + + <sect1 id="manual.intro.using.namespaces" xreflabel="Namespaces"> + <title>Namespaces</title> + + <sect2 id="manual.intro.using.namespaces.all" xreflabel="Available Namespaces"> + <title>Available Namespaces</title> + + + +<para> There are three main namespaces. +</para> + +<itemizedlist> + <listitem><para>std</para> +<para>The ISO C++ standards specify that "all library entities are defined +within namespace std." This includes namepaces nested +within <code>namespace std</code>, such as <code>namespace +std::tr1</code>. +</para> +</listitem> +<listitem><para>abi</para> +<para>Specified by the C++ ABI. This ABI specifies a number of type and +function APIs supplemental to those required by the ISO C++ Standard, +but necessary for interoperability. +</para> +</listitem> + +<listitem><para>__gnu_</para> +<para>Indicating one of several GNU extensions. Choices +include <code>__gnu_cxx</code>, <code>__gnu_debug</code>, <code>__gnu_parallel</code>, +and <code>__gnu_pbds</code>. +</para></listitem> +</itemizedlist> + +<para> A complete list of implementation namespaces (including namespace contents) is available in the generated source <ulink url="http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/namespaces.html">documentation</ulink>. +</para> + + + </sect2> + + <sect2 id="manual.intro.using.namespaces.std" xreflabel="namespace std"> + <title>namespace std</title> + + +<para> + One standard requirement is that the library components are defined + in <code>namespace std::</code>. Thus, in order to use these types or + functions, one must do one of two things: +</para> + +<itemizedlist> + <listitem><para>put a kind of <emphasis>using-declaration</emphasis> in your source +(either <code>using namespace std;</code> or i.e. <code>using +std::string;</code>) This approach works well for individual source files, but +should not be used in a global context, like header files. + </para></listitem> <listitem><para>use a <emphasis>fully +qualified name</emphasis>for each library symbol +(i.e. <code>std::string</code>, <code>std::cout</code>) Always can be +used, and usually enhanced, by strategic use of typedefs. (In the +cases where the qualified verbiage becomes unwieldy.) + </para> + </listitem> +</itemizedlist> + + </sect2> + + <sect2 id="manual.intro.using.namespaces.comp" xreflabel="Using Namepace Composition"> + <title>Using Namespace Composition</title> + +<para> +Best practice in programming suggests sequestering new data or +functionality in a sanely-named, unique namespace whenever +possible. This is considered an advantage over dumping everything in +the global namespace, as then name look-up can be explicitly enabled or +disabled as above, symbols are consistently mangled without repetitive +naming prefixes or macros, etc. +</para> + +<para>For instance, consider a project that defines most of its classes in <code>namespace gtk</code>. It is possible to + adapt <code>namespace gtk</code> to <code>namespace std</code> by using a C++-feature called + <emphasis>namespace composition</emphasis>. This is what happens if + a <emphasis>using</emphasis>-declaration is put into a + namespace-definition: the imported symbol(s) gets imported into the + currently active namespace(s). For example: +</para> +<programlisting> +namespace gtk +{ + using std::string; + using std::tr1::array; + + class Window { ... }; +} +</programlisting> +<para> + In this example, <code>std::string</code> gets imported into + <code>namespace gtk</code>. The result is that use of + <code>std::string</code> inside namespace gtk can just use <code>string</code>, without the explicit qualification. + As an added bonus, + <code>std::string</code> does not get imported into + the global namespace. Additionally, a more elaborate arrangement can be made for backwards compatibility and portability, whereby the + <code>using</code>-declarations can wrapped in macros that + are set based on autoconf-tests to either "" or i.e. <code>using + std::string;</code> (depending on whether the system has + libstdc++ in <code>std::</code> or not). (ideas from + <email>llewelly@dbritsch.dsl.xmission.com</email>, Karl Nelson <email>kenelson@ece.ucdavis.edu</email>) +</para> + + + </sect2> + </sect1> + + <sect1 id="manual.intro.using.macros" xreflabel="Macros"> + <title>Macros</title> + + <para>All pre-processor switches and configurations are all gathered + in the file <code>c++config.h</code>, which is generated during + the libstdc++ configuration and build process, and included by + files part of the public libstdc++ API. Most of these macros + should not be used by consumers of libstdc++, and are reserved + for internal implementation use. <emphasis>These macros cannot be + redefined</emphasis>. However, a select handful of these macro + control libstdc++ extensions and extra features, or provide + versioning information for the API, and are able to be used. + </para> + + <para>All library macros begin with <code>_GLIBCXX_</code> (except for + versions 3.1.x to 3.3.x, which use <code>_GLIBCPP_</code>). + </para> + + <para>Below is the macro which users may check for library version + information. </para> + + <variablelist> + <varlistentry> + <term><code>__GLIBCXX__</code></term> + <listitem> + <para>The current version of + libstdc++ in compressed ISO date format, form of an unsigned + long. For details on the value of this particular macro for a + particular release, please consult this <ulink url="abi.html"> + document</ulink>. + </para> + </listitem> + </varlistentry> + </variablelist> + + <para>Below are the macros which users may change with #define/#undef or + with -D/-U compiler flags. The default state of the symbol is + listed.</para> + + <para><quote>Configurable</quote> (or <quote>Not configurable</quote>) means + that the symbol is initially chosen (or not) based on + --enable/--disable options at library build and configure time + (documented <link linkend="manual.intro.setup.configure">here</link>), with the + various --enable/--disable choices being translated to + #define/#undef). + </para> + + <para> <acronym>ABI</acronym> means that changing from the default value may + mean changing the <acronym>ABI</acronym> of compiled code. In other words, these + choices control code which has already been compiled (i.e., in a + binary such as libstdc++.a/.so). If you explicitly #define or + #undef these macros, the <emphasis>headers</emphasis> may see different code + paths, but the <emphasis>libraries</emphasis> which you link against will not. + Experimenting with different values with the expectation of + consistent linkage requires changing the config headers before + building/installing the library. + </para> + + <variablelist> + <varlistentry><term><code>_GLIBCXX_DEPRECATED</code></term> + <listitem> + <para> + Defined by default. Not configurable. ABI-changing. Turning this off + removes older ARM-style iostreams code, and other anachronisms + from the API. This macro is dependent on the version of the + standard being tracked, and as a result may give different results for + <code>-std=c++98</code> and <code>-std=c++0x</code>. This may + be useful in updating old C++ code which no longer meet the + requirements of the language, or for checking current code + against new language standards. + </para> + </listitem></varlistentry> + + <varlistentry><term><code>_GLIBCXX_FORCE_NEW</code></term> + <listitem> + <para> + Undefined by default. When defined, memory allocation and + allocators controlled by libstdc++ call operator new/delete + without caching and pooling. Configurable via + <code>--enable-libstdcxx-allocator</code>. ABI-changing. + </para> + </listitem></varlistentry> + + + <varlistentry><term><code>_GLIBCXX_CONCEPT_CHECKS</code></term> + <listitem> + <para> + Undefined by default. Configurable via + <code>--enable-concept-checks</code>. When defined, performs + compile-time checking on certain template instantiations to + detect violations of the requirements of the standard. This + is described in more detail <ulink + url="../19_diagnostics/howto.html#3">here</ulink>. + </para> + </listitem></varlistentry> + + <varlistentry><term><code>_GLIBCXX_DEBUG</code></term> + <listitem> + <para> + Undefined by default. When defined, compiles + user code using the <ulink url="../ext/debug.html#safe">libstdc++ debug + mode</ulink>. + </para> + </listitem></varlistentry> + <varlistentry><term><code>_GLIBCXX_DEBUG_PEDANTIC</code></term> + <listitem> + <para> + Undefined by default. When defined while + compiling with the <ulink url="../ext/debug.html#safe">libstdc++ debug + mode</ulink>, makes the debug mode extremely picky by making the use + of libstdc++ extensions and libstdc++-specific behavior into + errors. + </para> + </listitem></varlistentry> + <varlistentry><term><code>_GLIBCXX_PARALLEL</code></term> + <listitem> + <para>Undefined by default. When defined, compiles + user code using the <ulink url="../ext/parallel_mode.html">libstdc++ parallel + mode</ulink>. + </para> + </listitem></varlistentry> + </variablelist> + + + </sect1> + + <sect1 id="manual.intro.using.concurrency" xreflabel="Concurrency"> + <title>Concurrency</title> + + <para>This section discusses issues surrounding the proper compilation + of multithreaded applications which use the Standard C++ + library. This information is GCC-specific since the C++ + standard does not address matters of multithreaded applications. + </para> + + <sect2 id="manual.intro.using.concurrency.prereq" xreflabel="Thread Prereq"> + <title>Prerequisites</title> + + <para>All normal disclaimers aside, multithreaded C++ application are + only supported when libstdc++ and all user code was built with + compilers which report (via <code> gcc/g++ -v </code>) the same thread + model and that model is not <emphasis>single</emphasis>. As long as your + final application is actually single-threaded, then it should be + safe to mix user code built with a thread model of + <emphasis>single</emphasis> with a libstdc++ and other C++ libraries built + with another thread model useful on the platform. Other mixes + may or may not work but are not considered supported. (Thus, if + you distribute a shared C++ library in binary form only, it may + be best to compile it with a GCC configured with + --enable-threads for maximal interchangeability and usefulness + with a user population that may have built GCC with either + --enable-threads or --disable-threads.) + </para> + <para>When you link a multithreaded application, you will probably + need to add a library or flag to g++. This is a very + non-standardized area of GCC across ports. Some ports support a + special flag (the spelling isn't even standardized yet) to add + all required macros to a compilation (if any such flags are + required then you must provide the flag for all compilations not + just linking) and link-library additions and/or replacements at + link time. The documentation is weak. Here is a quick summary + to display how ad hoc this is: On Solaris, both -pthreads and + -threads (with subtly different meanings) are honored. On OSF, + -pthread and -threads (with subtly different meanings) are + honored. On Linux/i386, -pthread is honored. On FreeBSD, + -pthread is honored. Some other ports use other switches. + AFAIK, none of this is properly documented anywhere other than + in ``gcc -dumpspecs'' (look at lib and cpp entries). + </para> + + </sect2> + + <sect2 id="manual.intro.using.concurrency.thread_safety" xreflabel="Thread Safety"> + <title>Thread Safety</title> + + +<para> +We currently use the <ulink url="http://www.sgi.com/tech/stl/thread_safety.html">SGI STL</ulink> definition of thread safety. +</para> + + + <para>The library strives to be thread-safe when all of the following + conditions are met: + </para> + <itemizedlist> + <listitem> + <para>The system's libc is itself thread-safe, + </para> + </listitem> + <listitem> + <para> + The compiler in use reports a thread model other than + 'single'. This can be tested via output from <code>gcc + -v</code>. Multi-thread capable versions of gcc output + something like this: + </para> +<programlisting> +%gcc -v +Using built-in specs. +... +Thread model: posix +gcc version 4.1.2 20070925 (Red Hat 4.1.2-33) +</programlisting> + +<para>Look for "Thread model" lines that aren't equal to "single."</para> + </listitem> + <listitem> + <para> + Requisite command-line flags are used for atomic operations + and threading. Examples of this include <code>-pthread</code> + and <code>-march=native</code>, although specifics vary + depending on the host environment. See <ulink + url="http://gcc.gnu.org/onlinedocs/gcc/Option-Summary.html">Machine + Dependent Options</ulink>. + </para> + </listitem> + <listitem> + <para> + An implementation of atomicity.h functions + exists for the architecture in question. See the internals documentation for more <ulink url="../ext/concurrence.html">details</ulink>. + </para> + </listitem> + + </itemizedlist> + <para>The user-code must guard against concurrent method calls which may + access any particular library object's state. Typically, the + application programmer may infer what object locks must be held + based on the objects referenced in a method call. Without getting + into great detail, here is an example which requires user-level + locks: + </para> + <programlisting> + library_class_a shared_object_a; + + thread_main () { + library_class_b *object_b = new library_class_b; + shared_object_a.add_b (object_b); // must hold lock for shared_object_a + shared_object_a.mutate (); // must hold lock for shared_object_a + } + + // Multiple copies of thread_main() are started in independent threads.</programlisting> + <para>Under the assumption that object_a and object_b are never exposed to + another thread, here is an example that should not require any + user-level locks: + </para> + <programlisting> + thread_main () { + library_class_a object_a; + library_class_b *object_b = new library_class_b; + object_a.add_b (object_b); + object_a.mutate (); + } </programlisting> + <para>All library objects are safe to use in a multithreaded program as + long as each thread carefully locks out access by any other + thread while it uses any object visible to another thread, i.e., + treat library objects like any other shared resource. In general, + this requirement includes both read and write access to objects; + unless otherwise documented as safe, do not assume that two threads + may access a shared standard library object at the same time. + </para> + <para>See chapters <ulink url="../17_intro/howto.html#3">17</ulink> (library + introduction), <ulink url="../23_containers/howto.html#3">23</ulink> + (containers), and <ulink url="../27_io/howto.html#9">27</ulink> (I/O) for + more information. + </para> + + + </sect2> + <sect2 id="manual.intro.using.concurrency.atomics" xreflabel="Atomics"> + <title>Atomics</title> + <para> + </para> + </sect2> + + <sect2 id="manual.intro.using.concurrency.io" xreflabel="IO"> + <title>IO</title> + <para>I'll assume that you have already read the + <ulink url="../17_intro/howto.html#3">general notes on library threads</ulink>, + and the + <ulink url="../23_containers/howto.html#3">notes on threaded container + access</ulink> (you might not think of an I/O stream as a container, but + the points made there also hold here). If you have not read them, + please do so first. + </para> + <para>This gets a bit tricky. Please read carefully, and bear with me. + </para> + + <sect3 id="concurrency.io.structure" xreflabel="Structure"> + <title>Structure</title> + <para>A wrapper + type called <code>__basic_file</code> provides our abstraction layer + for the <code>std::filebuf</code> classes. Nearly all decisions dealing + with actual input and output must be made in <code>__basic_file</code>. + </para> + <para>A generic locking mechanism is somewhat in place at the filebuf layer, + but is not used in the current code. Providing locking at any higher + level is akin to providing locking within containers, and is not done + for the same reasons (see the links above). + </para> + </sect3> + + <sect3 id="concurrency.io.defaults" xreflabel="Defaults"> + <title>Defaults</title> + <para>The __basic_file type is simply a collection of small wrappers around + the C stdio layer (again, see the link under Structure). We do no + locking ourselves, but simply pass through to calls to <code>fopen</code>, + <code>fwrite</code>, and so forth. + </para> + <para>So, for 3.0, the question of "is multithreading safe for I/O" + must be answered with, "is your platform's C library threadsafe + for I/O?" Some are by default, some are not; many offer multiple + implementations of the C library with varying tradeoffs of threadsafety + and efficiency. You, the programmer, are always required to take care + with multiple threads. + </para> + <para>(As an example, the POSIX standard requires that C stdio FILE* + operations are atomic. POSIX-conforming C libraries (e.g, on Solaris + and GNU/Linux) have an internal mutex to serialize operations on + FILE*s. However, you still need to not do stupid things like calling + <code>fclose(fs)</code> in one thread followed by an access of + <code>fs</code> in another.) + </para> + <para>So, if your platform's C library is threadsafe, then your + <code>fstream</code> I/O operations will be threadsafe at the lowest + level. For higher-level operations, such as manipulating the data + contained in the stream formatting classes (e.g., setting up callbacks + inside an <code>std::ofstream</code>), you need to guard such accesses + like any other critical shared resource. + </para> + </sect3> + + <sect3 id="concurrency.io.future" xreflabel="Future"> + <title>Future</title> + <para> A + second choice may be available for I/O implementations: libio. This is + disabled by default, and in fact will not currently work due to other + issues. It will be revisited, however. + </para> + <para>The libio code is a subset of the guts of the GNU libc (glibc) I/O + implementation. When libio is in use, the <code>__basic_file</code> + type is basically derived from FILE. (The real situation is more + complex than that... it's derived from an internal type used to + implement FILE. See libio/libioP.h to see scary things done with + vtbls.) The result is that there is no "layer" of C stdio + to go through; the filebuf makes calls directly into the same + functions used to implement <code>fread</code>, <code>fwrite</code>, + and so forth, using internal data structures. (And when I say + "makes calls directly," I mean the function is literally + replaced by a jump into an internal function. Fast but frightening. + *grin*) + </para> + <para>Also, the libio internal locks are used. This requires pulling in + large chunks of glibc, such as a pthreads implementation, and is one + of the issues preventing widespread use of libio as the libstdc++ + cstdio implementation. + </para> + <para>But we plan to make this work, at least as an option if not a future + default. Platforms running a copy of glibc with a recent-enough + version will see calls from libstdc++ directly into the glibc already + installed. For other platforms, a copy of the libio subsection will + be built and included in libstdc++. + </para> + </sect3> + + <sect3 id="concurrency.io.alt" xreflabel="Alt"> + <title>Alternatives</title> + <para>Don't forget that other cstdio implementations are possible. You could + easily write one to perform your own forms of locking, to solve your + "interesting" problems. + </para> + </sect3> + + </sect2> + + <sect2 id="manual.intro.using.concurrency.containers" xreflabel="Containers"> + <title>Containers</title> + + <para>This section discusses issues surrounding the design of + multithreaded applications which use Standard C++ containers. + All information in this section is current as of the gcc 3.0 + release and all later point releases. Although earlier gcc + releases had a different approach to threading configuration and + proper compilation, the basic code design rules presented here + were similar. For information on all other aspects of + multithreading as it relates to libstdc++, including details on + the proper compilation of threaded code (and compatibility between + threaded and non-threaded code), see Chapter 17. + </para> + <para>Two excellent pages to read when working with the Standard C++ + containers and threads are + <ulink url="http://www.sgi.com/tech/stl/thread_safety.html">SGI's + http://www.sgi.com/tech/stl/thread_safety.html</ulink> and + <ulink url="http://www.sgi.com/tech/stl/Allocators.html">SGI's + http://www.sgi.com/tech/stl/Allocators.html</ulink>. + </para> + <para><emphasis>However, please ignore all discussions about the user-level + configuration of the lock implementation inside the STL + container-memory allocator on those pages. For the sake of this + discussion, libstdc++ configures the SGI STL implementation, + not you. This is quite different from how gcc pre-3.0 worked. + In particular, past advice was for people using g++ to + explicitly define _PTHREADS or other macros or port-specific + compilation options on the command line to get a thread-safe + STL. This is no longer required for any port and should no + longer be done unless you really know what you are doing and + assume all responsibility.</emphasis> + </para> + <para>Since the container implementation of libstdc++ uses the SGI + code, we use the same definition of thread safety as SGI when + discussing design. A key point that beginners may miss is the + fourth major paragraph of the first page mentioned above + ("For most clients,"...), which points out that + locking must nearly always be done outside the container, by + client code (that'd be you, not us). There is a notable + exceptions to this rule. Allocators called while a container or + element is constructed uses an internal lock obtained and + released solely within libstdc++ code (in fact, this is the + reason STL requires any knowledge of the thread configuration). + </para> + <para>For implementing a container which does its own locking, it is + trivial to provide a wrapper class which obtains the lock (as + SGI suggests), performs the container operation, and then + releases the lock. This could be templatized <emphasis>to a certain + extent</emphasis>, on the underlying container and/or a locking + mechanism. Trying to provide a catch-all general template + solution would probably be more trouble than it's worth. + </para> + <para>The STL implementation is currently configured to use the + high-speed caching memory allocator. Some people like to + test and/or normally run threaded programs with a different + default. For all details about how to globally override this + at application run-time see <ulink url="../ext/howto.html#3">here</ulink>. + </para> + <para>There is a better way (not standardized yet): It is possible to + force the malloc-based allocator on a per-case-basis for some + application code. The library team generally believes that this + is a better way to tune an application for high-speed using this + implementation of the STL. There is + <ulink url="../ext/howto.html#3">more information on allocators here</ulink>. + </para> + + </sect2> + </sect1> + + <sect1 id="manual.intro.using.exception_safety" xreflabel="Exception Safety"> + <title>Exception Safety</title> + <para></para> + </sect1> + +<!-- Section 0x : Debug --> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" + parse="xml" href="debug.xml"> +</xi:include> + +</chapter> diff --git a/libstdc++-v3/doc/xml/manual/utilities.xml b/libstdc++-v3/doc/xml/manual/utilities.xml new file mode 100644 index 00000000000..77cdb6427eb --- /dev/null +++ b/libstdc++-v3/doc/xml/manual/utilities.xml @@ -0,0 +1,125 @@ +<?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.util" xreflabel="Utilities"> +<?dbhtml filename="utilities.html"?> + +<partinfo> + <keywordset> + <keyword> + ISO C++ + </keyword> + <keyword> + library + </keyword> + </keywordset> +</partinfo> + +<title>Utilities</title> + +<!-- Chapter 01 : Functors --> +<chapter id="manual.util.functors" xreflabel="Functors"> + <title>Functors</title> + <para>If you don't know what functors are, you're not alone. Many people + get slightly the wrong idea. In the interest of not reinventing + the wheel, we will refer you to the introduction to the functor + concept written by SGI as part of their STL, in + <ulink url="http://www.sgi.com/tech/stl/functors.html">their + http://www.sgi.com/tech/stl/functors.html</ulink>. + </para> +</chapter> + +<!-- Chapter 02 : Pairs --> +<chapter id="manual.util.pairs" xreflabel="Pairs"> + <title>Pairs</title> + <para>The <code>pair<T1,T2></code> is a simple and handy way to + carry around a pair of objects. One is of type T1, and another of + type T2; they may be the same type, but you don't get anything + extra if they are. The two members can be accessed directly, as + <code>.first</code> and <code>.second</code>. + </para> + <para>Construction is simple. The default ctor initializes each member + with its respective default ctor. The other simple ctor, + </para> + <programlisting> + pair (const T1& x, const T2& y); + </programlisting> + <para>does what you think it does, <code>first</code> getting <code>x</code> + and <code>second</code> getting <code>y</code>. + </para> + <para>There is a copy constructor, but it requires that your compiler + handle member function templates: + </para> + <programlisting> + template <class U, class V> pair (const pair<U,V>& p); + </programlisting> + <para>The compiler will convert as necessary from U to T1 and from + V to T2 in order to perform the respective initializations. + </para> + <para>The comparison operators are done for you. Equality + of two <code>pair<T1,T2></code>s is defined as both <code>first</code> + members comparing equal and both <code>second</code> members comparing + equal; this simply delegates responsibility to the respective + <code>operator==</code> functions (for types like MyClass) or builtin + comparisons (for types like int, char, etc). + </para> + <para> + The less-than operator is a bit odd the first time you see it. It + is defined as evaluating to: + </para> + <programlisting> + x.first < y.first || + ( !(y.first < x.first) && x.second < y.second ) + </programlisting> + <para>The other operators are not defined using the <code>rel_ops</code> + functions above, but their semantics are the same. + </para> + <para>Finally, there is a template function called <function>make_pair</function> + that takes two references-to-const objects and returns an + instance of a pair instantiated on their respective types: + </para> + <programlisting> + pair<int,MyClass> p = make_pair(4,myobject); + </programlisting> + +</chapter> + +<!-- Chapter 03 : Memory --> +<chapter id="manual.util.memory" xreflabel="Memory"> + + <title>Memory</title> + <para> + Memory contains three general areas. First, function and operator + calls via <function>new</function> and <function>delete</function> + operator or member function calls. Second, allocation via + <classname>allocator</classname>. And finally, smart pointer and + intelligent pointer abstractions. + </para> + + <!-- Section 01 : allocator --> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" + parse="xml" href="allocator.xml"> + </xi:include> + + <!-- Section 02 : auto_ptr --> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" + parse="xml" href="auto_ptr.xml"> + </xi:include> + + <!-- Section 03 : shared_ptr --> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" + parse="xml" href="shared_ptr.xml"> + </xi:include> + +</chapter> + +<!-- Chapter 04 : Traits --> +<chapter id="manual.util.traits" xreflabel="Traits"> + <title>Traits</title> + <para> + </para> +</chapter> + +</part> |
