Documentation

Data Conversion Classes and MATLAB Compiler SDK Interface

Overview

The data conversion classes are

  • MWArray

  • MWIndexArray

  • MWCellArray

  • MWCharacterArray

  • MWLogicalArray

  • MWNumericArray

  • MWStructArray

MWArray and MWIndexArray are abstract classes. The other classes represent the standard MATLAB® array types: cell, character, logical, numeric, and struct. Each class provides constructors and a set of properties and methods for creating and accessing the state of the underlying MATLAB array.

There are some data types (cell arrays, structure arrays, and arrays of complex numbers) commonly used in the MATLAB product that are not available as native .NET types. To represent these data types, you must create an instance of eitherMWCellArray, MWStructArray, or MWNumericArray.

Returning Data from MATLAB to Managed Code

All data returned from a MATLAB function to a .NET method is represented as an instance of the appropriate MWArray subclass. For example, a MATLAB cell array is returned as an MWCellArray object.

Return data is not automatically converted to a native array. If you need to get the corresponding native array type, call the ToArray method, which converts a MATLAB array to the appropriate native data type, except for cell and struct arrays.

Example of MWNumericArray in a .NET Application

Here is a code fragment that shows how to convert a double value (5.0) to a MWNumericArray type:

MWNumericArray arraySize = 5.0;
magicSquare = magic.MakeSqr(arraySize);

After the double value is converted and assigned to the variable arraySize, you can use the arraySize argument with the MATLAB based method without further conversion. In this example, the MATLAB based method is magic.MakeSqr(arraySize).

Interfaces Generated by the MATLAB Compiler SDK .NET Target

For each MATLAB function that you specify as part of a .NET assembly, the MATLAB Compiler SDK™ product generates an API based on the MATLAB function signature, as follows:

  • A single output signature that assumes that only a single output is required and returns the result in a single MWArray rather than an array of MWArray.

  • A standard signature that specifies inputs of type MWArray and returns values as an array of MWArray.

  • A feval signature that includes both input and output arguments in the argument list rather than returning outputs as a return value. Output arguments are specified first, followed by the input arguments.

Single Output API

Note

Typically you use the single output interface for MATLAB functions that return a single argument. You can also use the single output interface when you want to use the output of a function as the input to another function.

For each MATLAB function, the MATLAB Compiler SDK product generates a wrapper class that has overloaded methods to implement the various forms of the generic MATLAB function call. The single output API for a MATLAB function returns a single MWArray.

For example, the following table shows a generic function foo along with the single output API that the compiler generates for its several forms.

Generic MATLAB function
function [Out1, Out2, ..., varargout] = foo(In1, In2, ..., InN, 
varargin)
API if there are no input arguments
public MWArray foo() 
API if there are one or more input arguments
public MWArray foo(MWArray In1, MWArray In2...MWArray inN)
API if there are optional input arguments
public MWArray foo(MWArray In1, MWArray In2,      ..., MWArray 
inN
params MWArray[] varargin)

In the example, the input arguments In1, In2, and inN are of type MWArray.

Similarly, in the case of optional arguments, the params arguments are of type MWArray. (The varargin argument is similar to the varargin function in MATLAB — it allows the user to pass a variable number of arguments.)

Note

When you call a class method in your .NET application, specify all required inputs first, followed by any optional arguments.

Functions having a single integer input require an explicit cast to type MWNumericArray to distinguish the method signature from a standard interface signature that has no input arguments.

Standard API

Typically you use the standard interface for MATLAB functions that return multiple output values.

The standard calling interface returns an array of MWArray rather than a single array object.

The standard API for a generic function with none, one, more than one, or a variable number of arguments, is shown in the following table.

Generic MATLAB function
function [Out1, Out2, ..., varargout] = foo(In1, In2, ..., InN, 
varargin)
API if there are no input arguments
public MWArray[] foo(int numArgsOut) 
API if there is one input argument
public MWArray [] foo(int numArgsOut, MWArray In1) 
API if there are two to N input arguments
public MWArray[] foo(int numArgsOut, MWArray In1,MWArray In2, 
\... MWArray InN) 
API if there are optional arguments, represented by the varargin argument
public MWArray[] foo(int numArgsOut,MWArray in1,MWArray in2, 
MWArray InN,
params MWArray[] 
varargin)

Details about the arguments for these samples of standard signatures are shown in the following table.

ArgumentDescriptionDetails
numArgsOutNumber of outputs

An integer indicating the number of outputs you want the method to return.

The numArgsOut argument must always be the first argument in the list.

In1, In2, ...InNRequired input arguments

All arguments that follow numArgsOut in the argument list are inputs to the method being called.

Specify all required inputs first. Each required input must be of type MWArray or one of its derived types.

vararginOptional inputs

You can also specify optional inputs if your MATLAB code uses the varargin input: list the optional inputs, or put them in an MWArray[] argument, placing the array last in the argument list.

Out1, Out2, ...OutNOutput arguments

With the standard calling interface, all output arguments are returned as an array of MWArray.

feval API

In addition to the methods in the single API and the standard API, in most cases, the MATLAB Compiler SDK product produces an additional overloaded method. If the original MATLAB code contains no output arguments, then the compiler will not generate the feval method interface.

Consider a function with the following structure:

function [Out1, Out2, ..., varargout] = foo(In1, In2, ..., InN, 
varargin)

The compiler generates the following API, known as the feval interface,

public void foo 
            (int numArgsOut,
             ref MWArray [] ArgsOut, 
             MWArray[] ArgsIn)

where the arguments are as follows:

numArgsOutNumber of outputs

An integer indicating the number of outputs you want to return.

This number generally matches the number of output arguments that follow. The varargout array counts as just one argument, if present.

ref MWArray [] ArgsOutOutput arguments

Following numArgsOut are all the outputs of the original MATLAB code, each listed in the same order as they appear on the left side of the original MATLAB code.

A ref attribute prefaces all output arguments, indicating that these arrays are passed by reference.

MWArray[] ArgsInInput arguments

MWArray types or supported .NET primitive types.

When you pass an instance of an MWArray type, the underlying MATLAB array is passed directly to the called function. Native types are first converted to MWArray types.