From 14e638e6d91a7397f83d6f4de2d8aaccf67a9f53 Mon Sep 17 00:00:00 2001
From: Oliver Booth <me@olivr.me>
Date: Fri, 31 Mar 2023 14:53:02 +0100
Subject: [PATCH] feat: add IEnumerable<T>.ConcatOne

---
 CHANGELOG.md                           |  1 +
 X10D.Tests/src/Linq/EnumerableTests.cs | 31 ++++++++++++++++++++++++++
 X10D/src/Linq/EnumerableExtensions.cs  | 25 +++++++++++++++++++++
 3 files changed, 57 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 6ff7772..96d9c14 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -26,6 +26,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - X10D: Added `double.LinearToGamma([gamma])` and `float.LinearToGamma([gamma])`. (#60)
 - X10D: Added `double.GammaToLinear([gamma])` and `float.GammaToLinear([gamma])`. (#60)
 - X10D: Added `GreatestCommonFactor` for built-in integer types.
+- X10D: Added `IEnumerable<T>.ConcatOne(T)`.
 - X10D: Added `IEnumerable<T>.CountWhereNot(Func<T, bool>)`.
 - X10D: Added `IEnumerable<T>.FirstWhereNot(Func<T, bool>)`.
 - X10D: Added `IEnumerable<T>.FirstWhereNotOrDefault(Func<T, bool>)`.
diff --git a/X10D.Tests/src/Linq/EnumerableTests.cs b/X10D.Tests/src/Linq/EnumerableTests.cs
index 838ec54..e211309 100644
--- a/X10D.Tests/src/Linq/EnumerableTests.cs
+++ b/X10D.Tests/src/Linq/EnumerableTests.cs
@@ -6,6 +6,37 @@ namespace X10D.Tests.Linq;
 [TestClass]
 public class EnumerableTests
 {
+    [TestMethod]
+    public void ConcatOne_ShouldReturnConcatenatedSequence_GivenValidSequenceAndValue()
+    {
+        IEnumerable<string> source = new[] {"Hello"};
+        string[] expected = {"Hello", "World"};
+
+        string[] actual = source.ConcatOne("World").ToArray();
+
+        Assert.AreEqual(2, actual.Length);
+        CollectionAssert.AreEqual(expected, actual);
+    }
+
+    [TestMethod]
+    public void ConcatOne_ShouldReturnSingletonSequence_GivenEmptySequenceAndValidValue()
+    {
+        IEnumerable<string> source = Enumerable.Empty<string>();
+        string[] expected = {"Foobar"};
+
+        string[] actual = source.ConcatOne("Foobar").ToArray();
+
+        Assert.AreEqual(1, actual.Length);
+        CollectionAssert.AreEqual(expected, actual);
+    }
+
+    [TestMethod]
+    public void ConcatOne_ShouldThrowArgumentNullException_GivenNullSource()
+    {
+        IEnumerable<string>? source = null;
+        Assert.ThrowsException<ArgumentNullException>(() => source!.ConcatOne("Foobar"));
+    }
+
     [TestMethod]
     public void MinMax_ShouldReturnCorrectValues_UsingDefaultComparer()
     {
diff --git a/X10D/src/Linq/EnumerableExtensions.cs b/X10D/src/Linq/EnumerableExtensions.cs
index ed0115f..c94f10a 100644
--- a/X10D/src/Linq/EnumerableExtensions.cs
+++ b/X10D/src/Linq/EnumerableExtensions.cs
@@ -9,6 +9,31 @@ namespace X10D.Linq;
 /// </summary>
 public static class EnumerableExtensions
 {
+    /// <summary>
+    ///     Concatenates a single value to the end of a sequence.
+    /// </summary>
+    /// <param name="source">The source sequence.</param>
+    /// <param name="value">The value to concatenate to the end of the source sequence.</param>
+    /// <typeparam name="TSource">The type of the elements in <paramref name="source" />.</typeparam>
+    /// <returns>
+    ///     An <see cref="IEnumerable{T}" /> that contains the concatenated elements of the input sequence, and the specified
+    ///     value.
+    /// </returns>
+    /// <exception cref="ArgumentNullException"><paramref name="source" /> is <see langword="null" />.</exception>
+    public static IEnumerable<TSource> ConcatOne<TSource>(this IEnumerable<TSource> source, TSource value)
+    {
+#if NET6_0_OR_GREATER
+        ArgumentNullException.ThrowIfNull(source);
+#else
+        if (source is null)
+        {
+            throw new ArgumentNullException(nameof(source));
+        }
+#endif
+
+        return source.Concat(new[] {value});
+    }
+
     /// <summary>
     ///     Returns the minimum and maximum values in a sequence of values.
     /// </summary>