Added shuffled() method

README.md

@@ -239,6 +239,7 @@ will return:
 <a href="#set">set</a>
 <a href="#shift">shift</a>
 <a href="#shuffle">shuffle</a>
+<a href="#shuffled">shuffled</a>
 <a href="#skip">skip</a>
 <a href="#slice">slice</a>
 <a href="#some">some</a>
@@ -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&#60;int&#124;string,mixed&#62;** 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()
 

src/Map.php

@@ -3936,6 +3936,7 @@ public function shift()
 	 *
 	 * @param bool $assoc True to preserve keys, false to assign new keys
 	 * @return self<int|string,mixed> 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<int|string,mixed> 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.
 	 *

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() );