Fun with enumerators, part 3 - parameterized enumerators

[Part 1 - Introduction, Part 2 - Additional enumerators.]

In first two installments of this series, we took a look at for..in statement, described Delphi support for custom enumerators and demonstrated one possible way to add additional enumerator to a class that already implements one.

Today we'll implement a parameterized enumerator. Enumerators of this kind can be especially handy when used as filters. For example, an enumerator that takes a class reference as a parameter can be used to filter a TObjectList containing objects of many different classes.

IOW, we would like to write a following construct: for obj in list.Enum(TSomeClass) do. Clearly, Enum cannot be a property anymore, but it can be a function.

We can still use an enumerator factory object stored inside our class (as in the Part 2). Besides that, we must implement enumeration function that will take one or more parameters, preserve them inside the factory object and return the factory object so that Delphi compiler can call its GetEnumerator function.

Sounds complicated but in reality it really is simple.

First we have to add an internal factory object and an enumeration function to the TCustomStringList class.

  TCustomStringList = class(TStringList)
  private
    FEnumEveryNth: TCSLEnumEveryNthFactory;
  public
    constructor Create;
    destructor  Destroy; override;
    function SkipEveryNth(skip: integer): TCSLEnumEveryNthFactory;
  end;

constructor TCustomStringList.Create;
begin
  inherited;
  FEnumEveryNth := TCSLEnumEveryNthFactory.Create(Self);
end;

destructor TCustomStringList.Destroy;
begin
  FEnumEveryNth.Free;
  inherited;
end;

function TCustomStringList.SkipEveryNth(skip: integer): TCSLEnumEveryNthFactory;
begin
  FEnumEveryNth.Skip := skip;
  Result := FEnumEveryNth;
end;

Enumeration function SkipEveryNth takes one parameter and passes it to the factory object. Then it returns this factory object.

We also need a new factory class. This is an extended version of factory class from Part 2. It must implement storage for all enumerator parameters. In this case, this storage is implemented via property Skip.

  TCSLEnumEveryNthFactory = class
  private
    FOwner: TCustomStringList;
    FSkip: integer;
  public
    constructor Create(owner: TCustomStringList);
    function GetEnumerator: TCSLEnumEveryNth;
    property Skip: integer read FSkip write FSkip; 
  end;

constructor TCSLEnumEveryNthFactory.Create(owner: TCustomStringList);
begin
  inherited Create;
  FOwner := owner;
  FSkip := 1;
end;

function TCSLEnumEveryNthFactory.GetEnumerator: TCSLEnumEveryNth;
begin
  Result := TCSLEnumEveryNth.Create(FOwner, FSkip);
end;

As you can see, GetEnumerator was also changed - in addition to passing FOwner to the created enumerator, it also passes current value of the Skip property.

New enumerator is very similar to the one from the Part 2, except that it advances list index by the specified ammount (instead of advancing it by 2).

  TCSLEnumEveryNth = class
  private
    FOwner: TCustomStringList;
    FListIndex: integer;
    FSkip: integer;
  public
    constructor Create(owner: TCustomStringList; skip: integer);
    function GetCurrent: string;
    function MoveNext: boolean;
    property Current: string read GetCurrent;
  end;

constructor TCSLEnumEveryNth.Create(owner: TCustomStringList; skip: integer);
begin
  FOwner := owner;
  FListIndex := -skip;
  FSkip := skip;
end;

function TCSLEnumEveryNth.GetCurrent: string;
begin
  Result := FOwner[FListIndex];
end;

function TCSLEnumEveryNth.MoveNext: boolean;
begin
  Inc(FListIndex, FSkip);
  Result := (FListIndex < FOwner.Count);
end;

We can now write some test code.

procedure TfrmFunWithEnumerators.btnSkipEveryThirdClick(Sender: TObject);
var
  ln: string;
  s : string;
begin
  ln := '';
  for s in FslTest.SkipEveryNth(3) do
    ln := ln + s;
  lbLog.Items.Add('Parameterized enumerator: ' + ln);
end;

Delphi compiler will translate this for..in roughly into

enumerator := FslTest.SkipEveryNth(3).GetEnumerator;
while enumerator.MoveNext do
  ln := ln + enumerator.Current;
enumerator.Free;

So what is going on here?

1. FslTest.SkipEveryNth(3) sets  FslTest.FEnumEveryNth.Skip to 3 and returns FslTest.FEnumEveryNth.
   
   
2. Compiler calls FslTest.FEnumEveryNth.GetEnumerator.
   
   
3. FslTest.FEnumEveryNth,GetEnumerator calls TCSLEnumEveryNth.Create(FslTest, 3) and returns newly created object.
   
   
4. Enumerator loops until MoveNext returns false.

Test code result:

Tomorrow we'll do something even more interesting - we'll add new enumerator to existing class without creating a derived class.

Technorati tags: Delphi, enumerators, iterators