From 3fc2e7259ec5bb7dfe1a9f228a68c4bc25ddd0af Mon Sep 17 00:00:00 2001
From: Oliver Booth <me@olivr.me>
Date: Mon, 27 Feb 2023 13:15:20 +0000
Subject: [PATCH] Add Random.NextFrom([ReadOnly]Span<T>)

---
 CHANGELOG.md                       |  1 +
 X10D.Tests/src/Core/RandomTests.cs | 43 ++++++++++++++++++
 X10D/src/Core/RandomExtensions.cs  | 71 ++++++++++++++++++++++++++++++
 3 files changed, 115 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 13fa098..f77f0e8 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -38,6 +38,7 @@
 - X10D: Added `PopCount()` for built-in integer types
 - X10D: Added `Quaternion.ToAxisAngle(out float, out float)`
 - X10D: Added `Quaternion.ToVector3()`
+- X10D: Added `Random.NextFrom(Span<T>)` and `Random.NextFrom(ReadOnlySpan<T>)`
 - X10D: Added `ReadOnlySpan<char>.CountSubstring(char)`
 - X10D: Added `ReadOnlySpan<char>.CountSubstring(ReadOnlySpan<char>[, StringComparison])`
 - X10D: Added `ReadOnlySpan<char>.ToTimeSpan()`
diff --git a/X10D.Tests/src/Core/RandomTests.cs b/X10D.Tests/src/Core/RandomTests.cs
index 41d182b..698cc74 100644
--- a/X10D.Tests/src/Core/RandomTests.cs
+++ b/X10D.Tests/src/Core/RandomTests.cs
@@ -1,4 +1,5 @@
 using Microsoft.VisualStudio.TestTools.UnitTesting;
+using X10D.Collections;
 using X10D.Core;
 
 namespace X10D.Tests.Core;
@@ -126,6 +127,48 @@ public class RandomTests
         Assert.AreEqual(0, random.NextFrom(Source()));
     }
 
+    [TestMethod]
+    public void NextFromSpan_ShouldThrow_GivenNullRandom()
+    {
+        Random? random = null;
+        Assert.ThrowsException<ArgumentNullException>(() =>
+        {
+            Span<int> span = stackalloc int[1];
+            return random!.NextFrom(span);
+        });
+    }
+
+    [TestMethod]
+    public void NextFromReadOnlySpan_ShouldThrow_GivenNullRandom()
+    {
+        Random? random = null;
+        Assert.ThrowsException<ArgumentNullException>(() =>
+        {
+            Span<int> span = stackalloc int[1];
+            return random!.NextFrom(span.AsReadOnly());
+        });
+    }
+
+    [TestMethod]
+    public void NextFromSpan_ShouldReturnOnlyValue_GivenSpanWithLength1()
+    {
+        Span<int> span = stackalloc int[1];
+        span[0] = 42;
+
+        var random = new Random(1234);
+        Assert.AreEqual(42, random.NextFrom(span));
+    }
+
+    [TestMethod]
+    public void NextFromReadOnlySpan_ShouldReturnOnlyValue_GivenSpanWithLength1()
+    {
+        Span<int> span = stackalloc int[1];
+        span[0] = 42;
+
+        var random = new Random(1234);
+        Assert.AreEqual(42, random.NextFrom(span.AsReadOnly()));
+    }
+
     [TestMethod]
     public void NextInt16_ShouldBe13076_GivenSeed1234()
     {
diff --git a/X10D/src/Core/RandomExtensions.cs b/X10D/src/Core/RandomExtensions.cs
index c5faa0f..c4cc672 100644
--- a/X10D/src/Core/RandomExtensions.cs
+++ b/X10D/src/Core/RandomExtensions.cs
@@ -185,6 +185,77 @@ public static class RandomExtensions
         return list[random.Next(list.Count)];
     }
 
+    /// <summary>
+    ///     Returns a random element from the specified span of elements using the current <see cref="System.Random" /> instance.
+    /// </summary>
+    /// <typeparam name="T">The element type.</typeparam>
+    /// <param name="random">The <see cref="System.Random" /> instance.</param>
+    /// <param name="source">The span of elements from which to draw.</param>
+    /// <returns>A random element of type <typeparamref name="T" /> from <paramref name="source" />.</returns>
+    /// <exception cref="ArgumentNullException">
+    ///     <paramref name="random" /> is is <see langword="null" />
+    ///     -or-
+    ///     <paramref name="source" /> is <see langword="null" />.
+    /// </exception>
+    /// <example>
+    ///     <code lang="csharp">
+    /// Span&lt;int&gt; span = stackalloc span[5];
+    /// // populate the span ...
+    ///
+    /// var random = new Random();
+    /// var number = random.NextFrom(span);
+    /// </code>
+    /// </example>
+    public static T NextFrom<T>(this Random random, Span<T> source)
+    {
+#if NET6_0_OR_GREATER
+        ArgumentNullException.ThrowIfNull(random);
+#else
+        if (random is null)
+        {
+            throw new ArgumentNullException(nameof(random));
+        }
+#endif
+
+        return source[random.Next(source.Length)];
+    }
+
+    /// <summary>
+    ///     Returns a random element from the specified readonly span of elements using the current <see cref="System.Random" />
+    ///     instance.
+    /// </summary>
+    /// <typeparam name="T">The element type.</typeparam>
+    /// <param name="random">The <see cref="System.Random" /> instance.</param>
+    /// <param name="source">The readonly span of elements from which to draw.</param>
+    /// <returns>A random element of type <typeparamref name="T" /> from <paramref name="source" />.</returns>
+    /// <exception cref="ArgumentNullException">
+    ///     <paramref name="random" /> is is <see langword="null" />
+    ///     -or-
+    ///     <paramref name="source" /> is <see langword="null" />.
+    /// </exception>
+    /// <example>
+    ///     <code lang="csharp">
+    /// Span&lt;int&gt; span = stackalloc span[5];
+    /// // populate the span ...
+    ///
+    /// var random = new Random();
+    /// var number = random.NextFrom(span.AsReadOnly());
+    /// </code>
+    /// </example>
+    public static T NextFrom<T>(this Random random, ReadOnlySpan<T> source)
+    {
+#if NET6_0_OR_GREATER
+        ArgumentNullException.ThrowIfNull(random);
+#else
+        if (random is null)
+        {
+            throw new ArgumentNullException(nameof(random));
+        }
+#endif
+
+        return source[random.Next(source.Length)];
+    }
+
     /// <summary>
     ///     Returns a non-negative random integer.
     /// </summary>