Variants.VarArrayCreate Function

Creates a variant array.

Pascal

function VarArrayCreate(const Bounds: array of Integer; AVarType: TVarType): Variant;

C++

Variant VarArrayCreate(const array of Integer Bounds, TVarType AVarType);

File

Variants

Description

VarArrayCreate creates a variant array with the bounds given by Bounds and the element type given by VarType.

The Bounds parameter must contain an even number of values, where each pair of values specifies the upper and lower bounds of one dimension of the array.

Note: The Bounds_size parameter is the index of the last value in the Bounds array. This is one less than the total number of values. Thus, Bounds_size must always be an odd number.

The element type of the array, given by the VarType parameter, is a variant type code. This must be one of the constants defined in the System unit. It cannot include the varArray or varByRef bits. The element type cannot be varString or a custom System::Variant type. To create a variant array of strings use the varOleStr type code. If the element type is varVariant, the elements of the array are themselves variants and can in turn contain variant arrays.

If VarArrayCreate is unable to create the array, an EVariantArrayCreateError is raised.

Note: :Variant arrays with an element type of varByte are the preferred method of passing binary data between OLE Automation controllers and servers. Such arrays are subject to no translation of their data, and can be efficiently accessed using the VarArrayLock and VarArrayUnlock routines.

There's corresponding functionality under Linux. Should document when time permits.

C++ Examples:

Copy Code

/*
This example demonstrates the use of variant arrays. In this
example a variant array is created, modified, populated and then freed.
*/
void __fastcall TForm1::Button1Click(TObject *Sender)
{
    Variant array;
    int bounds[2] = {0, 9};

    /*
    Create a variant array of 10 elements, starting at 0
    and ending at 9. The array contains elements of type integer
    */
    array = VarArrayCreate(bounds, 1, varInteger);

    // Increase the length of the variant array
    VarArrayRedim(array, 49);

    MessageDlg(String("Variant array has ") + IntToStr(VarArrayDimCount(array)) +
        " dimensions", mtInformation, TMsgDlgButtons() << mbOK, 0);

    // Traverse the array from lower to higher bounds
    for (int i = VarArrayLowBound(array, 1); i <= VarArrayHighBound(array, 1); i++)
    {
        // Put the element I at index I
        VarArrayPut(array, i, &i, 0);
    }

    // Now read the elements of the array
    for (int i = VarArrayLowBound(array, 1); i <= VarArrayHighBound(array, 1); i++)
    {
        // Put the element I at index I
        if (VarArrayGet(array, &i, 0) != i)
            MessageDlg("Error! Invalid element found at current position!",
                mtError, TMsgDlgButtons() << mbOK, 0);
    }

    // Clear the variant array
    VarClear(array);
}

Delphi Examples:

Copy Code

{
This example demonstrates the use of variant arrays. In this
example a variant array is created, modified, populated and then freed.
}
procedure TForm1.Button1Click(Sender: TObject);
var
  Arr: Variant;
  I: Integer;
begin
  { Create a variant array of 10 elements, starting at 0
    and ending at 9. The array contains elements of type integer }
  Arr := VarArrayCreate([0, 9], varInteger);

  { Increase the length of the variant array }
  VarArrayRedim(Arr, 49);

  MessageDlg('Variant array has ' + IntToStr(VarArrayDimCount(Arr)) + ' dimensions',
      mtInformation, [mbOK], 0);

  { Traverse the array from lower to higher bounds }
  for I := VarArrayLowBound(Arr, 1) to VarArrayHighBound(Arr, 1) do
  begin
    { Put the element I at index I}
    VarArrayPut(Arr, I, [I]);
  end;

  { Now read the elements of the array }
  for I := VarArrayLowBound(Arr, 1) to VarArrayHighBound(Arr, 1) do
  begin
    { Put the element I at index I}
    if VarArrayGet(Arr, [I]) <> I then
      MessageDlg('Error! Invalid element found at current position!', mtError, [mbOK], 0);
  end;

  { Clear the variant array }
  VarClear(Arr);
end;