Introduce Duplicates extension

MoreLinq.Test/DuplicatesTest.cs

@@ -0,0 +1,140 @@
+#region License and Terms
+// MoreLINQ - Extensions to LINQ to Objects
+// Copyright (c) 2023 Julien Aspirot. All rights reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+#endregion
+
+namespace MoreLinq.Test
+{
+    using System.Collections.Generic;
+    using NUnit.Framework;
+
+    [TestFixture]
+    public class DuplicatesTest
+    {
+        [Test]
+        public void Duplicates_IsLazy()
+        {
+            _ = new BreakingSequence<object>().Duplicates();
+        }
+
+        [Test]
+        public void Streams_Duplicates_As_They_Are_Discovered()
+        {
+            static IEnumerable<string> Source()
+            {
+                yield return "DUPLICATED_STRING";
+                yield return "DUPLICATED_STRING";
+                throw new TestException();
+            }
+
+            using var source = TestingSequence.Of(Source());
+
+            void Act() => source.Duplicates().Take(1);
+
+            Assert.That(Act, Throws.Nothing);
+        }
+
+        [Test]
+        public void When_Asking_For_Duplicates_On_Sequence_Without_Duplicates_Then_Empty_Sequence_Is_Returned()
+        {
+            using var testingSequence = TestingSequence.Of("FirstElement", "SecondElement", "ThirdElement");
+
+            var duplicates = testingSequence.Duplicates();
+
+            Assert.That(duplicates, Is.Empty);
+        }
+
+        [Test]
+        public void When_Asking_For_Duplicates_On_Sequence_With_Duplicates_Then_Duplicates_Are_Returned()
+        {
+            using var testingSequence = TestingSequence.Of(
+                "FirstElement",
+                "DUPLICATED_STRING",
+                "DUPLICATED_STRING",
+                "DUPLICATED_STRING",
+                "ThirdElement"
+                );
+
+            var duplicates = testingSequence.Duplicates().ToArray();
+
+            Assert.That(duplicates, Contains.Item("DUPLICATED_STRING"));
+            Assert.That(duplicates.AtMost(1), Is.True);
+        }
+
+        [Test]
+        public void When_Asking_For_Duplicates_On_Sequence_With_Multiple_Duplicates_Then_Duplicates_Are_Returned()
+        {
+            using var testingSequence = TestingSequence.Of(
+                "FirstElement",
+                "DUPLICATED_STRING",
+                "DUPLICATED_STRING",
+                "DUPLICATED_STRING",
+                "ThirdElement",
+                "SECOND_DUPLICATED_STRING",
+                "SECOND_DUPLICATED_STRING"
+            );
+
+            var duplicates = testingSequence.Duplicates().ToArray();
+
+            Assert.That(duplicates, Contains.Item("DUPLICATED_STRING"));
+            Assert.That(duplicates, Contains.Item("SECOND_DUPLICATED_STRING"));
+            Assert.That(duplicates.AtMost(2), Is.True);
+        }
+
+        [Test]
+        public void When_Asking_For_Duplicates_On_Sequence_With_Custom_Always_True_Comparer_Then_Duplicates_Are_Returned()
+        {
+            using var testingSequence = TestingSequence.Of("FirstElement", "SecondElement", "ThirdElement");
+
+            var duplicates = testingSequence.Duplicates(new DummyStringAlwaysTrueComparer()).ToArray();
+
+            Assert.That(duplicates.AtMost(1), Is.True);
+        }
+
+        [Test]
+        public void When_Asking_For_Duplicates_On_Sequence_With_Custom_Always_False_Comparer_Then_Empty_Sequence_Is_Returned()
+        {
+            using var testingSequence = TestingSequence.Of("FirstElement", "SecondElement", "ThirdElement");
+
+            var duplicates = testingSequence.Duplicates(new DummyStringAlwaysFalseComparer());
+
+            Assert.That(duplicates, Is.Empty);
+        }
+
+        [Test]
+        public void When_Asking_For_Duplicates_On_Multiple_Duplicates_Sequence_With_Custom_Always_False_Comparer_Then_Empty_Sequence_Is_Returned()
+        {
+            using var testingSequence = TestingSequence.Of("DUPLICATED_STRING", "DUPLICATED_STRING", "DUPLICATED_STRING");
+
+            var duplicates = testingSequence.Duplicates(new DummyStringAlwaysFalseComparer());
+
+            Assert.That(duplicates, Is.Empty);
+        }
+
+        sealed class DummyStringAlwaysTrueComparer : IEqualityComparer<string>
+        {
+            public bool Equals(string? x, string? y) => true;
+
+            public int GetHashCode(string obj) => 0;
+        }
+
+        sealed class DummyStringAlwaysFalseComparer : IEqualityComparer<string>
+        {
+            public bool Equals(string? x, string? y) => false;
+
+            public int GetHashCode(string obj) => 0;
+        }
+    }
+}

MoreLinq/Duplicates.cs

@@ -0,0 +1,64 @@
+#region License and Terms
+// MoreLINQ - Extensions to LINQ to Objects
+// Copyright (c) 2023 Julien Aspirot. All rights reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+#endregion
+
+namespace MoreLinq
+{
+    using System;
+    using System.Collections.Generic;
+    using System.Linq;
+
+    static partial class MoreEnumerable
+    {
+        /// <summary>
+        /// Returns all duplicate elements of the given source.
+        /// </summary>
+        /// <param name="source">The source sequence.</param>
+        /// <typeparam name="TSource">The type of the elements in the source sequence.</typeparam>
+        /// <exception cref="ArgumentNullException"><paramref name="source"/> is null.</exception>
+        /// <returns>All elements that are duplicated.</returns>
+        /// <remarks>This operator uses deferred execution and streams its results.</remarks>
+
+        public static IEnumerable<TSource> Duplicates<TSource>(this IEnumerable<TSource> source) =>
+            Duplicates(source, null);
+
+        /// <summary>
+        /// Returns all duplicate elements of the given source, using the specified equality
+        /// comparer.
+        /// </summary>
+        /// <param name="source">The source sequence.</param>
+        /// <param name="comparer">
+        /// The equality comparer to use to determine whether one <typeparamref name="TSource"/>
+        /// equals another. If <see langword="null"/>, the default equality comparer for
+        /// <typeparamref name="TSource"/> is used.</param>
+        /// <typeparam name="TSource">The type of the elements in the source sequence.</typeparam>
+        /// <exception cref="ArgumentNullException"><paramref name="source"/> is null.</exception>
+        /// <returns>All elements that are duplicated.</returns>
+        /// <remarks>This operator uses deferred execution and streams its results.</remarks>
+
+        public static IEnumerable<TSource> Duplicates<TSource>(this IEnumerable<TSource> source, IEqualityComparer<TSource>? comparer)
+        {
+            if (source is null) throw new ArgumentNullException(nameof(source));
+
+            return from e in source.ScanBy(static e => e,
+                    static _ => 0,
+                    static (count, _, _) => unchecked(Math.Min(count + 1, 3)),
+                    comparer)
+                where e.Value is 2
+                select e.Key;
+        }
+    }
+}

MoreLinq/Extensions.g.cs

@@ -1283,6 +1283,41 @@ public static IEnumerable<TSource> DistinctBy<TSource, TKey>(this IEnumerable<TS
 
     }
 
+    /// <summary><c>Duplicates</c> extension.</summary>
+
+    [GeneratedCode("MoreLinq.ExtensionsGenerator", "1.0.0.0")]
+    public static partial class DuplicatesExtension
+    {
+        /// <summary>
+        /// Returns all duplicate elements of the given source.
+        /// </summary>
+        /// <param name="source">The source sequence.</param>
+        /// <typeparam name="TSource">The type of the elements in the source sequence.</typeparam>
+        /// <exception cref="ArgumentNullException"><paramref name="source"/> is null.</exception>
+        /// <returns>All elements that are duplicated.</returns>
+        /// <remarks>This operator uses deferred execution and streams its results.</remarks>
+
+        public static IEnumerable<TSource> Duplicates<TSource>(this IEnumerable<TSource> source)             => MoreEnumerable.Duplicates(source);
+
+        /// <summary>
+        /// Returns all duplicate elements of the given source, using the specified equality
+        /// comparer.
+        /// </summary>
+        /// <param name="source">The source sequence.</param>
+        /// <param name="comparer">
+        /// The equality comparer to use to determine whether one <typeparamref name="TSource"/>
+        /// equals another. If <see langword="null"/>, the default equality comparer for
+        /// <typeparamref name="TSource"/> is used.</param>
+        /// <typeparam name="TSource">The type of the elements in the source sequence.</typeparam>
+        /// <exception cref="ArgumentNullException"><paramref name="source"/> is null.</exception>
+        /// <returns>All elements that are duplicated.</returns>
+        /// <remarks>This operator uses deferred execution and streams its results.</remarks>
+
+        public static IEnumerable<TSource> Duplicates<TSource>(this IEnumerable<TSource> source, IEqualityComparer<TSource>? comparer)
+            => MoreEnumerable.Duplicates(source, comparer);
+
+    }
+
     /// <summary><c>EndsWith</c> extension.</summary>
 
     [GeneratedCode("MoreLinq.ExtensionsGenerator", "1.0.0.0")]

MoreLinq/MoreLinq.csproj

@@ -27,6 +27,7 @@
         - CountDown
         - Consume
         - DistinctBy
+        - Duplicates
         - EndsWith
         - EquiZip
         - Evaluate

MoreLinq/PublicAPI/net6.0/PublicAPI.Unshipped.txt

@@ -1 +1,6 @@
 #nullable enable
+MoreLinq.Extensions.DuplicatesExtension
+static MoreLinq.Extensions.DuplicatesExtension.Duplicates<TSource>(this System.Collections.Generic.IEnumerable<TSource>! source) -> System.Collections.Generic.IEnumerable<TSource>!
+static MoreLinq.Extensions.DuplicatesExtension.Duplicates<TSource>(this System.Collections.Generic.IEnumerable<TSource>! source, System.Collections.Generic.IEqualityComparer<TSource>? comparer) -> System.Collections.Generic.IEnumerable<TSource>!
+static MoreLinq.MoreEnumerable.Duplicates<TSource>(this System.Collections.Generic.IEnumerable<TSource>! source) -> System.Collections.Generic.IEnumerable<TSource>!
+static MoreLinq.MoreEnumerable.Duplicates<TSource>(this System.Collections.Generic.IEnumerable<TSource>! source, System.Collections.Generic.IEqualityComparer<TSource>? comparer) -> System.Collections.Generic.IEnumerable<TSource>!

MoreLinq/PublicAPI/netstandard2.0/PublicAPI.Unshipped.txt

@@ -1 +1,6 @@
 #nullable enable
+MoreLinq.Extensions.DuplicatesExtension
+static MoreLinq.Extensions.DuplicatesExtension.Duplicates<TSource>(this System.Collections.Generic.IEnumerable<TSource>! source) -> System.Collections.Generic.IEnumerable<TSource>!
+static MoreLinq.Extensions.DuplicatesExtension.Duplicates<TSource>(this System.Collections.Generic.IEnumerable<TSource>! source, System.Collections.Generic.IEqualityComparer<TSource>? comparer) -> System.Collections.Generic.IEnumerable<TSource>!
+static MoreLinq.MoreEnumerable.Duplicates<TSource>(this System.Collections.Generic.IEnumerable<TSource>! source) -> System.Collections.Generic.IEnumerable<TSource>!
+static MoreLinq.MoreEnumerable.Duplicates<TSource>(this System.Collections.Generic.IEnumerable<TSource>! source, System.Collections.Generic.IEqualityComparer<TSource>? comparer) -> System.Collections.Generic.IEnumerable<TSource>!

MoreLinq/PublicAPI/netstandard2.1/PublicAPI.Unshipped.txt

@@ -1 +1,6 @@
 #nullable enable
+MoreLinq.Extensions.DuplicatesExtension
+static MoreLinq.Extensions.DuplicatesExtension.Duplicates<TSource>(this System.Collections.Generic.IEnumerable<TSource>! source) -> System.Collections.Generic.IEnumerable<TSource>!
+static MoreLinq.Extensions.DuplicatesExtension.Duplicates<TSource>(this System.Collections.Generic.IEnumerable<TSource>! source, System.Collections.Generic.IEqualityComparer<TSource>? comparer) -> System.Collections.Generic.IEnumerable<TSource>!
+static MoreLinq.MoreEnumerable.Duplicates<TSource>(this System.Collections.Generic.IEnumerable<TSource>! source) -> System.Collections.Generic.IEnumerable<TSource>!
+static MoreLinq.MoreEnumerable.Duplicates<TSource>(this System.Collections.Generic.IEnumerable<TSource>! source, System.Collections.Generic.IEqualityComparer<TSource>? comparer) -> System.Collections.Generic.IEnumerable<TSource>!

README.md

@@ -206,6 +206,12 @@ projected type.
 
 This method has 2 overloads.
 
+### Duplicates
+
+Returns all duplicate elements of the given source.
+
+This method has 2 overloads.
+
 ### EndsWith
 
 Determines whether the end of the first sequence is equivalent to the second

bld/Copyright.props

@@ -7,6 +7,7 @@
         Portions © 2015 Felipe Sateler, “sholland”.
         Portions © 2016 Andreas Gullberg Larsen, Leandro F. Vieira (leandromoh).
         Portions © 2017 Jonas Nyrup (jnyrup).
+        Portions © 2023 Julien Aspirot (julienasp).
         Portions © Microsoft. All rights reserved.
     </Copyright>
   </PropertyGroup>