I've been asked a few times by my apprentice groups to explain
IEnumerable. Something that in C# we use every day.
IEnumerable is an interface, which when implemented supports iteration. There are two interfaces - the non-generic one (for looping over non-generic collections) and the generic one.
Firstly, lets look at the definition of the interfaces.
namespace System.Collections
{
public interface IEnumerable
{
IEnumerator GetEnumerator();
}
}
namespace System.Collections.Generic
{
public interface IEnumerable<out T> : IEnumerable
{
IEnumerator<T> GetEnumerator();
}
}
Now if we have a
Listand look at the first line of the definition we will see that it implements the interfaces.
public class List<T> : IList<T>, ICollection<T>, IEnumerable<T>,
IList, ICollection, IEnumerable
Let's create an example to play with. We will have a class (called
Place) with some fields.
public class Place
{
public string PlaceName { get; set; }
public string GaelicName { get; set; }
public int Population { get; set; }
public override string ToString()
{
return String.Format("Place {0} ({1}) pop {2}",
PlaceName, GaelicName, Population);
}
}
And in a console program let us populate an instance of a
List of
Place (List<Place>).
List<Place> places = new List
{
new Place { PlaceName = "Lewis and Harris", GaelicName = "Leòdhas agus na Hearadh", Population = 21031 },
new Place { PlaceName = "South Uist", GaelicName = "Uibhist a Deas", Population = 1754 },
new Place { PlaceName = "North Uist", GaelicName = "Uibhist a Tuath", Population = 1254 },
new Place { PlaceName = "Benbecula", GaelicName = "Beinn nam Fadhla", Population = 1303 },
new Place { PlaceName = "Barra", GaelicName = "Barraigh", Population = 1174 },
new Place { PlaceName = "Scalpay", GaelicName = "Sgalpaigh", Population = 291 },
new Place { PlaceName = "Great Bernera", GaelicName = "Beàrnaraigh Mòr", Population = 252 },
new Place { PlaceName = "Grimsay", GaelicName = "Griomasaigh", Population = 169 },
new Place { PlaceName = "Berneray", GaelicName = "Beàrnaraigh", Population = 138 },
new Place { PlaceName = "Eriskay", GaelicName = "Beàrnaraigh", Population = 143 },
new Place { PlaceName = "Vatersay", GaelicName = "Bhatarsaigh", Population = 90 },
new Place { PlaceName = "Baleshare", GaelicName = "Baile Sear", Population = 58 }
};
If we want to output them
foreach (Place place in places)
Console.WriteLine(place);
And when you run this it will use the
ToString() method
So what is exactly happening. Let's look at this code
var enumerator = places.GetEnumerator();
while (a.MoveNext())
{
Place p = enumerator.Current;
Console.WriteLine("Place {0}", p);
}
Here we are calling the
GetEnumerator() method. Out loop is then checking that we can move to the next element - this
MoveNext method will return true if there are (more) elements to process. If there are we can get the current element with the
Current method, which we can then print out. When we did our original loop - this is essentially what is happening. The
foreach statement in C# will hide this complexity. But
foreach will work with classes that implement
IEnumerable.
So let's extend our example to add another class (
IslandGroup) which we will use to encapsulate details about a group of islands - in this case the list of islands above are the Outer Hebrides. So let's create a class for this, with some properties including a
Dictionary containing the islands and one to return the total population.
Apologies for the lack of comments - my apprentice groups would crucify me!
public class IslandGroup : IEnumerable<place>
{
public string IslandGroupName { get; private set; }
public Dictionary<string,Place> Islands { get; private set; }
public IslandGroup(string islandGroupName)
{
this.IslandGroupName = islandGroupName;
Islands = new Dictionary<string,Place>();
}
public void AddIsland(Place island)
{
// Add the island if it isn't in the Islands already
if (!Islands.ContainsKey(island.PlaceName))
Islands.Add(island.PlaceName, island);
}
public int TotalPopulation
{
get
{
return Islands.Sum(v => v.Value.Population);
}
}
}
We can use this class and populate the dictionary as well as returning the total population of all the islands with something like this
IslandGroup outerHebrides = new IslandGroup("Outer Hebredies");
// Add each island to the class
foreach (var place in places)
outerHebrides.AddIsland(place);
Console.WriteLine("Population {0}", outerHebrides.TotalPopulation);
Now right click on
IEnumerable<Place> on the definition of the class - choose Implement Interface. This will create two methods as below
public IEnumerator<Place> GetEnumerator()
{
throw new NotImplementedException();
}
System.Collections.IEnumerator System.Collections.IEnumerable.GetEnumerator()
{
throw new NotImplementedException();
}
Why two methods - well look at the definition of
IEnumerable<T> which implements
IEnumerable. So you need both. In the end we will make one method (the non-generic
GetEnumerator()) call the other.
Have you heard of the
yield keyword. The
yield keyword is user an iterator method to give control back to the loop. So when you do a
foreach loop a method gets called to perform the iteration. In this method we will put in a
yield statement. So here is some code
public IEnumerator<Place> GetEnumerator()
{
foreach (var place in Islands)
yield return place.Value;
}
Our class encapsulates data for the islands which we store in a
Dictionary. In the loop we want to return each place - hence in our loop we are using the
.Value property and returning this. We are using
yield return <expression>, which every time this gets called the expression will be returned. In our code to execute this we will use the instance of the class
foreach (var item in outerHebrides)
Console.WriteLine(item);
But are you asking - why don't we just loop through the
Dictionary property using something like this
foreach (var item in outerHebrides.Islands)
Console.WriteLine(item.Value);
It just depends on what data you want to make available and what functionality you want to return. Let's say we want to return (in this case) the islands from lowest population first. Since we have written our own iterator we can do this.
public IEnumerator<Place> GetEnumerator()
{
var inOrder = from i in Islands.Values
orderby i.Population ascending
select i;
foreach (var place in inOrder)
yield return place;
}
Now when we run this the output will be in the order we determine
Finally, you don't need to implement the interface
IEnumerable<T> - you can have methods returning that type. So you could write a method like this
public IEnumerable<Place> GaelicAlphabeticalOrder()
{
var inOrder = from i in Islands.Values
orderby i.GaelicName ascending
select i;
foreach (var place in inOrder)
yield return place;
}
Which could be executed with
foreach (var place in places)
outerHebrides.AddIsland(place);
Thus we don't need to implement this at a class level - or if we do, we can provide alternative methods (and these methods
could take parameters etc.)
The
yield keyword can be used as above, but also as
yield break;
Which will end the iteration. You can also use the
yield keyword in static methods, for example
public static IEnumerable<string> ScottishIslandGroups()
{
yield return "Outer Hebrides";
yield return "Inner Hebrides";
yield return "Shetland";
yield return "Orkney";
yield return "Islands of the Clyde";
yield return "Islands of the Forth";
}
Or as a property
public static IEnumerable<string> WelshIslandGroups
{
get
{
yield return "Anglesey";
yield return "Bristol Channel";
yield return "Ceredigion";
yield return "Gower";
yield return "Gwynedd";
yield return "Pembrokeshire";
yield return "St Tudwal's Islands";
yield return "Vale of Glamorgan";
}
}
Used as
foreach (string islandGroup in IslandGroup.WelshIslandGroups)
Console.WriteLine(islandGroup);