Class

Variant

Description

A Variant is a special data type that can contain any type of data, including arrays. Use the VarType function or the Variant's Type method to determine the data type of a Variant.

When performing extensive numeric work, using Integer or Double may be preferable both for performance and to avoid conversion behavior which may or may not be desirable.

Methods

Name

Parameters

Returns

Shared

ArrayElementType

Integer

Equals

v As Variant

Boolean

Operator_Add

v As Variant

Variant

Operator_AddRight

v As Variant

Variant

Operator_And

v As Variant

Variant

Operator_AndRight

v As Variant

Variant

Operator_Compare

v As Variant

Integer

Operator_Divide

v As Variant

Variant

Operator_DivideRight

v As Variant

Variant

Operator_IntegerDivide

v As Variant

Variant

Operator_IntegerDivideRight

v As Variant

Variant

Operator_Modulo

v As Variant

Variant

Operator_ModuloRight

v As Variant

Variant

Operator_Multiply

v As Variant

Variant

Operator_MultiplyRight

v As Variant

Variant

Operator_Negate

Variant

Operator_Not

Variant

Operator_Or

v As Variant

Variant

Operator_OrRight

v As Variant

Variant

Operator_Power

v As Variant

Variant

Operator_PowerRight

v As Variant

Variant

Operator_Subtract

v As Variant

Variant

Operator_SubtractRight

v As Variant

Variant

Operator_XOr

v As Variant

Variant

Operator_XOrRight

v As Variant

Variant

Type

Integer

Constants

The following class constants can be used to determine the data type of the Variant using the Type method. If the variant is an array, use the ArrayElementType function to test for the type of array and compare the result to the class constants for scalars.

Class Constant

Integer Value

Description

TypeArray

4096

Array

TypeBoolean

11

Boolean

TypeCFStringRef

21

CFStringRef

TypeColor

16

Color

TypeCString

18

CString

TypeCurrency

6

Currency

TypeDateTime

38

DateTime

TypeDelegate

39

Integer

TypeDouble

5

Double

TypeInt32

2

Int32 or UInt32, 32 bit integer.

TypeInt64

3

Int64 or UInt64. 64 bit integer.

TypeNil

0

Nil

TypeObject

9

Object

TypeOSType

23

OSType

TypePString

20

PString

TypePtr

26

Ptr

TypeSingle

4

Single

TypeString

8

String

TypeStructure

36

Structure

TypeWString

19

WString

If a Variant stores an array, the Type method will equal Variant.TypeArray logically OR'ed with the array element type. You can get the element type by calling ArrayElementType.

Property descriptions

Variant.BooleanValue

BooleanValue As Boolean

Returns the value of the Variant as a Boolean.

This property is read-only.

Variant.CFStringRefValue

CFStringRefValue As CFStringRef

Returns the value of the Variant as a CFStringRef.

This property is read-only.

Variant.ColorValue

ColorValue As Color

Returns the value of the Variant as a Color.

This property is read-only.

Variant.CStringValue

CStringValue As CString

Returns the value of the Variant as a CString.

This property is read-only.

Variant.CurrencyValue

CurrencyValue As Currency

Returns the value of the Variant as a Currency.

This property is read-only.

Variant.DateTimeValue

DateTimeValue As DateTime

Returns the value of the Variant as a DateTime.

This property is read-only.

Variant.DoubleValue

DoubleValue As Double

Returns the value of the Variant as a Double.

This property is read-only.

Variant.Hash

Hash As Integer

Returns a hash value for the Variant, i.e., one that will always be the same for any Variant with the same value.

For objects, it is guaranteed to be unique among all objects currently in existence (though once an object dies, a future object may use the same hash value).

For strings, Hash is case-insensitive.

This property is read-only.

Variant.IsArray

IsArray As Boolean

Returns True if the Variant is an array.

This property is read-only.

Variant.IsNull

IsNull As Boolean

Returns True if the Variant is Nil.

This property is read-only.

Variant.IsNumeric

IsNumeric As Boolean

Returns True if the Variant is a numeric data type or contains a string with a numeric value. For example, if the Variant contains a string describing a number, such as "8", then IsNumeric returns True.

This property is read-only.

Variant.Int32Value

Int32Value As Int32

Returns the value of the Variant as an Int32.

This property is read-only.

Variant.Int64Value

Int64Value As Int64

Returns the value of the Variant as an Int64.

This property is read-only.

Variant.IntegerValue

IntegerValue As Integer

Returns the value of the Variant as an Integer.

This property is read-only.

Variant.ObjectValue

ObjectValue As Object

Returns the value of the Variant as an Object.

This property is read-only.

Variant.OSTypeValue

OSTypeValue As OSType

Returns the value of the Variant as an OSType.

This property is read-only.

Variant.PStringValue

PStringValue As PString

Returns the value of the Variant as a PString.

This property is read-only.

Variant.PtrValue

PtrValue As Ptr

Returns the value of the Variant as a Ptr.

This property is read-only.

Variant.SingleValue

SingleValue As Single

Returns the value of the Variant as a Single.

This property is read-only.

Variant.StringValue

StringValue As String

Returns the value of the Variant as a String.

If the Variant holds a DateTime, it is converted to a SQLDateTime format. See the DateTime class for details on this format.

Floating point types include all decimal places available to the extent precision allows. If you want a different format, consider using DoubleValue or IntegerValue and then using their ToString methods.

This property is read-only.

Variant.UInt32Value

UInt32Value As UInt32

Returns the value of the Variant as an UInt32.

This property is read-only.

Variant.UInt64Value

UInt64Value As UInt64

Returns the value of the Variant as an UInt64.

This property is read-only.

Method descriptions

Variant.ArrayElementType

ArrayElementType As Integer

Returns an integer that indicates the type of the array. The return value can be tested against the Variant class constants or be compared to the integer values given in the VarType description.

Variant.Equals

Equals(v As Variant) As Boolean

Returns True if the Variant has the same value as the Variant passed as a parameter.If the variants are not of the same type a common type is computed & the value is compared for equality.

Variant.Operator_Add

Operator_Add(v As Variant) As Variant

Used to define the addition operator for the Variant. See Operator Add.

Variant.Operator_AddRight

Operator_AddRight(v As Variant) As Variant

Used to define the addition operator for the Variant with the implicit Self on the right. See Operator AddRight.

Variant.Operator_And

Operator_And(v As Variant) As Variant

Used to define the And operator for the Variant. See Operator And.

Variant.Operator_AndRight

Operator_AndRight(v As Variant) As Variant

Used to define the And operator for the Variant with the implicit Self on the right. See Operator AndRight.

Variant.Operator_Compare

Operator_Compare(v As Variant) As Integer

Used to define all the comparison operators for the Variant.

Variant.Operator_Divide

Operator_Divide(v As Variant) As Variant

Used to define the division operator for the Variant. See Operator Divide.

Variant.Operator_DivideRight

Operator_DivideRight(v As Variant) As Variant

Used to define the division operator for the Variant with the implicit Self on the right. See Operator DivideRight.

Variant.Operator_IntegerDivide

Operator_IntegerDivide(v As Variant) As Variant

Used to define the integer division operator for the Variant. See Operator IntegerDivide.

Variant.Operator_IntegerDivideRight

Operator_IntegerDivideRight(v As Variant) As Variant

Used to define the integer division operator for the Variant with the implicit Self on the right. See Operator IntegerDivideRight.

Variant.Operator_Modulo

Operator_Modulo(v As Variant) As Variant

Used to define the Mod operator for the Variant. See Operator Modulo.

Variant.Operator_ModuloRight

Operator_ModuloRight(v As Variant) As Variant

Used to define the Mod operator for the Variant with the implicit Self on the right.

Variant.Operator_Multiply

Operator_Multiply(v As Variant) As Variant

Used to define the multiplication operator for the Variant. See Operator Multiply.

Variant.Operator_MultiplyRight

Operator_MultiplyRight(v As Variant) As Variant

Used to define the multiplication operator for the Variant with the implicit Self on the right. Operator Multiply Right.

Variant.Operator_Negate

Operator_Negate As Variant

Use to define the negation operator for the Variant. See Operator Negate.

Variant.Operator_Not

Operator_Not As Variant

Used to define the Not operator for the Variant. See Operator Not.

Variant.Operator_Or

Operator_Or(v As Variant) As Variant

Used to define the Or operator for the Variant. See Operator Or.

Variant.Operator_OrRight

Operator_OrRight(v As Variant) As Variant

Used to define the Or operator for the Variant with the implicit Self on the right. See Operator OrRight.

Variant.Operator_Power

Operator_Power(v As Variant) As Variant

Used to define the power (^) operator for the Variant. See Operator Power.

Variant.Operator_PowerRight

Operator_PowerRight(v As Variant) As Variant

Used to define the power (^) operator for the Variant with the implicit Self on the right. See Operator PowerRight.

Variant.Operator_Subtract

Operator_Subtract(v As Variant) As Variant

Used to define the subtraction operator for the Variant. See Operator Subtract.

Variant.Operator_SubtractRight

Operator_SubtractRight(v As Variant) As Variant

Used to define the subtraction operator for the Variant with the implicit Self on the right. See Operator SubtractRight.

Variant.Operator_XOr

Operator_XOr(v As Variant) As Variant

Used to define the XOr operator for the Variant. See the definitions of the XOr operator in the XOr description. See Operator XOr

Variant.Operator_XOrRight

Operator_XOrRight(v As Variant) As Variant

Used to define the XOr operator for the Variant with the implicit Self on the right. See the definitions of the XOr operator in the XOr description. See Operator XOrRight.

Variant.Type

Type As Integer

Returns an Integer, indicating the data type of the Variant. The values of each data type are given in the table in the Notes section of the VarType function.

If the Variant is an array, then Type returns TypeArray logically OR'ed with the array element type. You can get the element type by calling ArrayElementType.

An array of Dates will be designated as an array of Objects.

If the Variant is not Nil, it provides the same functionality as the VarType global function. You can use the Variant class constants instead of the integer values to determine the data type. The names are listed as Class Constants on the Variant page.

Notes

Particularities of the variant object

The default value of a Variant is Nil. However, unlike other objects, you can use the above methods with a Nil Variant without raising a NilObjectException.

For example, the following is valid for a Variant but not for any other Object:

Var v As Variant = Nil
Var vType As Integer ' To store the variant type

vType = v.Type ' It does not raise NilObjectException

This peculiarity allows you to use the method IsNull instead of v = Nil. They both give the same result:

Var v As Variant

If v = Nil Then
...
End If

' OR you can write

If v.IsNull Then
...
End If

Variants do not have a specific default value, but will instead get the default value of whatever type they are converted to (see the next section).

Automatic conversion of values

When you assign a Variant to a string, numeric, or DateTime variable, value of the Variant is converted to the variable's data type. For example,

Var v As Variant
Var n As Integer
Var s As String
v = 25
s = v ' s is "25"
v = "25"
n = v ' n is 25

If there is any ambiguity concerning the type conversion of a Variant, you should use one of the properties of the Variant class to force the compiler to convert the Variant to the desired type. In this example, the Product number is supposed to be the string concatenation of the Model number and the Part Number. To do this, use the StringValue property to specifically tell the compiler to do what you want:

Var model, partNumber, product As Variant
model = 100
partNumber = 546
product = model + partNumber ' product=646
product = model.StringValue + partNumber.StringValue ' product="100546"

Or, you could just type the variables as String and do string concatenation directly.

Variants used in an expression convert themselves to the type of the other operand, no matter what kind of data they contain, instead of deferring the type-conversion until runtime. This only affects expressions involving a Variant operand and an operand of some other type, not expressions in which both operands are variants.

Consider the following example:

Var v As Variant = 0.5

The comparison:

If v > 0 Then

returns False since v is being treated as an Integer and will round down to 0.

If you instead use:

If v > 0.0 Then

the comparison returns True.

The comparison:

If v.DoubleValue > 0 Then

also returns True.

Conversion from nil

If you assign a Nil Variant to an intrinsic type, then the value will be the default value for the intrinsic type:

Var v As Variant = Nil
Var b As Boolean = v ' False
Var d As Double = v ' 0.0
Var i As Integer = v  ' 0
Var s As String = v ' ""

Compatibility

All project types on all supported operating systems.

See also

Object parent class; IsNumeric, VarType functions; Dictionary classes;