System.Variants.Null

From RAD Studio API Documentation
Jump to: navigation, search

Delphi

function Null: Variant;

C++

extern DELPHI_PACKAGE System::Variant __fastcall Null(void);

Properties

Type Visibility Source Unit Parent
function public
System.Variants.pas
System.Variants.hpp
System.Variants System.Variants

Description

Returns a Null variant.

Use Null to obtain a Null variant that can indicate unknown or missing data. Null Variants can be assigned to variant variables in an application that must contain a null value. Assigning Null to a variant variable does not cause an error, and Null can be returned from any function with a variant return value.

Assigning Null to a variable of any type other than Variant causes either a compile-time error or raises an EVariantTypeMismatch exception. For example, in the following code the assignment of v, the Null variant, to variant q is successful; whereas the conversion of variant v, which is now Null, to the integer return type of the Test function, raises an exception.

function Test(v: Variant): Integer;
var
  q: Variant;
  msg: string;
begin
  q := v; { this is ok, since q is a variant }
  if VarIsNull(q) then
    msg := 'q is a null variant'
  else
    msg := 'q is not a null variant';
  ShowMessage(msg);
  Result := v; { this raises an exception!!!}
end;

procedure TForm1.Button1Click(Sender: TObject);
begin
  Test(Null);
end;
int Test(Variant v)
{
  Variant q = v; // this is ok, since q is a variant
  AnsiString msg;
  if (VarIsNull(q))
    msg = "q is a null variant";
  else
    msg = "q is not a null variant";
  ShowMessage(msg);
  return v; // this throws an exception!!!
}

void __fastcall TForm1::Button1Click(TObject *Sender)
{
  Test(Null());
}

Except for comparisons, which always result in Boolean values, expressions involving Null variants always result in Null variants.

Note: The Null variant returned by the Null function is different from the nil constant in Delphi code and the NULL macro in C++ code. Neither nil nor NULL is a variant. The nil constant is an object reference that does not refer to any actual object. The NULL macro is a pointer that does not refer to any actual object or value.

See Also