VARIANT$/VARIANT$$ function

Purpose | Returns the byte string contained in a Variant variable.
Syntax | AnsiVar = VARIANT$(VrntVar) WideVar = VARIANT$$(VrntVar) TypeVar = VARIANT$(BYTE, VrntVar)

Remarks

VARIANT$ extracts a string from a variant variable if a dynamic string (VT_BSTR) is found there. If the variant contains any other VT type, an empty string is returned. By definition, a BSTR is a wide Unicode string. It is generally safe to assume this is the case, unless the variant was created by PowerBASIC and you know the internal format is bytes rather than wide Unicode words.

The first form of VARIANT$ converts the wide Unicode contents to ANSI, returning it as an ANSI string. The second form of VARIANT$$ returns the contents directly as a wide Unicode string. Of course, in all assignment and parameter situations, PowerBASIC will automatically handle any conversions needed between ANSI and WIDE string values. For that reason, no additional code should be added to this operation for ANSI/WIDE conversion. Also, keep in mind that the correct choice of function can improve the performance of your program.

BYTE

If the BYTE option is specified, you are telling PowerBASIC that the string contains a set of BYTES rather than wide Unicode words. This would be the case if you stored a User-Defined Type in a variant:

LET VariantVar = ThisUDTVar AS STRING

ThatUDTVar = VARIANT$(BYTE, VariantVar)

This form of VARIANT$ always returns the contents as an ANSI byte string. This result can be assigned to an ANSI string variable or a User-Defined Type.

Legacy | Older legacy programs were forced to store Unicode characters in an ANSI string variable because wide string variables were not yet available. These programs should continue to use VARIANT$ with ACODE$ and variant assignment with UCODE$ until the program logic is updated to use wide Unicode variables.
See also | DIM, LET, OBJECT, LET (with Variants), VARIANT#, VARIANTVT
Example | DIM vVnt AS VARIANT vVnt = "Hello World"$$ a$ = VARIANT$(vVnt)