# 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:

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

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