      ______________________________________________________________________

      19   Diagnostics library                             [lib.diagnostics]

      ______________________________________________________________________

    1 This clause describes components that C++ programs may use  to  detect
      and report error conditions.

    2 The  following  subclauses  describe  components for reporting several
      kinds of exceptional conditions, documenting program assertions, and a
      global variable for error number codes, as summarized in Table 1:

                       Table 1--Diagnostics library summary

              +-----------------------------------------------------+
              |              Subclause                   Header(s)  |
              +-----------------------------------------------------+
              |_lib.std.exceptions_ Exception classes   <stdexcept> |
              +-----------------------------------------------------+
              |_lib.assertions_ Assertions              <cassert>   |
              +-----------------------------------------------------+
              |_lib.errno_ Error numbers                <cerrno>    |
              +-----------------------------------------------------+

      19.1  Exception classes                           [lib.std.exceptions]

    1 The Standard C++ library provides classes to be used to report certain
      errors (_lib.res.on.exception.handling_)  in  C++  programs.   In  the
      error  model  reflected  in these classes, errors are divided into two
      broad categories: logic errors and runtime errors.

    2 The distinguishing characteristic of logic errors is that they are due
      to  errors  in the internal logic of the program.  In theory, they are
      preventable.

    3 By contrast, runtime errors are due to events beyond the scope of  the
      program.   They  cannot  be  easily  predicted in advance.  The header
      <stdexcept> defines several types of predefined exceptions for report-
      ing errors in a C++ program.  These exceptions are related via inheri-
      tance.

      Header <stdexcept> synopsis

      namespace std {
        class logic_error;
          class domain_error;
          class invalid_argument;
          class length_error;
          class out_of_range;
        class runtime_error;
          class range_error;
          class overflow_error;
          class underflow_error;
      }

      19.1.1  Class logic_error                            [lib.logic.error]
      namespace std {
        class logic_error : public exception {
        public:
          logic_error(const string& what_arg);
        };
      }

    1 The class logic_error defines the type of objects thrown as exceptions
      to  report  errors  presumably detectable before the program executes,
      such as violations of logical preconditions or class invariants.

      logic_error(const string& what_arg);

      Effects:
        Constructs an object of class logic_error.
      Postcondition:
        strcmp(what(), what_arg.c_str()) == 0.

      19.1.2  Class domain_error                          [lib.domain.error]
      namespace std {
        class domain_error : public logic_error {
        public:
          domain_error(const string& what_arg);
        };
      }

    1 The class domain_error defines the type of objects  thrown  as  excep-
      tions by the implementation to report domain errors.

      domain_error(const string& what_arg);

      Effects:
        Constructs an object of class domain_error.
      Postcondition:
        strcmp(what(), what_arg.c_str()) == 0.

      19.1.3  Class invalid_argument                  [lib.invalid.argument]
      namespace std {
        class invalid_argument : public logic_error {
        public:
          invalid_argument(const string& what_arg);
        };
      }

    1 The  class  invalid_argument  defines  the  type  of objects thrown as
      exceptions to report an invalid argument.

      invalid_argument(const string& what_arg);

      Effects:
        Constructs an object of class invalid_argument.
      Postcondition:
        strcmp(what(), what_arg.c_str()) == 0.

      19.1.4  Class length_error                          [lib.length.error]
      namespace std {
        class length_error : public logic_error {
        public:
          length_error(const string& what_arg);
        };
      }

    1 The class length_error defines the type of objects  thrown  as  excep-
      tions  to  report an attempt to produce an object whose length exceeds
      its maximum allowable size.

      length_error(const string& what_arg);

      Effects:
        Constructs an object of class length_error.
      Postcondition:
        strcmp(what(), what_arg.c_str()) == 0.

      19.1.5  Class out_of_range                          [lib.out.of.range]
      namespace std {
        class out_of_range : public logic_error {
        public:
          out_of_range(const string& what_arg);
        };
      }

    1 The class out_of_range defines the type of objects  thrown  as  excep-
      tions to report an argument value not in its expected range.

      out_of_range(const string& what_arg);

      Effects:
        Constructs an object of class out_of_range.
      Postcondition:
        strcmp(what(), what_arg.c_str()) == 0.

      19.1.6  Class runtime_error                        [lib.runtime.error]
      namespace std {
        class runtime_error : public exception {
        public:
          runtime_error(const string& what_arg);
        };
      }

    1 The  class  runtime_error defines the type of objects thrown as excep-
      tions to report errors presumably detectable  only  when  the  program
      executes.

      runtime_error(const string& what_arg);

      Effects:
        Constructs an object of class runtime_error.
      Postcondition:
        strcmp(what(), what_arg.c_str()) == 0.

      19.1.7  Class range_error                            [lib.range.error]
      namespace std {
        class range_error : public runtime_error {
        public:
          range_error(const string& what_arg);
        };
      }

    1 The class range_error defines the type of objects thrown as exceptions
      to report range errors in internal computations.

      range_error(const string& what_arg);

      Effects:
        Constructs an object of class range_error.
      Postcondition:
        strcmp(what(), what_arg.c_str()) == 0.

      19.1.8  Class overflow_error                      [lib.overflow.error]
      namespace std {
        class overflow_error : public runtime_error {
        public:
          overflow_error(const string& what_arg);
        };
      }

    1 The class overflow_error defines the type of objects thrown as  excep-
      tions to report an arithmetic overflow error.

      overflow_error(const string& what_arg);

      Effects:
        Constructs an object of class overflow_error.
      Postcondition:
        strcmp(what(), what_arg.c_str()) == 0.

      19.1.9  Class underflow_error                    [lib.underflow.error]
      namespace std {
        class underflow_error : public runtime_error {
        public:
          underflow_error(const string& what_arg);
        };
      }

    1 The class underflow_error defines the type of objects thrown as excep-
      tions to report an arithmetic underflow error.

      underflow_error(const string& what_arg);

      Effects:
        Constructs an object of class underflow_error.
      Postcondition:
        strcmp(what(), what_arg.c_str()) == 0.

      19.2  Assertions                                      [lib.assertions]

    1 Provides macros for documenting C++ program assertions, and  for  dis-
      abling the assertion checks.

    2 Header <cassert> (Table 2):

                        Table 2--Header <cassert> synopsis

                              +--------------------+
                              | Type     Name(s)   |
                              +--------------------+
                              |Macro:   assert     |
                              +--------------------+

    3 The contents are the same as the Standard C library header <assert.h>.

      SEE ALSO: ISO C subclause 7.2.

      19.3  Error numbers                                        [lib.errno]

    1 Header <cerrno> (Table 3):

                        Table 3--Header <cerrno> synopsis

                        +--------------------------------+
                        | Type            Name(s)        |
                        +--------------------------------+
                        |Macros:   EDOM   ERANGE   errno |
                        +--------------------------------+

    2 The contents are the same as the Standard C library header  <errno.h>.

      SEE ALSO: ISO C subclause 7.1.4, 7.2, Amendment 1 subclause 4.3.