______________________________________________________________________

  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 errors
  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

  #include <string>
  namespace std {
    class exception;
      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;
  }

  19.1.1  Class exception                                [lib.exception]
  namespace std {
    class exception {
    public:
      exception(const string& what_arg);
      virtual ~exception();
      virtual string what() const;
    protected:
      exception();
    private:
  //  const string* desc; exposition only
  //  bool alloced;               exposition only
    };
  }

1 The class exception defines the base class for the  types  of  objects
  thrown  as  exceptions by C++ Standard library components, and certain
  expressions, to report errors detected during program execution.

  +-------                 BEGIN BOX 1                -------+
  For the sake of exposition, the stored data is presented here as:

  --const string* what, stores a null pointer or points to an object  of
    type  string whose value is intended to briefly describe the general
    nature of the exception thrown;

  --bool alloced, stores a nonzero value if the string object  what  has
    been allocated by the object of class exception.
  +-------                  END BOX 1                 -------+

  19.1.1.1  exception constructors                  [lib.exception.cons]

  exception(const string& what_arg);

  Effects:
    Constructs  an  object  of  class  exception and initializes desc to
    &string(what_arg) and alloced to a nonzero value.

    exception();

  Effects:
    Constructs an object of class exception and initializes desc  to  an
    unspecified value and alloced to zero.1)

  19.1.1.2  exception destructor                     [lib.exception.des]

  virtual ~exception();

  Effects:
    Destroys an object of class exception.  If alloced is  nonzero,  the
    function frees any object pointed to by what.

  19.1.1.3  exception::what                        [lib.exception::what]

  virtual string what() const;

  Returns:
    string(desc)  if  desc  is not a null pointer.  Otherwise, the value
    returned is implementation defined.

  19.1.2  Class logic_error                            [lib.logic.error]
  namespace std {
    class logic_error : public exception {
    public:
      logic_error(const string& what_arg);
      virtual ~logic_error();
  //  virtual string what() const;        inherited
    };
  }

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

  19.1.2.1  logic_error constructor               [lib.logic.error.cons]

  logic_error(const string& what_arg);

  Effects:
    Constructs  an  object  of  class logic_error, initializing the base
    class with exception(what_arg).

  19.1.3  Class domain_error                          [lib.domain.error]

  _________________________
  1)  This  protected default constructor for exception can, and should,
  avoid allocating any additional storage.

  namespace std {
    class domain_error : public logic_error {
    public:
      domain_error(const string& what_arg);
      virtual ~domain_error();
  //  virtual string what() const;        inherited
    };
  }

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

  19.1.3.1  domain_error constructor             [lib.domain.error.cons]

  domain_error(const string& what_arg);

  Effects:
    Constructs  an  object  of class domain, initializing the base class
    with logic_error(what_arg).

  19.1.4  Class invalid_argument                  [lib.invalid.argument]
  namespace std {
    class invalid_argument : public logic_error {
    public:
      invalid_argument(const string& what_arg);
      virtual ~invalid_argument();
  //  virtual string what() const;        inherited
    };
  }

1 The class invalid_argument defines the base class for the types of all
  objects  thrown  as  exceptions,  by  functions  in  the  Standard C++
  library, to report an invalid argument.

  19.1.4.1  invalid_argument                 [lib.invalid.argument.cons]
       constructor

  invalid_argument(const string& what_arg);

  Effects:
    Constructs  an  object  of  class invalid_argument, initializing the
    base class with logic_error(what_arg).

  19.1.5  Class length_error                          [lib.length.error]
  namespace std {
    class length_error : public logic_error {
    public:
      length_error(const string& what_arg);
      virtual ~length_error();
  //  virtual string what() const;        inherited
    };
  }

1 The class length_error defines the base class for  the  types  of  all
  objects  thrown  as  exceptions,  by  functions  in  the  Standard C++
  library, to report an attempt to produce an object whose length equals
  or exceeds its maximum allowable size.

  19.1.5.1  length_error constructor             [lib.length.error.cons]

  length_error(const string& what_arg);

  Effects:
    Constructs  an  object  of class length_error, initializing the base
    class with logic_error(what_arg).

  19.1.6  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);
      virtual ~out_of_range();
  //  virtual string what() const;        inherited
    };
  }

1 The class out_of_range defines the base class for  the  types  of  all
  objects  thrown  as  exceptions,  by  functions  in  the  Standard C++
  library, to report an out-of-range argument.

  19.1.6.1  out_of_range constructor             [lib.out.of.range.cons]

  out_of_range(const string& what_arg);

  Effects:
    Constructs an object of class out_of_range,  initializing  the  base
    class with logic_error(what_arg).

  19.1.7  Class runtime_error                        [lib.runtime.error]
  namespace std {
    class runtime_error : public exception {
    public:
      runtime_error(const string& what_arg);
      virtual ~runtime_error();
  //  virtual string what();      inherited
    protected:
      runtime_error();
    };
  }

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

  19.1.7.1  runtime_error constructors          [lib.runtime.error.cons]

  runtime_error(const string& what_arg);

  Effects:
    Constructs  an  object of class runtime, initializing the base class
    with exception(what_arg).

    runtime_error();

  Effects:
    Constructs an object of class runtime, initializing the  base  class
    with exception().

  19.1.8  Class range_error                            [lib.range.error]
  namespae std {
    class range_error : public runtime_error {
    public:
      range_error(const string& what_arg);
      virtual ~range_error();
  //  virtual string what() const;        inherited
    };
  }

1 The class range_error defines the type of objects thrown as exceptions
  by the implementation to report range errors.

  19.1.8.1  range_error constructor               [lib.range.error.cons]

  range_error(const string& what_arg);

  Effects:
    Constructs an object of class  range_error,  initializing  the  base
    class with runtime_error(what_arg).

  19.1.9  Class overflow_error                      [lib.overflow.error]
  namespace std {
    class overflow_error : public runtime_error {
    public:
      overflow_error(const string& what_arg);
      virtual ~overflow_error();
  //  virtual string what() const;        inherited
    };
  }

1 The  class  overflow_error defines the base class for the types of all
  objects thrown  as  exceptions,  by  functions  in  the  Standard  C++
  library, to report an arithmetic overflow error.

  19.1.9.1  overflow_error constructor         [lib.overflow.error.cons]

  overflow_error(const string& what_arg);

  Effects:
    Constructs  an object of class overflow_error, initializing the base
    class with runtime_error(what_arg).

  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)     |
                       +--------------------------+
                       |Macros:   assert   NDEBUG |
                       +--------------------------+

3 The contents are the same as the Standard C library.

  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 |
                        +-------------------------+
                        |Object:   errno          |
                        +-------------------------+

2 The contents are the same as the Standard C library.

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