From 2cd45fc3448c98d03dda75dbc236309083aae404 Mon Sep 17 00:00:00 2001
From: Aimeos <aimeos@aimeos.org>
Date: Wed, 13 Nov 2024 09:01:58 +0100
Subject: [PATCH] Added arsorted() method

---
 README.md         | 40 ++++++++++++++++++++++++++++++++++++++++
 src/Map.php       | 34 ++++++++++++++++++++++++++++++++++
 tests/MapTest.php | 12 ++++++++++++
 3 files changed, 86 insertions(+)

diff --git a/README.md b/README.md
index 19d6108..40ab29a 100644
--- a/README.md
+++ b/README.md
@@ -124,6 +124,7 @@ will return:
 <a href="#after">after</a>
 <a href="#all">all</a>
 <a href="#arsort">arsort</a>
+<a href="#arsorted">arsorted</a>
 <a href="#asort">asort</a>
 <a href="#at">at</a>
 <a href="#avg">avg</a>
@@ -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&#60;int&#124;string,mixed&#62;** 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&#124;SORT_FLAG_CASE and SORT_NATURAL&#124;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<int|string,mixed> 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();