Main Content

Pass Data to .NET Objects

When you call a .NET method or function from MATLAB®, MATLAB converts arguments into .NET types. MATLAB performs this conversion on each passed argument, except for arguments that are already .NET objects. The following topics provide information about passing specific data types to .NET methods.

For information about how MATLAB maps .NET types to MATLAB types, see Handle Data Returned from .NET Objects.

Pass Primitive .NET Types

The following table shows the MATLAB base types for passed arguments and the corresponding .NET types defined for input arguments. Each row shows a MATLAB type followed by the possible .NET argument matches, from left to right in order of closeness of the match.

MATLAB Primitive Type Conversion Table

MATLAB
Type
Closest Type <————— Other Matching .NET Types —————> Least Close Type
Preface Each .NET Type with System.
logicalBooleanByteSByteInt16UInt16Int32UInt32Int64UInt64SingleDoubleObject
doubleDoubleSingleDecimalInt64UInt64Int32UInt32Int16UInt16SByteByteObject
singleSingleDoubleDecimalObject        
int8SByteInt16Int32Int64SingleDoubleObject     
uint8ByteUInt16UInt32UInt64SingleDoubleObject     
int16Int16Int32Int64SingleDoubleObject      
uint16UInt16UInt32UInt64SingleDoubleObject      
int32Int32Int64SingleDoubleObject       
uint32UInt32UInt64SingleDoubleObject       
int64Int64DoubleObject         
uint64UInt64DoubleObject         
charCharStringObject         
stringStringObject          

The following primitive .NET argument types do not have direct MATLAB equivalent types. MATLAB passes these types as is:

  • System.IntPtr

  • System.UIntPtr

  • System.Decimal

  • enumerated types

Pass Cell Arrays

You can pass a cell array to a .NET property or method expecting an array of System.Object or System.String arguments, as shown in the following table.

MATLAB Cell Array Conversion Table

MATLAB TypeClosest Type <——— Other Matching .NET Types ———> Least Close Type

Cell array of string scalars and/or character arrays

System.String[]System.Object[]System.Object

Cell array (no string or character arrays)

System.Object[]System.Object 

Elements of a cell can be any of the following supported types:

Pass Nonprimitive .NET Objects

When calling a method that has an argument of a particular .NET class, pass an object that is an instance of that class or its derived classes. You can create such an object using the class constructor, or use an object returned by a member of the class. When a class member returns a .NET object, MATLAB leaves it as a .NET object. Use this object to interact with other class members.

Pass MATLAB String and Character Data

MATLAB automatically converts:

  • char array to a .NET System.String object. To pass an array of char arrays, create a cell array.

  • string scalar to a .NET System.String object.

  • Each string scalar in a string array to a .NET System.String object. The string array is converted to System.String[].

  • String value <missing> to null.

  • string.empty to System.String[] with size of 0.

Pass MATLAB Dictionary Data

Implicit Conversion

You can pass a MATLAB dictionary to a .NET method. For example, suppose that you have a .NET method MyClass.SomeMethod that takes a dictionary input argument.

mlDict = dictionary("a",1,"b",2);
MyClass.SomeMethod(mlDict);

MATLAB supports implicit conversion to these types:

  • System.Collections.Dictionary<,>

  • System.Collections.IDictionary<,>

  • System.Collections.IReadOnlyDictionary<,>

  • System.Collections.IDictionary

For the generic types (containing <,>), the keys and values must match the destination type. For example, if a method accepts Dictionary<int,int>, then you must pass a MATLAB dictionary that maps an int32 key to an int32 value. MATLAB does not convert the keys or values.

A MATLAB dictionary with entries of type cell can only be converted to a .NET dictionary with entries of type System.Object.

Explicit Conversion

You can explicitly create a generic .NET dictionary from a MATLAB dictionary by calling the NET.createDictionary function.

netDict = NET.createDictionary(mlDict);
MyClass.SomeMethod(netDict);

Pass System.Nullable Type

You can pass any of the following to a .NET method with System.Nullable<ValueType> input arguments:

  • Variable of the underlying <ValueType>

  • null value, []

  • System.Nullable<ValueType> object

When you pass a MATLAB variable of type ValueType, MATLAB reads the signature and automatically converts your variable to a System.Nullable<ValueType> object. For a complete list of possible ValueType values accepted for System.Nullable<ValueType>, refer to the MATLAB Primitive Type Conversion Table.

For examples, see Pass System.Nullable Arguments.

Pass NULL Values

MATLAB uses empty double ([]) values for reference type arguments.

Unsupported MATLAB Types

MATLAB does not support passing the following MATLAB types to .NET methods:

  • Structure arrays

  • Sparse arrays

  • Complex numbers

Choosing Method Signatures

MATLAB chooses the correct .NET method signature (including constructor, static and nonstatic methods) based on the following criteria.

When your MATLAB function calls a .NET method, MATLAB:

  1. Checks to make sure that the object (or class, for a static method) has a method by that name.

  2. Determines whether the invocation passes the same number of arguments of at least one method with that name.

  3. Makes sure that each passed argument can be converted to the type defined for the method.

If all the preceding conditions are satisfied, MATLAB calls the method.

In a call to an overloaded method, if there is more than one candidate, MATLAB selects the one with arguments that best fit the calling arguments, based on the MATLAB Primitive Type Conversion Table. First, MATLAB rejects all methods that have any argument types that are incompatible with the passed arguments. Among the remaining methods, MATLAB selects the one with the highest fitness value, which is the sum of the fitness values of all its arguments. The fitness value for each argument is how close the MATLAB type is to the .NET type. If two methods have the same fitness, MATLAB chooses the first one defined in the class.

For class types, MATLAB chooses the method signature based on the distance of the incoming class type to the expected .NET class type. The closer the incoming type is to the expected type, the better the match.

The rules for overloaded methods with optional arguments are described in Determining Which Overloaded Method Is Invoked.

Example — Choosing a Method Signature

Open a methodsview window for the System.String class and look at the entries for the Concat method:

import System.*
methodsview('System.String')

The Concat method takes one or more arguments. If the arguments are of type System.String, the method concatenates the values. For example, create two strings:

str1 = String('hello');
str2 = String('world');

When you type:

String.Concat(str1,str2)

MATLAB verifies the method Concat exists and looks for a signature with two input arguments. The following table shows the two signatures.

NameReturn TypeArgumentsQualifiers
ConcatSystem.String RetVal(System.Object arg0,
System.Object arg1)
Static
ConcatSystem.String RetVal(System.String str0,
System.String str1)
Static

Since str1 and str2 are of class System.String, MATLAB chooses the second signature and displays:

ans = 
helloworld

If the arguments are of type System.Object, the method displays the string representations of the values. For example, create two System.DateTime objects:

dt = DateTime.Today;
myDate = System.DateTime(dt.Year,3,1,11,32,5);

When you type:

String.Concat(dt,myDate)

MATLAB chooses the following signature, since System.DateTime objects are derived from the System.Object class.

QualifiersReturn TypeNameArguments
StaticSystem.String RetValConcat(System.Object arg0,
System.Object arg1)

This Concat method first applies the ToString method to the objects, then concatenates the strings. MATLAB displays information like:

ans = 
12/23/2008 12:00:00 AM3/1/2008 11:32:05 AM

Pass Arrays

For information about passing MATLAB arrays to .NET methods, see Use Arrays with .NET Applications and Pass MATLAB Arrays as Jagged Arrays.

How Array Dimensions Affect Conversion

The dimension of a .NET array is the number of subscripts required to access an element of the array. To get the number of dimensions, use the Rank property of the .NET System.Array type. The dimensionality of a MATLAB array is the number of non-singleton dimensions in the array.

MATLAB matches the array dimensionality with the .NET method signature, as long as the dimensionality of the MATLAB array is lower than or equal to the expected dimensionality. For example, you can pass a scalar input to a method that expects a 2-D array.

For a MATLAB array with number of dimensions, N, if the .NET array has fewer than N dimensions, the MATLAB conversion drops singleton dimensions, starting with the first one, until the number of remaining dimensions matches the number of dimensions in the .NET array.

Converting a MATLAB Array to System.Object

You can pass a MATLAB array to a method that expects a System.Object.

Pass MATLAB Arrays as Jagged Arrays

A MATLAB array is a rectangular array. .NET supports a jagged array, which is an array of arrays. So the elements of a jagged array can be of different dimensions and sizes.

Although .NET languages support jagged arrays, the term jagged is not a language keyword. C# function signatures use multiple pairs of square brackets ([][]) to represent a jagged array. In addition, a jagged array can be nested ([][][]), multidimensional ([,]), or nested with multidimensional elements (for example, [,,][,][]).

MATLAB automatically converts MATLAB arrays of numeric types to the corresponding jagged array type. If the input argument is a nonnumeric type or multidimensional, use the NET.createArray function to create an array to pass as a jagged array. For examples using NET.createArray, see Pass Jagged Arrays.

Related Topics