Variant type

From Wikipedia, the free encyclopedia
Jump to: navigation, search

Variant is a data type in certain programming languages, particularly Visual Basic, OCaml, and C++ when using the Component Object Model.

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 and record types. 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.

In unrelated usage, variant type is also used to refer to an algebraic data type (comparable to a tagged union), whose constructors are often called variants. In languages such as OCaml and Haskell, this kind of variant type is the standard language building block for representing many data structures.

Examples[edit]

In Visual Basic, a variant named A can be explicitly declared as shown in either of these two examples:

Dim A
Dim A as Variant

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

var A: variant;

Format[edit]

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; should be set to zero.
8 up to 8 The data the variant contains.

Types[edit]

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_R2 fltVal Single 00002842 FLOAT
5 0x05 VT_R4 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 pointer
  • 1 The type of an uninitialized variant.
  • 2 The type of a NULL value in a database, that is, not uninitialized, nor equivalent to a C++ null pointer.
  • 3 Missing arguments are actually a particular Error value titled "parameter not found".
  • 4 The object type set to a null reference.
  • 5 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[edit]

Collections[edit]

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[edit]

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[edit]

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.

External links[edit]