Using the C++ Math Library

Example Program: Calling Library Functions (ex2.cpp)

This example demonstrates how to call different versions of the same library function and how to pass optional input and output arguments. The example uses the svd() function.

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++ Applicationsfor information about building and running the example program.

In MATLAB, there is one svd() function that you can call with varying numbers of input and output arguments. The MATLAB version of svd() counts the number of arguments passed to it and performs a different calculation for each valid combination of input and output arguments.

An ordinary C++ function cannot count its arguments. It always requires the same number of inputs and outputs each time you call it. However, you can declare multiple C++ functions with the same name as long as the argument lists for the functions are different. This is called overloading a function. Argument lists differ if they contain different numbers of arguments or if the types of the arguments are different.

There are three ways to call the svd() function in MATLAB. Therefore there are three overloaded svd() functions in C++, each corresponding to one of the ways you can call svd() in MATLAB. This example demonstrates how to call each of the overloaded svd() functions.

Refer to the online MATLAB C++ Math Library Reference for an explanation of svd(). Accessing Online Reference Documentation describes how to access the Help Desk.

In this example, note the following:

• Each MATLAB function that can be called with varying numbers of arguments corresponds to a set of overloaded functions in the MATLAB C++ Math Library.
• Place all output arguments before any input arguments in the parameter list.
• The function return value corresponds to the first output argument.
• Always pass an input argument to a function as an mwArray object.
• Always pass an output argument as a pointer to mwArray object.
• You may omit optional arguments from the parameter list. Placeholder or default values are not necessary.
• MATLAB C++ Math Library functions never modify their input arguments and always modify their output arguments.
• Call C++ constructors where possible, for efficiency.

// ex2.cpp

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

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

int main(void)
{
    // Create the input matrix.
    mwArray X(4, 2, data);                             // # 3
    mwArray U, S, V;

    // Compute the singular value decomposition of the matrix.
    cout << "One input, one output: " << endl ;
    cout << "S = " << svd(X) << endl;                  // # 4

    // Pass in optional output arguments.
    U = svd(&S, &V, X);                                // # 5

    cout << "One input, three outputs: " << endl;
    cout << "U = " << U << "S = " << S << "V = " << V << endl;

    // Pass in optional input argument.
    U = svd(&S, &V, X, 0.0);                           // # 6

    cout << "Two inputs, three outputs: " << endl;
    cout << "U = " << U << "S = " << S << "V = " << V;

    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 static C++ array that initializes the svd() input matrix in the main() routine. The MATLAB C++ Math Library requires that the numbers in this array be in column-major order. See Example Program: Creating Arrays and Array I/O (ex1.cpp) in Chapter 3 for more information.
3. Call a C++ constructor to declare and initialize the matrix X to a four-row, two-column matrix. In your code, use C++ constructors whenever possible, as they are more efficient than a declaration followed by an assignment.
4. Call the simplest of the three svd() functions. This function takes one input matrix and produces one output matrix. Because C++ allows multiple functions with the same name to co-exist as long as their argument lists are different (this is called overloading a function), calling the simplest form of svd() does not require passing in extra NULL arguments as it would in the MATLAB C Math Library.
5. Call the second svd() function. This function takes one input and produces three outputs. Because C++, unlike MATLAB, does not allow multiple return values, you pass the extra outputs into the svd() function as output arguments. Output arguments are modified by the function to contain the appropriate results.

Just as input arguments are uniformly passed as const mwArray references, output arguments are always passed as pointers to mwArray objects. In C++, applying the & (address-of) operator to an object produces a pointer to that object.

6. Call the third svd() function, which takes two inputs and produces three outputs. The second input is an optional argument. Note again the convenience of C++ function overloading. Without overloading, this optional input argument would have appeared as a NULL value in the argument lists of the other calls to svd().

Output

The program produces the following output. See Using Array Stream I/O in Chapter 8 for details on the array input and output format.

One input, one output: 
S =   1.0e+01 *
 
  [
    1.42691 ;
    0.06268
  ]
 
 One input, three outputs: 
U =   [
    0.15248   0.82265  -0.39450  -0.37996 ;
    0.34992   0.42138   0.24280   0.80066 ;
    0.54735   0.02010   0.69791  -0.46143 ;
    0.74479  -0.38117  -0.54621   0.04074
  ]
 
S =   1.0e+01 *
 
  [
    1.42691   0.00000 ;
    0.00000   0.06268 ;
    0.00000   0.00000 ;
    0.00000   0.00000
  ]
 
V =   [
    0.64142  -0.76719 ;
    0.76719   0.64142
  ]
 
 Two inputs, three outputs: 
U =   [
    0.15248   0.82265 ;
    0.34992   0.42138 ;
    0.54735   0.02010 ;
    0.74479  -0.38117
  ]
 
S =   1.0e+01 *
 
  [
    1.42691   0.00000 ;
    0.00000   0.06268
  ]
 
V =   [
    0.64142  -0.76719 ;
    0.76719   0.64142
  ]

Summary of Library Calling Conventions

How to Call Operators