A Variant can serve as the universal data type. This means that you can store data of any type in a variable of type Variant. A Variant is also a data item used to communicate with COM/ActiveX objects.
The Variant data type is based on a structure that contains an indicator of the type of data in addition to the actual data or a pointer to the data in the case of large data items. The variant structure itself is 16 bytes. The following table shows the variant types (enumAVarType) that can be created by ATEasy statements:
|
Name |
Value |
ATEasy equivalent |
|
vtEmpty |
0 |
Un-initialized Variant variable |
|
vtNull |
1 |
SQL-style Null |
|
vtI2 |
2 |
Short |
|
vtI4 |
3 |
Long |
|
vtR4 |
4 |
Float |
|
vtR8 |
5 |
Double |
|
vtCy |
6 |
Currency |
|
vtDate |
7 |
DateTime |
|
vtBStr |
8 |
BString |
|
vtDispatch |
9 |
Object |
|
vtError |
10 |
Error Code |
|
vtBool |
11 |
Bool |
|
vtVariant |
12 |
Variant |
|
vtUnknown |
13 |
Object of known type, for example, ACheckBox |
|
vtDecimal |
14 |
Decimal |
|
vtUI1 |
17 |
Byte |
|
vtI8 (ATEasy 5.0) |
20 |
DLong |
|
vtUI8 (ATEasy 5.0) |
21 |
DDWord |
|
vtArray |
8192 |
Array. This can be combine with basic types (vtArray or vtI2 for array of short). |
|
vtByRef |
16384 |
Pointer. This can be combine with basic types (vtByRef or vtI2 for pointer to short). |
|
vtTypeMask |
4095 |
Mask the basic types from array and byref types. |
If an ATEasy variable of a data type not listed above is assigned to a Variant variable, it is converted to the closest matching type as shown in the following table:
|
Name |
ATEasy data type to be converted |
|
vtI2 |
Word, WChar |
|
vtI4 |
DWord, Enum |
|
vtBStr |
String |
|
vtUI1 |
Char |
If you assign one Variant to another, the resultant Variant will contain the value of the first Variant, but not the Variant itself, for example,
vrA = nA ! nA is Short
vrB = vrA
Then vrB contains the value of nA, not the Variant vrA.
If you assign a String to a Variant, ATEasy will first convert the value of the String variable to a BString and then store that value into the Variant.
The default value for a Variant is Empty.
Variants offer great flexibility, but at the expense of inefficiency, and can cause some problems when assigning unexpected values.
You will get an error if you attempt to perform a mathematical operation or function on a Variant that does not contain a number or something that can be interpreted as a number (for example, 2.4E13 is a valid number). When a Variant tries to convert a non-numeric (such as a String containing a number) to a numeric value, it uses the Regional settings from the Windows Control Panel to interpret the decimal separator, thousands separator, and currency symbol.
Using operators on Variants containing strings can lead to some problems. For instance, if two Variants (each containing a numeric value) are separated by the "+" operator, a simple addition occurs. If the two Variants contained strings, however, a concatenation would occur. But if one of them is a numeric and the other is a string, the Variant will try to convert the string to an number and try to add them. If the conversion is unsuccessful, you will get a "Type mismatch" error. If you wanted concatenation, you would need to first convert the numeric to a string.
Variants can be used as a way of handling a variety of data types. For instance, since all the elements in an array must be of the same data type, you can set the data type of an array to Variant and then store objects alongside other data types in that array.
Variant that contains arrays (vtArray) are stored in memory in different order than ATEasy or C based arrays. For example 2 rows 3 columns is stored: [0, 0], [1, 0], [0, 1], [1, 1], [0, 2], [1, 2]. In ATEasy it will be store: [0, 0], [0, 1], [0, 2], [1, 0], [1, 1], [1, 2]. Assigning ATEasy array to a variant or vise versa will convert the order of element in memory correctly.
If you assign an array to a Variant, ATEasy stores the entire array into the Variant, which can then be treated like an array, with sub-scripting, similar to an ATEasy array.
If an ATEasy struct variable is assigned to a variant variable, the variant be contain an array of variants where each of the data field of the structure will be converted to a single variant. ATEasy variables of type Procedure cannot be assigned to a variant -- the parser will flag this as an error.
For example:
structFields: Struct
{
lField1: Long
sField2: String
adField3: Double[3]
}
stFields: structFields
vr: Variant
stFields={1, "abc", {1.0, 2.0, 3.0}}
vr=stFields
vr[0]=2 ! replace 1 with 2
stFields=vr
print stFields.lField1 ! print 2
ATEasy offers several internal functions to manipulate variants:
VarChangeType - Changes and convert the Variant internal data type from one type to another
VarDimCount - Returns the number of dimension for a Variant
VarDimSize - Return or Sets the dimension size
VarErrorSCode - Returns the error number stored in a Variant (Variant with vtError)
VarType - returns the Variant current internal data type
enumAVarType - Enumerated type for all the Variant data types
Basic Data Types, Data Conversion, Numeric, Strings, User Defined Date Types