Variants unit

The compiler has built-in support for variants, and for many operations, variants can be used without thinking about it. The system unit has built-in support for some of the basic operations on a variant, as well as some compiler helper routines. However, some operations and definitions are implemented in the Variants unit so as not to burden the system unit with routines that may not always be needed.

There is a basic set of variants that are defined by the Windows OS, these are supported by the compiler and the routines in the Variants unit. Additional variant types can be registered using the TCustomVariantType type.

The variants unit also registers a handler for setting published properties (using RTTI) using variant-typed values. Nothing needs to be done for this except including the variants unit in your program.

Classes and records

EVariantArrayCreateError	class	Error raised when a problem is detected during creation of an array.
EVariantArrayLockedError	class	Error raised when an operation on a locked array is performed.
EVariantBadIndexError	class	Error raised when an invalid array index is detected.
EVariantBadVarTypeError	class	>Error raised when an invalid variant type is detected.
EVariantDispatchError	class	Exception raised in case of variant dispatching errors.
EVariantInvalidArgError	class	Error raised when an invalid argument is detected.
EVariantInvalidNullOpError	class	Variant invalid null operation error.
EVariantInvalidOpError	class	Error raised when an invalid operation is performed.
EVariantNotAnArrayError	class	Error raised when an array operation is performed on a non-array variant.
EVariantNotImplError	class	Error raised when a variant operation not implemented.
EVariantOutOfMemoryError	class	Error to signal an out-of-memory condition.
EVariantOverflowError	class	Error raised when an overflow error is detected.
EVariantParamNotFoundError	class	Error raised when a parameter is not found.
EVariantRangeCheckError	class	Exception class to signal range checks.
EVariantTypeCastError	class	Error raised when an invalid typecast is performed.
EVariantUnexpectedError	class	Exception raised during unexpected error.
IVarInstanceReference	interface	Interface for variants that refer to an object.
IVarInvokeable	interface	Interface needed for custom variants that need to implement dynamic properties and methods.
TCustomVariantType	class	Base class for a custom variant type.
TInvokeableVariantType	class	TCustomVariantType descendent that implements DispInvoke.
TPublishableVariantType	class	TInvokeableVariantType descendent that implements reading published properties.

Procedures and functions

assign(TNullPtr):Variant	operator
DynArrayFromVariant	procedure	Convert a variant to a dynamic arrayt.
DynArrayToVariant	procedure	Convert a Dynamic Array To a Variant.
FindCustomVariantType	function	Find a custom variant class on vartype.
FindVarData	function	Return a pointer to variant data.
GetPropValue	function	Return a property value as a variant.
GetVariantProp	function	Get variant valued property.
HandleConversionException	procedure	Convert an exception to a variant exception.
Null	function	Return a null variant.
SetClearVarToEmptyParam	procedure	Create an error variant with value VAR_PARAMNOTFOUND.
SetPropValue	procedure	Set a property value as a variant.
SetVariantProp	procedure	Set variant valued property.
Unassigned	function	Return an unassigned variant.
VarArrayAsPSafeArray	function	Return internal array of variant value.
VarArrayCreate	function	Create a variant array.
VarArrayCreateError	procedure	Raise an EVariantArrayCreateError error.
VarArrayDimCount	function	Return the number of dimensions of the array.
VarArrayHighBound	function	Return lower bound of an array.
VarArrayLock	function	get a pointer to data of a variant array.
VarArrayLockedError	procedure	Raise an EVariantArrayLockedError error.
VarArrayLowBound	function	Return lower bound of an array.
VarArrayOf	function	Create a variants array of a series of values.
VarArrayRef	function	Get a reference to a variant array.
VarArrayUnlock	procedure	Release data captured by VarArrayLock.
VarAsError	function	Create an error-typed variant.
VarAsType	function	Attempt to cast a variant to another type.
VarBadIndexError	procedure	Raise an EVariantBadIndexError error.
VarBadTypeError	procedure	Raise an EVariantBadVarTypeError error.
VarCastError	procedure	Raise a variant type cast error EVariantTypeCastError.
VarCastErrorOle	procedure	Raise a variant type cast error EVariantTypeCastError.
VarCheckEmpty	procedure	Raise exception if a variant is empty.
VarClear	procedure	Clear the variant value.
VarCompareValue	function	Compare 2 variant values.
VarCopyNoInd	procedure	Not supported.
VarEnsureRange	function	Make sure the variant is within a specified range.
VarFromDateTime	function	Create variant from TDateTime value.
VarInRange	function	Check if a variant is in a range of values.
VarInvalidArgError	procedure	Raise an EVariantInvalidArgError error.
VarInvalidNullOp	procedure	Raise an EVariantInvalidOpError error.
VarInvalidOp	procedure	Raise a EVariantInvalidOpError error.
VarIsArray	function	Check whether a variant is an array.
VarIsBool	function	Check if the variant is a boolean.
VarIsByRef	function	Check if the variant is a reference to a value.
VarIsClear	function	Check if a variant is clear.
VarIsCustom	function	Check if the variant is a custom value.
VarIsEmpty	function	Check if the variant is empty.
VarIsEmptyParam	function	Check if the variant is an error value for VAR_PARAMNOTFOUND.
VarIsError	function	Check if the variant has type varError.
VarIsFloat	function	Check if the variant is a floating-point value.
VarIsNull	function	Check if a variant is null.
VarIsNumeric	function	Check if the variant is a numerical value.
VarIsOrdinal	function	Check if the variant is an ordinal value.
VarIsStr	function	Check if the variant is a string.
VarIsType	function	Check if a variant is of certain type.
VarNotImplError	procedure	Raise an EVariantNotImplError error.
VarOutOfMemoryError	procedure	Raise an EVariantOutOfMemoryError error.
VarOverflowError	procedure	Raise an EVariantOverflowError error.
VarRangeCheckError	procedure	Raise an EVariantOverflowError error.
VarResultCheck	procedure	Check the result of an operation and raise exception if not OK.
VarSameValue	function	Check if 2 variants are the same.
VarSupports	function	Check if a variant supports an interface.
VarToDateTime	function	Convert a variant to datetime value.
VarToStr	function	Convert a variant to string value.
VarToStrDef	function	Convert a variant to string value, specifying a default.
VarToUnicodeStr	function	Convert a variant to string value.
VarToUnicodeStrDef	function	Convert a variant to string value, specifying a default.
VarToWideStr	function	Convert a variant to string value.
VarToWideStrDef	function	Convert a variant to string value, specifying a default.
VarType	function	Return the type of a variant.
VarTypeAsText	function	Return a textual description of the variant type.
VarTypeDeRef	function	Returns the resolved type of a variant.
VarTypeIsValidArrayType	function	Check if a variant type can be used in an array.
VarTypeIsValidElementType	function	Check if a variant type can be used in an array.
VarUnexpectedError	procedure	Raise an EVariantUnexpectedError error.

Types

TAnyProc	procedure type	Callback handler to clear variants of type Any.
TBooleanToStringRule	enumeration	Enumeration describing how to convert boolean values to string values.
TCustomVariantTypeClass	type	Class of TCustomVariantType.
TNullCompareRule	enumeration	Enumeration describing how to handle Null values when comparing variants.
TVarCompareResult	enumeration	Compare 2 variant values.
TVarDataArray	type	Dynamic array of vardata records.
TVarDispProc	procedure type	Callback to perform dispatch call on variant.
TVariantRelationship	enumeration	Enumerated type to describe comparison operations between variants.

Constants

CFirstUserType	constant	First allocated user type.
CIncVarType	constant	Increment above CMinVarType.
CMaxNumberOfCustomVarTypes	constant	Maximum amount of custom variant types.
CMaxVarType	constant	Maximum value for variant type.
CMinVarType	constant	First allowed custom variant type index.
FloatVarTypes	constant	Constant describing which variant types are considered floating point types.
OrdinalVarTypes	constant	Constant describing which variant types are considered ordinals.
VarOpAsText	constant	Names of operations.

Variables

ChangeAnyProc	variable	Not used.
ClearAnyProc	variable	Procedure called to clear a variant.
EmptyParam	variable	Empty parameter variant.
InvalidCustomVariantType	variable	Handler for invalid custom variants.
NullAsStringValue	variable	String value to use when converting a Null to a string.
NullEqualityRule	variable	Variable describing what to do when checking for equality of Null values.
NullMagnitudeRule	variable	Variable describing what to do when checking for order of Null values.
NullStrictConvert	variable	What to do when converting Null to another type.
OleVariantInt64AsDouble	variable	How to convert Int64 variants.
PackVarCreation	variable	Size to use when creating an array of integers.
RefAnyProc	variable	Handler called to obtain a reference to a varAny typed variant.
VarDispProc	variable	Handler called by DispInvoke.

Uses

• sysutils
• sysconst
• rtlconsts
• TypInfo
• Types