System.VarClear Function

Empties a Variant, so that it is unassigned.

Pascal

procedure VarClear(V: Variant);

C++

VarClear(Variant V);

File

System

Description

Calling VarClear is equivalent to assigning the Unassigned constant to the Variant. V can be either a Variant or an OleVariant, but it must be possible to assign a value to it (it must be an lvalue).

After calling VarClear, the VarIsEmpty function returns true, and the VarType function returns varEmpty. Using an unassigned variant in an expression causes an exception to be thrown. Likewise, if you attempt to convert an unassigned Variant to another type (using VarAsType ), an exception is thrown.

Note: Do not confuse clearing a Variant, which leaves it unassigned, with assigning a Null value. A Null Variant is still assigned, but has the value Null. Unlike unassigned Variants, Null Variants can be used in expressions and can be converted to other types of Variants.

C++ Examples:

Copy Code

/*
This example shows how to use the TVarData type in typecasts
of Variant variables to access the internals of a variable.
*/
#include <memory>       //for STL auto_ptr class

void __fastcall TForm1::Button1Click(TObject *Sender)
{
  Variant V;
  AnsiString mystr;
  if (TVarData(V).VType == varEmpty)
    ListBox1->Items->Add("Variants start empty.");
  VarClear(V);
  TVarData(V).VType = varString;
  mystr = "Here is my string";
  std::auto_ptr<char> MyBuffer(new char[mystr.Length() + 1]);
  StrCopy(MyBuffer.get(), mystr.c_str());
  TVarData(V).VString  = MyBuffer.get();
  mystr = PAnsiChar(TVarData(V).VString);
  ListBox1->Items->Add("This variant is now a string: " + mystr);
  VarClear(V);
  TVarData(V).VType = varInteger;
  TVarData(V).VInteger = 1234567;
  ListBox1->Items->Add("This variant is now an integer: " + IntToStr(TVarData(V).VInteger));
}

Delphi Examples:

Copy Code

{{
This example shows how to use the TVarData type in typecasts
of Variant variables to access the internals of a variable.
}
procedure TForm1.Button1Click(Sender: TObject);
var
  V: Variant;
  mystr: string;
  MyBuffer: PChar;
begin
  if TVarData(V).VType = varEmpty then
    ListBox1.Items.Add('Variants start empty.');
  VarClear(V);
  TVarData(V).VType := varString;
  mystr := 'Here is my string';
  MyBuffer:= GetMemory(Length(mystr));
  StrCopy(MyBuffer, PChar(mystr));
  TVarData(V).VString := MyBuffer;
  ListBox1.Items.Add('This variant is now a string: ' + PChar(TVarData(V).VString));
  VarClear(V);
  TVarData(V).VType := varInteger;
  TVarData(V).VInteger := 1234567;
  ListBox1.Items.Add('This variant is now an integer: ' + IntToStr(TVarData(V).VInteger));
end;