Updated to stablesort 0.1.8 and recoded to fit our style. Removed inplace static function.

Author: photonstorm

src/utils/array/StableSort.js

@@ -1,143 +1,170 @@
 /**
  * @author       Richard Davey <rich@photonstorm.com>
+ * @author       Angry Bytes (and contributors)
  * @copyright    2020 Photon Storm Ltd.
  * @license      {@link https://opensource.org/licenses/MIT|MIT License}
  */
 
-//! stable.js 0.1.6, https://github.com/Two-Screen/stable
-//! © 2017 Angry Bytes and contributors. MIT licensed.
-
 /**
- * @namespace Phaser.Utils.Array.StableSortFunctions
- */
-
-(function() {
-
- /**
- * A stable array sort, because `Array#sort()` is not guaranteed stable.
- * This is an implementation of merge sort, without recursion.
+ * The comparator function.
  *
- * @function Phaser.Utils.Array.StableSort
- * @since 3.0.0
+ * @ignore
  *
- * @param {array} arr - The input array to be sorted.
- * @param {function} comp - The comparison handler.
+ * @param {*} a - The first item to test.
+ * @param {*} b - The second itemt to test.
  *
- * @return {array} The sorted result.
+ * @return {boolean} True if they localCompare, otherwise false.
  */
-var stable = function(arr, comp) {
-    return exec(arr.slice(), comp);
-};
+function Compare (a, b)
+{
+    return String(a).localeCompare(b);
+}
 
- /**
- * Sort the input array and simply copy it back if the result isn't in the original array, which happens on an odd number of passes.
+/**
+ * Process the array contents.
  *
- * @function Phaser.Utils.Array.StableSortFunctions.inplace
- * @memberof Phaser.Utils.Array.StableSortFunctions
- * @since 3.0.0
  * @ignore
  *
- * @param {array} arr - The input array.
- * @param {function} comp - The comparison handler.
+ * @param {array} array - The array to process.
+ * @param {function} compare - The comparison function.
  *
- * @return {array} The sorted array.
+ * @return {array} - The processed array.
  */
-stable.inplace = function(arr, comp) {
-    var result = exec(arr, comp);
-
-    // This simply copies back if the result isn't in the original array,
-    // which happens on an odd number of passes.
-    if (result !== arr) {
-        pass(result, null, arr.length, arr);
-    }
-
-    return arr;
-};
-
-// Execute the sort using the input array and a second buffer as work space.
-// Returns one of those two, containing the final result.
-function exec(arr, comp) {
-    if (typeof(comp) !== 'function') {
-        comp = function(a, b) {
-            return String(a).localeCompare(b);
-        };
-    }
-
+function Process (array, compare)
+{
     // Short-circuit when there's nothing to sort.
-    var len = arr.length;
-    if (len <= 1) {
-        return arr;
+    var len = array.length;
+
+    if (len <= 1)
+    {
+        return array;
     }
 
     // Rather than dividing input, simply iterate chunks of 1, 2, 4, 8, etc.
     // Chunks are the size of the left or right hand in merge sort.
     // Stop when the left-hand covers all of the array.
     var buffer = new Array(len);
-    for (var chk = 1; chk < len; chk *= 2) {
-        pass(arr, comp, chk, buffer);
 
-        var tmp = arr;
-        arr = buffer;
+    for (var chk = 1; chk < len; chk *= 2)
+    {
+        RunPass(array, compare, chk, buffer);
+
+        var tmp = array;
+
+        array = buffer;
+
         buffer = tmp;
     }
 
-    return arr;
+    return array;
 }
 
-// Run a single pass with the given chunk size.
-var pass = function(arr, comp, chk, result) {
+/**
+ * Run a single pass with the given chunk size.
+ *
+ * @ignore
+ *
+ * @param {array} arr - The array to run the pass on.
+ * @param {function} comp - The comparison function.
+ * @param {number} chk - The number of iterations.
+ * @param {array} result - The array to store the result in.
+ */
+function RunPass (arr, comp, chk, result)
+{
     var len = arr.length;
     var i = 0;
+
     // Step size / double chunk size.
     var dbl = chk * 2;
+
     // Bounds of the left and right chunks.
     var l, r, e;
+
     // Iterators over the left and right chunk.
     var li, ri;
 
     // Iterate over pairs of chunks.
-    for (l = 0; l < len; l += dbl) {
+    for (l = 0; l < len; l += dbl)
+    {
         r = l + chk;
         e = r + chk;
-        if (r > len) r = len;
-        if (e > len) e = len;
+
+        if (r > len)
+        {
+            r = len;
+        }
+
+        if (e > len)
+        {
+            e = len;
+        }
 
         // Iterate both chunks in parallel.
         li = l;
         ri = r;
-        while (true) {
+
+        while (true)
+        {
             // Compare the chunks.
-            if (li < r && ri < e) {
+            if (li < r && ri < e)
+            {
                 // This works for a regular `sort()` compatible comparator,
                 // but also for a simple comparator like: `a > b`
-                if (comp(arr[li], arr[ri]) <= 0) {
+                if (comp(arr[li], arr[ri]) <= 0)
+                {
                     result[i++] = arr[li++];
                 }
-                else {
+                else
+                {
                     result[i++] = arr[ri++];
                 }
             }
-            // Nothing to compare, just flush what's left.
-            else if (li < r) {
+            else if (li < r)
+            {
+                // Nothing to compare, just flush what's left.
                 result[i++] = arr[li++];
             }
-            else if (ri < e) {
+            else if (ri < e)
+            {
                 result[i++] = arr[ri++];
             }
-            // Both iterators are at the chunk ends.
-            else {
+            else
+            {
+                // Both iterators are at the chunk ends.
                 break;
             }
         }
     }
-};
-
-// Export using CommonJS or to the window.
-if (typeof(module) !== 'undefined') {
-    module.exports = stable;
-}
-else {
-    window.stable = stable;
 }
 
-})();
+/**
+ * An in-place stable array sort, because `Array#sort()` is not guaranteed stable.
+ *
+ * This is an implementation of merge sort, without recursion.
+ *
+ * Function based on the Two-Screen/stable sort 0.1.8 from https://github.com/Two-Screen/stable
+ *
+ * @function Phaser.Utils.Array.StableSort
+ * @since 3.0.0
+ *
+ * @param {array} array - The input array to be sorted.
+ * @param {function} [compare] - The comparison function.
+ *
+ * @return {array} The sorted result.
+ */
+var StableSort = function (array, compare)
+{
+    if (compare === undefined) { compare = Compare; }
+
+    var result = Process(array, compare);
+
+    // This simply copies back if the result isn't in the original array, which happens on an odd number of passes.
+    if (result !== array)
+    {
+        RunPass(result, null, array.length, array);
+    }
+
+    return array;
+};
+
+module.exports = StableSort;