feature: introduce OrderedListInterface#shuffle

Signed-off-by: Maximilian Bösing <[email protected]>

src/OrderedList.php

@@ -20,10 +20,12 @@
 use function array_unshift;
 use function array_values;
 use function assert;
+use function count;
 use function hash;
 use function implode;
 use function is_callable;
 use function serialize;
+use function shuffle;
 use function sort;
 use function sprintf;
 use function usort;
@@ -471,4 +473,22 @@ public function removeAt(int $index): OrderedListInterface
     {
         return $this->filter(fn ($_, int $i) => $i !== $index);
     }
+
+    public function shuffle(): OrderedListInterface
+    {
+        if (count($this->data) <= 1) {
+            return $this;
+        }
+
+        $data = $this->data;
+
+        do {
+            shuffle($data);
+        } while ($this->data === $data);
+
+        $instance       = clone $this;
+        $instance->data = $data;
+
+        return $instance;
+    }
 }

src/OrderedListInterface.php

@@ -264,4 +264,11 @@ public function prepend($value): self;
      * @return OrderedListInterface<TValue>
      */
     public function removeAt(int $index): self;
+
+    /**
+     * Shuffles all the values within the list.
+     *
+     * @return OrderedListInterface<TValue>
+     */
+    public function shuffle(): self;
 }

tests/GenericOrderedListTest.php

@@ -1473,4 +1473,18 @@ public function testWillRemoveItemAtSpecificPosition(): void
         $list = $list->removeAt(1);
         self::assertSame([1, 3], $list->toNativeArray());
     }
+
+    public function testWillShuffleValuesInList(): void
+    {
+        $list = new GenericOrderedList([
+            1,
+            2,
+            3,
+        ]);
+
+        $list2 = $list->shuffle();
+        self::assertSame([1, 2, 3], $list->toNativeArray());
+        self::assertNotSame($list, $list2);
+        self::assertNotSame([1, 2, 3], $list2->toNativeArray());
+    }
 }