# DVARIANT Class

The `DVARIANT` class implements a `VARIANT` data type. The variant data type is a tagged union that can be used to represent any other data type. While lacking in efficiency, they are heavily used in COM Automation for its flexibility. The main purpose of the `DVARIANT` class is to make its use as easy as possible when you need to use them to work with COM Automation objects.

Include file: DVARIANT.INC.

Name | Description
--- | ---
Constructors | Initialize the class with the specified value.
Operators | Procedures that perform a certain function with their operands.
vType | Returns the VARIANT type.
Attach | Attaches a variant to the class.
Detach | Detaches the variant data from this class and transfers ownership to the passed variant.
ChangeType | Converts the variant from one type to another.
ChangeTypeEx | Converts the variant from one type to another.
GetDim | Gets the number of dimensions in the array.
GetLBound | Gets the lower bound for the specified dimension of the safe array.
GetUBound | Gets the upper bound for the specified dimension of the safe array.
GetElementCount | Gets the number of elements in the array.
DecToCY | Converts a DVARIANT of type decimal to a CY structure.
DecToDouble | Converts a DVARIANT of type decimal to a double.
Round | Rounds a variant to the specified number of decimal places.
FormatNumber | Formats a DVARIANT containing numbers into a string form.
GetBooleanElement | Extracts a single boolean element from a safe array of booleans.
GetDoubleElement | Extracts a single DOUBLE element from a safe array of doubles.
GetLongElement | Extracts a single LONG element from a safe array of longs.
GetLongIntElement | Extracts a single LONGINT element from a safe array of long integers.
GetShortElement | Extracts a single SHORT element from a safe array of shorts.
GetStringElement | Extracts a single BSTR element from a safe array of unicode strings.
GetULongElement | Extracts a single ULONG element from a safe array of unsigned longs.
GetULongIntElement | Extracts a single ULONGINT element from a safe array of unsigned long integers.
GetUShortElement | Extracts a single USHORT element from a safe array of unsigned shorts.
GetVariantElement | Extracts a single Variant element from a safe array of variants.
Put | Assigns values to a DVARIANT.
PutNull | Assigns a null value.
PutBool | Assigns a boolean value.
PutBoolean | Assigns a boolean value.
PutByte | Assigns a byte value.
PutUByte | Assigns an ubyte value.
PutShort | Assigns a short value.
PutUShort | Assigns an ushort value.
PutInt | Assigns an int_ value.
PutUInt | Assigns an uint value.
PutLong | Assigns a long value.
PutULong | Assigns an ulong value.
PutLongInt | Assigns a longint value.
PutULongInt | Assigns an ulongint value.
PutSingle | Assigns a single value.
PutFloat | Assigns a single value.
PutDouble | Assigns a double value.
PutBooleanArray | Initializes DVARIANT from an array of Boolean values.
PutShortArray | Initializes DVARIANT from an array of signed 16-bit integer values.
PutUShortArray | Initializes DVARIANT from an array of unsigned 16-bit integer values.
PutLongArray | Initializes DVARIANT from an array of signed 32-bit integer values.
PutULongArray | Initializes DVARIANT from an array of 32-bit unsigned integer values.
PutLongIntArray | Initializes DVARIANT from an array of signed 64-bit integer values.
PutULongIntArray | Initializes DVARIANT from an array of unsigned 64-bit integer values.
PutDoubleArray | Initializes DVARIANT from an array of unsigned 64-bit integer values.
PutStringArray | Initializes DVARIANT from an array of unsigned 64-bit integer values.
PutBuffer | Initializes DVARIANT with the contents of a buffer.
PutDateString | Initializes DVARIANT VT_DATE from a string.
PutDec | Initializes DVARIANT with the contents of a DECIMAL structure.
PutDecFromCY | Converts a currency value to a variant of type VT_DECIMAL.
PutDecFromDouble | Converts a double value to a variant of type VT_DECIMAL.
PutDecFromStr | Initializes DVARIANT as VT_DECIMAL from a string.
PutFileTime | Initializes DVARIANT with the contents of a FILETIME structure.
PutFileTimeArray | Initializes DVARIANT with an array of FILETIME structures.
PutGuid | Initializes DVARIANT from a GUID.
PutPropVariant | Initializes DVARIANT from the contents of a PROPVARIANT structure.
PutRecord | Initializes DVARIANT with a reference to an UDT.
PutRef | Assigns a value by reference (a pointer to a variable).
PutResource | Initializes the DVARIANT based on a string resource imbedded in an executable file.
PutSafeArray | Initializes DVARIANT from a safe array.
PutStrRet | Initializes DVARIANT with string stored in a STRRET structure.
PutSystemTime | Initializes DVARIANT with the contents of a SYSTEMTIME structure.
PutUtf8 | Initializes DVARIANT with the contents of an UTF-8 string.
PutVariantArrayElement | Initializes DVARIANT with a value stored in another VARIANT structure.
PutVbDate | Initializes DVARIANT with the contents of a DATE value.
ToBooleanArray | Extracts an array of boolean values from DVARIANT.
ToBooleanArrayAlloc | Extracts an array of boolean values from DVARIANT.
ToBstr | Extracts the content of the underlying variant and returns it as a BSTRING.
ToBuffer | Extracts the contents of a DVARIANT of type VT_ARRRAY OR VT_UI1 to a buffer.
ToBuffer (STRING) | Extracts the contents of a DVARIANT of type VT_ARRRAY OR VT_UI1 to a string used as a buffer.
ToDosDateTime | Extracts a date and time value in Microsoft MS-DOS format from a DVARIANT of type VT_DATE.
ToDoubleArray | Extracts an array of DOUBLE values from DVARIANT.
ToDoubleArrayAlloc | Extracts an array of DOUBLE values from DVARIANT.
ToFileTime | Returns the contents of a DVARIANT of type VT_DATE as a FILETIME structure.
ToGuid | Returns the contents of a DVARIANT containing a GUID string as a GUID structure.
ToGuidBStr | Returns the contents of a DVARIANT containing a GUID string as an unicode GUID string.
ToGuidStr | Returns the contents of a DVARIANT containing a GUID string as an unicode GUID string.
ToGuidWStr | Returns the contents of a DVARIANT containing a GUID string as an unicode GUID string.
ToLongArray | Extracts an array of LONG values from DVARIANT.
ToLongArrayAlloc | Extracts an array of LONG values from DVARIANT.
ToLongIntArray | Extracts an array of LONGINT values from DVARIANT.
ToLongIntArrayAlloc | Extracts an array of LONGINT values from DVARIANT.
ToShortArray | Extracts an array of Int16 values from DVARIANT.
ToShortArrayAlloc | Extracts an array of SHORT values from DVARIANT.
ToStr | Extracts the content of the underlying variant and returns it as a DWSTRING.
ToStringArray | Extracts data from a vector structure into a PWSTR array.
ToStringArrayAlloc | Extracts an array of PWSTR values from DVARIANT.
ToStrRet | Returns the contents of a DVARIANT of type VT_BSTR to a STRRET stucture.
ToSystemTime | Returns the contents of DVARIANT of type VT_DATE as a FILETIME structure.
ToULongArray | Extracts an array of ULONG values from DVARIANT.
ToULongArrayAlloc | Extracts an array of ULONG values from DVARIANT.
ToULongIntArray | Extracts an array of ULONGINT values from DVARIANT.
ToULongIntArrayAlloc | Extracts an array of ULONGINT values from DVARIANT.
ToUShortArray | Extracts an array of USHORT values from DVARIANT.
ToUShortArrayAlloc | Extracts an array of USHORT values from DVARIANT.
ToUtf8 | Returns the contents of a DVARIANT containing a BSTR as an UTF-8 encoded string.
ToVbDate | Returns the contents of a DVARIANT of type VT_DATE as a DATE value.

#### Helper Procedures

Name | Description
--- | ---
AfxDVarToStr | Extracts the contents of a DVARIANT to a DWSTRING.
AfxDVarToBuffer | Extracts the contents of a variant that contains an array of bytes.
AfxDVarToOptPrm | Returns a DVARIANT suitable to be used with optional parameters.

# Constructors

Creates an instance of the DVARIANT class.

    CONSTRUCTOR
    CONSTRUCTOR (BYREF dv AS DVARIANT)
    CONSTRUCTOR (BYVAL v AS VARIANT)
    CONSTRUCTOR (BYVAL pwsz AS WSTRING PTR)
    CONSTRUCTOR (BYREF dws AS DWSTRING)
    CONSTRUCTOR (BYREF bs AS BSTRING)
    CONSTRUCTOR (BYVAL pvar AS VARIANT PTR)
    CONSTRUCTOR (BYVAL cy AS CURRENCY)
    CONSTRUCTOR (BYVAL dec AS DECIMAL)
    DECLARE CONSTRUCTOR (BYVAL _value AS LONG)
    CONSTRUCTOR (BYREF pDisp AS IDispatch PTR, BYVAL fAddRef AS BOOLEAN = FALSE)
    CONSTRUCTOR (BYREF pUnk AS IUnknown PTR, BYVAL fAddRef AS BOOLEAN = FALSE)
    CONSTRUCTOR (BYVAL _value AS LONGINT, BYVAL _vType AS WORD = VT_I4)
    CONSTRUCTOR (BYVAL _value AS DOUBLE, BYVAL _vType AS WORD = VT_R8)
    CONSTRUCTOR (BYVAL _value AS LONGINT, BYREF strType AS STRING)
    CONSTRUCTOR (BYVAL _value AS DOUBLE, BYREF strType AS STRING)
    CONSTRUCTOR (BYVAL _pvar AS ANY PTR, BYVAL _vType AS WORD)
    CONSTRUCTOR (BYVAL _pvar AS ANY PTR, BYREF strType AS STRING)

Parameter | Description
--- | ---
cv | A DVARIANT.
v | A VARIANT.
pvar | Pointer to a VARIANT.
cy | A currency structure.
dec | A decimal structure.
b | A boolean value (TRUE or FALSE).
pwsz | Pointer to an unicode string. You can also pass a Free Basic ansi string or a string literal.
bs | A BSTRING.
dws | A DWSTRING.
pDisp | Pointer to a DISPATCH interface.
pUnk | Pointer to a UNKNOWN interface.
*_value* | A numeric value or variable.
*_pvar* | Pointer to a variable. This will create a VT_BYREF variant of the specified type.
*_vtype* | The variant type, e.g. VT_I4, VT_UI4.
strType | The variant type as a string: “BOOL”, “BYTE”, “UBYTE”, “SHORT”, “USHORT,”INT”, UINT”, “LONG”, “ULONG”, “LONGINT”, “SINGLE,”DOUBLE”, “NULL”.
fAddRef | TRUE or FALSE. If TRUE, increases the reference count of the passed interface.

#### Examples

    DIM dv AS DVARIANT = "Test string"   ' Creates a VT_BSTR (8) variant
    DIM dv AS DVARIANT = 12345           ' Creates a VT_I4 (3) variant
    DIM dv AS DVARIANT = 123456.78       ' Creates a VT_R8 (5) variant

We can use the constructors to pass values to parameters in procedures without assigning them first to a variable, e.g.:

    SUB Foo (BYREF dv AS DVARIANT)
       PRINT dv
    END SUB

    Foo "Test string"
    Foo 12345
    Foo DVARIANT(12345, "LONG")

    SUB Foo (BYVAL dv AS DVARIANT PTR)
       PRINT AfxDVarToStr(dv)
    END SUB
    Foo @DVARIANT("Test string")
    Foo @DVARIANT(12345)
    Foo @DVARIANT(12345, "LONG")```

    SUB Foo (BYVAL v AS VARIANT)
       PRINT AfxVarToStr(v)
    END SUB

    Foo DVARIANT("Test string")
    Foo DVARIANT(12345)
    Foo DVARIANT(12345, "LONG")

    SUB Foo (BYVAL v AS VARIANT PTR)
       PRINT AfxVarToStr(v)
    END SUB
    Foo DVARIANT("Test string")
    Foo DVARIANT(12345)
    Foo DVARIANT(12345, "LONG")

# Operators

Procedures that perform a certain function with their operands. They do the same actions that the native FreeBasic operators but with variants. For detailed descriptions see the FreeBasic documentation.

Global Operators

    OPERATOR & (BYREF dv1 AS DVARIANT, BYREF dv2 AS DVARIANT) AS DVARIANT
    OPERATOR * (BYREF dv AS DVARIANT) AS VARIANT PTR

Cast Operators

    OPERATOR Cast () AS VARIANT
    OPERATOR Cast () AS VARIANT PTR
    OPERATOR CAST () BYREF AS WSTRING

Assignment operators

    OPERATOR Let (BYREF dv AS DVARIANT)
    OPERATOR Let (BYVAL v AS VARIANT)
    OPERATOR Let (BYVAL pvar AS VARIANT PTR)
    OPERATOR LET (BYVAL pwszStr AS WSTRING PTR)
    OPERATOR Let (BYVAL cy AS CURRENCY)
    OPERATOR Let (BYVAL dec AS DECIMAL)
    OPERATOR Let (BYREF bs AS BSTRING)
    OPERATOR Let (BYREF dws AS DWSTRING)
    DECLARE OPERATOR LET (BYVAL _value AS LONG)
    OPERATOR Let (BYREF pDisp AS IDispatch PTR)
    OPERATOR Let (BYREF pUnk AS IUnknown PTR)
    OPERATOR Let (BYVAL _value AS LONGINT)
    OPERATOR Let (BYVAL _value AS DOUBLE)
    OPERATOR += (BYREF dv AS DVARIANT)
    OPERATOR -= (BYREF dv AS DVARIANT)
    OPERATOR *= (BYREF dv AS DVARIANT)
    OPERATOR /= (BYREF dv AS DVARIANT)
    OPERATOR \= (BYREF dv AS DVARIANT)
    OPERATOR Mod= (BYREF dv AS DVARIANT)
    OPERATOR Imp= (BYREF dv AS DVARIANT)
    OPERATOR Eqv= (BYREF dv AS DVARIANT)
    OPERATOR ^= (BYREF dv AS DVARIANT)

Arithmetic operators

    OPERATOR + (BYREF dv1 AS DVARIANT, BYREF dv2 AS DVARIANT) AS DVARIANT
    OPERATOR - (BYREF dv1 AS DVARIANT, BYREF dv2 AS DVARIANT) AS DVARIANT
    OPERATOR * (BYREF dv1 AS DVARIANT, BYREF dv2 AS DVARIANT) AS DVARIANT
    OPERATOR / (BYREF dv1 AS DVARIANT, BYREF dv2 AS DVARIANT) AS DVARIANT
    OPERATOR \ (BYREF dv1 AS DVARIANT, BYREF dv2 AS DVARIANT) AS DVARIANT
    OPERATOR ^ (BYREF dv1 AS DVARIANT, BYREF dv2 AS DVARIANT) AS DOUBLE
    OPERATOR Mod (BYREF dv1 AS DVARIANT, BYREF dv2 AS DVARIANT) AS INTEGER
    OPERATOR - (BYREF dv AS DVARIANT) AS DVARIANT

Relational operators

    OPERATOR = (BYREF dv1 AS DVARIANT, BYREF dv2 AS DVARIANT) AS BOOLEAN
    OPERATOR <> (BYREF dv1 AS DVARIANT, BYREF dv2 AS DVARIANT) AS BOOLEAN
    OPERATOR < (BYREF dv1 AS DVARIANT, BYREF dv2 AS DVARIANT) AS BOOLEAN
    OPERATOR > (BYREF dv1 AS DVARIANT, BYREF dv2 AS DVARIANT) AS BOOLEAN
    OPERATOR <= (BYREF dv1 AS DVARIANT, BYREF dv2 AS DVARIANT) AS BOOLEAN
    OPERATOR >= (BYREF dv1 AS DVARIANT, BYREF dv2 AS DVARIANT) AS BOOLEAN

Bitwise operators

    OPERATOR And (BYREF dv1 AS DVARIANT, BYREF dv2 AS DVARIANT) AS INTEGER
    OPERATOR Eqv (BYREF dv1 AS DVARIANT, BYREF dv2 AS DVARIANT) AS INTEGER
    OPERATOR Imp (BYREF dv1 AS DVARIANT, BYREF dv2 AS DVARIANT) AS INTEGER
    OPERATOR Not (BYREF dv AS DVARIANT) AS INTEGER
    OPERATOR Or (BYREF dv1 AS DVARIANT, BYREF dv2 AS DVARIANT) AS INTEGER
    OPERATOR Xor (BYREF dv1 AS DVARIANT, BYREF dv2 AS DVARIANT) AS INTEGER

    SUB Foo (BYVAL v AS VARIANT)
       PRINT AfxVarToStr(@v)
    END SUB
    DIM dv AS DVARIANT = "Test string"
    Foo dv

Using the pointer syntax:

    SUB Foo (BYVAL v AS VARIANT)
       PRINT AfxVarToStr(@v)
    END SUB
    DIM pdv AS DVARIANT PTR  = NEW DVARIANT("Test string")
    Foo *pdv
    Delete pdv

Using the constructors

    SUB Foo (BYVAL v AS VARIANT)
       PRINT AfxVarToStr(@v)
    END SUB
    Foo DVARIANT(12345, "LONG")

#### Note to the CAST operator

The CAST operators allow to transparently pass the underlying VARIANT to a procedure. They aren’t called directly.

    SUB Foo (BYREF v AS VARIANT)
       PRINT AfxVarToStr(@v)
    END SUB
    Foo DVARIANT(12345, "LONG")

    SUB Foo2 (BYVAL v AS VARIANT)
       PRINT AfxVarToStr(@v)
    END SUB
    Foo2 DVARIANT(12345, "LONG")

    SUB Foo3 (BYREF dv AS DVARIANT)
       PRINT dv
    END SUB
    Foo3 DVARIANT(12345, "LONG")

    SUB Foo4 (BYVAL dv AS DVARIANT PTR)
       PRINT AfxDVarToStr(dv)
    END SUB
    Foo4 @DVARIANT(12345, "LONG")

#### Remarks

I haven’t added a cast to return a numeric value because with procedures like PRINT that can use both a number or a string the compiler will fail, not knowing which cast it should use. If you want to convert it to a number, use VAL(DVARIANT).

## vType

Returns the VARIANT type.

    FUNCTION vType () AS VARTYPE

The following table shows the available data types and where these values can be used.

Type | Description | VARIANT | Typedesc | Property set | Safe array
--- | --- | --- | --- | --- | ---
VT_EMPTY | Not specified. | X |  | X |
VT_NULL | Null. | X |  | X |
VT_I1 | BYTE. A character. | X | X | X | X
VT_UI1 | UBYTE. An unsigned character. | X | X | X | X
VT_I2 | SHORT. A 2-byte integer. | X | X | X | X
VT_UI2 | USHORT. An unsigned short. | X | X | X | X
VT_I4 | LONG. A 4-byte integer. | X | X | X | X
VT_UI4 | ULONG. An unsigned long. | X | X | X | X
VT_I8 | LONGINT. A 64-bit integer. | X | X | X | X
VT_UI8 | ULONGINT. A 64-bit unsigned integer. | X | X | X | X
VT_INT | LONG. An integer. | X | X | X | X
VT_UINT | ULOG. An unsigned integer. | X | X |  | X
VT_R4 | SINGLE. A 4-byte real. | X | X | X | X
VT_R8 | DOUBLE. A 8-byte real. | X | X | X | X
VT_CY | CY. Currency. | X | X | X | X
VT_DATE | DOUBLE. A date. | X | X | X | X
VT_BSTR | BSTR. A string. | X | X | X | X
VT_DISPATCH | IDispatch PTR. An IDispatch pointer. | X | X |  | X
VT_ERROR | SCODE. An SCODE value. | X | X | X | X
VT_BOOL | BOOLEAN. A Boolean value (True = -1, False = 0) | X | X | X | X
VT_VARIANT | VARIANT PTR. A variant pointer. | X | X | X | X
VT_UNKNOWN | IUnknown PTR. An IUnknown pointer. | X | X |  | X
VT_DECIMAL | DECIMAL PTR. A 16-byte fixed-pointer value. | X | X |  | X
VT_VOID | NULL. A C-style void. |  |  | X |
VT_HRESULT | HRESULT. An HRESULT value. |  |  | X |
VT_PTR | A pointer type. |  |  | X |
VT_SAFEARRAY | SAFEARRAY PTR. A safe array. Use VT_ARRAY in VARIANT. |  | X |  |
VT_CARRAY | A C-style array. |  | X |  |
VT_USERDEFINED | A user-defined type. |  |  | X |
VT_LPSTR | ZSTRING. A null-terminated string. |  | X | X |
VT_LPWSTR | WSTRING. A wide null-terminated string. |  | X | X |
VT_RECORD | A user-defined type. | X | X |  | X
VT_INT_PTR | A signed machine register size width. |  |  | X |
VT_UINT_PTR | An unsigned machine register size width. |  |  | X |
VT_FILETIME | FILETIME. A FILETIME value. |  |  | X |
VT_BLOB | Length-prefixed bytes. |  |  | X |
VT_STREAM | IStream PTR. The name of the stream follows. |  |  | X |
VT_STORAGE | The name of the storage follows. |  |  | X |
VT_STREAMED_OBJECT | The stream contains an object. |  |  | X |
VT_STORED_OBJECT | The storage contains an object. |  |  | X |
VT_BLOB_OBJECT | The blob contains an object. |  |  | X |
VT_CF | A clipboard format. |  |  | X |
VT_CLSID | CLSID. A class ID. |  |  | X |
VT_VERSIONED_STREAM | A stream with a GUID version. |  |  | X |
VT_BSTR_BLOB | Reserved for system use. |  |  |  |
VT_VECTOR | A simple counted array. |  |  | X |
VT_ARRAY | SAFEARRAY PTR. A SAFEARRAY pointer. | X |  |  |
VT_BYREF | A void pointer for local use. | X |  |  |
VT_RESERVED | Reserved. |  |  |  |
VT_ILLEGAL |  |  |  |  |
VT_ILLEGALMASKED |  |  |  |  |
VT_TYPEMASK |  |  |  |  |

## Attach

Attaches a variant to the class.

    FUNCTION Attach (BYVAL pvar AS VARIANT PTR) AS HRESULT
    FUNCTION Attach (BYREF v AS VARIANT) AS HRESULT

Parameter | Description
--- | ---
pvar | Pointer to the variant to attach.
v | The variant to attach.

#### Remark

Marks the source variant as VT_EMPTY instead of clearing it with VariantClear because we aren’t making a duplicate of the contents, but transferring ownership.

#### Return value

Returns S_OK (0) on success or an HRESULT error code on failure.

## Detach

Detaches the variant data from this class and transfers ownership to the passed variant.

    FUNCTION Detach (BYVAL pvar AS VARIANT PTR) AS HRESULT
    FUNCTION Detach (BYREF v AS VARIANT) AS HRESULT

Parameter | Description
--- | ---
pvar | Pointer to the variant where the contents of the variant data will be moved.
v | Variant where the contents of the variant data will be moved.

#### Remark

This method transfers ownership of the underlying variant and marks it as empty.

#### Return value

Returns S_OK (0) or an HRESULT error code.

## ChangeType

Converts the variant from one type to another.

    FUNCTION ChangeType (BYVAL vtNew AS VARTYPE, BYVAL wFlags AS USHORT = 0) AS HRESULT

Parameter | Description
--- | ---
vtNew | The new variant type.
wFlags | VARIANT_NOVALUEPROP : Prevents the function from coercing an object to a fundamental type by getting the Value property. Applications should set this flag only if necessary, because it makes their behavior inconsistent with other applications. VARIANT_ALPHABOOL : Converts a VT_BOOL value to a string containing either “True” or “False”. VARIANT_NOUSEROVERRIDE : For conversions to or from VT_BSTR, passes LOCALE_NOUSEROVERRIDE to the core coercion routines. VARIANT_LOCALBOOL : For conversions from VT_BOOL to VT_BSTR and back, uses the language specified by the locale in use on the local computer.

#### Return value

Returns S_OK (0) or an HRESULT error code.

## ChangeTypeEx

Converts the variant from one type to another.

    FUNCTION ChangeTypeEx (BYVAL vtNew AS VARTYPE, BYVAL lcid AS LCID = 0, BYVAL wFlags AS USHORT = 0) AS HRESULT

Parameter | Description
--- | ---
vtNew | The new variant type.
lcid | The locale identifier. The LCID is useful when the type of the source or destination VARIANTARG is VT_BSTR, VT_DISPATCH, or VT_DATE.
wFlags | VARIANT_NOVALUEPROP : Prevents the function from attempting to coerce an object to a fundamental type by getting the Value property. Applications should set this flag only if necessary, because it makes their behavior inconsistent with other applications. VARIANT_ALPHABOOL : Converts a VT_BOOL value to a string containing either “True” or “False”. VARIANT_NOUSEROVERRIDE : For conversions to or from VT_BSTR, passes LOCALE_NOUSEROVERRIDE to the core coercion routines. VARIANT_LOCALBOOL : For conversions from VT_BOOL to VT_BSTR and back, uses the language specified by the locale in use on the local computer.

#### Return value

Returns S_OK (0) or an HRESULT error code.

## GetDim

Gets the number of dimensions in the array.

    FUNCTION GetDim () AS ULONG

#### Return value

Returns the number of dimensions for variants of type VT_ARRAY; returns 0 otherwise.

## GetLBound

Gets the lower bound for the specified dimension of the safe array.

    FUNCTION GetLBound (BYVAL nDim AS UINT = 1) AS LONG

Parameter | Description
--- | ---
nDim | The dimension of the array.

#### Return value

Returns the lower bound for the specified dimension of the safe array for variants of type VT_ARRAY; returns 0 otherwise.

## GetUBound

Gets the upper bound for the specified dimension of the safe array.

    FUNCTION GetUBound (BYVAL nDim AS UINT = 1) AS LONG

Parameter | Description
--- | ---
nDim | The dimension of the array.

#### Return value

Returns the upper bound for the specified dimension of the safe array for variants of type VT_ARRAY; returns 0 otherwise.

## GetElementCount

Gets the number of elements in the array.

    FUNCTION GetElementCount () AS ULONG

#### Return value

Returns the number of elements for variants of type VT_ARRAY; returns 1 otherwise.

## DecToCY

Converts a DVARIANT of type decimal to a CY structure.

    FUNCTION DecToCY () AS CY

#### Return value

Returns the contents of a VT_DECIMAL variant as a CY structure.

## DecToDouble

Converts a DVARIANT of type decimal to a double.

    FUNCTION DecToDouble () AS DOUBLE

#### Return value

Returns the contents of a VT_DECIMAL variant as a DOUBLE.

## Round

Rounds a variant to the specified number of decimal places.

    FUNCTION Round (BYREF dv AS DVARIANT, BYVAL cDecimals AS LONG) AS DVARIANT

Parameter | Description
--- | ---
dv | The DVARIANT to round.
cDecimals | The number of decimal places.

#### Return value

A DVARIANT containing the rounded result.

## FormatNumber

Formats a DVARIANT containing numbers into a string form.

    FUNCTION FormatNumber (BYVAL iNumDig AS LONG = -1, BYVAL ilncLead AS LONG = -2, _
       BYVAL iUseParens AS LONG = -2, BYVAL iGroup AS LONG = -2, BYVAL dwFlags AS DWORD = 0) AS DWSTRING

Parameter | Description
--- | ---
iNumDig | The number of digits to pad to after the decimal point. Specify -1 to use the system default value.
ilncLead | Specifies whether to include the leading digit on numbers. -2 : Use the system default. -1 : Include the leading digit. 0 : Do not include the leading digit.
iUseParens | Specifies whether negative numbers should use parentheses. -2 : Use the system default. -1 : Use parentheses. 0 : Do not use parentheses.
iGroup | Specifies whether thousands should be grouped. For example 10,000 versus 10000. -2 : Use the system default. -1 : Group thousands. 0 : Do not group thousands.
dwFlags | VAR_CALENDAR_HIJRI is the only flag that can be set.

#### Return value

A DWSTRING containing the formatted value.

#### Remarks

This function uses the user’s default locale while calling VarTokenizeFormatString and VarFormatFromTokens.

## GetBooleanElement

Extracts a single boolean element from a safe array of booleans.

    FUNCTION GetBooleanElement (BYVAL iElem AS ULONG) AS BOOLEAN

Parameter | Description
--- | ---
iElem | The index of the element of the array.

#### Return value

The retrieved value.

## GetDoubleElement

Extracts a single DOUBLE element from a safe array of doubles.

    FUNCTION GetDoubleElement (BYVAL iElem AS ULONG) AS DOUBLE

Parameter | Description
--- | ---
iElem | The index of the element of the array.

#### Return value

The retrieved value.

## GetLongElement

Extracts a single LONG element from a safe array of longs.

    FUNCTION GetLongElement (BYVAL iElem AS ULONG) AS LONG

Parameter | Description
--- | ---
iElem | The index of the element of the array.

#### Return value

The retrieved value.

## GetLongIntElement

Extracts a single LONGINT element from a safe array of long integers.

    FUNCTION GetLongIntElement (BYVAL iElem AS ULONG) AS LONGINT

Parameter | Description
--- | ---
iElem | The index of the element of the array.

#### Return value

The retrieved value.

## GetShortElement

Extracts a single SHORT element from a safe array of short integers.

    FUNCTION GetShortElement (BYVAL iElem AS ULONG) AS SHORT

Parameter | Description
--- | ---
iElem | The index of the element of the array.

#### Return value

The retrieved value.

## GetStringElement

Extracts a single BSTR element from a safe array of unicode strings.

    FUNCTION GetStringElement (BYVAL iElem AS ULONG) AS BSTR

Parameter | Description
--- | ---
iElem | The index of the element of the array.

#### Return value

The retrieved value.

## GetULongElement

Extracts a single ULONG element from a safe array of unsigned longs.

    FUNCTION GetULongElement (BYVAL iElem AS ULONG) AS ULONG

Parameter | Description
--- | ---
iElem | The index of the element of the array.

#### Return value

The retrieved value.

## GetULongIntElement

Extracts a single ULONGINT element from a safe array of unsigned long integers.

    FUNCTION GetULongIntElement (BYVAL iElem AS ULONG) AS ULONGINT

Parameter | Description
--- | ---
iElem | The index of the element of the array.

#### Return value

The retrieved value.

## GetUShortElement

Extracts a single USHORT element from a safe array of unsigned shorts.

    FUNCTION GetUShortElement (BYVAL iElem AS ULONG) AS USHORT

Parameter | Description
--- | ---
iElem | The index of the element of the array.

#### Return value

The retrieved value.

## GetVariantElement

Extracts a single Variant element from a safe array of variants.

    FUNCTION GetVariantElement (BYVAL iElem AS ULONG) AS DVARIANT

Parameter | Description
--- | ---
iElem | The index of the element of the array.

#### Return value

The retrieved value.

## Put

Assigns values to a DVARIANT.

    SUB Put (BYREF wsz AS WSTRING)
    SUB Put (BYREF dws AS DWSTRING)
    SUB Put (BYREF bs AS BSTRING)
    FUNCTION Put (BYREF dv AS DVARIANT) AS HRESULT
    FUNCTION Put (BYVAL v AS VARIANT) AS HRESULT
    FUNCTION Put (BYVAL pvar AS VARIANT PTR) AS HRESULT
    FUNCTION Put (BYREF pDisp AS IDispatch PTR, BYVAL fAddRef AS BOOLEAN = FALSE) AS HRESULT
    FUNCTION Put (BYREF pUnk AS IUnknown PTR, BYVAL fAddRef AS BOOLEAN = FALSE) AS HRESULT
    SUB Put (BYVAL _value AS LONGINT, BYVAL _vType AS WORD = VT_I4)
    SUB Put (BYVAL _value AS DOUBLE, BYVAL _vType AS WORD = VT_R8)
    SUB Put (BYVAL _value AS LONGINT, BYREF strType AS STRING)
    SUB Put (BYVAL _value AS DOUBLE, BYREF strType AS STRING)
    SUB Put (BYVAL _pv AS ANY PTR, BYVAL _vType AS WORD)
    SUB Put (BYVAL _pv AS ANY PTR, BYREF strType AS STRING)

Parameter | Description
--- | ---
wsz | A Unicode string. You can also pass a FreeBasic ansi string or a string literal.
dws | A DWSTRING variable.
bs | A BSTRING variable.
dv | A DVARIANT variable.
v | A VARIANT variable.
v | A VARIANT variable.
pvar | Pointer to a VARIANT variable.
pDisp | Pointer to a DISPATCH interface.
pUnk | Pointer to a UNKNOWN interface.
*_pv* | Pointer to a variable. This will create a VT_BYREF variant of the specified type.
*_vtype* | The variant type, e.g. VT_I4, VT_UI4.
strType | The variant type as a string: “BOOL”, “BYTE”, “UBYTE”, “SHORT”, “USHORT,”INT”, UINT”, “LONG”, “ULONG”, “LONGINT”, “SINGLE,”DOUBLE”, “NULL”.
fAddRef | TRUE or FALSE. If TRUE, increases the reference count of the passed interface.

## PutNull

Assigns a null value to the DVARIANT.

    SUB PutNull

## PutBool

Assigns a boolean value to the DVARIANT.

    SUB PutBool (BYVAL _value AS BOOL)

## PutBoolean

Assigns a boolean value to the DVARIANT.

    SUB PutBoolean (BYVAL _value AS BOOLEAN)

## PutByte

Assigns a byte value to the DVARIANT.

    SUB PutByte (BYVAL _value AS BYTE)

## PutUByte

Assigns an unsigned ubyte value to the DVARIANT.

    SUB PutUByte (BYVAL _value AS UBYTE)

## PutShort

Assigns a short integer value to the DVARIANT.

    SUB PutShort (BYVAL _value AS SHORT)

## PutUShort

Assigns an unsigned short integer value to the DVARIANT.

    SUB PutUShort (BYVAL _value AS USHORT)

## PutInt

Assigns an INT_ (long) value to the DVARIANT.

    SUB PutInt (BYVAL _value AS INT_)

### Remark

Don’t confuse an INT_ (LONG) with the Free Basic INTEGER data type.

## PutUInt

Assigns an UINT (unsigned long) value to the DVARIANT.

    SUB PutUInt (BYVAL _value AS UINT)

### Remark

Don’t confuse an UINT (ULONG) with the Free Basic UINTEGER data type.

## PutLong

Assigns a LONG value to the DVARIANT.

    SUB PutLong (BYVAL _value AS LONG)

## PutULong

Assigns a ULONG value to the DVARIANT.

    SUB PutULong (BYVAL _value AS ULONG)

## PutLongInt

Assigns a LONGINT value to the DVARIANT.

    SUB PutULong (BYVAL _value AS LONGINT)

## PutULongInt

Assigns a ULONGINT value to the DVARIANT.

    SUB PutULongInt (BYVAL _value AS ULONGINT)

## PutSingle

Assigns a SINGLE value to the DVARIANT.

    SUB PutSingle (BYVAL _value AS SINGLE)

## PutFloat

Assigns a SINGLE value to the DVARIANT.

    SUB PutFloat (BYVAL _value AS SINGLE)

## PutDouble

Assigns a DOUBLE value to the DVARIANT.

    SUB PutDouble (BYVAL _value AS DOUBLE)

## PutBooleanArray

Initializes DVARIANT from an array of Boolean values.

    FUNCTION PutBooleanArray (BYVAL prgf AS WINBOOL PTR, BYVAL cElems AS ULONG) AS HRESULT

Parameter | Description
--- | ---
prgf | Pointer to source array of Boolean values.
cElems | The number of elements in the array.

#### Return value

If this function succeeds, it returns S_OK (0). Otherwise, it returns an HRESULT error code.

#### Remarks

Creates a VT_ARRAY OR VT_BOOL variant.

## PutShortArray

Initializes DVARIANT from an array of signed 16-bit integer values.

    FUNCTION PutShortArray (BYVAL prgf AS SHORT PTR, BYVAL cElems AS ULONG) AS HRESULT

Parameter | Description
--- | ---
prgf | Pointer to source array of SHORT values.
cElems | The number of elements in the array.

#### Return value

If this function succeeds, it returns S_OK (0). Otherwise, it returns an HRESULT error code.

#### Remarks

Creates a VT_ARRAY OR VT_I2 variant.

## PutUshortArray

Initializes DVARIANT from an array of 16-bit unsigned integer values.

    FUNCTION PutUshortArray (BYVAL prgf AS USHORT PTR, BYVAL cElems AS ULONG) AS HRESULT

Parameter | Description
--- | ---
prgf | Pointer to source array of USHORT values.
cElems | The number of elements in the array.

#### Return value

If this function succeeds, it returns S_OK (0). Otherwise, it returns an HRESULT error code.

#### Remarks

Creates a VT_ARRAY OR VT_UI2 variant.

## PutLongArray

Initializes DVARIANT from an array of signed 32-bit integer values.

    FUNCTION PutLongArray (BYVAL prgf AS LONG PTR, BYVAL cElems AS ULONG) AS HRESULT

Parameter | Description
--- | ---
prgf | Pointer to source array of LONG values.
cElems | The number of elements in the array.

#### Return value

If this function succeeds, it returns S_OK (0). Otherwise, it returns an HRESULT error code.

#### Remarks

Creates a VT_ARRAY OR VT_I4 variant.

## PutULongArray

Initializes DVARIANT from an array of 32-bit unsigned integer values.

    FUNCTION PutULongArray (BYVAL prgf AS ULONG PTR, BYVAL cElems AS ULONG) AS HRESULT

Parameter | Description
--- | ---
prgf | Pointer to source array of ULONG values.
cElems | The number of elements in the array.

#### Return value

If this function succeeds, it returns S_OK (0). Otherwise, it returns an HRESULT error code.

#### Remarks

Creates a VT_ARRAY OR VT_UI4 variant.

## PutLongIntArray

Initializes DVARIANT from an array of signed 64-bit integer values.

    FUNCTION PutLongIntArray (BYVAL prgf AS LONGINT PTR, BYVAL cElems AS ULONG) AS HRESULT

Parameter | Description
--- | ---
prgf | Pointer to source array of LONGINT values.
cElems | The number of elements in the array.

#### Return value

If this function succeeds, it returns S_OK (0). Otherwise, it returns an HRESULT error code.

#### Remarks

Creates a VT_ARRAY OR VT_I8 variant.

## PutULongIntArray

Initializes DVARIANT from an array of unsigned 64-bit integer values.

    FUNCTION PutULongIntArray (BYVAL prgf AS ULONGINT PTR, BYVAL cElems AS ULONG) AS HRESULT

Parameter | Description
--- | ---
prgf | Pointer to source array of ULONGINT values.
cElems | The number of elements in the array.

#### Return value

If this function succeeds, it returns S_OK (0). Otherwise, it returns an HRESULT error code.

#### Remarks

Creates a VT_ARRAY OR VT_UI8 variant.

## PutDoubleArray

Initializes DVARIANT from an array of unsigned 64-bit integer values.

    FUNCTION PutDoubleArray (BYVAL prgf AS DOUBLE PTR, BYVAL cElems AS ULONG) AS HRESULT

Parameter | Description
--- | ---
prgf | Pointer to source array of DOUBLE values.
cElems | The number of elements in the array.

#### Return value

If this function succeeds, it returns S_OK (0). Otherwise, it returns an HRESULT error code.

#### Remarks

Creates a VT_ARRAY OR VT_R8 variant.

## PutStringArray

Initializes DVARIANT from an array of unicode strings.

    FUNCTION PutStringArray (BYVAL prgsz AS PDWSTRING, BYVAL cElems AS ULONG) AS HRESULT

Parameter | Description
--- | ---
prgsz | Pointer to source array of unicode strings.
cElems | The number of elements in the array.

#### Return value

If this function succeeds, it returns S_OK (0). Otherwise, it returns an HRESULT error code.

#### Remarks

Creates a VT_ARRAY OR VT_BSTR variant.

## PutBuffer

Initializes DVARIANT with the contents of a buffer.

    FUNCTION PutBuffer (BYVAL pv AS VOID PTR, BYVAL cb AS UINT) AS HRESULT

Parameter | Description
--- | ---
pv | Pointer to the source buffer.
cb | The length of the buffer, in bytes.

#### Return value

If this function succeeds, it returns S_OK (0). Otherwise, it returns an HRESULT error code.

#### Remarks

Creates a VT_ARRAY OR VT_UI1 variant.

### Example

    DIM dv AS DVARIANT
    DIM strIn AS STRING = "Test string"
    dv.PutBuffer(STRPTR(strIn), LEN(strIn))

    DIM nBytes AS LONG = dv.GetElementCount
    DIM strOut AS STRING = SPACE(nBytes)
    dv.ToBuffer(STRPTR(strOut), nBytes)
    PRINT strOut

## PutDateString

Initializes DVARIANT VT_DATE from a string.

    FUNCTION PutDateString (BYVAL pwszDate AS WSTRING PTR, BYVAL lcid AS LCID = 0, _
       BYVAL dwFlags AS ULONG = 0) AS HRESULT

Parameter | Description
--- | ---
pwszDate | The date value to convert, e.g. “2018-08-20 19:42”.
lcid | The locale identifier.
dwFlags | One or more of the following flags. LOCALE_NOUSEROVERRIDE : Uses the system default locale settings, rather than custom locale settings. VAR_CALENDAR_HIJRI : If set then the Hijri calendar is used. Otherwise the calendar set in the control panel is used. VAR_TIMEVALUEONLY : Omits the date portion of a VT_DATE and returns only the time. Applies to conversions to or from dates. VAR_DATEVALUEONLY : Omits the time portion of a VT_DATE and returns only the date. Applies to conversions to or from dates.

#### Return value

If this function succeeds, it returns S_OK (0). Otherwise, it returns an HRESULT error code.

#### Remarks

Creates a VT_DATE variant.

## PutDec

Initializes DVARIANT with the contents of a DECIMAL structure.

    FUNCTION PutDec (BYCAL dec AS DECIMAL) AS HRESULT

Parameter | Description
--- | ---
dec | A DECIMAL structure.

#### Return value

If this function succeeds, it returns S_OK (0). Otherwise, it returns an HRESULT error code.

#### Remarks

Creates a VT_DECIMAL OR VT_BYREF variant.

## PutDecFromCY

Converts a currency value to a variant of type VT_DECIMAL.

    FUNCTION PutDecFromCY (BYVAL cyIn AS CY) AS HRESULT

Parameter | Description
--- | ---
cyIn | The currency value to convert.

#### Return value

This function can return one of these values.

Value | Meaning
--- | ---
S_OK | Success.
DISP_E_TYPEMISMATCH | The argument could not be coerced to the specified type.
E_INVALIDARG | One of the arguments is not valid.
E_OUTOFMEMORY | Insufficient memory to complete the operation.

#### Remarks

Creates a VT_DECIMAL variant.

## PutDecFromDouble

Converts a double value to a variant of type VT_DECIMAL.

    FUNCTION PutDecFromDouble (BYVAL dbIn AS DOUBLE) AS HRESULT

Parameter | Description
--- | ---
dbIn | The DOUBLE value to convert.

#### Return value

This function can return one of these values.

Value | Meaning
--- | ---
S_OK | Success.
DISP_E_TYPEMISMATCH | The argument could not be coerced to the specified type.
E_INVALIDARG | One of the arguments is not valid.
E_OUTOFMEMORY | Insufficient memory to complete the operation.

#### Remarks

Creates a VT_DECIMAL variant.

## PutDecFromStr

Initializes DVARIANT as VT_DECIMAL from a string.

    FUNCTION PutDecFromStr (BYVAL pwszIn AS WSTRING PTR, BYVAL lcid AS LCID = 0, _
       BYVAL dwFlags AS ULONG = 0) AS HRESULT

Parameter | Description
--- | ---
pwszIn | The string value to convert.
lcid | The locale identifier.
dwFlags | One or more of the following flags. LOCALE_NOUSEROVERRIDE : Uses the system default locale settings, rather than custom locale settings. VAR_TIMEVALUEONLY : Omits the date portion of a VT_DATE and returns only the time. Applies to conversions to or from dates. VAR_DATEVALUEONLY : Omits the time portion of a VT_DATE and returns only the date. Applies to conversions to or from dates.

#### Return value

This function can return one of these values.

Value | Meaning
--- | ---
S_OK | Success.
DISP_E_TYPEMISMATCH | The argument could not be coerced to the specified type.
E_INVALIDARG | One of the arguments is not valid.
E_OUTOFMEMORY | Insufficient memory to complete the operation.

#### Remarks

Creates a VT_DECIMAL variant.

## PutFileTime

Initializes DVARIANT with the contents of a FILETIME structure.

    FUNCTION PutFileTime (BYVAL pft AS FILETIME PTR) AS HRESULT

Parameter | Description
--- | ---
pft | Pointer to a FILETIME structure.

#### Return value

If this function succeeds, it returns S_OK (0). Otherwise, it returns an HRESULT error code.

#### Remarks

Creates a VT_DATE variant.

## PutFileTimeArray

Initializes DVARIANT with an array of FILETIME structures.

    FUNCTION PutFileTimeArray (BYVAL prgft AS FILETIME PTR, BYVAL cElems AS ULONG) AS HRESULT

Parameter | Description
--- | ---
prgft | Pointer to an array of FILETIME structures.
cElems | The number of elements in the array pointed to by prgft.

#### Return value

If this function succeeds, it returns S_OK (0). Otherwise, it returns an HRESULT error code.

#### Remarks

Creates a VT_ARRAY OR VT_DATE variant.

## PutGuid

Initializes DVARIANT from a GUID.

    FUNCTION PutGuid (BYVAL rguid AS GUID PTR) AS HRESULT

Parameter | Description
--- | ---
rguid | Reference to the source GUID.

#### Return value

If this function succeeds, it returns S_OK (0). Otherwise, it returns an HRESULT error code.

#### Remarks

Creates a VT_ARRAY OR VT_UI1 variant.

## PutPropVariant

Initializes DVARIANT from the contents of a PROPVARIANT structure.

    FUNCTION PutPropVariant (BYVAL pPropVar AS PROPVARIANT PTR) AS HRESULT

Parameter | Description
--- | ---
pPropVar | Pointer to a source PROPVARIANT structure.

#### Return value

If this function succeeds, it returns S_OK (0). Otherwise, it returns an HRESULT error code.

#### Remarks

Normally, the data stored in the PROPVARIANT is copied to the VARIANT without a datatype change. However, in the following cases, there is no direct VARIANT support for the datatype, and they are converted as shown.

VT_BLOB, VT_STREAM
Converted to VT_UNKNOWN. The punkVal member will contain a pointer to an IStream that contains the source data.

VT_LPSTR, VT_LPWSTR, VT_CLSID
Converted to VT_BSTR,

VT_FILETIME
Converted to VT_DATE.

VT_VECTOR OR x
Converted to VT_ARRAY OR x

The following types cannot be converted with this function.

VT_STORAGE
VT_BLOB_OBJECT
VT_STREAMED_OBJECT
VT_STORED_OBJECT
VT_CF
VT_VECTOR OR VT_CF

## PutRecord

Initializes DVARIANT with a reference to an UDT.

    FUNCTION PutRecord (BYVAL pIRecordInfo AS IRecordInfo PTR, BYVAL pRec AS VOID PTR) AS HRESULT

Parameter | Description
--- | ---
pIRecordInfo | Pointer to the IRecordInfo interface.
pRec | Pointer to the UDT.

#### Return value

If this function succeeds, it returns S_OK (0). Otherwise, it returns an HRESULT error code.

#### Remarks

Creates a VT_RECORD variant.

## PutRef

Assigns a value by reference (a pointer to a variable).

    FUNCTION PutRef (BYVAL _pvar AS ANY PTR, BYVAL _vType AS WORD) AS HRESULT
    FUNCTION PutRef (BYVAL _pvar AS ANY PTR, BYREF strType AS STRING) AS HRESULT

Parameter | Description
--- | ---
*_pvar* | Pointer to a variable.
*_vType* | Type of the variant: VT_BOOL, VT_I1, VT_UI1, VT_I2, VT_UI2, VT_INT, VT_UINT, VT_I4, VT_UI4, VT_I8, VT_UI8, VT_R4, VT_R8, VT_BSTR, VT_UNKNOWN, VT_DISPATCH, VT_DECIMAL, VT_CY, VT_DATE, VT_VARIANT, VT_SAFEARRAY, VT_ERROR.
strType | Type of the variant: “BOOL”, “BYTE”, “UBYTE”, “SHORT”, “USHORT”, “INT”, “UINT”, “LONG”, “ULONG”, “LONGINT”, “ULONGINT”, “SINGLE”, “DOUBLE”, “BSTR”, “UNKNOWN”, “DISPATCH”, “DECIMAL”, “CY”, “DATE”, “VARIANT”, “SAFEARRAY”, “ERROR”.

#### Return value

If this function succeeds, it returns S_OK (0). Otherwise, it returns an HRESULT error code.

#### Remarks

Creates a VT_BYREF variant of the sepecified type.

## PutResource

Initializes the DVARIANT based on a string resource imbedded in an executable file.

    FUNCTION PutResource (BYVAL hinst AS HINSTANCE, BYVAL id AS UINT) AS HRESULT

Parameter | Description
--- | ---
hinst | The instance handle.
id | Integer identifier of the string to be loaded.

#### Return value

If this function succeeds, it returns S_OK (0). Otherwise, it returns an HRESULT error code.

#### Remarks

Creates a VT_BSTR variant. If the resource does not exist, this function initializes the VARIANT as VT_EMPTY and returns a failure code.

## PutSafeArray

Initializes DVARIANT from a safe array.

    FUNCTION PutSafeArray (BYVAL parray AS SAFEARRAY PTR) AS HRESULT

Parameter | Description
--- | ---
parray | Pointer to safe array.

#### Return value

If this function succeeds, it returns S_OK (0). Otherwise, it returns an HRESULT error code.

#### Remarks

Creates a VT_ARRAY variant.

## PutStrRet

Initializes DVARIANT with the string stored in a STRRET structure.

    FUNCTION PutStrRet (BYVAL pstrret AS STRRET PTR, BYVAL pidl AS PCUITEMID_CHILD) AS HRESULT

Parameter | Description
--- | ---
pstrret | Pointer to a STRRET structure.
pidl | PIDL of the item whose details are being retrieved.

#### Return value

If this function succeeds, it returns S_OK (0). Otherwise, it returns an HRESULT error code.

#### Remarks

Creates a VT_BSTR variant. This function frees the resources used for the STRRET contents.

## PutSystemTime

Initializes DVARIANT with the contents of a SYSTEMTIME structure.

    FUNCTION PutSystemTime (BYVAL pst AS SYSTEMTIME PTR) AS HRESULT

Parameter | Description
--- | ---
pst | Pointer to a SYSTEMTIME structure.

#### Return value

If this function succeeds, it returns S_OK (0). Otherwise, it returns an HRESULT error code.

#### Remarks

Creates a VT_DATE variant.

## PutUtf8

Initializes DVARIANT with the contents of an UTF-8 string.

    FUNCTION PutUtf8 (BYREF strUtf8 AS STRING) AS HRESULT

Parameter | Description
--- | ---
strUtf8 | The UTF-8 encoded string.

#### Return value

If this function succeeds, it returns S_OK (0). Otherwise, it returns an HRESULT error code.

#### Remarks

Creates a VT_BSTR variant.

## PutVariantArrayElement

Initializes DVARIANT with a value stored in another VARIANT structure.

    FUNCTION PutVariantArrayElement (BYVAL pvarIn AS VARIANT PTR, BYVAL iElem AS ULONG) AS HRESULT

Parameter | Description
--- | ---
pvarIn | Reference to the source VARIANT structure.
iElem | Index of one of the source VARIANT structure elements.

#### Return value

If this function succeeds, it returns S_OK (0). Otherwise, it returns an HRESULT error code.

#### Remarks

This helper function works for VARIANT structures of the following types:

    VT_BSTR
    VT_BOOL
    VT_I2
    VT_I4
    VT_I8
    VT_U12
    VT_U14
    VT_U18
    VT_DATE
    VT_ARRAY | (any one of VT_BSTR, VT_BOOL, VT_I2, VT_I4, VT_I8, VT_U12, VT_U14, VT_U18, VT_DATE)

Additional types may be supported in the future.

This function extracts a single value from the source VARIANT structure and uses that value to initialize the output VARIANT structure. The calling application must use VariantClear to free the VARIANT referred to by pvar when it is no longer needed.

If the source VARIANT is an array, iElem must be less than the number of elements in the array.

If the source VARIANT has a single value, iElem must be 0.

If the source VARIANT is empty, this function always returns an error code.

You can use GetElementCount to obtain the number of elements in the array or array.

## PutVbDate

Initializes DVARIANT with the contents of a DATE value.

    FUNCTION PutVbDate (BYREF vbDate AS DATE_) AS HRESULT

Parameter | Description
--- | ---
vbDate | The DATE value.

#### Return value

If this function succeeds, it returns S_OK (0). Otherwise, it returns an HRESULT error code.

#### Remarks

Creates a VT_DATE variant.

## ToBooleanArray

Extracts an array of boolean values from DVARIANT.

    FUNCTION ToBooleanArray (BYVAL prgf AS WINBOOL PTR, BYVAL crgn AS ULONG) AS ULONG

Parameter | Description
--- | ---
prgf | Pointer to a buffer that contains crgn boolean values. When this function returns, the buffer has been initialized with elements extracted from the source VARIANT structure.
crgn | The number of elements in the buffer pointed to by prgf.

#### Return value

The count of WINBOOL elements extracted from the DVARIANT.

#### Remarks

This helper function is used when the calling application expects a VARIANT to hold an array that consists of a fixed number of boolean values.

If the source VARIANT is of type VT_ARRAY OR VT_BOOL, this function extracts up to crgn WINBOOL values and places them into the buffer pointed to by prgf. If the VARIANT contains more elements than will fit into the prgf buffer, this function returns 0.

## ToBooleanArrayAlloc

Extracts an array of boolean values from DVARIANT.

    FUNCTION ToBooleanArrayAlloc (BYVAL pprgf AS WINBOOL PTR PTR) AS ULONG

Parameter | Description
--- | ---
prgf | Pointer to a WINBOOL PTR variable that will recive a pointer to an array of WINBOOL values extracted from the source DVARIANT.

#### Return value

The count of WINBOOL elements extracted from the DVARIANT.

#### Remarks

This helper function is used when the calling application expects a DVARIANT to hold an array of WINBOOL values.

If DVARIANT is of type VT_ARRAY OR VT_BOOL, this function extracts an array of WINBOOL values into a newly allocated array. The calling application is responsible for using CoTaskMemFree to release the array pointed to by pprgf when it is no longer needed.

## ToBstr

Extracts the content of the underlying variant and returns it as a BSTRING.

    FUNCTION ToBstr () AS BSTRING

#### Return value

The contents of the variant as a BSTRING.

#### Example

    DIM dv AS DVARIANT = "Test string"
    DIM bs AS BSTRING = dv.ToBstr

## ToBuffer

Extracts the contents of a DVARIANT of type VT_ARRRAY OR VT_UI1 to a buffer.

    FUNCTION ToBuffer (BYVAL pv AS VOID PTR, BYVAL cb AS UINT) AS HRESULT

Parameter | Description
--- | ---
pv | Pointer to a buffer of length cb bytes. When this function returns, contains the first cb bytes of the extracted buffer value.
cb | The size of the pv buffer, in bytes. The buffer should be the same size as the data to be extracted, or smaller.

#### Return value

Returns one of the following values:

Value | Meaning
--- | ---
S_OK | Data successfully extracted.
E_INVALIDARG | The VARIANT was not of type VT_ARRRAY OR VT_UI1.
E_FAIL | The VARIANT buffer value had fewer than cb bytes.

#### Remarks

This function is used when the calling application expects a VARIANT to hold a buffer value. The calling application should check that the value has the expected length before it calls this function.

If DVARIANT has type VT_ARRAY OR VT_UI1, this function extracts the first cb bytes from the structure and places them in the buffer pointed to by pv.

If the stored value has fewer than cb bytes, then function fails and the buffer is not modified.

If the value has more than cb bytes, then function succeeds and truncates the value.

To retrieve the size of the array call GetElementCount.

### Example

    DIM dv AS DVARIANT
    DIM strIn AS STRING = "Test string"
    dv.PutBuffer(STRPTR(strIn), LEN(strIn))

    DIM nBytes AS LONG = dv.GetElementCount
    DIM strOut AS STRING = SPACE(nBytes)
    dv.ToBuffer(STRPTR(strOut), nBytes)
    PRINT strOut

## ToBuffer (STRING)

Extracts the contents of a DVARIANT of type VT_ARRRAY OR VT_UI1 to a string used as a buffer.

    FUNCTION ToBuffer () AS STRING

#### Return value

A string with the contents of the array.

## ToDosDateTime

Extracts a date and time value in Microsoft MS-DOS format from a DVARIANT of type VT_DATE.

    FUNCTION ToDosDateTime (BYVAL pwDate AS USHORT PTR, BYVAL pwTime AS USHORT PTR) AS HRESULT

Parameter | Description
--- | ---
pwDate | When this function returns, contains the extracted USHORT that represents a MS-DOS date.
pwTime | When this function returns, contains the extracted contains the extracted WORD that represents a MS-DOS time.

#### Return value

If this function succeeds, it returns S_OK (0). Otherwise, it returns an HRESULT error code.

#### Remarks

This helper function is used when the calling application expects a DVARIANT to hold a datetime value.

If DVARIANT is of type VT_DATE, this function extracts the datetime value.

If DVARIANT is not of type VT_DATE, the function attempts to convert the value in the VARIANT structure into the right format. If a conversion is not possible, it returns a failure code.

## ToDoubleArray

Extracts an array of DOUBLE values from DVARIANT.

    FUNCTION ToDoubleArray (BYVAL prgn AS DOUBLE PTR, BYVAL crgn AS ULONG) AS ULONG

Parameter | Description
--- | ---
prgn | Pointer to a buffer that contains crgn DOUBLE variables. When this function returns, the buffer has been initialized with DOUBLE elements extracted from DVARIANT.
crgn | The number of elements in the buffer pointed to by prgn.

#### Return value

This helper function is used when the calling application expects a VARIANT to hold an array that consists of a fixed number of DOUBLE values.

If the source VARIANT is of type VT_ARRAY OR VT_R8, this function extracts up to crgn DOUBLE values and places them into the buffer pointed to by prgn. If the VARIANT contains more elements than will fit into the prgn buffer, this function returns 0.

## ToDoubleArrayAlloc

Extracts an array of DOUBLE values from DVARIANT.

    FUNCTION ToDoubleArrayAlloc (BYVAL pprgn AS ULONGINT PTR PTR) AS ULONG

Parameter | Description
--- | ---
pprgf | Pointer to a DOUBLE PTR variable that will recive a pointer to an array of DOUBLE values extracted from the source DVARIANT.

#### Return value

The count of DOUBLE elements extracted from the DVARIANT.

#### Remarks

This helper function is used when the calling application expects a DVARIANT to hold an array of DOUBLE values.

If DVARIANT is of type VT_ARRAY OR VT_R8, this function extracts an array of DOUBLE values into a newly allocated array. The calling application is responsible for using CoTaskMemFree to release the array pointed to by pprgn when it is no longer neede

## ToFileTime

Returns the contents of a DVARIANT of type VT_DATE as a FILETIME structure.

    FUNCTION ToFileTime (BYVAL stfOut AS AFX_PSTIME_FLAGS) AS FILETIME

Parameter | Description
--- | ---
stfOut | Specifies one of the following time flags: PSTF_UTC (0) : Indicates coordinated universal time. PSTF_LOCAL (1) : Indicates local time.

#### Return value

A FILETIME structure.

## ToGuid

Returns the contents of a DVARIANT containing a GUID string as a GUID structure.

    FUNCTION ToGuid () AS GUID

#### Return value

Returns the contents of a DVARIANT containing a GUID string as an unicode GUID string.

## ToGuidBStr

Returns the contents of a DVARIANT containing a GUID string as an unicode GUID string.

    FUNCTION ToGuidBStr () AS BSTRING

#### Return value

A GUID string.

## ToGuidStr

Returns the contents of a DVARIANT containing a GUID string as an unicode GUID string.

    FUNCTION ToGuidStr () AS DWSTRING

#### Return value

A GUID string.

## ToGuidWStr

Returns the contents of a DVARIANT containing a GUID string as an unicode GUID string.

    FUNCTION ToGuidWStr () AS DWSTRING

#### Return value

A GUID string.

## ToLongArray

Extracts an array of LONG values from DVARIANT.

    FUNCTION ToLongArray (BYVAL prgn AS LONG PTR, BYVAL crgn AS ULONG) AS ULONG

Parameter | Description
--- | ---
prgn | Pointer to a buffer that contains crgn LONG variables. When this function returns, the buffer has been initialized with Int32 elements extracted from DVARIANT.
crgn | The number of elements in the buffer pointed to by prgn.

#### Return value

This helper function is used when the calling application expects a VARIANT to hold an array that consists of a fixed number of Int32 values.

If the source VARIANT is of type VT_ARRAY OR VT_I4, this function extracts up to crgn Int32 values and places them into the buffer pointed to by prgn. If the VARIANT contains more elements than will fit into the prgn buffer, this function returns 0.

## ToLongArrayAlloc

Extracts an array of LONG values from DVARIANT.

    FUNCTION ToLongArrayAlloc (BYVAL pprgn AS LONG PTR PTR) AS ULONG

Parameter | Description
--- | ---
pprgn | Pointer to a LONG PTR variable that will recive a pointer to an array of LONG values extracted from the source DVARIANT.

#### Return value

The count of LONG elements extracted from the DVARIANT.

#### Remarks

This helper function is used when the calling application expects a DVARIANT to hold an array of LONG values.

If DVARIANT is of type VT_ARRAY OR VT_I4, this function extracts an array of LONG values into a newly allocated array. The calling application is responsible for using CoTaskMemFree to release the array pointed to by pprgn when it is no longer needed.

## ToLongIntArray

Extracts an array of LONGINT values from DVARIANT.

    FUNCTION ToLongIntArray (BYVAL prgn AS LONGINT PTR, BYVAL crgn AS ULONG) AS ULONG

Parameter | Description
--- | ---
prgn | Pointer to a buffer that contains crgn LONGINT variables. When this function returns, the buffer has been initialized with Int64 elements extracted from DVARIANT.
crgn | The number of elements in the buffer pointed to by prgn.

#### Return value

This helper function is used when the calling application expects a VARIANT to hold an array that consists of a fixed number of Int64 values.

If the source VARIANT is of type VT_ARRAY OR VT_UI4, this function extracts up to crgn Int64 values and places them into the buffer pointed to by prgn. If the VARIANT contains more elements than will fit into the prgn buffer, this function returns 0.

## ToLongIntArrayAlloc

Extracts an array of LONGINT values from DVARIANT.

    FUNCTION ToLongIntArrayAlloc (BYVAL pprgn AS LONGINT PTR PTR) AS ULONG

Parameter | Description
--- | ---
pprgn | Pointer to a LONGINT PTR variable that will recive a pointer to an array of LONGINT values extracted from the source DVARIANT.

#### Return value

The count of LONGINT elements extracted from the DVARIANT.

#### Remarks

This helper function is used when the calling application expects a DVARIANT to hold an array of LONGINT values.

If DVARIANT is of type VT_ARRAY OR VT_I8, this function extracts an array of LONGINT values into a newly allocated array. The calling application is responsible for using CoTaskMemFree to release the array pointed to by pprgn when it is no longer needed.

## ToShortArray

Extracts an array of Int16 values from DVARIANT.

    FUNCTION ToShortArray (BYVAL prgn AS SHORT PTR, BYVAL crgn AS ULONG) AS ULONG

Parameter | Description
--- | ---
prgn | Pointer to a buffer that contains crgn Int16 variables. When this function returns, the buffer has been initialized with Int16 elements extracted from DVARIANT.
crgn | The number of elements in the buffer pointed to by prgn.

#### Return value

The count of Int16 elements extracted from the DVARIANT.

#### Remarks

This helper function is used when the calling application expects a VARIANT to hold an array that consists of a fixed number of Int16 values.

If the source VARIANT is of type VT_ARRAY OR VT_I2, this function extracts up to crgn Int16 values and places them into the buffer pointed to by prgn. If the VARIANT contains more elements than will fit into the prgn buffer, this function returns 0.

## ToShortArrayAlloc

Extracts an array of SHORT values from DVARIANT.

    FUNCTION ToShortArrayAlloc (BYVAL pprgn AS SHORT PTR PTR) AS ULONG

Parameter | Description
--- | ---
pprgn | Pointer to a SHORT PTR variable that will recive a pointer to an array of SHORT values extracted from the source DVARIANT.

#### Return value

The count of SHORT elements extracted from the DVARIANT.

#### Remarks

This helper function is used when the calling application expects a DVARIANT to hold an array of SHORT values.

If DVARIANT is of type VT_ARRAY OR VT_I2, this function extracts an array of SHORT values into a newly allocated array. The calling application is responsible for using CoTaskMemFree to release the array pointed to by pprgn when it is no longer needed.

## ToStr

Extracts the content of the underlying variant and returns it as a DWSTRING.

    FUNCTION ToStr () AS DWSTRING

#### Return value

The contents of the variant as a DWSTRING.

#### Example

    DIM dv AS DVARIANT = "Test string"
    DIM dws AS DWSTRING = dv.ToStr

## ToStringArray

Extracts data from a vector structure into a PWSTR array.

    FUNCTION ToStringArray (BYVAL prgsz AS PWSTR, BYVAL crgsz AS ULONG) AS ULONG

Parameter | Description
--- | ---
prgsz | Pointer to a buffer that contains crgn PWSTR values. When this function returns, the buffer has been initialized with elements extracted from the source VARIANT structure.
crgsz | The number of elements in the buffer pointed to by prgsz.

#### Return value

The count of PWSTR elements extracted from the DVARIANT.

#### Remarks

This helper function is used when the calling application expects a DVARIANT to hold an array of PWSTR values. If the VARIANT contains more elements than will fit into the prgsz buffer, this function returns 0.

## ToStringArrayAlloc

Extracts an array of PWSTR values from DVARIANT.

    FUNCTION ToStringArrayAlloc (BYVAL pprgsz AS PWSTR PTR) AS ULONG

Parameter | Description
--- | ---
pprgsz | Pointer to a PWSTR PTR variable that will recive a pointer to an array of PWSTR values extracted from the source DVARIANT.

#### Return value

The count of PWSTR elements extracted from the DVARIANT.

#### Remarks

This helper function is used when the calling application expects a DVARIANT to hold an array of PWSTR values.

This function extracts an array of PWSTR values into a newly allocated array. The calling application is responsible for using CoTaskMemFree to free the memory used by each of the strings and to release the array pointed to by pprgn when it is no longer needed.

## ToStrRet

Returns the contents of a DVARIANT of type VT_BSTR to a STRRET stucture.

    FUNCTION ToStrRet () AS STRRET

#### Return value

A STRRET structure.

## ToSystemTime

Returns the contents of DVARIANT of type VT_DATE as a FILETIME structure.

    FUNCTION ToSystemTime () AS SYSTEMTIME

#### Return value

A SYSTEMTIME structure.

## ToULongArray

Extracts an array of ULONG values from DVARIANT.

    FUNCTION ToULongArray (BYVAL prgn AS ULONG PTR, BYVAL crgn AS ULONG) AS ULONG

Parameter | Description
--- | ---
prgn | Pointer to a buffer that contains crgn ULONG variables. When this function returns, the buffer has been initialized with UInt32 elements extracted from DVARIANT.
crgn | The number of elements in the buffer pointed to by prgn.

#### Return value

The count of UInt32 elements extracted from the DVARIANT.

#### Remarks

This helper function is used when the calling application expects a VARIANT to hold an array that consists of a fixed number of UInt32 values.

If the source VARIANT is of type VT_ARRAY OR VT_UI4, this function extracts up to crgn UInt32 values and places them into the buffer pointed to by prgn. If the VARIANT contains more elements than will fit into the prgn buffer, this function returns 0.

## ToULongArrayAlloc

Extracts an array of ULONG values from DVARIANT.

    FUNCTION ToULongArrayAlloc (BYVAL pprgn AS ULONG PTR PTR) AS ULONG

Parameter | Description
--- | ---
pprgn | Pointer to a ULONG PTR variable that will recive a pointer to an array of ULONG values extracted from the source DVARIANT.

#### Return value

The count of ULONG elements extracted from the DVARIANT.

#### Remarks

This helper function is used when the calling application expects a DVARIANT to hold an array of ULONG values.

If DVARIANT is of type VT_ARRAY OR VT_UI4, this function extracts an array of ULONG values into a newly allocated array. The calling application is responsible for using CoTaskMemFree to release the array pointed to by pprgn when it is no longer needed.

## ToULongIntArray

Extracts an array of ULONGINT values from DVARIANT.

    FUNCTION ToULongIntArray (BYVAL prgn AS ULONGINT PTR, BYVAL crgn AS ULONG) AS ULONG

Parameter | Description
--- | ---
prgn | Pointer to a buffer that contains crgn ULONGINT variables. When this function returns, the buffer has been initialized with UInt64 elements extracted from DVARIANT.
crgn | The number of elements in the buffer pointed to by prgn.

#### Return value

The count of UInt64 elements extracted from the DVARIANT.

#### Remarks

This helper function is used when the calling application expects a VARIANT to hold an array that consists of a fixed number of UInt64 values.

If the source VARIANT is of type VT_ARRAY OR VT_UI8, this function extracts up to crgn UInt64 values and places them into the buffer pointed to by prgn. If the VARIANT contains more elements than will fit into the prgn buffer, this function returns 0.

## ToULongIntArrayAlloc

Extracts an array of ULONGINT values from DVARIANT.

    FUNCTION ToULongIntArrayAlloc (BYVAL pprgn AS ULONGINT PTR PTR) AS ULONG

Parameter | Description
--- | ---
pprgn | Pointer to a ULONGINT PTR variable that will recive a pointer to an array of ULONGINT values extracted from the source DVARIANT.

#### Return value

The count of ULONGINT elements extracted from the DVARIANT.

#### Remarks

This helper function is used when the calling application expects a DVARIANT to hold an array of ULONGINT values.

If DVARIANT is of type VT_ARRAY OR VT_UI8, this function extracts an array of ULONGINT values into a newly allocated array. The calling application is responsible for using CoTaskMemFree to release the array pointed to by pprgn when it is no longer needed.

## ToUShortArray

Extracts an array of UInt16 values from DVARIANT.

    FUNCTION ToUShortArray (BYVAL prgn AS USHORT PTR, BYVAL crgn AS ULONG) AS ULONG

Parameter | Description
--- | ---
prgn | Pointer to a buffer that contains crgn UInt16 variables. When this function returns, the buffer has been initialized with UInt16 elements extracted from DVARIANT.
crgn | The number of elements in the buffer pointed to by prgn.

#### Return value

The count of UInt16 elements extracted from the DVARIANT.

#### Remarks

This helper function is used when the calling application expects a VARIANT to hold an array that consists of a fixed number of UInt16 values.

If the source VARIANT is of type VT_ARRAY OR VT_I2, this function extracts up to crgn UInt16 values and places them into the buffer pointed to by prgn. If the VARIANT contains more elements than will fit into the prgn buffer, this function returns 0.

## ToUShortArrayAlloc

Extracts an array of USHORT values from DVARIANT.

    FUNCTION ToUShortArrayAlloc (BYVAL pprgn AS USHORT PTR PTR) AS ULONG

Parameter | Description
--- | ---
pprgn | Pointer to a USHORT PTR variable that will recive a pointer to an array of USHORT values extracted from the source DVARIANT.

#### Return value

The count of USHORT elements extracted from the DVARIANT.

#### Remarks

This helper function is used when the calling application expects a DVARIANT to hold an array of USHORT values.

If DVARIANT is of type VT_ARRAY OR VT_UI2, this function extracts an array of SHORT values into a newly allocated array. The calling application is responsible for using CoTaskMemFree to release the array pointed to by pprgn when it is no longer needed.

## ToUtf8

Returns the contents of a DVARIANT containing a BSTR as an UTF-8 encoded string.

    FUNCTION ToUtf8 () AS STRING

#### Return value

The UTF-8 string.

## ToVbDate

Returns the contents of a DVARIANT of type VT_DATE as a DATE value.

    FUNCTION ToVbDate () AS DATE_

#### Return value

A DATE_ value (double).

## AfxDVarToStr

Extracts the contents of a DVARIANT to a DWSTRING.

    FUNCTION AfxDVarToStr (BYREF dv AS DVARIANT) AS DWSTRING

## AfxDVarToStr

Extracts the contents of a DVARIANT to a DWSTRING.

    FUNCTION AfxDVarToStr (BYVAL pdv AS DVARIANT PTR) AS DWSTRING
    #define DVAR_TOSTR(dv) AfxDVarToStr(dv)

## AfxDVarToBuffer

Extracts the contents of a variant that contains an array of bytes.

    FUNCTION AfxDVarToBuffer (BYREF cvIn AS DVARIANT, BYVAL pv AS LPVOID, BYVAL cb AS ULONG) AS HRESULT

Parameter | Description
--- | ---
cvIn | Reference to the source DVARIANT.
pv | Pointer to a buffer of length cb bytes. When this function returns, contains the first cb bytes of the extracted buffer value.
cb | The size of the pv buffer, in bytes. The buffer should be the same size as the data to be extracted, or smaller.

#### Return value

Returns one of the following values:

HRESULT code | Description
--- | ---
S_OK | Data successfully extracted.
E_INVALIDARG | The VARIANT was not of type VT_ARRRAY
E_FAIL | The VARIANT buffer value had fewer than cb bytes.

## AfxDVarOptPrm

Returns a DVARIANT suitable to be used with optional parameters.

    FUNCTION AfxDVarOptPrm () AS DVARIANT
    #define DVAR_OPTPRM AfxDVarOptPrm

#### Remarks

If you want to call a method that has optional variant parameters, you still have to pass the parameters, but in a way that the methods know that they were omitted. Specifically, you have to pass them as type VT_ERROR, code DISP_E_PARAM_NOT_FOUND.

    DIM v AS VARIANT = TYPE(VT_ERROR, 0, 0, 0, DISP_E_PARAMNOTFOUND)