______________________________________________________________________
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 (_lib.std.exceptions_), documenting
program assertions (_lib.assertions_), and a global variable for error
number codes (_lib.errno_).
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.
4 Headers:
--<stdexcept>
5 Table 1:
Table 1--Header <stdexcept> synopsis
+-------------------------------------------------+
| Type Name(s) |
+-------------------------------------------------+
|Classes: |
|domain_error length_error overflow_error |
|exception logic_error range_error |
|invalid_argument out_of_range runtime_error |
+-------------------------------------------------+
6 The header <stdexcept> defines several types of predefined exceptions
for reporting errors in a C++ program. These exceptions are related
via inheritance, as indicated in Table 2:
Table 2--Standard exceptions inheritance hierarchy
+----------------------------------------------+
|Base class Derived class Derived class |
+----------------------------------------------+
|exception |
| logic_error |
| domain_error |
| invalid_argument |
| length_error |
| out_of_range |
| runtime_error |
| range_error |
| overflow_error |
+----------------------------------------------+
19.1.1 Class exception [lib.exception]
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 Standard C++ library functions, and certain
expressions, to report errors detected during program execution.
2 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.
19.1.1.1 exception constructors [lib.exception.cons]
exception(const string& what_arg);
1 Constructs an object of class exception and initializes desc to
&string(what_arg) and alloced to a nonzero value.
exception();
2 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();
1 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;
1 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]
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);
1 Constructs an object of class logic_error, initializing the base class
with exception(what_arg).
19.1.2.2 logic_error destructor [lib.logic.error.des]
virtual ~logic_error();
1 Destroys an object of class logic_error.
19.1.2.3 logic_error::what [lib.logic.error::what]
// virtual string what() const inherited;
1 Behaves the same as exception::what().
19.1.3 Class domain_error [lib.domain.error]
_________________________
1) This protected default constructor for exception can, and should,
avoid allocating any additional storage.
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);
1 Constructs an object of class domain, initializing the base class with
logic_error(what_arg).
19.1.3.2 domain_error destructor [lib.domain.error.des]
virtual ~domain_error();
1 Destroys an object of class domain.
19.1.3.3 domain::what [lib.domain.error::what]
// virtual string what() const; inherited
1 Behaves the same as exception::what().
19.1.4 Class invalid_argument [lib.invalid.argument]
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);
1 Constructs an object of class invalid_argument, initializing the base
class with logic_error(what_arg).
19.1.4.2 invalid_argument destructor [lib.invalid.argument.des]
virtual ~invalid_argument();
1 Destroys an object of class invalid_argument.
19.1.4.3 invalid_argument::what [lib.invalid.argument::what]
// virtual string what() const inherited;
1 Behaves the same as exception::what().
19.1.5 Class length_error [lib.length.error]
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 NPOS.
19.1.5.1 length_error constructor [lib.length.error.cons]
length_error(const string& what_arg);
1 Constructs an object of class length_error, initializing the base
class with logic_error(what_arg).
19.1.5.2 length_error destructor [lib.length.error.des]
virtual ~length_error();
1 Destroys an object of class length_error.
19.1.5.3 length_error::what [lib.length.error::what]
// virtual string what() const; inherited
1 Behaves the same as exception::what().
19.1.6 Class out_of_range [lib.out.of.range]
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);
1 Constructs an object of class out_of_range, initializing the base
class with logic_error(what_arg).
19.1.6.2 out_of_range destructor [lib.out.of.range.des]
virtual ~out_of_range();
1 Destroys an object of class out_of_range.
19.1.6.3 out_of_range::what [lib.out.of.range::what]
// virtual string what() const; inherited
1 Behaves the same as exception::what().
19.1.7 Class runtime_error [lib.runtime.error]
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);
1 Constructs an object of class runtime, initializing the base class
with exception(what_arg).
runtime_error();
2 Constructs an object of class runtime, initializing the base class
with exception().
19.1.7.2 runtime_error destructor [lib.runtime.error.des]
virtual ~runtime_error();
1 Destroys an object of class runtime.
19.1.7.3 runtime::what [lib.runtime.error::what]
// virtual string what() const inherited;
1 Behaves the same as exception::what().
19.1.8 Class range_error [lib.range.error]
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);
1 Constructs an object of class range_error, initializing the base class
with runtime_error(what_arg).
19.1.8.2 range_error destructor [lib.range.error.des]
virtual ~range_error();
1 Destroys an object of class range_error.
19.1.8.3 range_error::what [lib.range.error::what]
// virtual int what() const; inherited
1 Behaves the same as exception::what().
19.1.9 Class overflow_error [lib.overflow.error]
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);
1 Constructs an object of class overflow_error, initializing the base
class with runtime_error(what_arg).
19.1.9.2 overflow_error destructor [lib.overflow.error.des]
virtual ~overflow_error();
1 Destroys an object of class overflow_error.
19.1.9.3 overflow_error::what [lib.overflow.error::what]
// virtual string what() const; inherited
1 Behaves the same as exception::what().
19.2 Assertions [lib.assertions]
1 Provides macros for documenting C++ program assertions, and for dis
abling the assertion checks.
2 Headers:
--<cassert>
3 Table 3:
Table 3--Header <cassert> synopsis
+--------------------------+
| Type Name(s) |
+--------------------------+
|Macros: assert NDEBUG |
+--------------------------+
4 The contents are the same as the Standard C library.
SEE ALSO: ISO C subclause 7.2.
19.3 Error numbers [lib.errno]
1 Headers:
--<cerrno>
2 Table 4:
Table 4--Header <cerrno> synopsis
+-------------------------+
| Type Name(s) |
+-------------------------+
|Macros: EDOM ERANGE |
+-------------------------+
|Object: errno |
+-------------------------+
3 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.