|
The TSE3 library uses exceptions to indicate unrecoverable errors. The member functions which raise errors are clearly indicatated in the documentation.
For this reason it is important that you write your application with
exception handlers (at the very least, enclose your main
function in a try/catch block, otherwise
any errors will lead to a segfault.
Every different TSE3 error is derived from a common base class,
Error. This class in turn derives from the standard library
exception class exception. It is up to you at what level
you catch any exception (i.e. specific subclass like
PhraseListError, all TSE3 errors with Error or
all library exceptions with exception).
The suggested format for catching errors is as shown below:
try
{
// perform TSE3 activity that might throw an exception
phraseList.insert(newPhrase);
}
catch (const Error &e)
{
// do some error handling
cerr << "An error occured of type " << e.reason << endl;
exit(1);
}
That is, catch by const reference. Of course, you will probably want
to catch a more specific exception type; in the above example a
PhraseListError.
The base Error class includes a reason code parameter. You
may therefore distinguish the cause of the error in two ways, by
type of exception caught or by inspecting the reason code. Reason codes
are defined by the ErrorCode enum type.
The reason for this (seemingly redundant) reason code is simple: when writing an application it is easier to work out which internationalised error string to show to the user on reciept of an exception by indexing into a table by reason code, rather that trying to convert an exception type into a string.
The TSE3 library provides a set of standard English string representations
of each ErrorCode value.
The error class definitions are located in the file
tse3/Error.h. The other TSE3 header files do not include
this directly, so if you need to handle TSE3 exceptions you will need to
#include this in your own code.
Note that some erroneous operations, like attempting to remove a
Phrase from the PhraseList which was never
inserted, result in no error being raised and the method returning silently.
Such occurences are clearly marked in the documentation.
Since TSE3 error handling is based on the C++ exception mechanism, memory
allocation failure is also expected to raise an exception
(std::bad_alloc). For this reason, you will not see code that
checks the return value of new against the value zero in the
TSE3 source.
In fact, TSE3 does not even attempt to catch a bad_alloc since
if there is a memory leak, there really is no useful work that the
library can perform - it is probably too late to gracefully degrade. It
is up to the library user to catch any occurance of bad_alloc
and warn the application user, if possible.
|