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 System.Nullable Type

• 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 System.Nullable Type

To pass a System.Nullable<ValueType> object to .NET , simply 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.

See Examples Passing System.Nullable to .NET.

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 pseudo-code:

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 pseudo-code:

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

• .NET Type to MATLAB Type Mapping

• How MATLAB Handles System.String Objects

• How MATLAB Handles System.__ComObject Type

• How MATLAB Handles System.Nullable Type

.NET Type to MATLAB Type Mapping

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.Nullable<ValueType>	System.Nullable<ValueType>
System.Array	See Using Arrays with .NET Applications
System.__ComObject	See How MATLAB Handles System.__ComObject Type
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.

How MATLAB Handles System.__ComObject Type

The System.__ComObject type represents a Microsoft COM object. It is a non-visible, public class in the mscorlib assembly with no public methods. Under certain circumstances, a .NET object returns an instance of System.__ComObject. MATLAB handles the System.__ComObject based on the return types defined in the metadata.

MATLAB Converts Object.  If the return type of a method or property is strongly typed, and the result of the invocation is System.__ComObject, MATLAB automatically converts the returned object to the appropriate type.

For example, suppose your assembly defines a type, TestType, and provides a method, GetTestType, with the following signature:

NetDocTest.TestType RetVal GetTestType(NetDocTest.MyClass this)

The return type of GetTestType is strongly typed and the .NET Framework returns an object of type System.__ComObject. MATLAB automatically converts the object to the appropriate type, NetDocTest.TestType, shown in the following pseudo-code:

obj = NetDocTest.MyClass;
var = obj.GetTestType

MATLAB displays:

var = 

  NetDocTest.TestType handle with no properties.
  Package: NetDocTest

  Methods, Events, Superclasses

Casting Object to Appropriate Type.  If the return type of a method or property is System.Object, and the result of the invocation is System.__ComObject, MATLAB returns System.__ComObject. To use the returned object, you must cast it to a valid class or interface type. Use your product documentation to identify the valid types for this object.

To call a member of the new type, cast the object using the MATLAB conversion syntax:

objConverted = namespace.classname(obj)

where obj is a System.__ComObject type.

For example, an item in a Microsoft^® Excel^® sheet collection can be a chart or a worksheet. The following command converts the System.__ComObject variable mySheet to a Chart or a Worksheet object newSheet:

newSheet = Microsoft.Office.Interop.Excel.interfacename(mySheet);

where interfacename is Chart or Worksheet. For an example, see Accessing Microsoft Office 2007 Applications with .NET.

Passing a COM Object Between Processes.  If you pass a COM object to or from a function, you must lock the object so that MATLAB does not automatically release it when the object goes out of scope. To lock the object, call the NET.disableAutoRelease function. You must then unlock the object, using the NET.enableAutoRelease function, after you are through using it.

How MATLAB Handles System.Nullable Type

If .NET returns a System.Nullable type, MATLAB returns the corresponding System.Nullable type. To use a System.Nullable object in MATLAB:

• Determine how to handle null values.

• Choose a method to detect null values. You can either check the object's HasValue property, or use the object's GetValueOrDefault method.

• Use a variable of the object's underlying type where appropriate in any MATLAB expression.

A System.Nullable type lets you assign null values to types that do not support null value. For example, a logical type can have either a true or false value. Suppose you have a survey with true or false questions, and you want to know if users answered the question. You can check this condition by using a System.Nullable<logical> type and setting the default answer to null.

Examples:

• Example C# Class for Using System.Nullable in MATLAB

• Examples Passing System.Nullable to .NET

• Examples Displaying System.Nullable Object

• Reading System.Nullable Values Using GetValueOrDefault

• Reading System.Nullable Values Using HasValue

Example C# Class for Using System.Nullable in MATLAB.  The following C# code defines MyClass, which you can build and use to run the following example. For information, see Building a .NET Application for MATLAB Examples.

using System;
using System.Collections.Generic;
using System.Text;

namespace NetDocNullable
{
    public class MyClass
    {
        private Nullable<double> myField = null;

        public Nullable<double> GetField()
        {
            return myField;
        }
        public Nullable<double> SetField(Nullable<double> db)
        {
            myField = db;
            return myField;
        }
    }
}

MyClass provides access to a variable myField of type Nullable<double>. The value of myField can be a double or the null value. Use the GetField and SetField methods to access myField. The following table shows the types for the input and output arguments.

MyClass Method	Input Type	Output Type
GetField	N/A	System.Nullable <System*Double>
SetField	System.Nullable <System*Double>	System.Nullable <System*Double>

If you built the NetDocNullable assembly and it is in your c:\work folder, load the file and create a MyClass object with the commands:

NET.addAssembly('c:\work\NetDocNullable.dll');
obj = NetDocNullable.MyClass;

Examples Passing System.Nullable to .NET.  To see how to pass a System.Nullable type to .NET, look at the SetField method in the MyClass Method table. The input type is System.Nullable<System*Double>. In MATLAB, you can pass the following types to SetField:

• System.Nullable<System*Double>

• double

• null value []

For example, to pass a System.Nullable<System*Double>, use the GetField method, which returns this type. The following commands use the return object netData in the SetField method:

netData = obj.GetField;
res = obj.SetField(netData);

For example, to pass a double, type:

res = obj.SetField(-99);

To pass a null value, type:

res = obj.SetField([]);

Examples Displaying System.Nullable Object.  In the example:

netData = obj.SetField(-99)

the return value, netData, contains the following information:

netData = 
  System.Nullable<System*Double>
  Package: System

  Properties:
    HasValue: 1
       Value: -99

The netData.HasValue property is true (1) and the Value property is -99.

The following example sets netData to null:

netData = obj.SetField([])

MATLAB displays:

netData = 
  System.Nullable<System*Double>
  Package: System

  Properties:
    HasValue: 0

 Methods, Superclasses

The netData HasValue property is false (0), and it has no Value property.

Reading System.Nullable Values Using GetValueOrDefault.  To use a System.Nullable object in MATLAB, you need to decide how to handle null values. If you want every value to be of the underlying <ValueType>, use the GetValueOrDefault method.

To display the method signature for GetValueOrDefault, look at the methods in the System.Nullable<System*Double> class:

netData = obj.SetField(-99);
methods(netData,'-full')

The GetValueOrDefault methods always returns a double value:

double scalar RetVal 
   GetValueOrDefault(System.Nullable<System*Double> this)

To use netData in MATLAB, create a variable, myData. In this example, its value is -99:

myData = netData.GetValueOrDefault;

If netData is set to null, GetValueOrDefault returns a default double value. For example:

netData = obj.SetField([]);
myData = netData.GetValueOrDefault

myData is a double and its value is 0.

The GetValueOrDefault method lets you define the default value. For example, if you want the default value to be -1, type:

myData = netData.GetValueOrDefault(-1)

MATLAB displays:

myData =
    -1

Reading System.Nullable Values Using HasValue.  With the GetValueOrDefault method, every return value is of the underlying type. If you want to process null values differently, use the System.Nullable HasValue property.

For example, create a line graph from 0 to the value of netData. If netData contains null, display the message No Data. This code creates the figure:

netData = obj.SetField(-99);
if netData.HasValue
  plot([0 netData.Value]);
else
  disp('No Data');
end;

This code displays the message:

netData = obj.SetField([]);
if netData.HasValue
  myData = round(netData.Value)
else
  disp('No Data');
end;

Back to Top

Using a .NET Object

Using Arrays with .NET Applications

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