Welcome to the new DelphiDabbler Code Library Documentation.

This is a new site that's currently running on alpha code. There are going to be bugs. If you discover any, please report them on the site's issues page (GitHub account required). Thanks.

Warning: Many URLs are going to change. Refer to the README file to discover which library project's documentation has been completed.

Insert<T> class method

Project: Array Utilities Unit

Unit: DelphiDabbler.Lib.ArrayUtils

Record: TArrayUtils

Applies to: ~>0.1

class procedure Insert<T>(var A: TArray<T>; AValue: T; AIndex: Integer);
  overload; static;

class procedure Insert<T>(var A: TArray<T>; const AValues: array of T;
  AIndex: Integer);
  overload; static;

Description

Inserts an element, or an array of elements, at a given index in an array.

The length of the array is increased by the number if elements inserted.

Parameters:

Example

Eample #1

This first example inserts single elements before the middle, first and last elements of an array of integers and finally appends an element to the array.

procedure Insert_Eg1;
var
  A, Expected: TArray<Integer>;
begin
  A := TArray<Integer>.Create(1, 2, 3, 4, 5);

  TArrayUtils.Insert<Integer>(A, 6, 2);  // insert before middle item
  Expected := TArray<Integer>.Create(1, 2, 6, 3, 4, 5);
  Assert(TArrayUtils.Equal<Integer>(Expected, A));

  TArrayUtils.Insert<Integer>(A, 7, 0);  // insert before first item
  Expected := TArray<Integer>.Create(7, 1, 2, 6, 3, 4, 5);
  Assert(TArrayUtils.Equal<Integer>(Expected, A));

  TArrayUtils.Insert<Integer>(A, 8, 6);  // insert before last item
  Expected := TArray<Integer>.Create(7, 1, 2, 6, 3, 4, 8, 5);
  Assert(TArrayUtils.Equal<Integer>(Expected, A));

  TArrayUtils.Insert<Integer>(A, 9, 8);  // insert after last item
  Expected := TArray<Integer>.Create(7, 1, 2, 6, 3, 4, 8, 5, 9);
  Assert(TArrayUtils.Equal<Integer>(Expected, A));
end;

Example #2

The second example inserts an array of integers into other such arrays, at the start, in the middle and at the end of the target array.

procedure Insert_Eg2;
var
  ATarget, AInsert, AExpected: TArray<Integer>;
begin
  AInsert := TArray<Integer>.Create(42, 56);

  // Insert non-empty array at end of ATarget non-empty array
  ATarget := TArray<Integer>.Create(1, 2, 3, 4, 5);
  TArrayUtils.Insert<Integer>(ATarget, AInsert, Length(ATarget));
  AExpected := TArray<Integer>.Create(1, 2, 3, 4, 5, 42, 56);
  Assert(TArrayUtils.Equal<Integer>(AExpected, ATarget));

  // Insert non-empty array in middle of non-empty array
  ATarget := TArray<Integer>.Create(2, 4, 6, 8, 10);
  TArrayUtils.Insert<Integer>(ATarget, AInsert, 3);
  AExpected := TArray<Integer>.Create(2, 4, 6, 42, 56, 8, 10);
  Assert(TArrayUtils.Equal<Integer>(AExpected, ATarget));

  // Insert non-empty array before start of ATarget non-empty array
  ATarget := TArray<Integer>.Create(1, 2, 3);
  TArrayUtils.Insert<Integer>(ATarget, AInsert, 0);
  AExpected := TArray<Integer>.Create(42, 56, 1, 2, 3);
  Assert(TArrayUtils.Equal<Integer>(AExpected, ATarget));
end;

See Also