Skip to content

TArrayUtils-Chop.md

Latest commit

 

History

History
122 lines (91 loc) · 4.55 KB

TArrayUtils-Chop.md

File metadata and controls

122 lines (91 loc) · 4.55 KB

Chop<T> class method

Project: Array Utilities Unit

Unit: DelphiDabbler.Lib.ArrayUtils

Record: TArrayUtils

Applies to: ~>0.1

class function Chop<T>(var A: TArray<T>;
  AStartIndex, AEndIndex: Integer): TArray<T>;
  overload; static;

class function Chop<T>(var A: TArray<T>; AStartIndex: Integer): TArray<T>;
  overload; static;

Description

Removes a contiguous range of elements from an array and returns an array containing the removed elements.

The elements of the returned array are shallow copies of the corresponding elements of the original array, so any references within the resulting array are the same as those in the initial array.

The original array is updated in place.

Parameters:

  • A - The array from which the range of elements is to be chopped. If A is empty then an empty array is always returned.

  • AStartIndex - The index of the first element of A that is to be included in the removed section.

    If AStartIndex ≤ 0 then the removed section begins at the first element of A.

    If AStartIndex ≥ Length(A) then nothing is deleted and an empty array is returned.

  • AEndIndex - Optional parameter that specifies the index of the last element of A that is to be included in the removed section.

    If AEndIndex is omitted or AEndIndex ≥ Length(A) then the removed section continues to the end of A.

    If AEndIndex < AStartIndex then nothing is deleted and an empty array is returned.

Returns:

  • An array containing the elements of that were removed from A.

Note

If the returned array needs to have deep copies of the deleted array elements then pass the return value of Chop<T> to the deep copying overload of Copy<T>, along with a suitable TCloner<T> implementation.

Examples

Example #1

This example shows the most flexible use of Chop<T> where both the start and end indexes are provided:

procedure Chop_Eg1;
var
  A, ATest, ASlice, AExpectedSlice, AExpectedRemainder: TArray<string>;
begin
  A := TArray<string>.Create('a', 'stitch', 'in', 'time', 'saves', 'nine');
  // slice from the start of A
  ATest := Copy(A);
  ASlice := TArrayUtils.Chop<string>(ATest, 0, 2);
  AExpectedRemainder := TArray<string>.Create('time', 'saves', 'nine');
  AExpectedSlice := TArray<string>.Create('a', 'stitch', 'in');
  Assert(TArrayUtils.Equal<string>(AExpectedRemainder, ATest, SameStr));
  Assert(TArrayUtils.Equal<string>(AExpectedSlice, ASlice, SameStr));
  // Chop in the middle of ATest
  ATest := Copy(A);
  ASlice := TArrayUtils.Chop<string>(ATest, 2, 4);
  AExpectedRemainder := TArray<string>.Create('a', 'stitch', 'nine');
  AExpectedSlice := TArray<string>.Create('in', 'time', 'saves');
  Assert(TArrayUtils.Equal<string>(AExpectedRemainder, ATest, SameStr));
  Assert(TArrayUtils.Equal<string>(AExpectedSlice, ASlice, SameStr));
  // Chop at the end of ATest
  ATest := Copy(A);
  ASlice := TArrayUtils.Chop<string>(ATest, 4, 5);
  AExpectedRemainder := TArray<string>.Create('a', 'stitch', 'in', 'time');
  AExpectedSlice := TArray<string>.Create('saves', 'nine');
  Assert(TArrayUtils.Equal<string>(AExpectedRemainder, ATest, SameStr));
  Assert(TArrayUtils.Equal<string>(AExpectedSlice, ASlice, SameStr));
end;

Example #2

This second example show the use of the basic version of Chop<T> where only the start index is provided:

procedure Chop_Eg2;
var
  A, ATest, ASlice, AExpectedSlice, AExpectedRemainder: TArray<string>;
begin
  A := TArray<string>.Create('a', 'stitch', 'in', 'time', 'saves', 'nine');
  // slice from mid to end of A
  ATest := Copy(A);
  ASlice := TArrayUtils.Chop<string>(ATest, 3);
  AExpectedRemainder := TArray<string>.Create('a', 'stitch', 'in');
  AExpectedSlice := TArray<string>.Create('time', 'saves', 'nine');
  Assert(TArrayUtils.Equal<string>(AExpectedRemainder, ATest, SameStr));
  Assert(TArrayUtils.Equal<string>(AExpectedSlice, ASlice, SameStr));
  // Chop of all of ATest
  ATest := Copy(A);
  ASlice := TArrayUtils.Chop<string>(ATest, 0);
  AExpectedRemainder := TArray<string>.Create();
  AExpectedSlice := Copy(A);
  Assert(TArrayUtils.Equal<string>(AExpectedRemainder, ATest, SameStr));
  Assert(TArrayUtils.Equal<string>(AExpectedSlice, ASlice, SameStr));
end;

See Also