Add TrySingle<TSource>(IEnumerable<TSource>, out TSource)

[shmuelie]

Motivation

In LINQ we have the Single and SingleOrDefault methods, but they don't tell you if it succeeded or not.

The problem with these methods is that if there is more than one element in source (or more than one matching element in case of predicate) they all throw a System.InvalidOperationException. That is fine if more than one element is an error or very rare. If more than one element is common or expected then this will cause major slow downs.

Additionaly, in cases of (example: int collections), default(int) is 0, which wouldn't tell the caller whether the operation succeeded (returning the item 0) or not (returning the default 0).

Proposal

namespace System.Linq
{
    public static class Enumerable
    {
        public static TSource Single<TSource>(this IEnumerable<TSource> source);
        public static TSource Single<TSource>(this IEnumerable<TSource> source, Func<TSource, bool> predicate);
        public static TSource SingleOrDefault<TSource>(this IEnumerable<TSource> source);
        public static TSource SingleOrDefault<TSource>(this IEnumerable<TSource> source, Func<TSource, bool> predicate);
+       public static bool TrySingle<TSource>(this IEnumerable<TSource> source, out TSource element);
+       public static bool TrySingle<TSource>(this IEnumerable<TSource> source, Func<TSource, bool> predicate, out TSource element);

        public static TSource First<TSource>(this IEnumerable<TSource> source);
        public static TSource First<TSource>(this IEnumerable<TSource> source, Func<TSource, bool> predicate);
        public static TSource FirstOrDefault<TSource>(this IEnumerable<TSource> source);
        public static TSource FirstOrDefault<TSource>(this IEnumerable<TSource> source, Func<TSource, bool> predicate);
+       public static bool TryFirst<TSource>(this IEnumerable<TSource> source, out TSource element);
+       public static bool TryFirst<TSource>(this IEnumerable<TSource> source, Func<TSource, bool> predicate, out TSource element);

        public static TSource Last<TSource>(this IEnumerable<TSource> source);
        public static TSource Last<TSource>(this IEnumerable<TSource> source, Func<TSource, bool> predicate);
        public static TSource LastOrDefault<TSource>(this IEnumerable<TSource> source);
        public static TSource LastOrDefault<TSource>(this IEnumerable<TSource> source, Func<TSource, bool> predicate);
+       public static bool TryLast<TSource>(this IEnumerable<TSource> source, out TSource element);
+       public static bool TryLast<TSource>(this IEnumerable<TSource> source, Func<TSource, bool> predicate, out TSource element);

        public static TSource ElementAt<TSource>(this IEnumerable<TSource> source, int index);
        public static TSource ElementAtOrDefault<TSource>(this IEnumerable<TSource> source, int index);
+       public static bool TryElementAt<TSource>(this IEnumerable<TSource> source, int index, out TSource element);
    }

    public static class Queryable
    {
        public static TSource Single<TSource>(this IQueryable<TSource> source);
        public static TSource Single<TSource>(this IQueryable<TSource> source, Expression<Func<TSource, bool>> predicate);
        public static TSource SingleOrDefault<TSource>(this IQueryable<TSource> source);
        public static TSource SingleOrDefault<TSource>(this IQueryable<TSource> source, Expression<Func<TSource, bool>> predicate);
+       public static (bool success, T value) TrySingle<T>(this IQueryable<T> source);
+       public static (bool success, T value) TrySingle<T>(this IQueryable<T> source, Expression<Func<TSource, bool>> predicate);
+       public static bool TrySingle<TSource>(this IQueryable<TSource> source, out TSource element);
+       public static bool TrySingle<TSource>(this IQueryable<TSource> source, Expression<Func<TSource, bool>> predicate, out TSource element);

        public static TSource First<TSource>(this IQueryable<TSource> source);
        public static TSource First<TSource>(this IQueryable<TSource> source, Expression<Func<TSource, bool>> predicate);
        public static TSource FirstOrDefault<TSource>(this IQueryable<TSource> source);
        public static TSource FirstOrDefault<TSource>(this IQueryable<TSource> source, Expression<Func<TSource, bool>> predicate);
+       public static (bool success, T value) TryFirst<T>(this IQueryable<T> source);
+       public static (bool success, T value) TryFirst<T>(this IQueryable<T> source, Expression<Func<TSource, bool>> predicate);
+       public static bool TryFirst<TSource>(this IQueryable<TSource> source, out TSource element);
+       public static bool TryFirst<TSource>(this IQueryable<TSource> source, Expression<Func<TSource, bool>> predicate, out TSource element);

        public static TSource Last<TSource>(this IQueryable<TSource> source);
        public static TSource Last<TSource>(this IQueryable<TSource> source, Expression<Func<TSource, bool>> predicate);
        public static TSource LastOrDefault<TSource>(this IQueryable<TSource> source);
        public static TSource LastOrDefault<TSource>(this IQueryable<TSource> source, Expression<Func<TSource, bool>> predicate);
+       public static (bool success, T value) TryLast<T>(this IQueryable<T> source);
+       public static (bool success, T value) TryLast<T>(this IQueryable<T> source, Expression<Func<TSource, bool>> predicate);
+       public static bool TryLast<TSource>(this IQueryable<TSource> source, out TSource element);
+       public static bool TryLast<TSource>(this IQueryable<TSource> source, Expression<Func<TSource, bool>> predicate, out TSource element);

        public static TSource ElementAt<TSource>(this IQueryable<TSource> source, int index);
        public static TSource ElementAtOrDefault<TSource>(this IQueryable<TSource> source, int index);
+       public static (bool success, T value) TryElementAt<T>(this IQueryable<T> source, int index);
+       public static bool TryElementAt<TSource>(this IQueryable<TSource> source, int index, out TSource element);
    }
}

Original

I'd like to propose a new LINQ method: TrySingle. The idea is pretty much the same as the existing Single method except it does not throw an exception when there is not only a single item in the sequence.

To do this I made to modifications to the Single contract:

1. First the method returns bool. true if the sequence contains exactly one item, false otherwise.
2. I added an out parameter of type TSource. This will "hold" the single element on success. On failure it is filled with default(TSource).

I have found this method very useful in my own code and if accepted can quickly put together a pull request.

[JonHanna]

If one was going to do this, I would see it as cleaner if all of the methods with XxxOrDefault() had a TryXXX.

[shmuelie]

I do see what you're getting at but I'm not "replacing" the SingleOrDefault() method, since that still throws an exception.

[MgSam]

I'd say any API additions with the Try pattern should be held off until the Tuple design for C# 7 is finalized. It might be better for these types of methods to return tuples.

[shmuelie]

I actually like the way this works because it makes using this method in a if statement very easy:

int I;
if (seq.TrySingle(out I))
{
   ...
}

(I admit though that TryXXX might not be the best name for this method though)

[JonHanna]

I wouldn't suggest any of them as a replacement (I'd argue vehemently against), but rather just as one might say "I want to get the single matching element here, or if there isn't a single matching element, know that I failed to get it" one might also say "I want to get the first matching element here, or if there isn't one, know that I failed to get it" and so on.

FWIW, some code I'm playing with now has a TryGetFirst, TryGetLast and TryGetElementAt because it became necessary to distinguish from default(TSource) of a failure and of the element happening to be the default.

[shmuelie]

Ah yes, for Last, First, and ElementAt a TryXXX method would be great. The issue here is that I'm trying to avoid an exception which event the xxxOrDefault doesn't do. My use of the TryXXX naming may not have been the best choice.

[JonHanna]

Yep. Much of the time the SingleOrDefault would work, but if the default value is a possible real value, then it's no good to you.

[shmuelie]

How would SingleOrDefault work? My case is that having more than one item is common and that means both Single and SingleOrDefault throw an exception, something I really don't want happening! (SingleOrDefault returns default on no items)

[JonHanna]

Ah. I get your meaning now. Single of course has two failure modes...

[shmuelie]

Maybe a name other than TrySingle?

[JonHanna]

I wonder if a caller might want to distinguish failure because there are none from failure because there are more than one?

[shmuelie]

So say return an enum?

enum SequenceLength
{
   Empty,
   Single,
   More
}

[shmuelie]

After the discussion above, some more thinking myself, and looking at the contributing guidelines...

Rational

In LINQ we have the Single and SingleOrDefault methods:

namespace System.Linq
{
    public static class Enumerable
    {
        public static TSource Single<TSource>(this IEnumerable<TSource> source);
        public static TSource Single<TSource>(this IEnumerable<TSource> source, Func<TSource, bool> predicate);
        public static TSource SingleOrDefault<TSource>(this IEnumerable<TSource> source);
        public static TSource SingleOrDefault<TSource>(this IEnumerable<TSource> source, Func<TSource, bool> predicate);
    }
}

The problem with these methods is that if there is more than one element in source (or more than one matching element in case of predicate) they all throw a System.InvalidOperationException. That is fine if more than one element is an error or very rare. If more than one element is common or expected then this will cause major slow downs.

New Methods

I propose the following methods be added:

namespace System.Linq
{
    public static class Enumerable
    {
        public static bool Single<TSource>(this IEnumerable<TSource> source, out TSource element);
        public static bool Single<TSource>(this IEnumerable<TSource> source, Func<TSource, bool> predicate, out TSource element);
    }
}

Contracts

public static bool Single<TSource>(this IEnumerable<TSource> source, out TSource element);

1. If source is null, throw System.ArgumentNullException.
2. If source is empty or has more than one element, set element to default(TSource) and return false.
3. If source has one element, set element to that element and return true.

public static bool Single<TSource>(this IEnumerable<TSource> source, Func<TSource, bool> predicate, out TSource element);

1. If source or predicate is null, throw System.ArgumentNullException.
2. If source has no elements or has no elements that predicate returns true for or has more than one element that predicate returns true for, set element to default(TSource) and return false.
3. If source has one element that predicate returns true for, set element to that element and return true.

---

As to @JonHanna 's point about wanting to know more information, I feel that would be a whole new method.

[Clockwork-Muse]

...if more than one element is common/expected, then you have one of two situations:

1. You don't particularly care which you get, so First(...) would be appropriate.
2. You do care, so the exception thrown in Single(...) is appropriate.

"Exceptions are slow" is irrelevant in the case of requesting user input to resolve the issue - displaying to the screen and acting on the input is going to take far longer.

If you're planning on doing something like showing a pop-up with multiple results (if they exist) for selection, you're going to have to get them regardless. At that point, it'd be better to start with the results of a Where(...) query and go from there.

What was the situation you were planning on using this method to solve?