Using the C++ Math Library

Example Program: Handling Exceptions (ex5.cpp)

This example demonstrates the MATLAB C++ Math Library's error handling facilities. The program deliberately triggers a library exception by specifying a negative number as an array index. You can find the code for this example in the <matlab>/extern/examples/cppmath directory on UNIX systems and in the <matlab>\extern\examples\cppmath directory on PCs, where <matlab> represents the top-level directory of your installation. See Building C++ Applications for information about building and running the example program.

In the example, note the following:

• You should always have a try and catch block in your main routine.
• Exceptions are caught by object type. mwException is the top-level exception class.
• A C++ program may have multiple catch blocks, each of which catches different types of exceptions.
• Once an exception is thrown, it propagates up the call stack until it reaches the first catch block that catches exceptions of its type.
• All the exceptions in the MATLAB C++ Math Library contain an associated error message.

Note    This example uses a simple exception handling mechanism and does not use nested try blocks or multiple catch blocks. Though these C++ features are compatible with the MATLAB C++ Math Library, they are beyond the scope of this book. Refer to your C++ reference manual for information on nested try blocks and multiple catch blocks.

// ex5.cpp

#include <stdlib.h>
#include "matlab.hpp"

static double data[] = { 1, 2, 3, 4, 5, 6 };

mwArray compute(const mwArray &in)
{ 
    // Cause an error: use a negative index.
    return in(-5) * 17;                                   // #1
}

int main(void)
{
    // Handle exceptions for all code in the try-block.
    try {                                                 // #2 
        mwArray mat0(2, 3, data);
        mwArray mat1;
    
        mat1 = compute(mat0);                             // #3 
        cout << mat1 << endl;
    }
    // Catch and print any exceptions that occur.
    catch (mwException &ex) {                             // #4
        cout << ex << endl;
        return(EXIT_FAILURE);
    }
    return(EXIT_SUCCESS);
}

The numbered items in the list below correspond to the numbered comments in the code example:

1. Deliberately cause an error. The compute() function attempts an illegal operation: a negative number was used as a matrix index. This operation causes the MATLAB C++ Math Library to throw an exception. An exception propagates up the call-chain, or stack, until it reaches a catch block that handles it. Even though the compute() function does not contain a catch block, the exception is properly handled by the catch block in main().
2. Begin a try block. The try keyword introduces the block. A try block is like a safety net. try blocks are always followed by one or more catch blocks. The catch block that follows a try block processes any exceptions thrown during execution of the try block. In addition to catching exceptions that are generated by the code in the try block, the catch block catches exceptions thrown by the functions called from within the try block and by the functions called from within those functions, and so on.

An exception is a C++ object. Every C++ object has a type. When an exception is thrown, the exception stops at the nearest (in terms of the call chain, or stack) catch block that handles exceptions of its type. In this case, because there is only one catch block in the program, there is only one place for the exceptions to stop.

3. Call the compute() function. If the function does not throw an exception, the value of mat1 is printed. Note the absence of code to test for an error from compute(). The lack of error-checking code makes the rest of the code easier to follow. This is another of the advantages of exception handling: catch blocks separate error-handling code from ordinary code, making the rest of the function easier to read and maintain.
4. Begin a catch block. The catch keyword introduces the block.  Catch blocks are always associated with try blocks.  Catch blocks "catch'' or stop a propagating exception according to the type of the exception.

This catch block catches all exceptions of type mwException or one of its subclasses. mwException is the base exception class for the MATLAB C++ Math Library. Exceptions not caught by this catch block, i.e., any exceptions not of type mwException, cause the abrupt termination of the program. Depending on the operating system, an error message may or may not be printed.

Output

The program produces this output:

WARNING: Subscript indices must be integer values.
RuntimeError
Exception!  File: handler.cpp, Line: 169
    Index into matrix is negative or zero.  See release notes on
    changes to logical indices.

In general, printing an mwException using a C++ output stream produces two output lines. The first describes the type of exception (generic, in this case) and identifies the file and line number where the exception was thrown. The file name and line number often refer to MATLAB C++ Math Library code rather than to your code. They indicate the origin of the exception, rather than where it was caught or where the error occurred in your code.

The second line describes the exception in more detail. In this case, the message tells you that an illegal indexing operation occurred. The subscript, -5, was applied to a matrix for which the valid subscripts fall between one and six, inclusive.

Handling C++ Math Library Exceptions in Your Code

Replacing the Default Library Error Handler