Using the C++ Math Library

Example - Using load() and save() (ex7.cpp)

This example demonstrates how to use the functions load() and save() to write your data to a disk file and read it back again. 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 the example, note the following:

• You must name the variables when you save them to a MAT-file.
• You must specify the name of the variable you want to read from a MAT-file.
• load() and save() do not conform to the standard MATLAB C++ Math Library calling convention:
• Not all arguments are of type mwArray or mwArray *.
• Output and input arguments to load() are interspersed.
• MAT-files must have the three-letter extension mat. If you do not specify the .mat extension, load() and save() automatically add it.

// ex7.cpp

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

int main(void)
{
    try {
        mwArray x, y, z, a, b, c;                        // #2

        x = rand(4,4); // <3>
        y = magic(7);
        z = eig(x);

        // Save (and name) the variables.
        save("ex5.mat", "x", x, "y", y, "z", z);         // #4

        // Load the named variables.
        load("ex5.mat", "x", &a, "y", &b, "z", &c);      // #5

        // Check to be sure the variables are equal.
      if (tobool(a == x) && tobool(b == y) && tobool(c == z)) // #6
        {
            cout << "Success: all variables equal." << endl;
        }
        else 
        {
            cout << "Failure: loaded values not equal to
                     saved values." << endl;
        }
    }
    catch (mwException &ex) {
        cout << ex << endl;
    }
   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 and initialize variables. x, y, and z are written to the MAT-file using save(). a, b, and c store the data read back from the MAT-file by load().
3. Assign data to the variables that will be saved to a file. x stores a 4-by-4 array that contains randomly-generated numbers. y stores a 7-by-7 magic square. z contains the eigenvalues of x.
4. Save three variables to the file ex5.mat. In one call to save(), you can save up to 16 variables to the file identified by the first argument. Subsequent arguments come in pairs: the first argument in the pair (a string) labels the variable in the file; the contents of the second argument, an mwArray, is written to the file.

An additional signature for save() allows you to specify a mode for writing to the file: "w" for overwrite, "u" for update (append), and "w4" for overwrite in version 4 format. Without the mode argument, as in this example, save() overwrites the data.

Note that you must provide a name for each variable you save. When you retrieve data from a file, you must provide the name of the variable you want to load. You can choose any name for the variable; it does not have to correspond to the name of the variable within the program.

5. Load the named variables from the file "ex5.mat". Note that the function load() does not follow the standard C++ Math Library calling convention where output arguments precede input arguments. The output arguments, a, b, and c, are interspersed with the input arguments.

Pass arguments in this order: the filename and then the name/variable pairs themselves. You can read in up to 16 mwArray objects at a time. An important difference between the syntax of load() and save() is the type of the variable portion of each pair. Because you're loading data into a variable, load() needs the address of the variable: &a, &b, &c.  a, b, and c are output arguments whereas x, y, and z in the save() call are input arguments. Notice how the name of the output argument does not have to match the name for the variable stored in the file.

6. Compare the data loaded from the file to the original data that was written to the file. a, b, and c contain the loaded data; x, y, and z contain the original data. The calls to tobool() are necessary because C++ requires that the conditional expression of an if statement be a scalar Boolean. tobool() reduces the rank of its argument to a scalar, and then returns a Boolean value.

Output

When run, the program produces this output:

Success: all variables equal.

Importing Array Data from a MAT-File

Translating from MATLAB to C++