[API Proposal]: Add some LINQ extension to return a single element but not throw for multiple

[LWChris]

Background and motivation

When we are interested in whether there is exactly one element in an IEnumeable<T> (with or without a predicate), there's three possible outcomes:

• No, n=0
• Yes, n=1
• No, n>1

LINQ does currently not provide an easy way to "retrieve if n=1, default otherwise" without the need to handle exceptions: FirstOrDefault, LastOrDefault and SingleOrDefault all return default(T) for n=0, and the element for n=1. But for n> 1, the first two also return an element, and the latter throws an InvalidOperationException.

I have made the same request 6 years ago (#29398) as UniqueOrDefault, but it was closed, because Eirik Tsarpalis didn't like the name "Unique". He felt it implies the return value is a boolean, like "All" or "Any". I didn't agree; I'd name such a function "IsUnique". He didn't reply to that for a month, then just closed the issue.

Well, I don't insist on any name in particular, but I still need the functionality quite often and find myself adding a custom extension to many projects. Please re-consider adding it, under a name that you see fit.

API Proposal

namespace System.Collections.Generic;

public partial static class Enumerable
{
    public static T? OnlyOrDefault<T>(this IEnumerable<T> sequence);
    public static T? OnlyOrDefault<T>(this IEnumerable<T> sequence, Func<T, bool> predicate);
}

API Usage

private static bool TryGetAutoCompleteSuggestion(this IEnumerable<string> entries, string input, out string? suggestion) {
    suggestion = entries.OnlyOrDefault(e => e.StartsWith(input));
    return suggestion != null;
}

var selectedOption = availableOptions.OnlyOrDefault() // If there's only one option applicable, use that,
    ?? availableOptions.OnlyOrDefault(o => o.IsDefault) // otherwise select default option if unambiguous,
    ?? ShowOptionSelectDialog(availableOptions); // otherwise let the user pick one.

Alternative Designs

namespace System.Collections.Generic;

public enum Cardinality
{
  Empty, // or Zero, None
  Single, // or One, Only
  Many // or Multiple
}

public partial static class Enumerable
{
    public static bool TryGetOnly<T>(this IEnumerable<T> sequence, out T? element);
    public static bool TryGetOnly<T>(this IEnumerable<T> sequence, out T? element, out Cardinality cardinality);
    public static bool TryGetOnly<T>(this IEnumerable<T> sequence, Func<T, bool> predicate, out T? element);
    public static bool TryGetOnly<T>(this IEnumerable<T> sequence, Func<T, bool> predicate, out T? element, out Cardinality cardinality);
}

This is fitting the "TryGet" pattern, but it wouldn't fit that well alongside [First|Last|Single](OrDefault)?

Risks

None.

[dotnet-policy-service]

Tagging subscribers to this area: @dotnet/area-system-linq
See info in area-owners.md if you want to be subscribed.

[DaZombieKiller]

Perhaps something along the lines of DistinctOrDefault would be a suitable name? There is prior art here in Enumerable.Distinct/DistinctBy.

[svick]

There is prior art here in Enumerable.Distinct/DistinctBy.

I think that's a point against the Distinct name, since it implies doing equality comparisons.

[tannergooding]

We've had a few proposals/issues on this over the years, I think the last one suggested Unique and got closed: #29398

The suggested names have been pretty varied however and so I don't think there's a good way to link them all here.

It is a highly requested thing however and has had comments made in API review, LDM, and other meetings; not to mention at the MVP summit, Microsoft Build, and other conferences on how people wish "something" existed.

[DaZombieKiller]

There is prior art here in Enumerable.Distinct/DistinctBy.

I think that's a point against the Distinct name, since it implies doing equality comparisons.

But equality comparisons are inherently required to determine if the value is unique, are they not?

Edit: I think I may have misunderstood the intent of the API proposal, if it's operating based on the number of items in the collection then I agree that Distinct is not an appropriate name.

[timcassell]

What about just adding an extra bool throwIfMultiple param to SingleOrDefault? I think the SingleOrDefault name is already ideal, it's just the behavior that needs to change.

Btw, I do like Try* methods for distinguishing between valid default values and not existing.

[DrkWzrd]

What about just adding an extra bool throwIfMultiple param to SingleOrDefault? I think the SingleOrDefault name is already ideal, it's just the behavior that needs to change.

This is the only that makes sense trying to avoid a breaking change but, SingleOrDefault should have returned default if not single (single OR default) from the beggining. This should warrant a breaking change in my opinion.

[tannergooding]

That’s too breaking, it’s unlikely to happen

[DrkWzrd]

Adding an optional parameter is a breaking change?

[tannergooding]

I was responding to the following, which I took to mean suggesting we take a break in the implementation.

SingleOrDefault should have returned default if not single (single OR default) from the beggining. This should warrant a breaking change in my opinion.

Adding a new overload with a parameter is not-breaking, but the expectation (and general Framework Design Guidlines) would be that SingleOrDefault(false) has the same behavior as SingleOrDefault().