diff --git a/README.md b/README.md
index 877b7d1..cbd892d 100644
--- a/README.md
+++ b/README.md
@@ -239,6 +239,7 @@ will return:
set
shift
shuffle
+shuffled
skip
slice
some
@@ -371,6 +372,7 @@ will return:
* [toReversed()](#toreversed) : Reverses the element order in a copy of the map (alias)
* [rsort()](#rsort) : Reverse sort elements using new keys
* [shuffle()](#shuffle) : Randomizes the element order
+* [shuffled()](#shuffled) : Randomizes the element order in a copy of the map
* [sort()](#sort) : Sorts the elements in-place assigning new keys
* [sorted()](#sorted) : Sorts the elements in a copy of the map using new keys
* [toSorted()](#tosorted) : Sorts the elements in a copy of the map using new keys (alias)
@@ -4436,6 +4438,36 @@ Map::from( [2 => 'a', 4 => 'b'] )->shuffle( true );
// [2 => 'a', 4 => 'b'] in random order with keys preserved
```
+**See also:**
+
+* [shuffled()](#shuffled) - Shuffles the elements in a copy of the map.
+
+
+### shuffled()
+
+Shuffles the elements in a copy of the map.
+
+```php
+public function shuffled( bool $assoc = false ) : self
+```
+
+* @param **bool** `$assoc` True to preserve keys, false to assign new keys
+* @return **self<int|string,mixed>** New map with a shuffled copy of the elements
+
+**Examples:**
+
+```php
+Map::from( [2 => 'a', 4 => 'b'] )->shuffled();
+// ['a', 'b'] in random order with new keys
+
+Map::from( [2 => 'a', 4 => 'b'] )->shuffled( true );
+// [2 => 'a', 4 => 'b'] in random order with keys preserved
+```
+
+**See also:**
+
+* [shuffle()](#shuffle) - Shuffles the elements in the map without returning a new map
+
### skip()
diff --git a/src/Map.php b/src/Map.php
index 04adaec..7b8dad5 100644
--- a/src/Map.php
+++ b/src/Map.php
@@ -3936,6 +3936,7 @@ public function shift()
*
* @param bool $assoc True to preserve keys, false to assign new keys
* @return self Updated map for fluid interface
+ * @see shuffled() - Shuffles the elements in a copy of the map
*/
public function shuffle( bool $assoc = false ) : self
{
@@ -3957,11 +3958,32 @@ public function shuffle( bool $assoc = false ) : self
shuffle( $this->list() );
}
-
return $this;
}
+ /**
+ * Shuffles the elements in a copy of the map.
+ *
+ * Examples:
+ * Map::from( [2 => 'a', 4 => 'b'] )->shuffled();
+ * Map::from( [2 => 'a', 4 => 'b'] )->shuffled( true );
+ *
+ * Results:
+ * The map in the first example will contain "a" and "b" in random order and
+ * with new keys assigned. The second call will also return all values in
+ * random order but preserves the keys of the original list.
+ *
+ * @param bool $assoc True to preserve keys, false to assign new keys
+ * @return self New map with a shuffled copy of the elements
+ * @see shuffle() - Shuffles the elements in the map without returning a new map
+ */
+ public function shuffled( bool $assoc = false ) : self
+ {
+ return ( clone $this )->shuffle( $assoc );
+ }
+
+
/**
* Returns a new map with the given number of items skipped.
*
diff --git a/tests/MapTest.php b/tests/MapTest.php
index 1ff994b..0fedfea 100644
--- a/tests/MapTest.php
+++ b/tests/MapTest.php
@@ -2730,6 +2730,17 @@ public function testShuffleAssoc()
}
+ public function testShuffled()
+ {
+ $m = new Map( range( 0, 100, 10 ) );
+ $r = $m->shuffled();
+
+ $this->assertNotSame( $r, $m );
+ $this->assertInstanceOf( Map::class, $r );
+ $this->assertNotEquals( $r->toArray(), $m->toArray() );
+ }
+
+
public function testSkip()
{
$this->assertSame( [2 => 3, 3 => 4], Map::from( [1, 2, 3, 4] )->skip( 2 )->toArray() );