Using the C++ Math Library

Example Program: Writing Simple Functions (ex4.cpp)

This example demonstrates how to write a simple function that takes two matrix arguments and returns a matrix value. 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:

• Your routines should return an mwArray object, not a reference to one.
• mwArray objects are most efficiently passed by reference.
• Input arrays should be declared const.
• The vectorized routines in the MATLAB C++ Math Library eliminate, in many cases, the need for you to write explicit for-loops in your own code.

// ex4.cpp

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

static double data0[] = { 2, 6, 4, 8 };                  // #2
static double data1[] = { 1, 5, 3, 7 };

mwArray average(const mwArray &m1, const mwArray &m2)    // #3
{
    return rdivide(plus(m1, m2), 2);      // (m1 + m2) / 2
}

int main(void) // <4>
{
    // Create two matrices
    mwArray mat0(2, 2, data0);    // mat0 = [ 2 4; 6 8 ]    #5
    mwArray mat1(2, 2, data1);    // mat1 = [ 1 3; 5 7 ]
    mwArray mat2;

    mat2 = average(mat0, mat1);                          // #6

    cout << mat0 << "\t + \n" << mat1
         << "\t / 2 = \n" << mat2;                       // #7

    return(EXIT_SUCCESS);
}

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

1. Include header files. matlab.hpp declares the MATLAB C++ Math Library's data types and functions. matlab.hpp includes iostream.h, which declares the input and output streams cin and cout.  stdlib.h contains the definition of EXIT_SUCCESS.
2. Declare the data that is used to initialize the arrays in the main program. As noted in Example Program: Creating Arrays and Array I/O (ex1.cpp), use a one-dimensional C++ array to initialize a Math Library array from C++ static data; the mwArray constructor takes a one-dimensional array as an argument.

Remember that C++ stores its two-dimensional arrays in row-major order, whereas the C++ Math Library stores arrays in column-major order. When setting up static matrix data, always enter the data in column-major order.

3. Declare the average() function, which ``averages'' two matrices. For each pair of elements in the two input matrices, m1(i,j) and m2(i,j), the function computes the average of the two elements and stores the result in the corresponding element of the output array.

For efficiency, pass the two input matrices by const reference. The const indicates that the input parameters are not modified.

average() returns an mwArray rather than a reference to an mwArray. Your functions should never return a reference to an mwArray because returning a reference to a local variable is an error in C++. Refer to a C++ reference guide for more information.

Note that this routine does not contain an explicit loop. The functions you call - rdivide() and plus() - contain the necessary loops. Vectorized functions like these are common in the MATLAB C++ Math Library and provide a great convenience: you don't need to write the loops to process array data.

4. Declare the main routine. main() declares the matrix variables, calls the average() function, and prints the results.
5. Declare three matrices. Initialize mat0 and mat1 to 2-by-2 square matrices, using the static data declared earlier. The data initializing mat0 and mat1 is arranged in column-major order. The first row of mat0 is 2 4, the second 6 8. The first row of mat1 is 1 3, the second 5 7. Without a specified size or initial data, mat2 is a null or empty array.
6. Call the average() function. Pass mat0 and mat1 as input arguments and assign the result to mat2.
7. Print the result. This code demonstrates another convenience of C++: a single line of code sending more than one object to an output stream. The output appears on the stream in the same order it appears in the code.

Output

The program produces this output:

  [
         2        4 ;
         6        8
  ]
 
         + 
  [
         1        3 ;
         5        7
  ]
 
         / 2 = 
  [
    1.50000   3.50000 ;
    5.50000   7.50000
  ]

Stand-Alone Programs

Writing Efficient Programs