.NET 3.5+

LINQ Element Operators

by Richard Carr, published at http://www.blackwasp.co.uk/LinqElement.aspx

The fifteenth part of the LINQ to Objects tutorial examines the element standard query operators. These operators allow single items to be extracted from collections based upon their position in the sequence or upon a provided predicate.

SingleOrDefault

As you may expect, the SingleOrDefault method provides similar functionality to the Single standard query operator but returns a default value if the source sequence is empty or, when using a predicate, should no matching items be present. An exception will still be thrown if several items match.

var item = singleItem.SingleOrDefault();                // "One Item"
item = empty.SingleOrDefault();                         // null
item = items.SingleOrDefault();                         // Exception
item = items.SingleOrDefault(i => i.StartsWith("E"));   // "Eight"
item = items.SingleOrDefault(i => i.StartsWith("X"));   // null
item = items.SingleOrDefault(i => i.StartsWith("F"));   // Exception

ElementAt

The ElementAt standard query operator allows you to locate an item in a collection based upon its index. This method treats any sequence that implements IEnumerable<T> in a similar manner to an array or list that includes a zero-based index. For example, to retrieve the sixth value in the list you can pass five to the method's argument; passing zero would return the first item.

var item = items.ElementAt(5); // "Five"

If the source collection is empty, or if the index value provided is out of range, an exception will be thrown:

var item = empty.ElementAt(5); // Exception

ElementAtOrDefault

The last of the element operators that returns a single object, rather than a new sequence, is ElementAtOrDefault. This operator is used in the same manner as ElementAt. If the source collection is empty or the index is invalid, the default value for the expected type is returned.

var item = items.ElementAtOrDefault(5);     // "Five"
item = empty.ElementAtOrDefault(5);         // null

DefaultIfEmpty

The final element standard query operator is DefaultIfEmpty. Unlike the previous methods, this operator returns a sequence of values using deferred execution. When executed against a collection that is not empty, the new sequence is a copy of the source list. You can see this by running the code below and inspecting the results.

var newSequence = items.DefaultIfEmpty(); // Copy of items

If the source collection is empty, a new sequence is generated and a single item is added to it. This item is the default value for the expected type. In the following code, the returned sequence will contain a single, null string.

var newSequence = empty.DefaultIfEmpty(); // One null item

A second overloaded version of the DefaultIfEmpty method is available. This version accepts a single argument that must be of the type of the elements in the source collection. When executed against a sequence that contains items, the resultant sequence is a copy of the original. When executed against an empty list, a new sequence is generated and the item provided as the argument is added to that list.

var newSequence = empty.DefaultIfEmpty("Default Value");
// One item containing "Default Value"