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.

Pick<T> class method

Project: Array Utilities Unit

Unit: DelphiDabbler.Lib.ArrayUtils

Record: TArrayUtils

Applies to: ~>0.1

class function Pick<T>(const A: array of T;
  const AIndices: array of Integer): TArray<T>;
  static;

Description

Returns an array containing elements copied from given indices in an array.

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 not modified.

Parameters:

Returns:

Notes

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

  2. To ensure that the returned elements are in the same order they occur in A then AIndices must be sorted in ascending order. This can be achieved by passing the array of required indices to either the CopySorted<Integer> or Sort<Integer> methods.

  3. If only one copy of each element at a given index is to be picked then ensure that AIndices contains no duplicates. The DeDup<Integer> method can be used to achieve this.

Example

procedure Pick_Eg;
var
  A, AGot, AExpected: TArray<string>;
  Indices: TArray<Integer>;
begin
  A := TArray<string>.Create('a', 'stitch', 'in', 'time', 'saves', 'nine');

  // extract a single element of A
  AGot := TArrayUtils.Pick<string>(A, [2]);
  AExpected := TArray<string>.Create('in');
  Assert(TArrayUtils.Equal<string>(AExpected, AGot, SameStr));

  // Pick the elements of A with odd indices, in the original order
  AGot := TArrayUtils.Pick<string>(A, [1, 3, 5]);
  AExpected := TArray<string>.Create('stitch', 'time', 'nine');
  Assert(TArrayUtils.Equal<string>(AExpected, AGot, SameStr));

  // Pick one or more copies of specified elements of A, in a different order
  // to their order in A
  AGot := TArrayUtils.Pick<string>(A, [5, 3, 1, 5]);
  AExpected := TArray<string>.Create('nine', 'time', 'stitch', 'nine');
  Assert(TArrayUtils.Equal<string>(AExpected, AGot, SameStr));

  // Pick two unique elements of A, ignoring out of range elements
  AGot := TArrayUtils.Pick<string>(A, [0, -1, Length(A), Length(A)-1]);
  AExpected := TArray<string>.Create('a', 'nine');
  Assert(TArrayUtils.Equal<string>(AExpected, AGot, SameStr));

  // Return elements in the same order they appear in A, with no duplicates
  Indices := TArrayUtils.CopySorted<Integer>(
    TArrayUtils.DeDup<Integer>([3, 1, 2, 2, 3, 2])
  );
  AGot := TArrayUtils.Pick<string>(A, Indices);
  AExpected := TArray<string>.Create('stitch', 'in', 'time');
  Assert(TArrayUtils.Equal<string>(AExpected, AGot, SameStr));
end;

See Also