Data Conversion Rules

This topic describes the data conversion rules for the MATLAB^® Compiler™ components. These components are dual interface Microsoft^® COM objects that support data types compatible with Automation.

Note

Automation (formerly called OLE Automation) is a technology that allows software packages to expose their unique features to scripting tools and other applications. Automation uses the Component Object Model (COM), but may be implemented independently from other OLE features, such as in-place activation.

When a method is invoked on a MATLAB Compiler component, the input parameters are converted to the MATLAB internal array format and passed to the compiled MATLAB function. When the function exits, the output parameters are converted from the MATLAB internal array format to COM Automation types.

The COM client passes all input and output arguments in the compiled MATLAB functions as type VARIANT. The COM VARIANT type is a union of several simple data types. A type VARIANT variable can store a variable of any of the simple types, as well as arrays of any of these values.

The Win32 application program interface (API) provides many functions for creating and manipulating VARIANTs in C/C++, and Visual Basic^® provides native language support for this type.

Note

This discussion of data refers to both VARIANT and Variant data types. VARIANT is the C++ name and Variant is the corresponding data type in Visual Basic.

See the Visual Studio^® documentation for definitions and API support for COM VARIANTs. VARIANT variables are self describing and store their type code as an internal field of the structure.

The following table lists the VARIANT type codes supported by the MATLAB Compiler components.

VARIANT Type Codes Supported

`VARIANT` Type Code (C/C++)	C/C++ Type	`Variant` Type Code (Visual Basic)	Visual BasicType	Definition
`VT_EMPTY`	`—`	`vbEmpty`	`—`	Uninitialized `VARIANT`
`VT_I1`	`char`	`—`	`—`	Signed one-byte character
`VT_UI1`	unsigned `char`	`vbByte`	`Byte`	Unsigned one-byte character
`VT_I2`	`short`	`vbInteger`	`Integer`	Signed two-byte integer
`VT_UI2`	`unsigned short`	—	—	Unsigned two-byte integer
`VT_I4`	`long`	`vbLong`	`Long`	Signed four-byte integer
`VT_UI4`	`unsigned long`	—	—	Unsigned four-byte integer
`VT_R4`	`float`	`vbSingle`	`Single`	IEEE^® four-byte floating-point value
`VT_R8`	`double`	`vbDouble`	`Double`	IEEE eight-byte floating-point value
`VT_CY`	`CY`⁺	`vbCurrency`	`Currency`	Currency value (64-bit integer, scaled by 10,000)
`VT_BSTR`	`BSTR`⁺	`vbString`	`String`	String value
`VT_ERROR`	`SCODE`⁺	`vbError`	—	An `HRESULT` (signed four-byte integer representing a COM error code)
`VT_DATE`	`DATE`⁺	`vbDate`	`Date`	Eight-byte floating point value representing date and time
`VT_INT`	`int`	—	—	Signed integer; equivalent to type `int`
`VT_UINT`	`unsigned int`	—	—	Unsigned integer; equivalent to type `unsigned int`
`VT_DECIMAL`	`DECIMAL`⁺	`vbDecimal`	—	96-bit (12-byte) unsigned integer, scaled by a variable power of 10
`VT_BOOL`	`VARIANT_BOOL`⁺	`vbBoolean`	`Boolean`	Two-byte Boolean value (0xFFFF = True; 0x0000 = False)
`VT_DISPATCH`	`IDispatch*`	`vbObject`	`Object`	`IDispatch*` pointer to an object
`VT_VARIANT`	`VARIANT`⁺	`vbVariant`	`Variant`	`VARIANT` (can only be specified if combined with `VT_BYREF` or `VT_ARRAY`)
<anything`>\|VT_ARRAY`	—	—	—	Bitwise combine `VT_ARRAY` with any basic type to declare as an array
<anything`>\|VT_BYREF`	—	—	—	Bitwise combine `VT_BYREF` with any basic type to declare as a reference to a value
⁺Denotes Windows-specific type. Not part of standard C/C++.

The following table lists the rules for converting from MATLAB to COM.

MATLAB to COM VARIANT Conversion Rules

MATLAB Data Type	`VARIANT` Type for Scalar Data	`VARIANT` Type for Array Data	Comments
`cell`	A 1-by-1 cell array converts to a single `VARIANT` with a type conforming to the conversion rule for the MATLAB data type of the cell contents.	A multidimensional cell array converts to a `VARIANT` of type `VT_VARIANT\|VT_ARRAY` with the type of each array member conforming to the conversion rule for the MATLAB data type of the corresponding cell.
`structure`	`VT_DISPATCH`	`VT_DISPATCH`	A MATLAB `struct` array is converted to an `MWStruct` object. (See Class MWStruct (MATLAB Compiler SDK)) This object is passed as a `VT_DISPATCH` type.
`char`	A 1-by-1 `char` matrix converts to a `VARIANT` of type `VT_BSTR` with string length = 1.	A 1-by-L `char` matrix is assumed to represent a character vector of length L in MATLAB. This case converts to a `VARIANT` of type `VT_BSTR` with a string length = L. `char` matrices of more than one row, or of a higher dimensionality convert to a `VARIANT` of type `VT_BSTR\|VT_ARRAY`. Each string in the converted array is of length 1 and corresponds to each character in the original matrix.	Arrays of character vectors are not supported as `char` matrices. To pass an array of character vectors, use a cell array of 1-by-L `char` matrices.
`sparse`	`VT_DISPATCH`	`VT_DISPATCH`	A MATLAB sparse array is converted to an `MWSparse` object. (See Class MWSparse (MATLAB Compiler SDK)) This object is passed as a `VT_DISPATCH` type.
`double`	A real 1-by-1 double matrix converts to a `VARIANT` of type `VT_R8`. A complex 1-by-1 double matrix converts to a `VARIANT` of type `VT_DISPATCH`.	A real multidimensional double matrix converts to a `VARIANT` of type `VT_R8\|VT_ARRAY`. A complex multidimensional double matrix converts to a `VARIANT` of type `VT_DISPATCH`.	Complex arrays are passed to and from compiled MATLAB functions using the `MWComplex` class. (See Class MWComplex)
`single`	A real 1-by-1 single matrix converts to a `VARIANT` of type `VT_R4`. A complex 1-by-1 single matrix converts to a `VARIANT` of type `VT_DISPATCH`.	A real multidimensional single matrix converts to a `VARIANT` of type `VT_R4\|VT_ARRAY`. A complex multidimensional single matrix converts to a `VARIANT` of type `VT_DISPATCH`.	Complex arrays are passed to and from compiled MATLAB functions using the `MWComplex` class. (See Class MWComplex)
`int8`	A real 1-by-1 `int8` matrix converts to a `VARIANT` of type `VT_I1`. A complex 1-by-1 `int8` matrix converts to a `VARIANT` of type `VT_DISPATCH`.	A real multidimensional `int8` matrix converts to a `VARIANT` of type V`T_I1\|VT_ARRAY`. A complex multidimensional `int8` matrix converts to a `VARIANT` of type `VT_DISPATCH`.	Complex arrays are passed to and from compiled MATLAB functions using the `MWComplex` class. (See Class MWComplex)
`uint8`	A real 1-by-1 `uint8` matrix converts to a `VARIANT` of type `VT_UI1`. A complex 1-by-1 `uint8` matrix converts to a `VARIANT` of type `VT_DISPATCH`.	A real multidimensional `uint8` matrix converts to a `VARIANT` of type `VT_UI1\|VT_ARRAY`.A complex multidimensional `uint8` matrix converts to a `VARIANT` of type `VT_DISPATCH`.	Complex arrays are passed to and from compiled MATLAB functions using the `MWComplex` class. (See Class MWComplex)
`int16`	A real 1-by-1 `int16` matrix converts to a `VARIANT` of type `VT_I2`. A complex 1-by-1 `int16` matrix converts to a `VARIANT` of type `VT_DISPATCH`.	A real multidimensional `int16` matrix converts to a `VARIANT` of type `VT_I2\|VT_ARRAY`. A complex multidimensional `int16` matrix converts to a `VARIANT` of type `VT_DISPATCH`.	Complex arrays are passed to and from compiled MATLAB functions using the `MWComplex` class. (See Class MWComplex)
`uint16`	A real 1-by-1 `uint16` matrix converts to a `VARIANT` of type `VT_UI2`. A complex 1-by-1 `uint16` matrix converts to a `VARIANT` of type `VT_DISPATCH`.	A real multidimensional `uint16` matrix converts to a `VARIANT` of type `VT_UI2\|VT_ARRAY`. A complex multidimensional `uint16` matrix converts to a `VARIANT` of type `VT_DISPATCH`.	Complex arrays are passed to and from compiled MATLAB functions using the `MWComplex` class. (See Class MWComplex)
`int32`	A 1-by-1 `int32` matrix converts to a `VARIANT` of type `VT_I4`. A complex 1-by-1 `int32` matrix converts to a `VARIANT` of type `VT_DISPATCH`.	A multidimensional `int32` matrix converts to a `VARIANT` of type `VT_I4\|VT_ARRAY`. A complex multidimensional `int32` matrix converts to a `VARIANT` of type `VT_DISPATCH`.	Complex arrays are passed to and from compiled MATLAB functions using the `MWComplex` class. (See Class MWComplex)
`uint32`	A 1-by-1 `uint32` matrix converts to a `VARIANT` of type `VT_UI4`. A complex 1-by-1 `uint32` matrix converts to a `VARIANT` of type `VT_DISPATCH`.	A multidimensional `uint32` matrix converts to a `VARIANT` of type `VT_UI4\|VT_ARRAY`. A complex multidimensional `uint32` matrix converts to a `VARIANT` of type `VT_DISPATCH`.	Complex arrays are passed to and from compiled MATLAB functions using the `MWComplex` class. (See Class MWComplex)
Function handle	`VT_EMPTY`	`VT_EMPTY`	Not supported
Java^® class	`VT_EMPTY`	`VT_EMPTY`	Not supported
User class	`VT_EMPTY`	`VT_EMPTY`	Not supported
logical	`VT_Bool`	`VT_Bool\|VT_ARRAY`

The following table lists the rules for conversion from COM to MATLAB.

COM VARIANT to MATLAB Conversion Rules

`VARIANT` Type	MATLAB Data Type (scalar or array data)	Comments
`VT_EMPTY`	Not applicable	Empty array created.
`VT_I1`	`int8`
`VT_UI1`	`uint8`
`VT_I2`	`int16`
`VT_UI2`	`uint16`
`VT_I4`	`int32`
`VT_UI4`	`uint32`
`VT_R4`	`single`
`VT_R8`	`double`
`VT_CY`	`double`
`VT_BSTR`	`char`	A `VARIANT` of type `VT_BSTR` converts to a 1-by-L MATLAB `char` array, where L = the length of the character vector to be converted. A `VARIANT` of type `VT_BSTR\|VT_ARRAY` converts to a MATLAB cell array of 1-by-L `char` arrays.
`VT_ERROR`	`int32`
`VT_DATE`	`double`	1. `VARIANT` dates are stored as doubles starting at midnight Dec. 31, 1899. The MATLAB dates are stored as doubles starting at 0/0/00 00:00:00. Therefore, a `VARIANT` date of 0.0 maps to a MATLAB numeric date of 693960.0. `VARIANT` dates are converted to MATLAB double types and incremented by 693960.0. 2. `VARIANT` dates can be optionally converted to character vectors. See Data Conversion Flags for more information on type coercion.
`VT_INT`	`int32`
`VT_UINT`	`uint32`
`VT_DECIMAL`	`double`
`VT_BOOL`	`logical`
`VT_DISPATCH`	(varies)	`IDispatch*` pointers are treated within the context of what they point to. Objects must be supported types with known data extraction and conversion rules, or expose a generic `Value` property that points to a single `VARIANT` type. Data extracted from an object is converted based upon the rules for the particular `VARIANT` obtained. Currently, support exists for Excel^® `Range` objects as well as the MATLAB Compiler types `MWStruct`, `MWComplex`, `MWSparse`, and `MWArg`.
<anything`>\|VT_BYREF`	(varies)	Pointers to any of the basic types are processed according to the rules for what they point to. The resulting MATLAB array contains a deep copy of the values.
<anything`>\|VT_ARRAY`	(varies)	Multidimensional `VARIANT` arrays convert to multidimensional MATLAB arrays, each element converted according to the rules for the basic types. Multidimensional `VARIANT` arrays of type `VT_VARIANT\|VT_ARRAY` convert to multidimensional cell arrays, each cell converted according to the rules for that specific type.

Was this topic helpful?

Documentation