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

<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" 
	 xml:id="std.diagnostics" xreflabel="Diagnostics">
<?dbhtml filename="diagnostics.html"?>

<info><title>
  Diagnostics
  <indexterm><primary>Diagnostics</primary></indexterm>
</title>
  <keywordset>
    <keyword>
      ISO C++
    </keyword>
    <keyword>
      library
    </keyword>
  </keywordset>
</info>



<section xml:id="std.diagnostics.exceptions" xreflabel="Exceptions"><info><title>Exceptions</title></info>
  <?dbhtml filename="exceptions.html"?>
  

  <section xml:id="std.diagnostics.exceptions.api"><info><title>API Reference</title></info>
    
    <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 source documentation.
    </para>
    
    <para>
      Full API details.
    </para>
    
    <!-- Doxygen XML: api/group__exceptions.xml -->
      
  </section>
  <section xml:id="std.diagnostics.exceptions.data" xreflabel="Adding Data to Exceptions"><info><title>Adding Data to <classname>exception</classname></title></info>
    
    <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>

  </section>
</section>

<section xml:id="std.diagnostics.concept_checking" xreflabel="Concept Checking"><info><title>Concept Checking</title></info>
  
  <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
   <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.boost.org/libs/concept_check/concept_check.htm">the
   Boost libraries</link>, and we are pleased to incorporate it into the
   GNU C++ library.
 </para>
 <para>
   The new version imposes a much smaller space overhead on the generated
   object file.  The checks are also cleaner and easier to read and
   understand.
 </para>

 <para>
   They are off by default for all versions of GCC.
   They can be enabled at configure time with
   <link linkend="manual.intro.setup.configure"><literal>--enable-concept-checks</literal></link>.
   You can enable them on a per-translation-unit basis with
     <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>

</section>

</chapter>