Using the C++ Math Library

Exception Handling in the MATLAB C++ Math Library

Note    You only need to read this section if your C++ compiler does not support exception handling. Check your compiler documentation to see if it includes this support.

Because not all C++ compilers fully support exception handling, the MATLAB C++ Math Library, provides an alternative exception handling mechanism. The mwException class defines a virtual function called do_raise(). Instead of using the throw keyword to throw an exception, the library code calls do_raise() instead. When built with a compiler that fully supports exceptions, the do_raise() function throws the exception using the throw keyword. Otherwise, do_raise() prints the exception and calls exit(-1).

The disadvantage to this approach is that in an environment without support for exceptions, all exceptions are automatically fatal. However, compiler support for exceptions is growing more widespread rapidly, so this situation should be temporary.

Using the MLM_THROW Macros to Throw Exceptions

In order to make this dual support transparent, all exceptions are thrown with do_raise() rather than throw. Six macros make this dual mechanism easy for you to use in your own code.

The macros are named MLM_THROW<X>, where <X> is an integer from 0 to 5. The integer suffix indicates the number of additional arguments that the macro takes. Each macro takes at least two arguments (not counted in the integer suffix): the type of exception to throw and a text string message that describes the problem. The type of exception corresponds to the name of one of the exception classes documented below. Additional arguments are text strings, integers, or doubles that substitute for format specifiers in the first string argument. The number of format specifiers correspond to the number of additional arguments.

The macros process the message and any extra arguments with sprintf(). MLM_THROW3(), for example, takes five arguments: the type of exception, the text string message, and three additional arguments. This mechanism lets you write descriptive error messages.

The last member of the set of macros is MLM_THROW5(). If you need to pass more than five additional arguments to MLM_THROW<X>, you must write additional macros. Look in the file mlmexcpt.h for the definitions of the macros and pattern your new macros after them. You'll find the header in the <matlab>/extern/include/cpp directory, on Unix systems, or the <matlab>\extern\include\cpp directory, on PCs, of your MATLAB C++ Math Library installation.

The following example taken from the MATLAB C++ Math Library's indexing code demonstrates the use of the MLM_THROW2 macro. The indexing code verifies that an index that accesses array data is valid. If a specified index is less than the minimum, or base, index, the library throws an mwDomainError exception.

if (i < index_base) 
    MLM_THROW2(mwDomainError, \
      "An index (%ld) was less than %ld, the minimum legal index."\
               i, index_base)

Two things to note about this code:

• The keyword throw does not appear. The macro itself throws the exception.
• The MLM_THROW2() statement is similar to an ordinary printf() call. MLM_THROW2() passes its second, third, and fourth arguments to sprintf(), which formats them just as printf() would.

Note    The backslashes at the ends of lines are required because MLM_THROW2() is a macro rather than a function call. Backslashes would not be necessary if the entire call to MLM_THROW2() fit on a single line.

Including an mwArray in an Exception Message

The subclasses of mwException contain text-based messages describing the error that triggers the exception. In many cases, faulty data causes the problem, in which case it may be useful to include part of the array data in the error message.

The constructors of the exception classes take a string as an argument. Using the standard C++ class strstream, you can produce a string representation of all or part of an mwArray.

mwArray A = rand(4);
strstream string;
string << "This matrix: " << A << "caused the problem." << endl
       << ends;
MLM_THROW0(mwRangeError, string.str());

This code formats an error message in a strstream, which dynamically grows to accommodate the data stored in it. Calling str() on the strstream freezes it so that the strstream can no longer grow. str() then returns the string stored in the strstream.

Replacing the Default Library Error Handler

Memory Management