dtl

RootException


Category: exceptions	Component type: type

Description

RootException is the base class of all exceptions in the DTL. An exception of this type stores strings representing which method the exception was thrown in, a message describing what error occurred, and what actual exception type was thrown. The call to the constructor initializes these strings. The user can extract a stringified message with all of this information from the exception using the standard what() method. Subclasses may also pass in a stringified representation of their type name as the third argument to the constructor (see below).

Definition

Defined in the RootException.h header file.

Example: Trivial case of throwing and catching a RootException

void IWillThrow() { vector<int> v(5); // create a vector of 5 elements try { for (int i = 0; i <= 5; i++){ v.at(i) = i; // v.at(5) will throw std::invalid_argument exception } catch (invalid_argument &ex) { // for a method SomeClass::foo(), method string would be "SomeClass:foo()" // for a global function as used here, just use its name throw RootException("IWillThrow()", ex.what()); } }; int main() { try { // call our method which throws IWillThrow(); } catch (RootException &ex) { // can also say: cout << ex << endl; // operator<<() for RootExceptions just streams out what() cout << ex.what() << endl; } return 0; // won't reach here ... exception thrown above }

Model of

Standard C++ library exception.

Public base classes

std::exception

Members

Member	Where defined	Description
RootException()	`RootException`	Default constructor. Sets method and message fields to empty strings and exception type string to "RootException".
RootException(const string &meth, const string &err, const string &excType = "RootException")	`RootException`	Constructor which takes a specific method, error string, and stringified exception type to initialize itself.
virtual const char* what() const throw()	`RootException`	Overrides behavior in std::exception. Returns a C string describing the exception, including the method it was thrown in, the error message describing why it was thrown, and what type of exception was thrown. Subclasses do and may override what() based on their needs. See Note [1].
virtual const TCHAR* twhat() const throw()	`RootException`	Returns a pointer to a TCHAR describing the exception, including the method it was thrown in, the error message describing why it was thrown, and what type of exception was thrown. Subclasses do and may override twhat() based on their needs. See Note [1]. This is useful for returning unicode error messages. See Unicode documentation.
`friend wostream &operator<<(wostream &o, const RootException &ex)`	`RootException`	Note that this is a friend function, and not a member. Streams out ex.twhat() to o. As twhat() is virtual, the appropriate version of that method will be called for ex.
`friend ostream &operator<<(ostream &o, const RootException &ex)`	`RootException`	Note that this is a friend function, and not a member. Streams out ex.what() to o. As what() is virtual, the appropriate version of that method will be called for ex.

Notes

[1] A RootException contains a protected string member named whatbuf. This seemingly extra member is needed as the std::exception does not contain a portable, mutable way to access its own member that is used to hold the error message. This effects the implementation of the what() method as the exception needs a way to build its own error string, possibly partly based on what the superclass exception does in its work. An example of how to implement what() for a subclass of RootException can be found in the DBException class:

// DBException::what() ... DBException derives from RootException virtual const char *what() const throw() { string rootWhat = RootException::what(); // let RootException build up the common part of the error string ostringstream o; o << rootWhat; // stream out ODBC errors to the what() string if (sqlErrors.size() > 0) { o << "SQL Errors: " << endl; for (size_t i = 0; i < sqlErrors.size(); i++) { o << "(" << i << ") " << sqlErrors[i] << endl; } } // this gymnastics is needed so result isn't destroyed // paste these two lines into all what() code whatbuf = o.str(); return whatbuf.c_str(); }