Non-recoverable internal errors share the following distinguishing characteristics. They are:

Non-recoverable internal errors by definition have no recovery mechanism. Examples of these errors include bounds errors, and inserting a null pointer into a collection.

Why does a library define some errors as unrecoverable? Because detecting errors takes time. For performance reasons, a library demands some minimal level of correctness on the part of your program, and pitches anything that falls short. Errors are non-recoverable in the sense that the production version of the library has no mechanism for detecting such errors and, hence, no opportunity for recovering from them.

Bounds errors are non-recoverable because the cost of checking to make sure an index is in range can well exceed the cost of the array access itself. If a program does a lot of array accesses, checking every one may result in a slow program. To avoid this, the library may require you to always use a valid index. Because a minimum level of correctness is demanded, non-recoverable errors are simple in concept and relatively easy to avoid.

You can best discover and eliminate non-recoverable errors by compiling and linking your application with the debug version of the library. See "The Debug Version of Tools.h++" for details. The debug version includes lots of extra checks designed to uncover coding errors. Some of these checks may take extra time, or even cause debug messages to be printed out, so you will want to compile and link with the production version for an efficient final product.

If the debug version of the library discovers an error, it typically aborts the program.

Recoverable internal errors are similar to their non-recoverable relatives in that they are easy to predict and occur at low levels. They differ in that they are:

A bounds error in a linked list or an attempt to use an invalid date are both examples of recoverable internal errors. The library's response to these errors is to throw an exception inheriting from RWInternalErr.

The production version of the library can check for recoverable internal errors because the cost is relatively low. For example, to find a bounds error in a linked list, the cost of walking the list will far exceed the cost of detecting whether the index is in bounds. Hence, you can afford to check for a bounds error on every access.

If an error is discovered, the library will throw an exception inheriting from RWInternalErr, as we have mentioned. Here's what it looks like when Tools.h++ throws an exception:

// Find link "i"; the index must be in range:
RWIsvSlink* RWIsvSlist::at(size_t i) const
{
   if (i >= entries()){
     if(RW_NPOS == i)
       RWTHROW( RWBoundsErr( RWMessage( RWTOOL_NPOSINDEX)));
     else
       RWTHROW( RWBoundsErr( RWMessage( RWTOOL_INDEXERR,
              (unsigned)i,
              (unsigned)entries()) ));
   }
 
   register RWIsvSlink* link = head_.next_;
   while (i--) link = link->next_;
   return link;
}

In this code, note how the function always attempts to detect a bounds error. If it finds one, it throws an instance of RWBoundsErr, a class that inherits from RWInternalErr. This instance contains an internationalized message, discussed in "Localizing Messages" in Chapter 16. The RWTHROW macro is discussed in "Error Handlers."

Throwing an exception gives you the opportunity to catch and possibly recover the exception. However, because the internal logic of the program has been compromised, most likely you will want to attempt to save the document you are working on, and abort the program.

Tools.h++ uses the macro RWTHROW to throw an exception. If your compiler supports exceptions, this macro resolves by calling a function which throws the exception. If your compiler does not support exceptions, the macro resolves to call an error handler with prototype:

void errHandler(const RWxmsg&);

The default error handler aborts the program. You can change the default handler with the function:

typedef void (*rwErrHandler)(const RWxmsg&);
rwErrHandler rwSetErrHandler(rwErrHandler);

The next example demonstrates how a user-defined error handler works in a compiler that doesn't support exceptions:

#include <rw/rwerr.h>
#include <rw/coreerr.h>
#include <iostream.h>
 
#ifdef RW_NO_EXCEPTIONS
 
void myOwnErrorHandler(const RWxmsg& error){
  cout << "myOwnErrorHandler(" << error.why() << ")" << endl;
}
 
int main(){
  rwSetErrHandler(myOwnErrorHandler);  // Comment out this line 
                              // to get the default error handler.
  RWTHROW( RWExternalErr(RWMessage( RWCORE_GENERIC, 12345, "Howdy!") ));
  cout << "Done." << endl;
  return 0;
}
 
#else  //RW_NO_EXCEPTIONS
 
#error This example only for compilers without exception handling
 
#endif

In his landmark book Object-oriented Software Construction, Bertrand Meyer suggests regarding functions as a contract between a caller and a callee. If the caller agrees to abide by a set of preconditions, the callee guarantees to return results that satisfy a set of postconditions. The following comparison shows the usefulness of Meyer's paradigm in Tools.h++. Let's look first at a bounds error in C:

char buff[20];
char j = buff[20];                      // Bounds error!

Such a bounds error is extremely tough to detect in C, but easy in C++, as shown below:

RWCString buff(20);
char j = buff[20];                     // Detectable bounds error

The bounds error is easy to detect in C++ because the operator[] can be overloaded to perform an explicit bounds check. In other words, when the flag RWDEBUG is set, operator[] also executes the PRECONDITION clause, as below:

char& RWCString::operator[](size_t I){
   RWPRECONDITION(i < length() );
   return rep[i];
}

The case just described would trigger a failure because operator[]would find that the PRECONDITION is not met.

Here's a slightly more complicated example:

template <class T> void List::insert(T* obj){
   RWPRECONDITION( obj!= 0 );
   head = new Link(head, obj);
   RWPOSTCONDITION( this->contains(obj) );
}

In this example, the job of the function insert() is to insert the object pointed to by the argument into a linked list of pointers to objects of type T. The only precondition for the function to work is that the pointer obj not be null. If this condition is satisfied, then the function guarantees to successfully insert the object. The condition is checked by the postcondition clause.

The macros RWPRECONDITION and RWPOSTCONDITION are defined in <rw/defs.h> and compile out to no-ops, so long as the preprocessor macro RWDEBUG is not defined. Here's what appears in the makefile:

#ifdef RWDEBUG
#  define RWPRECONDITION(a)      assert(a)
#  define RWPOSTCONDITION(a)     assert(a)
#else
#  define RWPRECONDITION(a)      ((void*)0)
#  define RWPOSTCONDITION(a)     ((void*)0)
#endif