Imported gcc-4.4.3

[msp430-gcc.git] / libstdc++-v3 / doc / xml / manual / diagnostics.xml

diff --git a/libstdc++-v3/doc/xml/manual/diagnostics.xml b/libstdc++-v3/doc/xml/manual/diagnostics.xml
new file mode 100644 (file)
index 0000000..ebdc6c7
--- /dev/null
+++ b/libstdc++-v3/doc/xml/manual/diagnostics.xml
@@ -0,0 +1,130 @@
+<?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
+  <indexterm><primary>Diagnostics</primary></indexterm>
+</title>
+
+<chapter id="manual.diagnostics.exceptions" xreflabel="Exceptions">
+  <?dbhtml filename="exceptions.html"?>
+  <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
+      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>