Error Handling

Error handling in the QDL standard library is done in one of three ways, corresponding to the three ways errors are classified:

1. Programmer errors (bugs)
   These errors are handled using assertions.
2. Serious or unusual errors related to the program's environment.
   These errors are handled using exceptions.
3. Minor errors related to the program's environment
   These errors are handled by returning an error code or failure flag.

The first category of errors is caused by a function being misused by the programmer.  The documentation for each function specifies how a function should be used; if the programmer breaks the rules, the standard library uses assertions as its line of defense.  An assertion is a test made at run-time which, upon failure, causes the program to abort or drop into the debugger.  Assertions are removed when the program is compiled in the release mode, thus increasing performance.  The philosophy behind assertion-testing is that the programmer has made a mistake which will (hopefully) be fixed before the program is released; therefore, there is no need for assertion-checking in a release-mode program.

Assertions listed in the documentation for a function do not have to be put in place by the implementer, but usually are.  An implementer may choose not to put in an assertion if it is complicated or would take too much CPU time.  My implementation of the standard library have all assertions listed in the documentation. 

The second category of errors is caused by conditions primarily outside the program's control.  An out-of-memory error is perhaps the most serious of these.  By throwing an exception, control is automatically passed to a point in code (a handler) the programmer has designated to handle the error.  Exceptions are used whenever the error is very serious and/or unusual.

The third category of errors is also caused by conditions primarily outside the program's control, but only minor errors are handled with a return code.  An error can be judged as minor if it will most likely not cause the program to malfunction, and if the programmer should not be expected to have an exception handler set up to catch the error.

The lines dividing the categories are thin; in some cases it is not obvious which error-handling method should be used.  Often, which method is optimal depends on the situation in which a function is called; the decision is based on which error-handling method is optimal in what the library designers thought would be the most common contexts.

In some cases, both an assertion and an exception may be used.  When this is done, it based on the idea that a particular condition should never exist in a properly written program, but may happen so rarely in an improperly written program as to slip into a release version of the program.  The idea is that it is better for an exception to be thrown than for the program to malfunction or simply crash.

The Exception Class

Any class can be used as an exception object, but all exceptions in the standard library are derived from a generic class called Exception.  This class is defined as follows:

Published Class Exception:
	Uses Mini Memory Manager;
Public:
	Cast Returns @ Const String;
	Function Descr Returns @ Const String:
		Return Description; End;
	Function Stack Returns @ Const String:
		Return CallStack; End;
	Function Constructor (Descr: String);
	Function Constructor;
	Static Function Constructor;
	Static Function Destructor;
Private:
	Description: String;
	CallStack: String;
End Class;

There are many exception classes derived from this one; each section of the standard library documentation has a page for exceptions:

• File Management Exceptions
• Memory Management
•