From c1b52d16d79336e493597aa26b8c684e61ff3f3e Mon Sep 17 00:00:00 2001
From: Aimeos <aimeos@aimeos.org>
Date: Mon, 18 Nov 2024 17:36:50 +0100
Subject: [PATCH] Added asorted() 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 40ab29a..28a375a 100644
--- a/README.md
+++ b/README.md
@@ -126,6 +126,7 @@ will return:
 <a href="#arsort">arsort</a>
 <a href="#arsorted">arsorted</a>
 <a href="#asort">asort</a>
+<a href="#asorted">asorted</a>
 <a href="#at">at</a>
 <a href="#avg">avg</a>
 <a href="#before">before</a>
@@ -366,6 +367,7 @@ will return:
 * [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
+* [asorted()](#asorted) : Sort elements preserving keys in a copy of the map
 * [krsort()](#krsort) : Reverse sort elements by keys
 * [ksort()](#ksort) : Sort elements by keys
 * [order()](#order) : Orders elements by the passed keys
@@ -827,6 +829,44 @@ Map::from( [0 => 'C', 1 => 'b'] )->arsort( SORT_STRING|SORT_FLAG_CASE );
 ```
 
 
+### asorted()
+
+Sorts all elements and maintains the key association in a copy of the map.
+
+```php
+public function asorted( int $options = SORT_REGULAR ) : self
+```
+
+* @param **int** `$options` Sort options for `asort()`
+* @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 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( ['a' => 1, 'b' => 0] )->asorted();
+// ['b' => 0, 'a' => 1]
+
+Map::from( [0 => 'b', 1 => 'a'] )->asorted();
+// [1 => 'a', 0 => 'b']
+
+Map::from( [0 => 'C', 1 => 'b'] )->asorted();
+// [0 => 'C', 1 => 'b'] because 'C' < 'b'
+
+Map::from( [0 => 'C', 1 => 'b'] )->asorted( SORT_STRING|SORT_FLAG_CASE );
+// [1 => 'b', 0 => 'C'] because 'C' -> 'c' and 'c' > 'b'
+```
+
+
 ### at()
 
 Returns the value at the given position.
diff --git a/src/Map.php b/src/Map.php
index 2531573..febb285 100644
--- a/src/Map.php
+++ b/src/Map.php
@@ -518,6 +518,40 @@ public function asort( int $options = SORT_REGULAR ) : self
 	}
 
 
+	/**
+	 * Sorts a copy of all elements and maintains the key association.
+	 *
+	 * Examples:
+	 *  Map::from( ['a' => 1, 'b' => 0] )->asorted();
+	 *  Map::from( [0 => 'b', 1 => 'a'] )->asorted();
+	 *  Map::from( [0 => 'C', 1 => 'b'] )->asorted();
+	 *  Map::from( [0 => 'C', 1 => 'b'] )->asorted( SORT_STRING|SORT_FLAG_CASE );
+	 *
+	 * Results:
+	 *  ['b' => 0, 'a' => 1]
+	 *  [1 => 'a', 0 => 'b']
+	 *  [0 => 'C', 1 => 'b'] // because 'C' < 'b'
+	 *  [1 => 'b', 0 => 'C'] // 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 asort()
+	 * @return self<int|string,mixed> Updated map for fluid interface
+	 */
+	public function asorted( int $options = SORT_REGULAR ) : self
+	{
+		return ( clone $this )->asort( $options );
+	}
+
+
 	/**
 	 * Returns the value at the given position.
 	 *
diff --git a/tests/MapTest.php b/tests/MapTest.php
index e08f2d6..b4efd8f 100644
--- a/tests/MapTest.php
+++ b/tests/MapTest.php
@@ -141,6 +141,18 @@ public function testAsortStringsCase()
 	}
 
 
+	public function testAsorted()
+	{
+		$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->asorted();
+
+		$this->assertInstanceOf( Map::class, $r );
+		$this->assertNotSame( $r->toArray(), $m->toArray() );
+		$this->assertSame( [3 => -4, 1 => -3, 2 => -2, 4 => -1, 5 => 0, 8 => 1, 9 => 2, 7 => 3, 6 => 4], $r->toArray() );
+	}
+
+
 	public function testAt()
 	{
 		$this->assertSame( 1, Map::from( [1, 3, 5] )->at( 0 ) );