diff --git a/README.md b/README.md index 19d6108..40ab29a 100644 --- a/README.md +++ b/README.md @@ -124,6 +124,7 @@ will return: after all arsort +arsorted asort at avg @@ -363,6 +364,7 @@ will return: ### Order By * [arsort()](#arsort) : Reverse sort elements preserving keys +* [arsorted()](#arsorted) : Reverse sort elements preserving keys in a copy of the map * [asort()](#asort) : Sort elements preserving keys * [krsort()](#krsort) : Reverse sort elements by keys * [ksort()](#ksort) : Sort elements by keys @@ -749,6 +751,44 @@ Map::from( [0 => 'C', 1 => 'b'] )->arsort( SORT_STRING|SORT_FLAG_CASE ); ``` +### arsorted() + +Sorts all elements in reverse order and maintains the key association in a copy of the map. + +```php +public function arsorted( int $options = SORT_REGULAR ) : self +``` + +* @param **int** `$options` Sort options for `arsort()` +* @return **self<int|string,mixed>** Updated map for fluid interface + +The keys are preserved using this method and no new map is created. + +The `$options` parameter modifies how the values are compared. Possible parameter values are: +- SORT_REGULAR : compare elements normally (don't change types) +- SORT_NUMERIC : compare elements numerically +- SORT_STRING : compare elements as strings +- SORT_LOCALE_STRING : compare elements as strings, based on the current locale or changed by `setlocale()` +- SORT_NATURAL : compare elements as strings using "natural ordering" like `natsort()` +- SORT_FLAG_CASE : use SORT_STRING|SORT_FLAG_CASE and SORT_NATURAL|SORT_FLAG_CASE to sort strings case-insensitively + +**Examples:** + +```php +Map::from( ['b' => 0, 'a' => 1] )->arsorted(); +// ['a' => 1, 'b' => 0] + +Map::from( ['a', 'b'] )->arsorted(); +// ['b', 'a'] + +Map::from( [0 => 'C', 1 => 'b'] )->arsorted(); +// [1 => 'b', 0 => 'C'] + +Map::from( [0 => 'C', 1 => 'b'] )->arsorted( SORT_STRING|SORT_FLAG_CASE ); +// [0 => 'C', 1 => 'b'] because 'C' -> 'c' and 'c' > 'b' +``` + + ### asort() Sorts all elements and maintains the key association. diff --git a/src/Map.php b/src/Map.php index 6009b84..2531573 100644 --- a/src/Map.php +++ b/src/Map.php @@ -449,6 +449,40 @@ public function arsort( int $options = SORT_REGULAR ) : self } + /** + * Sorts a copy of all elements in reverse order and maintains the key association. + * + * Examples: + * Map::from( ['b' => 0, 'a' => 1] )->arsorted(); + * Map::from( ['a', 'b'] )->arsorted(); + * Map::from( [0 => 'C', 1 => 'b'] )->arsorted(); + * Map::from( [0 => 'C', 1 => 'b'] )->arsorted( SORT_STRING|SORT_FLAG_CASE ); + * + * Results: + * ['a' => 1, 'b' => 0] + * ['b', 'a'] + * [1 => 'b', 0 => 'C'] + * [0 => 'C', 1 => 'b'] // because 'C' -> 'c' and 'c' > 'b' + * + * The parameter modifies how the values are compared. Possible parameter values are: + * - SORT_REGULAR : compare elements normally (don't change types) + * - SORT_NUMERIC : compare elements numerically + * - SORT_STRING : compare elements as strings + * - SORT_LOCALE_STRING : compare elements as strings, based on the current locale or changed by setlocale() + * - SORT_NATURAL : compare elements as strings using "natural ordering" like natsort() + * - SORT_FLAG_CASE : use SORT_STRING|SORT_FLAG_CASE and SORT_NATURALSORT_FLAG_CASE to sort strings case-insensitively + * + * The keys are preserved using this method and no new map is created. + * + * @param int $options Sort options for arsort() + * @return self Updated map for fluid interface + */ + public function arsorted( int $options = SORT_REGULAR ) : self + { + return ( clone $this )->arsort( $options ); + } + + /** * Sorts all elements and maintains the key association. * diff --git a/tests/MapTest.php b/tests/MapTest.php index 1bc6fc6..e08f2d6 100644 --- a/tests/MapTest.php +++ b/tests/MapTest.php @@ -102,6 +102,18 @@ public function testArsortStringsCase() } + public function testArsorted() + { + $l = [1 => -3, 2 => -2, 3 => -4, 4 => -1, 5 => 0, 6 => 4, 7 => 3, 8 => 1, 9 => 2]; + $m = new Map( $l ); + $r = $m->arsorted(); + + $this->assertInstanceOf( Map::class, $r ); + $this->assertNotSame( $r->toArray(), $m->toArray() ); + $this->assertSame( [6 => 4, 7 => 3, 9 => 2, 8 => 1, 5 => 0, 4 => -1, 2 => -2, 1 => -3, 3 => -4], $r->toArray() ); + } + + public function testAsortNummeric() { $m = ( new Map( [1 => -3, 2 => -2, 3 => -4, 4 => -1, 5 => 0, 6 => 4, 7 => 3, 8 => 1, 9 => 2] ) )->asort();