Enumerable.Single Method

Definition

Returns a single, specific element of a sequence.

Overloads

Single<TSource>(IEnumerable<TSource>, Func<TSource,Boolean>)

Returns the only element of a sequence that satisfies a specified condition, and throws an exception if more than one such element exists.

Single<TSource>(IEnumerable<TSource>)

Returns the only element of a sequence, and throws an exception if there is not exactly one element in the sequence.

Single<TSource>(IEnumerable<TSource>, Func<TSource,Boolean>)

Source:
Single.cs
Source:
Single.cs
Source:
Single.cs

Returns the only element of a sequence that satisfies a specified condition, and throws an exception if more than one such element exists.

C#
public static TSource Single<TSource>(this System.Collections.Generic.IEnumerable<TSource> source, Func<TSource,bool> predicate);

Type Parameters

TSource

The type of the elements of source.

Parameters

source
IEnumerable<TSource>

An IEnumerable<T> to return a single element from.

predicate
Func<TSource,Boolean>

A function to test an element for a condition.

Returns

TSource

The single element of the input sequence that satisfies a condition.

Exceptions

source or predicate is null.

No element satisfies the condition in predicate.

-or-

More than one element satisfies the condition in predicate.

-or-

The source sequence is empty.

Examples

The following code example demonstrates how to use Single<TSource>(IEnumerable<TSource>, Func<TSource,Boolean>) to select the only element of an array that satisfies a condition.

C#
string[] fruits = { "apple", "banana", "mango",
                      "orange", "passionfruit", "grape" };

string fruit1 = fruits.Single(fruit => fruit.Length > 10);

Console.WriteLine(fruit1);

/*
 This code produces the following output:

 passionfruit
*/

The following code example demonstrates that Single<TSource>(IEnumerable<TSource>, Func<TSource,Boolean>) throws an exception when the sequence does not contain exactly one element that satisfies the condition.

C#
string fruit2 = null;

try
{
    fruit2 = fruits.Single(fruit => fruit.Length > 15);
}
catch (System.InvalidOperationException)
{
    Console.WriteLine(@"The collection does not contain exactly
                    one element whose length is greater than 15.");
}

Console.WriteLine(fruit2);

// This code produces the following output:
//
// The collection does not contain exactly
// one element whose length is greater than 15.

Remarks

The Single<TSource>(IEnumerable<TSource>, Func<TSource,Boolean>) method throws an exception if the input sequence contains no matching element. To instead return null when no matching element is found, use SingleOrDefault.

Applies to

.NET 9 and other versions
Product Versions
.NET Core 1.0, Core 1.1, Core 2.0, Core 2.1, Core 2.2, Core 3.0, Core 3.1, 5, 6, 7, 8, 9
.NET Framework 3.5, 4.0, 4.5, 4.5.1, 4.5.2, 4.6, 4.6.1, 4.6.2, 4.7, 4.7.1, 4.7.2, 4.8, 4.8.1
.NET Standard 1.0, 1.1, 1.2, 1.3, 1.4, 1.6, 2.0, 2.1
UWP 10.0

Single<TSource>(IEnumerable<TSource>)

Source:
Single.cs
Source:
Single.cs
Source:
Single.cs

Returns the only element of a sequence, and throws an exception if there is not exactly one element in the sequence.

C#
public static TSource Single<TSource>(this System.Collections.Generic.IEnumerable<TSource> source);

Type Parameters

TSource

The type of the elements of source.

Parameters

source
IEnumerable<TSource>

An IEnumerable<T> to return the single element of.

Returns

TSource

The single element of the input sequence.

Exceptions

source is null.

The input sequence contains more than one element.

-or-

The input sequence is empty.

Examples

The following code example demonstrates how to use Single<TSource>(IEnumerable<TSource>) to select the only element of an array.

C#
string[] fruits1 = { "orange" };

string fruit1 = fruits1.Single();

Console.WriteLine(fruit1);

/*
 This code produces the following output:

 orange
*/

The following code example demonstrates that Single<TSource>(IEnumerable<TSource>) throws an exception when the sequence does not contain exactly one element.

C#
string[] fruits2 = { "orange", "apple" };
string fruit2 = null;

try
{
    fruit2 = fruits2.Single();
}
catch (System.InvalidOperationException)
{
    Console.WriteLine("The collection does not contain exactly one element.");
}

Console.WriteLine(fruit2);

/*
 This code produces the following output:

 The collection does not contain exactly one element.
*/

Remarks

The Single<TSource>(IEnumerable<TSource>) method throws an exception if the input sequence is empty. To instead return null when the input sequence is empty, use SingleOrDefault.

Applies to

.NET 9 and other versions
Product Versions
.NET Core 1.0, Core 1.1, Core 2.0, Core 2.1, Core 2.2, Core 3.0, Core 3.1, 5, 6, 7, 8, 9
.NET Framework 3.5, 4.0, 4.5, 4.5.1, 4.5.2, 4.6, 4.6.1, 4.6.2, 4.7, 4.7.1, 4.7.2, 4.8, 4.8.1
.NET Standard 1.0, 1.1, 1.2, 1.3, 1.4, 1.6, 2.0, 2.1
UWP 10.0