Variant type (COM)

Variant is a data type in certain programming languages, particularly Visual Basic, OCaml, Delphi and C++ when using the Component Object Model. It is an implementation of the eponymous concept in computer science.

In Visual Basic (and Visual Basic for Applications) the Variant data type is a tagged union that can be used to represent any other data type (for example, integer, floating-point, single- and double-precision, object, etc.) except fixed-length string type. In Visual Basic, any variable not declared explicitly or the type of which is not declared explicitly, is taken to be a variant.

While the use of not explicitly declared variants is not recommended, they can be of use when the needed data type can only be known at runtime, when the data type is expected to vary, or when optional parameters and parameter arrays are desired. In fact, languages with a dynamic type system often have variant as the only available type for variables.

Among the major changes in Visual Basic .NET, being a .NET language, the variant type was replaced with the .NET object type. There are similarities in concept, but also major differences, and no direct conversions exist between these two types. For conversions, as might be needed if Visual Basic .NET code is interacting with a Visual Basic 6 COM object, the normal methodology is to use .NET marshalling.

Examples

In Visual Basic, a variant named A can be declared either explicitly or implicitly:

Dim A
Dim A as Variant

In Delphi, a variant named A is declared in the following way:

var A: variant;

Format

A variable of variant type, for brevity called a "variant", as defined in Visual Basic, needs 16 bytes storage and its layout is as follows:

Offset	Size	Description
0	2	The value returned by VarType; specifies what kind of data the variant contains.
2	6	Reserved bytes; used only for VT_DECIMAL type.
8	up to 8	The data the variant contains.

Types

A few examples of variants that one can encounter in Visual Basic follow. In other languages other kinds of variants can be used as well.

VarType	Hex	Propvariant Type	Propvariant Member	TypeName	Data bytes	C and C++ type
0	0x00	VT_EMPTY	None	Empty1
1	0x01	VT_NULL	None	Null2
2	0x02	VT_I2	iVal	Integer	2A00	SHORT
3	0x03	VT_I4	lVal	Long	2A000000	LONG
4	0x04	VT_R4	fltVal	Single	00002842	FLOAT
5	0x05	VT_R8	dblVal	Double	0000000000004540	DOUBLE
6	0x06	VT_CY	cyVal	Currency	A068060000000000	CY structure
7	0x07	VT_DATE	date	Date	00000000C0D5E140	DATE (double)
8	0x08	VT_BSTR	bstrVal	String	xxxxxxxx	(BSTR):(OLECHAR *):(WCHAR *):(wchar_t *)
9	0x09	VT_DISPATCH	pdispVal
10	0x0a	VT_ERROR	scode	Error	2A000A80	HRESULT (long int)
11	0x0b	VT_BOOL	boolVal	Boolean	FFFF	VARIANT_BOOL (short)
12	0x0c	VT_VARIANT	pvarVal	Variant		VARIANT
13	0x0d	VT_UNKNOWN	punkVal	Nothing4	00000000	IUnknown *
14	0x0e	VT_DECIMAL	decVal			DECIMAL
16	0x10	VT_I1	cVal	Byte		CHAR
17	0x11	VT_UI1	bVal	Byte	2A	BYTE (unsigned char)
18	0x12	VT_UI2	uiVal			WORD (unsigned short)
19	0x13	VT_UI4	ulVal			DWORD (unsigned int)
20	0x14	VT_I8	hVal
21	0x15	VT_UI8	uhVal
22	0x16	VT_INT	intVal
23	0x17	VT_UINT	uintVal
24	0x18	VT_VOID
25	0x19	VT_HRESULT		Missing3	80020004	HRESULT (long int)
26	0x1a	VT_PTR
27	0x1b	VT_SAFEARRAY	parray
28	0x1c	VT_CARRAY
29	0x1d	VT_USERDEFINED
30	0x1e	VT_LPSTR	pszVal
31	0x1f	VT_LPWSTR	pwszVal
36	0x24	VT_RECORD
37	0x25	VT_INT_PTR	pintVal
38	0x26	VT_UINT_PTR	puintVal
8192	0x2000	VT_ARRAY	parray
9				Object reference5	xxxxxxxx	IUnknown *

• ¹ The type of an uninitialized variant.
• ² The type of a NULL value in a database, that is, not uninitialized, nor equivalent to a C++ null pointer.
• ³ Missing arguments are actually a particular Error value titled "parameter not found".
• ⁴ The object type set to a null reference.
• ⁵ TypeName will return the name of the class of the object contained. The data would be an interface pointer, that is, a pointer to a pointer to a virtual method table (which is an array of function pointers).

Common uses

Collections

The Collection class in OLE Automation can store items of different data types. Since the data type of these items cannot be known at compile time, the methods to add items to and retrieve items from a collection use variants. If in Visual Basic the For Each construct is used, the iterator variable must be of object type, or a variant.

Dispatch method calls

In OLE Automation the IDispatch interface is used when the class of an object cannot be known in advance. Hence when calling a method on such an object the types of the arguments and the return value is not known at compile time. The arguments are passed as an array of variants and when the call completes a variant is returned.

Optional parameters

In Visual Basic a procedure argument can be declared to be optional by prefixing it with the Optional keyword. When the argument is omitted Visual Basic passes a special value to the procedure, called Missing in the table above, indicating that the argument is missing. Since the value could either be a supplied value or a special value, a variant must be used.

Function GetText(Optional ByVal Index) As String
    If IsMissing(Index) Then
        GetText = Item(CurrentItem)
    Else
        GetText = Item(Index)
    End If
End Function

Similarly the keyword ParamArray can be used to pass all following arguments in a variant array.

See also

• Tagged union
• Union type

External links

• C++ Boost.Variant
• https://msdn.microsoft.com/en-ca/library/cc237865.aspx
• https://msdn.microsoft.com/en-us/library/windows/desktop/aa380072(v=vs.85).aspx