TSE3 documentation Version 0.3.0 Index API  Version  Structure 

TSE3 error handling

C++ exceptions

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:

        // perform TSE3 activity that might throw an exception
    catch (const Error &e)
        // do some error handling
        cerr << "An error occured of type " << e.reason << endl;

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.

Error reason codes

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.

General information

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.

Memory allocation errors

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.
 © Pete Goodliffe, 2001-2003 Copyright Psalm 150