Variant

From Xojo Documentation

Class (inherits from Object)

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.

Properties
BooleanValue Int32Value SingleValue
CFStringRefValue Int64Value StringValue
CStringValue IntegerValue UInt32Value
ColorValue OSTypeValue UInt64Value
CurrencyValue ObjectValue WStringValue
DateValue PStringValue WindowPtrValue
DoubleValue PtrValue
Methods
ArrayElementType Operator_Compare Operator_Not
Equals Operator_Divide Operator_Or
Hash Operator_DivideRight Operator_OrRight
IsArray Operator_IntegerDivide Operator_Power
IsNull Operator_IntegerDivideRight Operator_PowerRight
IsNumeric Operator_Modulo Operator_Subtract
Operator_Add Operator_ModuloRight Operator_SubtractRight
Operator_AddRight Operator_Multiply Operator_XOr
Operator_And Operator_MultiplyRight Operator_XOrRight
Operator_AndRight Operator_Negate Type

Class 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
Introduced 2008r1
4096 Array
TypeBoolean 11 Boolean
TypeCFStringRef 21 CFStringRef
TypeColor 16 Color
TypeCString 18 CString
TypeCurrency 6 Currency
TypeDate 7 Date
TypeDouble 5 Double
TypeInt32 2 Int32 This is an Integer for 32-bit apps. This is the replacement for TypeInteger.
TypeInt64 3 Int64 or UInt64. This is Integer for 64-bit apps. This is the replacement for TypeLong.
TypeNil 0 Nil
TypeObject 9 Object
TypeOSType 23 OSType
TypePString 20 PString
TypePtr 26 Ptr
TypeSingle 4 Single
TypeString 8 String
TypeStructure
Introduced 2008r1
36 Structure
TypeText 37 Text
TypeWindowPtr 22 WindowPtr
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.

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:

Dim v As Variant = Nil
Dim 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:

Dim 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 date variable, value of the variant is converted to the variable's data type. For example,

Dim v As Variant
Dim n As Integer
Dim 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:

Dim 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:

Dim 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:

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

See Also

IsNumeric, VarType functions; Dictionary classes;