Library Routines (Using the C++ Math Library)

Using the C++ Math Library

Utility Functions

In addition to its mathematical functions, the interpreted MATLAB environment provides services such as memory management and array input and output. The MATLAB C++ Math Library cannot draw on the MATLAB environment for these essential services, so it provides its own services that initialize and control the library environment and that help you perform indexing.

These functions require several new types that describe pointers to functions. You will find these types used in the tables of functions below; these types are not part of MATLAB.

// Used for print handling functions
typedef void (*mwOutputFunc)(const char *);
// Used for error handling functions
typedef void (*mwErrorFunc)(const char*, mwBool);
// Used for exception handling
typedef void (*mwExceptionMsgFunc)(const mwException &);
// Used for memory allocation functions
typedef void *(*mwMemAllocFunc)(size_t);
typedef void (*smwMemFreeFunc)(void *);
typedef void *(*mwMemReallocFunc)(void *, size_t);
typedef void *(*mwMemCallocFunc)(size_t, size_t);

For more information on the error and exception handling functions, refer to the section Handling Exceptions in Chapter 7; for more information on print handling, see Defining a Print Handler in Chapter 7.

Print Handling
Function
Purpose

mwOutputFunc
mwGetPrintHandler(void);
Return a pointer to the function specified in the most recent call to mwSetPrintHandler() or to the default print handler, if you haven't specified a print handler.

void
mwSetPrintHandler(mwOutputFunc f);
Set the print handling routine. The print handler is responsible for handling all ``normal'' (non-error) output.

**Print Handling**
Function	Purpose
`mwOutputFunc` `mwGetPrintHandler(void);`	Return a pointer to the function specified in the most recent call to `mwSetPrintHandler()` or to the default print handler, if you haven't specified a print handler.
`void` `mwSetPrintHandler(mwOutputFunc f);`	Set the print handling routine. The print handler is responsible for handling all ``normal'' (non-error) output.

Error and Exception Handling
Function
Purpose

void
mwDisplayException(const mwException &ex);
Using the error handler, displays the given exception.

mwErrorFunc
mwGetErrorMsgHandler(void);
Return a pointer to the function specified in the most recent call to mwSetErrorMsgHandler() or to the default error handler, if you haven't specified an error handler.

mwExceptionMsgFunc
mwGetExceptionMsgHandler(void);
Return a pointer to the function specified in the most recent call to
mwSetExceptionMsgHandler() or to the default exception message handler, if you haven't specified an exception message handler.

void
mwSetErrorMsgHandler(mwErrorFunc f);
Set the error handling routine. The error handler is responsible for handling all error message output.

void
mwSetExceptionMsgHandler(mwExceptionMsgFunc f)
The default exception handling function simply prints the exception using the error handling routine. If this behavior is inappropriate for your application, this function allows you to set an alternate exception handling function.

**Error and Exception Handling**
Function	Purpose
`void` `mwDisplayException(const mwException &ex);`	Using the error handler, displays the given exception.
`mwErrorFunc` `mwGetErrorMsgHandler(void);`	Return a pointer to the function specified in the most recent call to `mwSetErrorMsgHandler()` or to the default error handler, if you haven't specified an error handler.
`mwExceptionMsgFunc` `mwGetExceptionMsgHandler(void);`	Return a pointer to the function specified in the most recent call to `mwSetExceptionMsgHandler()` or to the default exception message handler, if you haven't specified an exception message handler.
`void` `mwSetErrorMsgHandler(mwErrorFunc f);`	Set the error handling routine. The error handler is responsible for handling all error message output.
`void` `mwSetExceptionMsgHandler(mwExceptionMsgFunc f)`	The default exception handling function simply prints the exception using the error handling routine. If this behavior is inappropriate for your application, this function allows you to set an alternate exception handling function.

Memory Allocation
Function
Purpose

void
mwSetLibraryAllocFcns(
    mwMemCallocFunc callocProc,
    mwMemFreeFunc freeProc,
    mwMemReallocFunc reallocProc,
    mwMemAllocFunc mallocproc,
    mwMemCompactFunc=0);
Set the MATLAB C++ Math Library's memory management functions. Gives you complete control over memory management.

**Memory Allocation**
Function	Purpose
`void` `mwSetLibraryAllocFcns(` `mwMemCallocFunc callocProc,` `mwMemFreeFunc freeProc,` `mwMemReallocFunc reallocProc,` `mwMemAllocFunc mallocproc,` `mwMemCompactFunc=0);`	Set the MATLAB C++ Math Library's memory management functions. Gives you complete control over memory management.

MATLAB uses the : (colon) operator to generate sequences of numbers: both vectors and matrix indices. Because the colon operator is unavailable in C++, the MATLAB C++ Math Library provides two families of functions, ramp() and colon(), to support the same functionality. The ramp() functions are best suited for generating vectors, the colon() functions for array indices.

Chapter 4, Indexing into Arrays, contains more details on the use of generated sequences in array indexing operations.

Generating Sequences
Function
Purpose

mwArray
ramp(mwArray start,
     mwArray end);
Generate a vector of (end-start)+1 elements. The elements in the vector are start, start+1, start+2, ... , start+n, end. Each element in the vector is one greater than the preceding element, with the possible exception of the last element (see below).

mwArray
ramp(mwArray start,
     mwArray step,
     mwArray end);
Generate a vector of ((end-start)/step)+1 elements. The elements in the vector are start, start+step, start+(2*step), start+(3*step), ...,start+(n*step), end. Each element in the vector is step greater than the preceding element, with the possible exception of the last element. Iteration stops when start+(n*step) is larger than end, yet the last value in the vector is always end; this can decrease the distance between the last two elements to less than step. Specifying a negative step generates a decreasing sequence; specifying a sequence that will not terminate raises an exception.

**Generating Sequences**
Function	Purpose
`mwArray` `ramp(mwArray start,` `mwArray end);`	Generate a vector of `(end-start)+1` elements. The elements in the vector are `start`, `start+1`, `start+2`, `...` , `start+n`, `end`. Each element in the vector is one greater than the preceding element, with the possible exception of the last element (see below).
`mwArray` `ramp(mwArray start,` `mwArray step,` `mwArray end);`	Generate a vector of `((end-start)/step)+1` elements. The elements in the vector are `start`, `start+step`, `start+(2step)`, `start+(3step)`, `...`,`start+(nstep)`, `end`. Each element in the vector is `step` greater than the preceding element, with the possible exception of the last element. Iteration stops when `start+(nstep)` is larger than `end`, yet the last value in the vector is always `end`; this can decrease the distance between the last two elements to less than `step`. Specifying a negative step generates a decreasing sequence; specifying a sequence that will not terminate raises an exception.

Indexing
Function
Purpose

mwIndex
colon();
Generate a ``sequence'' of indices. colon() stands for ``every value.'' For example, A(colon()) means every value in the matrix. A(1,colon()) means every column in the first row.

mwIndex
colon(mwArray start,
      mwArray end);
This function is identical to the analogous ramp() function, except that it is more efficient when used as a matrix index.

mwIndex
colon(mwArray start,
      mwArray step,
      mwArray stop);
This function is identical to the analogous ramp() function, except that it is more efficient when used as an array index.

mwArray
end(mwArray &mat,       mwArray &x,
      mwArray &y);

Generate the last index for an array dimension. Acts like end in the MATLAB expression A(3,6:end). x is the dimension to compute end for. Use 1 to indicate the row dimension; use 2 to indicate the column dimension. y is the number of indices in the subscript.

**Indexing**
Function	Purpose
`mwIndex` `colon();`	Generate a ``sequence'' of indices. `colon()` stands for ``every value.'' For example, `A(colon())` means every value in the matrix. `A(1,colon())` means every column in the first row.
`mwIndex` `colon(mwArray start,` `mwArray end);`	This function is identical to the analogous `ramp()` function, except that it is more efficient when used as a matrix index.
`mwIndex` `colon(mwArray start,` `mwArray step,` `mwArray stop);`	This function is identical to the analogous `ramp()` function, except that it is more efficient when used as an array index.
`mwArray` `end(mwArray &mat, mwArray &x,` `mwArray &y);`	Generate the last index for an array dimension. Acts like `end` in the MATLAB expression `A(3,6:end)`. `x` is the dimension to compute end for. Use 1 to indicate the row dimension; use 2 to indicate the column dimension. `y` is the number of indices in the subscript.

Sparse Matrix Functions Array Access Functions