______________________________________________________________________
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.