Added sortObjects method

Author: minwork

README.md

@@ -66,6 +66,7 @@ Here, you can quickly get started by becoming familiar with each and every metho
 * Ordering
     * [orderByKeys](#orderbykeysarray-array-mixed-keys-bool-appendunmatched--true-array)
     * [sortByKeys](#sortbykeysarray-array-mixed-keys--null-bool-assoc--true-array)
+    * [sortObjects](#sortobjectsarray-objects-string-method-args-array)
 * Computations
     * [sum](#sumarray-arrays-array)
     * [diffObjects](#diffobjectsarray-array1-array-array2-array-arrays-array)
@@ -536,6 +537,34 @@ Arr::sortByKeys(['a' => 3, 'b' => 1, 'c' => 6]) -> ['b' => 1, 'a' => 3, 'c' => 6
 Arr::sortByKeys(['a' => 3, 'b' => 1, 'c' => 6], null, false) -> [1, 3, 6]
 ```
 
+### `sortObjects(array $objects, string $method, ...$args): array`
+Sort array of objects by comparing result of supplied method name 
+
+`$object1->$method(...$args) <=> $object2->$method(...$args)`
+
+```php
+$object1 = new class() {
+    function getValue() {
+        return 1; 
+    }
+};
+$object2 = new class() {
+    function getValue(bool $reverse = false) {
+        return $reverse ? 1/2 : 2; 
+    }
+};
+$object3 = new class() {
+    function getValue(bool $reverse = false) {
+        return $reverse ? 1/3 : 3; 
+    }
+};
+
+$array = [$object2, $object3, $object1];
+
+Arr::sortObjects($array, 'getValue') -> [$object1, $object2, $object3]
+Arr::sortObjects($array, 'getValue', true) -> [$object3, $object2, $object1]
+```  
+
 ## Computations
 
 ### `sum(array ...$arrays): array`

src/Arr.php

@@ -553,7 +553,7 @@ public static function orderByKeys(array $array, $keys, bool $appendUnmatched =
      * @param array $array Array of arrays
      * @param mixed $keys Keys in format specified by getKeysArray method or null to perform sort using 0-depth keys
      * @param bool $assoc If sorting should preserve main array keys (default: true)
-     * @return array Sorted array
+     * @return array New sorted array
      * @see \Minwork\Helper\Arr::getKeysArray()
      */
     public static function sortByKeys(array $array, $keys = null, bool $assoc = true): array
@@ -568,6 +568,25 @@ public static function sortByKeys(array $array, $keys = null, bool $assoc = true
         return $return;
     }
 
+    /**
+     * Sort array of objects using result of calling supplied method name on object as value to compare
+     *
+     * @param array $objects Array of objects
+     * @param string $method Name of a method called for every array element (object) in order to obtain value to compare
+     * @param mixed ...$args Arguments for method
+     * @return array New sorted array
+     */
+    public static function sortObjects(array $objects, string $method, ...$args): array
+    {
+        $result = $objects;
+
+        uasort($result, function ($a, $b) use ($method, $args) {
+            return $a->$method(...$args) <=> $b->$method(...$args);
+        });
+
+        return $result;
+    }
+
     /**
      * Sum associative arrays by their keys into one array
      *

test/ArrTest.php

@@ -599,6 +599,41 @@ public function testSortByKeys()
         ], Arr::sortByKeys($array3, 'b.c', false));
     }
 
+    public function testSortObjects()
+    {
+        $object1 = new class() {
+            public static $counter = 1;
+            public $i = 1;
+
+            public function __clone()
+            {
+                $this->i = ++self::$counter;
+            }
+
+            public function getValue(bool $reverse = false) {
+                return $reverse ? 1 / $this->i : $this->i;
+            }
+        };
+        $object2 = clone $object1;
+        $object3 = clone $object1;
+        $object4 = clone $object1;
+        $object5 = clone $object1;
+
+        $proto = [$object1, $object2, $object3, $object4, $object5];
+        $array = $proto;
+
+        $this->assertSame(Arr::mapObjects($array, 'getValue'), [1, 2, 3, 4, 5]);
+        $this->assertSame(Arr::mapObjects($array, 'getValue', true), [1, 1/2, 1/3, 1/4, 1/5]);
+
+        // Ensure order is not the same
+        do {
+            $array = Arr::shuffle($array);
+        } while ($array === $proto);
+
+        $this->assertSame($proto, Arr::sortObjects($array, 'getValue'));
+        $this->assertSame(array_reverse($proto, true), Arr::sortObjects($array, 'getValue', true));
+    }
+
     public function testSum()
     {
         $arrays = [