Amazon.com Widgets Enumerating and the for…in Loop

Enumerating and the for…in Loop

By Nick at January 12, 2013 15:05
Filed Under: Delphi, Software Development

One of those fun little issues in our business is trying to figure out the difference between iterating and enumerating.  This StackOverflow answer does a pretty good job of explaining it.  Iterating is doing something – usually a series of steps – over and over again.  Enumerating is going over each item in a given collection.  A subtle difference, sure.  One usually iterates when enumerating. 

Okay, so enumerating is going over each item in a collection.  IEnumerable can enumerate over the items in a collection as we saw in my last article.  But you can enumerate over other things as well.  For instance, in Delphi, you can use the for…in statement to enumerate over the characters in a string. 

But this makes me wonder:  how does something become, well, enumeratable?  How do you make something so that you can use with the for…in statement? 

Well, it’s pretty easy.  The rules for Delphi are simple:

  • To create a class or record to enumerate, it must provide a method called GetEnumerator() which in turn needs to be a function that returns a class, an interface, or a record that is an enumerator.
  • To be returned as an enumerator, that class, record, or implemented interface needs to have the following:
    • A method called MoveNext that returns a Boolean indicating whether the end as been reached or not
    • A read-only property called Current that indicates the item that is currently being “looked at” as the enumeration occurs. 

So, at this point, a simple demo would be helpful, eh?

You can already enumerate the characters in a string, but it’s a simple example, and so the following example implements this easy to understand enumeration on a string:

TForInDemoClassEnumerator = class
  private
    FString: string;
    FIndex: integer;
  protected
    function GetCurrent: Char; virtual;
  public
    constructor Create(aString: string);
    function MoveNext: Boolean;
    property Current: Char read GetCurrent;
  end;

TForInDemo = class
  private
    FTheString: string;
    procedure SetTheString(const Value: string);
  public
    constructor Create(aString: string);
    function GetEnumerator: TForInDemoClassEnumerator;
    property TheString: string read FTheString write SetTheString;
  end;

 

This code declares two classes.  The first class is the enumerator – the class that does the work of  moving over each item, and which will be returned by the call to GetEnumerator.  The second is the class that will be enumerated.  Notice, too, that TForInDemoClassEnumerator has the read-only property Current with the reader GetCurrent and MoveNext methods.  The TForInDemo class has a call to GetEnumerator that returns an instance of TForInDemoClassEnumerator

First let’s look at TForInDemoClassEnumerator.  You create it by passing the constructor the item to be enumerated – in this case a string.  Hence, the constructor:

constructor Create(aString: string);

Here is the implementation of the MoveNext method:

function TForInDemoClassEnumerator.MoveNext: Boolean;
begin
  Result := FIndex < FString.Length;
  if Result then
  begin
    Inc(FIndex);
  end;
end;

This code does two things.  First, it sets the result. The function returns True if the enumerator is able to move to the next item, and False if it has reached the end of the items to be enumerated.  In this case, it merely checks to see the index is before the length of the string.   If the end has not yet been reached, it just increases the FIndex field.  So it’s job here is merely to move the index along, and report if the end has been reached.

The actual item itself is returned by the GetCurrent method, which is self-explanatory:

function TForInDemoClassEnumerator.GetCurrent: Char;
begin
  Result := FString[FIndex];
end;

And that is it for the enumerator.  It’s pretty simple.  But we’ll soon see that you can do some cool things with these enumerators because you have complete control over how they return the data that they are enumerating over.

The next step is to see how the actual class to be enumerated provides its enumerator to the compiler.  When the compiler builds the for…in loop construct, it looks at the in part of the construct and thinks “Hey, I need an enumerator here, so I’ll call GetEnumerator”.  If the item in question indeed has a method called GetEnumerator, it calls it, and all is well.  If not, the compiler raises an error because the type in the in part of the for…in loop isn’t enumeratable. 

But of course, our TForInDemo class has such a method, and it is quite simple:

function TForInDemo.GetEnumerator: TForInDemoClassEnumerator;
begin
  Result := TForInDemoClassEnumerator.Create(FTheString);
end;

It merely creates and returns an instance of our enumerator, passing it the string value it is storing for the purpose of enumerating.   Pretty easy and straight forward, really.

Now that we’ve created all these classes, you can run the following code:

procedure DoStuff;
var
  ForInDemo: TForInDemo;
  C: Char;
begin
  ForInDemo := TForInDemo.Create('HelloWorld');;
  try
    for C in ForInDemo do
    begin
      Write(C, ',');
    end;
    WriteLn;

  finally
    ForInDemo.Free;
  end;
end;

 

IEnumerator<T> Interface

Now the above discussion talks a lot about specific methods that must be included as part of an enumerator, and as part of a class that wants to be enumerated.  And of course, that should immediately make you think “Interfaces!”.  And sure enough, there are some nice interfaces that fall out of this. (You knew I’d work interfaces into things here eventually, didn’t you.  Yes, you did.) 

Consider this interface:

type
  IEnumerator<T> = interface
  ['{DD445F01-975D-405E-BCC1-09D3E78CB0FF}']
    function GetCurrent: T;
    function MoveNext: Boolean;
    property Current: T read GetCurrent;
  end;

That should look awfully familiar.  It’s the exact two methods and one property needed to implement an enumerator – hence the name. 

I’ve declared this IEnumerator<T> interface myself, but the Delphi RTL includes a similar one in the System.pas unit. And at its base, IEnumerable<T> is all about implementing the GetEnumerator method.   

It leverages generics because the type of what is being enumerated doesn’t matter as far as the interface is concerned.  And remember when I said that a call to GetEnumerator could return an interface?  Well it can, and the compiler will happily use an IEnumerator<T> to implement the for…in loop.

Thus, your enumerators can implement this interface and your calls to GetEnumerator can return this interface, and you can add flexibility to how they are implemented.  Here’s an example:

  TStringEnumerator = class(TInterfacedObject, IEnumerator<Char>)
  private
    FIndex: integer;
    FString: string;
    function GetCurrent: Char;
  public
    constructor Create(aString: string);
    function MoveNext: Boolean;
    property Current: Char read GetCurrent;
  end;

  TInterfaceEnumeratorDemo = class
  private
    FTheString: string;
    procedure SetTheString(const Value: string);
  public
    constructor Create(aString: string);
    function GetEnumerator: IEnumerator<Char>;
    property TheString: string read FTheString write SetTheString;
  end;

Notice that the call to GetEnumerator returns an IEnumerator<Char> which is actually the individual type being iterated. In this case, the generic type needs to be the same type as the variable being returned in the for part of the for…in loop.  

This enables you to do the following:

procedure DoInterfaceStuff;
var
  InterfacedEnumerator: TInterfaceEnumeratorDemo;
  c: Char;
begin
  InterfacedEnumerator := TInterfaceEnumeratorDemo.Create('GoodbyeWorld');
  try
    for c in InterfacedEnumerator do
    begin
      Write(C, ',');
    end;
    WriteLn;
  finally
    InterfacedEnumerator.Free;
  end;
end;

 

Specialized Enumerators

The implementation of an enumerator is, as I mentioned, really simple.  But what if you wanted to get a little creative in the GetCurrent method?  After all, at that point you have complete control over what the enumerator returns.  In our simple case with characters and strings, what if we decided to, say, always return the upper case version of the character?  Or if we were iterating over integers, return the squares of the numbers in the collection?  That would be super easy, right? Well, yes, it would.

Consider this code:

  TForInDemoClassUpperCaseEnumerator = class(TForInDemoClassEnumerator)
  protected
    function GetCurrent: Char; override;
  end;
...
function TForInDemoClassUpperCaseEnumerator.GetCurrent: Char;
begin
  Result := UpCase(inherited GetCurrent);
end;

This class descends from TForInDemoClassEnumerator and overrides the existing enumerator for our demo class and returns the upper case of the character in question. 

If we wanted, we could return this class from our GetEnumerator call, but that would be sort of playing a trick on the user of our code. How about if we provide two different enumerators, and then make each available for enumeration in a for…in loop.  Surely that is possible, right?  Of course it is. 

First, we’ll look at the end result and then work our way backwards to see how it was implemented, because you have to play a little trick to expose more than one enumerator for a class:

procedure DoMoreStuff;
var
  C: Char;
  ForInExtraDemo: TForInDemoExtraIterators;
begin

  ForInExtraDemo := TForInDemoExtraIterators.Create('Greetings');
  try
    for C in ForInExtraDemo.AsUpperCase do
    begin
      Write(C, ',');
    end;
    WriteLn;
end;

This little routine will display the string “Greetings” as “G,R,E,E,T,I,N,G,S” in the console.  But note in the for…in loop that the actual class is not passed to the in clause, but a method that returns a “proxy” class that has the desired enumerator attached to it instead.  This is implemented as follows:

TUpperCaseEnumeratorProxy = class
  private
    FOwner: TForInDemo;
  public
    constructor Create(aOwner: TForInDemo);
    function GetEnumerator: TForInDemoClassUpperCaseEnumerator;
  end;
..
constructor TUpperCaseEnumeratorProxy.Create(aOwner: TForInDemo);
begin
  inherited Create;
  FOwner := aOwner
end;

function TUpperCaseEnumeratorProxy.GetEnumerator: TForInDemoClassUpperCaseEnumerator;
begin
  Result := TForInDemoClassUpperCaseEnumerator.Create(FOwner.TheString);
end

This is just another class that can be enumerated – it has a call to GetEnumerator – and thus be returned by a method call on our “real” enumerating class.  It returns an instance of an enumerator called TForInDemoClassUpperCaseEnumerator which we looked at above.  So, if you want to iterate over the upper case version of the strings, you call it as we did in the DoMoreStuff method above.  The trick here is that instead of iterating over the class itself, you iterate over the proxy class using ForInExtraDemo.AsUpperCase.  It’s a neat little trick, eh?

Thus, the enumerating class becomes:

  TForInDemoExtraIterators = class(TForInDemo)
  private
    FUpper: TUpperCaseEnumeratorProxy;
  public
    constructor Create(aString: string);
    property AsUpperCase: TUpperCaseEnumeratorProxy read FUpper;
  end;
...
constructor TForInDemoExtraIterators.Create(aString: string);
begin
  inherited Create(aString);
  FUpper := TUpperCaseEnumeratorProxy.Create(Self);
end;

Conclusion

So, that should give you a little insight into what happens with for…in loops and  how you can create classes that participate automatically.  I’m working towards never using the old for I := 0 to Count –1 do; construct, and making my classes enumeratable.

The code for this article with further examples can be found with my demo code on BitBucket.

Comments (1) -

1/13/2013 3:19:31 AM #

Hi Nick,

Nice article. Thanks.

You should add that a record can be used as well for enumeration. And in a case like your TForInDemo, actually it is better to use a record because you then don't have to create/free the underlaying class. This is what I have done in my article francois-piette.blogspot.be/.../...its-within.html for the bit enumerator.

In my opinion, each time we need an iterator for an external item (such as a string, an integer, or anything else which doesn't already has an enumerator, then a record (or an interface) is better to avoid the manage the lifecycle.

Francois Piette Belgium |

Comments are closed

My Book

A Pithy Quote for You

"We make men without chests and expect of them virtue and enterprise. We laugh at honor and are shocked to find traitors in our midst. We castrate and then bid the geldings to be fruitful."    –  C. S. Lewis

Amazon Gift Cards

General Disclaimer

The views I express here are entirely my own and not necessarily those of any other rational person or organization.  However, I strongly recommend that you agree with pretty much everything I say because, well, I'm right.  Most of the time. Except when I'm not, in which case, you shouldn't agree with me.