diff --git a/README.md b/README.md index e2b7ddf..551d83a 100644 --- a/README.md +++ b/README.md @@ -285,6 +285,7 @@ will return: unique unshift usort +usorted values walk where @@ -391,6 +392,7 @@ will return: * [uksort()](#uksort) : Sorts elements by keys using callback * [uksorted()](#uksorted) : Sorts elements by keys using callback in a copy of the map * [usort()](#usort) : Sorts elements using callback assigning new keys +* [usorted()](#usorted) : Sorts elements using callback assigning new keys in a copy of the map ### Shorten @@ -6186,6 +6188,37 @@ Map::from( ['a' => 'B', 'b' => 'a'] )->usort( function( $itemA, $itemB ) { ``` +### usorted() + +Sorts a copy of all elements using a callback without maintaining the key association. + +```php +public function usorted( callable $callback ) : self +``` + +* @param **callable** `$callback` Function with (itemA, itemB) parameters and returns -1 (<), 0 (=) and 1 (>) +* @return **self<int|string,mixed>** Updated map for fluid interface + +The given callback will be used to compare the values. The callback must accept +two parameters (item A and B) and must return -1 if item A is smaller than +item B, 0 if both are equal and 1 if item A is greater than item B. Both, a +method name and an anonymous function can be passed. + +The keys are NOT preserved and elements get a new index. + +**Examples:** + +```php +Map::from( ['a' => 'B', 'b' => 'a'] )->usorted( 'strcasecmp' ); +// [0 => 'a', 1 => 'B'] + +Map::from( ['a' => 'B', 'b' => 'a'] )->usorted( function( $itemA, $itemB ) { + return strtolower( $itemA ) <=> strtolower( $itemB ); +} ); +// [0 => 'a', 1 => 'B'] +``` + + ### values() Resets the keys and return the values in a new map. diff --git a/src/Map.php b/src/Map.php index 0b1781a..de37e70 100644 --- a/src/Map.php +++ b/src/Map.php @@ -5640,6 +5640,35 @@ public function usort( callable $callback ) : self } + /** + * Sorts a copy of all elements using a callback using new keys. + * + * The given callback will be used to compare the values. The callback must accept + * two parameters (item A and B) and must return -1 if item A is smaller than + * item B, 0 if both are equal and 1 if item A is greater than item B. Both, a + * method name and an anonymous function can be passed. + * + * Examples: + * Map::from( ['a' => 'B', 'b' => 'a'] )->usorted( 'strcasecmp' ); + * Map::from( ['a' => 'B', 'b' => 'a'] )->usorted( function( $itemA, $itemB ) { + * return strtolower( $itemA ) <=> strtolower( $itemB ); + * } ); + * + * Results: + * [0 => 'a', 1 => 'B'] + * [0 => 'a', 1 => 'B'] + * + * The keys aren't preserved and elements get a new index. + * + * @param callable $callback Function with (itemA, itemB) parameters and returns -1 (<), 0 (=) and 1 (>) + * @return self Updated map for fluid interface + */ + public function usorted( callable $callback ) : self + { + return ( clone $this )->usort( $callback ); + } + + /** * Resets the keys and return the values in a new map. * diff --git a/tests/MapTest.php b/tests/MapTest.php index a6f74bc..8faa22f 100644 --- a/tests/MapTest.php +++ b/tests/MapTest.php @@ -3610,6 +3610,19 @@ public function testUsort() } + public function testUsorted() + { + $m = new Map( ['foo', 'bar-10', 'bar-1'] ); + $r = $m->usorted( function( $a, $b ) { + return strrev( $a ) <=> strrev( $b ); + } ); + + $this->assertNotSame( $r, $m ); + $this->assertInstanceOf( Map::class, $r ); + $this->assertSame( ['bar-10', 'bar-1', 'foo'], $r->toArray() ); + } + + public function testUnionArray() { $m = new Map( ['name' => 'Hello'] );