Learn more about MATLAB

Handling .NET Data in MATLAB Software

On this page…
Passing Data to a .NET Object Handling Data Returned from a .NET Object

Passing Data to a .NET Object

When you make a call in the MATLAB software to a .NET method or function, MATLAB automatically 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 data to .NET:

• Passing Primitive .NET Types

• Passing Nonprimitive .NET Objects

• Passing MATLAB Strings

• Passing NULL Values

• Unsupported MATLAB Types

• Choosing Method Signatures

• Example — Choosing a Method Signature

• Passing Arrays

• Example — Passing Arrays

Passing 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.
logical	Boolean	Byte	SByte	Int16	UInt16	Int32	UInt32	Int64	UInt64	Single	Double	Object
double	Double	Single	Decimal	Int64	UInt64	Int32	UInt32	Int16	UInt16	SByte	Byte	Object
single	Single	Double	Decimal	Object
int8	SByte	Int16	Int32	Int64	Single	Double	Object
uint8	Byte	UInt16	UInt32	UInt64	Single	Double	Object
int16	Int16	Int32	Int64	Single	Double	Object
uint16	UInt16	UInt32	UInt64	Single	Double	Object
int32	Int32	Int64	Single	Double	Object
uint32	UInt32	UInt64	Single	Double	Object
int64	Int64	Double	Object
uint64	UInt64	Double	Object
char	Char	String	Object

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

Passing Nonprimitive .NET Objects

When calling a method that has an argument of a particular .NET class, you must 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 so you can continue to use it to interact with other class members.

Passing MATLAB Strings

To convert a string or char array to a .NET System.String object:

mlArray = 'This is a string';
netArray = System.String(mlArray);

mlArrayType = class(mlArray)
netArrayType = class(netArray)

MATLAB displays:

mlArrayType =
char
netArrayType =
System.String

Passing NULL Values

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

Unsupported MATLAB Types

You cannot pass the following MATLAB types to .NET methods:

• Structure arrays

• Cell 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.

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. There are two signatures:

Static System.String RetVal Concat(System.Object arg0, 
  System.Object arg1)
Static System.String RetVal Concat(System.String str0, 
  System.String str1)

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:

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

When you type:

String.Concat(objDate,myDate)

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

Static System.String RetVal Concat(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

Passing Arrays

For a method with an input argument of a one-dimensional .NET array, you can pass either a MATLAB array or an array created using the NET.createArray function. For example, suppose a method has the following signature:

public regularMethod2(Int32[] int32ArrArg)

After creating an object obj, you can pass a MATLAB array, as shown in the following pseudocode:

obj.regularMethod2(int32([2,3])) 

For a method with an input argument of a multidimensional .NET array, you must pass a .NET array. For example, suppose another method has the following signature:

public regularMethod3(Int32[,] int32TwoDimArg)

Create a .NET array, as shown in the following pseudocode:

netArr = NET.createArray('System.Int32', 2, 2); 
obj.regularMethod3(netArr)

For more information, see Using Arrays with .NET Applications.

Example — Passing Arrays

Create a string array strArr and populate it:

strArr = NET.createArray('System.String', 3);
space = ' ';
strArr.Set(0,'hello');
strArr.Set(1,space);
strArr.Set(2,'world');

Since strArr is of class System.String[], when you type:

String.Concat(strArr)

MATLAB chooses the following signature, shown in the methodsview('System.String') window:

Static System.String RetVal Concat(System.String[] values)

and displays:

ans = 
hello world

Back to Top

Handling Data Returned from a .NET Object

The following table shows how MATLAB converts data from a .NET object into MATLAB variables. These are the values displayed in a method signature.

C# .NET Type	MATLAB Type
System.Int16	int16 scalar
System.UInt16	uint16 scalar
System.Int32	int32 scalar
System.UInt32	uint32 scalar
System.Int64	int64 scalar
System.UInt64	uint64 scalar
System.Single	single scalar
System.Double	double scalar
System.Boolean	logical scalar
System.Byte	uint8 scalar
System.Enum	enum
System.Char	char
System.Decimal	System.Decimal
System.Object	System.Object
System.IntPtr	System.IntPtr
System.UIntPtr	System.UIntPtr
System.String	System.String
System.Array	See Using Arrays with .NET Applications
class name	class name
struct name	struct name

How MATLAB Handles System.String Objects

Use the char function to convert a System.String object to a MATLAB string. For example, type:

str = System.String('create a System.String');
strml = char(str);
whos

MATLAB displays:

  Name       Size            Bytes  Class            

  str        1x1                60  System.String    
  strml      1x22               44  char             

MATLAB displays the string value of System.String objects, instead of the standard object display. For example, type:

a = System.String('test')
b = a.Concat('hello', ' world')

MATLAB displays:

a = 
test
b = 
hello world

The System.String class illustrates how MATLAB handles fields and properties, as described in .NET Fields in the MATLAB Workspace and Calling .NET Properties That Take an Argument. To see reference information about the class, search for the term System.String in the .NET Framework Class Library, as described in To Learn More About the .NET Framework.

Back to Top

Using a .NET Object

Using Arrays with .NET Applications

© 1984-2009- The MathWorks, Inc.    -   Site Help   -   Patents   -   Trademarks   -   Privacy Policy   -   Preventing Piracy   -   RSS