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
1	nothing	VT_EMPTY
2	2 byte integer	VT_I2
3	4 byte integer	VT_I4
4	4 byte float	VT_R4
5	8 byte double	VT_R8
6	currency	VT_CY
7	date	VT_DATE
8	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);