From 822794e7b221d2b2beadd06519221ce66ced1b55 Mon Sep 17 00:00:00 2001
From: Aimeos <aimeos@aimeos.org>
Date: Fri, 22 Nov 2024 10:27:05 +0100
Subject: [PATCH] Added uasorted() method

---
 README.md         | 33 +++++++++++++++++++++++++++++++++
 src/Map.php       | 29 +++++++++++++++++++++++++++++
 tests/MapTest.php | 13 +++++++++++++
 3 files changed, 75 insertions(+)

diff --git a/README.md b/README.md
index 02d3fd3..9caf567 100644
--- a/README.md
+++ b/README.md
@@ -278,6 +278,7 @@ will return:
 <a href="#tree">tree</a>
 <a href="#trim">trim</a>
 <a href="#uasort">uasort</a>
+<a href="#uasorted">uasorted</a>
 <a href="#uksort">uksort</a>
 <a href="#union">union</a>
 <a href="#unique">unique</a>
@@ -385,6 +386,7 @@ will return:
 * [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)
 * [uasort()](#uasort) : Sorts elements preserving keys using callback
+* [uasorted()](#uasorted) : Sorts elements preserving keys using callback in a copy of the map
 * [uksort()](#uksort) : Sorts elements by keys using callback
 * [usort()](#usort) : Sorts elements using callback assigning new keys
 
@@ -5957,6 +5959,37 @@ Map::from( ['a' => 'B', 'b' => 'a'] )->uasort( function( $itemA, $itemB ) {
 ```
 
 
+### uasorted()
+
+Sorts a copy of all elements using a callback and maintains the key association.
+
+```php
+public function uasorted( callable $callback ) : self
+```
+
+* @param **callable** `$callback` Function with (itemA, itemB) parameters and returns -1 (<), 0 (=) and 1 (>)
+* @return **self&#60;int&#124;string,mixed&#62;** 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 preserved using this method and no new map is created.
+
+**Examples:**
+
+```php
+Map::from( ['a' => 'B', 'b' => 'a'] )->uasorted( 'strcasecmp' );
+// ['b' => 'a', 'a' => 'B']
+
+Map::from( ['a' => 'B', 'b' => 'a'] )->uasorted( function( $itemA, $itemB ) {
+    return strtolower( $itemA ) <=> strtolower( $itemB );
+} );
+// ['b' => 'a', 'a' => 'B']
+```
+
+
 ### uksort()
 
 Sorts the map elements by their keys using a callback.
diff --git a/src/Map.php b/src/Map.php
index 4494b33..d88990d 100644
--- a/src/Map.php
+++ b/src/Map.php
@@ -5426,6 +5426,35 @@ public function uasort( callable $callback ) : self
 	}
 
 
+	/**
+	 * Sorts all elements using a callback and maintains the key association.
+	 *
+	 * 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'] )->uasorted( 'strcasecmp' );
+	 *  Map::from( ['a' => 'B', 'b' => 'a'] )->uasorted( function( $itemA, $itemB ) {
+	 *      return strtolower( $itemA ) <=> strtolower( $itemB );
+	 *  } );
+	 *
+	 * Results:
+	 *  ['b' => 'a', 'a' => 'B']
+	 *  ['b' => 'a', 'a' => 'B']
+	 *
+	 * The keys are preserved using this method and no new map is created.
+	 *
+	 * @param callable $callback Function with (itemA, itemB) parameters and returns -1 (<), 0 (=) and 1 (>)
+	 * @return self<int|string,mixed> Updated map for fluid interface
+	 */
+	public function uasorted( callable $callback ) : self
+	{
+		return ( clone $this )->uasort( $callback );
+	}
+
+
 	/**
 	 * Sorts the map elements by their keys using a callback.
 	 *
diff --git a/tests/MapTest.php b/tests/MapTest.php
index 9057702..54714c0 100644
--- a/tests/MapTest.php
+++ b/tests/MapTest.php
@@ -3562,6 +3562,19 @@ public function testUasort()
 	}
 
 
+	public function testUasorted()
+	{
+		$m = new Map( ['a' => 'foo', 'c' => 'bar-10', 1 => 'bar-1'] );
+		$r = $m->uasorted( function( $a, $b ) {
+			return strrev( $a ) <=> strrev( $b );
+		} );
+
+		$this->assertNotSame( $r, $m );
+		$this->assertInstanceOf( Map::class, $r );
+		$this->assertSame( ['c' => 'bar-10', 1 => 'bar-1', 'a' => 'foo'], $r->toArray() );
+	}
+
+
 	public function testUksort()
 	{
 		$m = ( new Map( ['a' => 'foo', 'c' => 'bar-10', 1 => 'bar-1'] ) )->uksort( function( $a, $b ) {