Data Conversion (MATLAB COM Builder)

MATLAB COM Builder

Data Conversion Rules

This section describes the data conversion rules for MATLAB COM Builder components. COM Builder components are dual interface COM objects that support COM Automation compatible data types. When a method is invoked on a COM Builder component, the input parameters are converted to MATLAB internal array format and passed to the compiled MATLAB function. When the function exits, the output parameters are converted from 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. 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.

Table B-1 lists the VARIANT type codes supported by COM Builder components. Table B-2 and Table B-3 list the data conversion rules between COM VARIANTs and MATLAB arrays.

Table B-1: VARIANT Type Codes Supported
VARIANT Type Code
(C/C++)
C/C++ Type
Variant Type Code
(Visual Basic)
Visual Basic Type
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
-
A 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++.

**Table B-1: VARIANT Type Codes Supported**
VARIANT Type Code (C/C++)	C/C++ Type	Variant Type Code (Visual Basic)	Visual Basic Type	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`	`-`	A `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_BYRE`F 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++.

Table B-2: 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.) 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 string 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 strings are not supported as char matrices. To pass an array of strings, use a cell array of 1-by-L char matrices.

sparse
VT_DISPAATCH
VT_DISPATCH
A MATLAB sparse array is converted to an MWSparse object. (See Class MWSparse.) 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 M-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 M-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 VT_I1|VT_ARRAY. A complex multidimensional int8 matrix converts to a VARIANT of type VT_DISPATCH.
Complex arrays are passed to and from compiled M-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 M-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 M-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 M-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 M-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 M-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

Table B-2: **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.) 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 string 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 strings are not supported as `char` matrices. To pass an array of strings, use a cell array of 1-by-L `char` matrices.
`sparse`	`VT_DISPAATCH`	`VT_DISPATCH`	A MATLAB sparse array is converted to an `MWSparse` object. (See Class MWSparse.) 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 M-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 M-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 M-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 M-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 M-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 M-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 M-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 M-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`

Table B-3: COM VARIANT to MATLAB Conversion Rules
VARIANT Type
MATLAB Data Type (scalar or array data)
Comments

VT_EMPTY
N/A
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 string 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. 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 strings. See Data Conversion Flags for more information on type coercion.

VT_INT
int32

VT_UINT
unit32

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 COM Builder types MWStruct, MWComplex, MWSparse, and MWArg. See Utility Library Classes for information on COM Builder types.

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

**Table B-3: COM VARIANT to MATLAB Conversion Rules**
VARIANT Type	MATLAB Data Type (scalar or array data)	Comments
`VT_EMPTY`	N/A	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 string 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. 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 strings. See Data Conversion Flags for more information on type coercion.
`VT_INT`	`int32`
`VT_UINT`	`unit32`
`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 COM Builder types `MWStruct`, `MWComplex`, `MWSparse`, and `MWArg`. See Utility Library Classes for information on COM Builder types.
`<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.

Data Conversion Array Formatting Flags