From a508b374e22b87d4bd6b4010ed8ec6d30737aef2 Mon Sep 17 00:00:00 2001
From: Aimeos <aimeos@aimeos.org>
Date: Sat, 23 Nov 2024 13:22:16 +0100
Subject: [PATCH] Added uksorted() 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 9caf567..e2b7ddf 100644
--- a/README.md
+++ b/README.md
@@ -280,6 +280,7 @@ will return:
 <a href="#uasort">uasort</a>
 <a href="#uasorted">uasorted</a>
 <a href="#uksort">uksort</a>
+<a href="#uksorted">uksorted</a>
 <a href="#union">union</a>
 <a href="#unique">unique</a>
 <a href="#unshift">unshift</a>
@@ -388,6 +389,7 @@ will return:
 * [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
+* [uksorted()](#uksorted) : Sorts elements by keys using callback in a copy of the map
 * [usort()](#usort) : Sorts elements using callback assigning new keys
 
 ### Shorten
@@ -6021,6 +6023,37 @@ Map::from( ['B' => 'a', 'a' => 'b'] )->uksort( function( $keyA, $keyB ) {
 ```
 
 
+### uksorted()
+
+Sorts a copy of the map elements by their keys using a callback.
+
+```php
+public function uksorted( callable $callback ) : self
+```
+
+* @param **callable** `$callback` Function with (keyA, keyB) 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 keys. The callback must accept
+two parameters (key A and B) and must return -1 if key A is smaller than
+key B, 0 if both are equal and 1 if key A is greater than key 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( ['B' => 'a', 'a' => 'b'] )->uksorted( 'strcasecmp' );
+// ['a' => 'b', 'B' => 'a']
+
+Map::from( ['B' => 'a', 'a' => 'b'] )->uksorted( function( $keyA, $keyB ) {
+    return strtolower( $keyA ) <=> strtolower( $keyB );
+} );
+// ['a' => 'b', 'B' => 'a']
+```
+
+
 ### union()
 
 Builds a union of the elements and the given elements without returning a new map.
diff --git a/src/Map.php b/src/Map.php
index d88990d..0b1781a 100644
--- a/src/Map.php
+++ b/src/Map.php
@@ -5485,6 +5485,35 @@ public function uksort( callable $callback ) : self
 	}
 
 
+	/**
+	 * Sorts a copy of the map elements by their keys using a callback.
+	 *
+	 * The given callback will be used to compare the keys. The callback must accept
+	 * two parameters (key A and B) and must return -1 if key A is smaller than
+	 * key B, 0 if both are equal and 1 if key A is greater than key B. Both, a
+	 * method name and an anonymous function can be passed.
+	 *
+	 * Examples:
+	 *  Map::from( ['B' => 'a', 'a' => 'b'] )->uksorted( 'strcasecmp' );
+	 *  Map::from( ['B' => 'a', 'a' => 'b'] )->uksorted( function( $keyA, $keyB ) {
+	 *      return strtolower( $keyA ) <=> strtolower( $keyB );
+	 *  } );
+	 *
+	 * Results:
+	 *  ['a' => 'b', 'B' => 'a']
+	 *  ['a' => 'b', 'B' => 'a']
+	 *
+	 * The keys are preserved using this method and no new map is created.
+	 *
+	 * @param callable $callback Function with (keyA, keyB) parameters and returns -1 (<), 0 (=) and 1 (>)
+	 * @return self<int|string,mixed> Updated map for fluid interface
+	 */
+	public function uksorted( callable $callback ) : self
+	{
+		return ( clone $this )->uksort( $callback );
+	}
+
+
 	/**
 	 * Builds a union of the elements and the given elements without overwriting existing ones.
 	 * Existing keys in the map will not be overwritten
diff --git a/tests/MapTest.php b/tests/MapTest.php
index 54714c0..a6f74bc 100644
--- a/tests/MapTest.php
+++ b/tests/MapTest.php
@@ -3586,6 +3586,19 @@ public function testUksort()
 	}
 
 
+	public function testUksorted()
+	{
+		$m = new Map( ['a' => 'foo', 'c' => 'bar-10', 1 => 'bar-1'] );
+		$r = $m->uksorted( function( $a, $b ) {
+			return (string) $a <=> (string) $b;
+		} );
+
+		$this->assertNotSame( $r, $m );
+		$this->assertInstanceOf( Map::class, $r );
+		$this->assertSame( [1 => 'bar-1', 'a' => 'foo', 'c' => 'bar-10'], $r->toArray() );
+	}
+
+
 	public function testUsort()
 	{
 		$m = ( new Map( ['foo', 'bar-10', 'bar-1'] ) )->usort( function( $a, $b ) {