gcc/libstdc++-v3/doc/xml/manual/diagnostics.xml

127 lines
4.3 KiB
XML
Raw Normal View History

Convert documentation to DocBook. 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. From-SVN: r132226
2008-02-11 01:01:33 +01:00
<?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 hierarchy can be
Convert documentation to DocBook. 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. From-SVN: r132226
2008-02-11 01:01:33 +01:00
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&amp; 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
&quot;Assignable&quot; (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>