CASTVARIANT

Purpose:

Explicitly casts the input to a Variant of a specified type for Automation.

Syntax:

CASTVARIANT(val, type, vtype)

val

-

A scalar, series, table or string.

type

-

Optional. An integer specifying the Variant type. If not specified, defaults to the original type of the input. Valid conversions are as follows:

 

Type

Description

VARTYPE

nothing

VT_EMPTY

2 byte integer

VT_I2

4 byte integer

VT_I4

4 byte float

VT_R4

8 byte double

VT_R8

currency

VT_CY

date

VT_DATE

binary string

VT_BSTR

10

error

VT_ERROR

11

boolean

VT_BOOL

12

variant

VT_VARIANT

13

unknown

VT_UNKNOWN

16

char

VT_I1

17

unsigned char

VT_UI1

18

unsigned short

VT_UI2

19

unsigned int

VT_UI4

20

8 byte integer

VT_I8

21

8 byte unsigned

VT_UI8

22

machine int

VT_INT

23

unsigned machine int

VT_UINT

24

void

VT_VOID

28

C-style array

VT_CARRAY

30

null-terminated string

VT_LPSTR

31

wide null-terminated string

VT_LPWSTR

 

vtype

-

Optional. An integer. Specifies the type when converting to a Variant. Only valid if type is 12 (Variant). Defaults to 5 (double). Valid vtypes are the same as above.

Returns:

The input value. The input is marked so that it is converted to the specified type when used with ActiveX Automation.

Example:

xl = createobject("Excel.Application");

xl.workbooks.add();

xl.range("A1").value = "1.11.58";

xl.range("B1").value = castvariant("1.11.58", 7);

xl.visible = 1;

 

Starts Excel and creates a new workbook. The string "1.11.58" is placed in cell A1 and the same string is converted into date form and placed in cell B1. A1 contains a string and B1 contains the time value 1:11:58 AM.

 

a = {1,1.5,2,2.5,3};

xl.range("C1:C5").value = castvariant(a, 2);

 

The cells C1 through C5 contain the values 1, 1, 2, 2, 3 since the series in variable a was converted to an array of 2 byte integers.

Remarks:

CASTVARIANT is helpful with ActiveX Automation when an object of an explicit type is to be transferred. The data is converted only when transferred.

 

Normally, a series is transferred as an array of doubles. As shown in the second example, CASTVARIANT can convert the series to an array of almost any type supported by Automation.

 

Use CASTVARIANTARRAY to convert a series to an array of variants.

 

See GETVARIANTDATA to return a series as a variant of a specific type or as an array of variants.

 

Use vtype to specify the type when converting to a variant. For example:

 

b = 100;

castvariant(b, 2);

 

converts b to a 2 byte integer, but

 

castvariant(b, 12, 2);

 

converts b to a variant that contains a 2 byte integer.

See Also:

CREATEOBJECT

CASTVARIANTARRAY

GETDATA

GETVARIANTDATA

PUTDATA