Add Random.GetItems (#319)

Author: SimonCropp

apiCount.include.md

@@ -1 +1 @@
-**API count: 539**
+**API count: 542**

api_list.include.md

@@ -293,6 +293,9 @@
 
 #### Random
 
+ * `void GetItems<T>(Random, ReadOnlySpan<T>, Span<T>)` [reference](https://learn.microsoft.com/en-us/dotnet/api/system.random.getitems#system-random-getitems-1(system-readonlyspan((-0))-system-span((-0))))
+ * `T[] GetItems<T>(Random, ReadOnlySpan<T>, int)` [reference](https://learn.microsoft.com/en-us/dotnet/api/system.random.getitems#system-random-getitems-1(system-readonlyspan((-0))-system-int32))
+ * `T[] GetItems<T>(Random, T[], int)` [reference](https://learn.microsoft.com/en-us/dotnet/api/system.random.getitems#system-random-getitems-1(-0()-system-int32))
  * `void NextBytes(Random, Span<byte>)` [reference](https://learn.microsoft.com/en-us/dotnet/api/system.random.nextbytes#system-random-nextbytes(system-span((system-byte))))
  * `void Shuffle<T>(Random, T[])` [reference](https://learn.microsoft.com/en-us/dotnet/api/system.random.nextbytes#system-random-nextbytes(system-span((system-byte))))
  * `void Shuffle<T>(Random, Span<T>)` [reference](https://learn.microsoft.com/en-us/dotnet/api/system.random.nextbytes#system-random-nextbytes(system-span((system-byte))))

readme.md

@@ -12,7 +12,7 @@ The package targets `netstandard2.0` and is designed to support the following ru
  * `net5.0`, `net6.0`, `net7.0`, `net8.0`, `net9.0`, `net10.0`
 
 
-**API count: 539**<!-- singleLineInclude: apiCount. path: /apiCount.include.md -->
+**API count: 542**<!-- singleLineInclude: apiCount. path: /apiCount.include.md -->
 
 
 **See [Milestones](../../milestones?state=closed) for release notes.**
@@ -767,6 +767,9 @@ The class `Polyfill` includes the following extension methods:
 
 #### Random
 
+ * `void GetItems<T>(Random, ReadOnlySpan<T>, Span<T>)`
+ * `T[] GetItems<T>(Random, ReadOnlySpan<T>, int)`
+ * `T[] GetItems<T>(Random, T[], int)`
  * `void NextBytes(Random, Span<byte>)` [reference](https://learn.microsoft.com/en-us/dotnet/api/system.random.nextbytes#system-random-nextbytes(system-span((system-byte))))
  * `void Shuffle<T>(Random, T[])` [reference](https://learn.microsoft.com/en-us/dotnet/api/system.random.nextbytes#system-random-nextbytes(system-span((system-byte))))
  * `void Shuffle<T>(Random, Span<T>)` [reference](https://learn.microsoft.com/en-us/dotnet/api/system.random.nextbytes#system-random-nextbytes(system-span((system-byte))))

src/Consume/Consume.cs

@@ -476,7 +476,17 @@ void Random_Methods()
         Span<byte> bufferSpan = new byte[10];
         random.NextBytes(bufferSpan);
         random.Shuffle(bufferSpan);
+
+        ReadOnlySpan<int> choicesSpan = [1, 2, 3, 4, 5];
+        Span<int> destination = new int[10];
+        random.GetItems(choicesSpan, destination);
+
+        var resultFromSpan = random.GetItems(choicesSpan, 10);
 #endif
+
+        int[] choicesArray = [1, 2, 3, 4, 5];
+        var resultFromArray = random.GetItems(choicesArray, 10);
+
         var bufferArray = new byte[10];
         random.Shuffle(bufferArray);
     }

src/Polyfill/Polyfill_Random.cs

@@ -7,7 +7,82 @@ namespace Polyfills;
 
 static partial class Polyfill
 {
+#if !NET8_0_OR_GREATER
+
+#if FeatureMemory
+
+    /// <summary>
+    /// Fills the elements of a specified span with items chosen at random from the provided set of choices.
+    /// </summary>
+    //Link: https://learn.microsoft.com/en-us/dotnet/api/system.random.getitems#system-random-getitems-1(system-readonlyspan((-0))-system-span((-0)))
+    public static void GetItems<T>(
+        this Random target,
+        ReadOnlySpan<T> choices,
+        Span<T> destination)
+    {
+        if (choices.IsEmpty)
+        {
+            throw new ArgumentException("Choices cannot be empty.", nameof(choices));
+        }
+
+        for (int i = 0; i < destination.Length; i++)
+        {
+            destination[i] = choices[target.Next(choices.Length)];
+        }
+    }
+
+    /// <summary>
+    /// Creates an array populated with items chosen at random from the provided set of choices.
+    /// </summary>
+    //Link: https://learn.microsoft.com/en-us/dotnet/api/system.random.getitems#system-random-getitems-1(system-readonlyspan((-0))-system-int32)
+    public static T[] GetItems<T>(
+        this Random target,
+        ReadOnlySpan<T> choices,
+        int length)
+    {
+        if (choices.IsEmpty)
+        {
+            throw new ArgumentException("Choices cannot be empty.", nameof(choices));
+        }
+
+        T[] result = new T[length];
+        for (int i = 0; i < length; i++)
+        {
+            result[i] = choices[target.Next(choices.Length)];
+        }
+
+        return result;
+    }
+
+#endif
+
+    /// <summary>
+    /// Creates an array populated with items chosen at random from the provided set of choices.
+    /// </summary>
+    //Link: https://learn.microsoft.com/en-us/dotnet/api/system.random.getitems#system-random-getitems-1(-0()-system-int32)
+    public static T[] GetItems<T>(
+        this Random target,
+        T[] choices,
+        int length)
+    {
+        if (choices.Length == 0)
+        {
+            throw new ArgumentException("Choices cannot be null or empty.", nameof(choices));
+        }
+
+        T[] result = new T[length];
+        for (int i = 0; i < length; i++)
+        {
+            result[i] = choices[target.Next(choices.Length)];
+        }
+
+        return result;
+    }
+
+#endif
+
 #if (NETSTANDARD || NETFRAMEWORK || NETCOREAPP2_0) && FeatureMemory
+
     /// <summary>
     /// Fills the elements of a specified span of bytes with random numbers.
     /// </summary>

src/Tests/PolyfillTests_Random.cs

@@ -1,13 +1,60 @@
 partial class PolyfillTests
 {
+
 #if FeatureMemory
+
     [Test]
     public void RandomNextBytesSpan()
     {
         var random = new Random();
         Span<byte> buffer = new byte[10];
         random.NextBytes(buffer);
-        Assert.IsTrue(buffer.ToArray().Any(b => b != 0));
+        Assert.IsTrue(buffer.ToArray().Any(_ => _ != 0));
+    }
+
+    [Test]
+    public void RandomGetItems_ReadOnlySpan_Span()
+    {
+        var random = new Random();
+        ReadOnlySpan<int> choices = [1, 2, 3, 4, 5];
+        Span<int> destination = new int[10];
+        random.GetItems(choices, destination);
+
+        Assert.IsTrue(destination.Length == 10);
+        foreach (var item in destination)
+        {
+            Assert.IsTrue(choices.Contains(item));
+        }
+    }
+
+    [Test]
+    public void RandomGetItems_ReadOnlySpan_Int()
+    {
+        var random = new Random();
+        ReadOnlySpan<int> choices = [1, 2, 3, 4, 5];
+        var length = 10;
+        var result = random.GetItems(choices, length);
+
+        Assert.AreEqual(length, result.Length);
+        foreach (var item in result)
+        {
+            Assert.Contains(item, choices.ToArray());
+        }
+    }
+
+    [Test]
+    public void RandomGetItems_Array_Int()
+    {
+        var random = new Random();
+        int[] choices = [1, 2, 3, 4, 5];
+        var length = 10;
+        var result = random.GetItems(choices, length);
+
+        Assert.AreEqual(length, result.Length);
+        foreach (var item in result)
+        {
+            Assert.Contains(item, choices);
+        }
     }
 
     [Test]
@@ -19,7 +66,9 @@ public void RandomShuffleSpan()
         random.Shuffle(buffer);
         Assert.IsTrue(buffer.ToArray().Any(b => b != 0));
     }
+
 #endif
+
     [Test]
     public void RandomShuffleArray()
     {