Using the C++ Math Library

Converting Data to MATLAB Arrays

The operators and functions in the MATLAB C++ Math Library operate on arrays and produce arrays as results. However, because all data is not available in array form, the library provides functions for converting data to and from arrays. In general, anywhere the library interface requires an mwArray, you can use a data type that can be converted to an mwArray.

In C++, two types of routines, constructors and casts, handle the conversions. Constructors transform raw data into C++ objects. Casts extract data from already-constructed objects. Constructors always result in new objects, whereas casts either produce new objects or provide pointers to the data in the original objects. C++ automatically performs many of these conversions for you.

Converting Data into a MATLAB Array

You can convert five types of data to an mwArray:

• A scalar
• A string
• An array of double-precision floating-point numbers
• A MATLAB mxArray pointer, also known as a MatlabMatrix pointer
• An mwSubArray

A new mwArray object is created when any of these data types is converted to an mwArray object.

The most common conversions are from scalars, strings, and arrays of doubles to mwArrays. If you are working with MEX-Files or the MATLAB C Math Library, you may need to convert the mxArray pointers that those routines return into mwArray objects since the MATLAB C++ Math Library does not handle mxArray pointers. mwSubArray objects result from indexing operations; the library itself handles them for you.

The table below demonstrates how to convert the various data types to an mwArray. The table shows an implicit conversion and an explicit conversion for each data type. C++ automatically performs implicit conversions for you. Explicit conversions are ones that you can explicitly invoke.

For most uses, the code in the implicit column is sufficient. C++ determines which constructor to invoke from the types of the operands on either side of the assignment statement. In some cases, however, C++ may not be able to determine unambiguously which conversion to apply, and an explicit conversion may be necessary.

Table 3-6: Converting to an mwArray 

From...	Implicit Constructor	Explicit Constructor
Scalar	mwArray A; A = 5;	mwArray A; A = mwArray(5)
String	mwArray A; A = "abcd";	mwArray A; A = mwArray("abcd");
Array of doubles	Not Available	mwArray A; static double x[]={1,5}; A = mwArray(1,2,x);
mxArray pointer	mwArray A; mxArray *mat; A = mat;	mwArray A; mxArray *mat; A = mwArray(mat);
mwSubArray	mwArray A, B; B = ramp(1,10); mwSubArray sub=B(8); A = sub;	mwArray A, B; B = ramp(1,10); mwSubArray sub = B(8); A = mwArray(sub);

You can also use cast syntax in the explicit case. See a C++ manual for more information about the equivalence between constructors and casts.

Converting a MATLAB Array into Data

mwArrays can be converted into two types of data:

• Scalars
• MATLAB mxArray pointers

The table below demonstrates how to extract data from an mwArray. In the pointer case (mxArray pointer), the conversion returns a pointer to the internal data of the mwArray object rather than to a new object. Take care not to modify the data referenced by the pointer. The returned pointer is defined as const to remind you that the data it points to should not be modified.

There are two limitations to the types of mwArray you can cast into a double:

• You cannot assign a nonscalar mwArray to a C++ scalar variable (int or double). You can only cast 1-by-1 arrays to scalars.
• You cannot cast a complex mwArray (scalar or nonscalar) to a double-precision scalar or an array. Before assigning a complex array to a real-valued variable, convert the complex mwArray to a real mwArray with the real() or imag() functions.

Both of these cases raise an exception.

Table 3-7: Extracting Data from an mwArray 

To...	Implicit Cast	Explicit Cast
Integer	int32 i; mwArray A = 5; i = A;	int32 i; mwArray A = 5; i = (int32)A;
Double	double x; mwArray A = 5; x = A;	double x; mwArray A = 5; x = (double)A;

Refer to Extracting Data from an mwArray in Chapter 10 to learn about mwArray::GetData() and mwArray::ToString().

Efficiency Considerations

Conversions are not always efficient operations. It is important to minimize their use in certain situations. In particular, using a scalar array as a loop index bound is very inefficient. You obtain much better performance by first converting the mwArray to an integer and then using the integer as the loop bound variable.

The following code demonstrates an inefficient use of an mwArray as a loop bound variable. In each iteration of the for-loop, the comparison i < A requires that A be converted from an mwArray to a scalar. This conversion is expensive.

// Inefficient loop bound variable
mwArray A = 5;
int i;
for (i=0; i<A; i++)
    cout << "Counting: " << i << endl;

The code below runs much faster because the variable A is explicitly cast to an integer before the loop begins; integer j rather than A is used as the for-loop bound variable.

// Efficient loop bound variable
mwArray A = 5;
int i, j = A;
for (i=0; i < j; i++)
     cout << "Counting: " << i << endl;

In this case, the cast operation is invoked only once.

Performing Common Array Programming Tasks

Determining Array Size