Syntax

Variant

Description

A data type used to declare variables that can hold one of many different types of data.

Comments

During a variant's existence, the type of data contained within it can change. Variants can contain any of the following types of data:

Type of Data

Basic Control Engine Data Types

Numeric

Integer, Long, Single, Double, Boolean, Date, Currency

Logical

Boolean

Dates and times

Date

String

String

Object

Object

No valid data

A variant with no valid data is considered Null

Uninitialized

An uninitialized variant is considered Empty

There is no type-declaration character for variants.

The number of significant digits representable by a variant depends on the type of data contained within the variant.

Variant is the default data type for the Basic Control Engine. If a variable is not explicitly declared with Dim, Public, or Private, and there is no type-declaration character (i.e., #, @, !, %, or &), then the variable is assumed to be Variant.

Determining the Subtype of a Variant

The following functions are used to query the type of data contained within a variant:

Function

Description

VarType

Returns a number representing the type of data contained within the variant.

IsNumeric

Returns TRUE if a variant contains numeric data. The following are considered numeric:

Integer, Long, Single, Double, Date, Boolean, Currency

If a variant contains a string, this function returns TRUE if the string can be converted to a number.

If a variant contains an Object whose default property is numeric, then IsNumeric returns TRUE.

IsObject

Returns TRUE if a variant contains an object.

IsNull

Returns TRUE if a variant contains no valid data.

IsEmpty

Returns TRUE if a variant is un-initialized.

IsDate

Returns TRUE if a variant contains a date.

If the variant contains a string, then this function returns TRUE if the string can be converted to a date.

If the variant contains an Object, then this function returns TRUE if the default property of that object can be converted to a date.

Assigning to Variants

Before a Variant has been assigned a value, it is considered empty. Thus, immediately after declaration, the VarType function will return ebEmpty. An uninitialized variant is 0 when used in numeric expressions and is a zero-length string when used within string expressions.

A Variant is Empty only after declaration and before assigning it a value. The only way for a Variant to become Empty after having received a value is for that variant to be assigned to another Variant containing Empty, for it to be assigned explicitly to the constant Empty, or for it to be erased using the Erase statement.

When a variant is assigned a value, it is also assigned that value's type. Thus, in all subsequent operations involving that variant, the variant will behave like the type of data it contains.

Operations on Variants

Normally, a Variant behaves just like the data it contains. One exception to this rule is that, in arithmetic operations, variants are automatically promoted when an overflow occurs. Consider the following statements:

  Dim a As Integer,b As Integer,c As Integer

  Dim x As Variant,y As Variant,z As Variant

  a% = 32767
  b% = 1
  c% = a% + b%      'This will overflow.

  x = 32767
  y = 1
  z = x + y         'z becomes a Long because of Integer overflow.

In the above example, the addition involving Integer variables overflows because the result (32768) overflows the legal range for integers. With Variant variables, on the other hand, the addition operator recognizes the overflow and automatically promotes the result to a Long.

Adding Variants

The + operator is defined as performing two functions: when passed strings, it concatenates them; when passed numbers, it adds the numbers.

With variants, the rules are complicated because the types of the variants are not known until execution time. If you use +, you may unintentionally perform the wrong operation.

It is recommended that you use the & operator if you intend to concatenate two String variants. This guarantees that string concatenation will be performed and not addition.

Variants That Contain No Data

A Variant can be set to a special value indicating that it contains no valid data by assigning the Variant to Null:

  Dim a As Variant

  a = Null

The only way that a Variant becomes Null is if you assign it as shown above.

The Null value can be useful for catching errors since its value propagates through an expression.

Variant Storage

Variants require 16 bytes of storage internally:

A 2-byte type

A 2-byte extended type for data objects

Bytes of padding for alignment

An 8-byte value

Unlike other data types, writing variants to Binary or Random files does not write 16 bytes. With variants, a 2-byte type is written, followed by the data (2 bytes for Integer and so on).

Disadvantages of Variants

The following list describes some disadvantages of variants:

1. Using variants is slower than using the other fundamental data types (that is, Integer, Long, Single, Double, Date, Object, String, Currency, and Boolean). Each operation involving a Variant requires examination of the variant's type.

2. Variants require more storage than other data types (16 bytes as opposed to 8 bytes for a Double, 2 bytes for an Integer, and so on).

3. Unpredictable behavior. You may write code to expect an Integer variant. At runtime, the variant may be automatically promoted to a Long variant, causing your code to break.

Passing Nonvariant Data to Routines Taking Variants

Passing nonvariant data to a routine that is declared to receive a variant by reference prevents that variant from changing type within that routine. For example:

  Sub Foo(v As Variant)

    v = 50             'OK.
    v = "Hello, world."      'Get a type-mismatch error here!
  End Sub

  Sub Main()
    Dim i As Integer
    Foo i              'Pass an integer by reference.
  End Sub

In the above example, since an Integer is passed by reference (meaning that the caller can change the original value of the Integer), the caller must ensure that no attempt is made to change the variant's type.

Passing Variants to Routines Taking Nonvariants

Variant variables cannot be passed to routines that accept nonvariant data by reference, as demonstrated in the following example:

  Sub Foo(i As Integer)

  End Sub

  Sub Main()
    Dim a As Variant
    Foo a     'Compiler gives type-mismatch error here.
  End Sub

See also

Currency (data type); Date (data type); Double (data type); Integer (data type); Long (data type); Object (data type); Single (data type); String (data type); Boolean (data type); DefType (statement); CVar (function); Empty (constant); Null (constant); VarType (function).

V