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