From Xojo Documentation

You are currently browsing the old Xojo documentation site. Please visit the new Xojo documentation site!

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.

BooleanValue DoubleValue PStringValue
CFStringRefValue Int32Value PtrValue
CStringValue Int64Value SingleValue
ColorValue IntegerValue StringValue
CurrencyValue OSTypeValue UInt32Value
DateTimeValue ObjectValue UInt64Value
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 4096 Array
TypeBoolean 11 Boolean
TypeCFStringRef 21 CFStringRef
TypeColor 16 Color
TypeCString 18 CString
TypeCurrency 6 Currency
TypeDate 7 Date
TypeDateTime 38 DateTime
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
TypeText 37 Text
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.


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 date 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 // ""


All project types on all supported operating systems.

See Also

IsNumeric, VarType functions; Dictionary classes;