Merge pull request #592 from simov/stableSort

[FEATURE][ADD] Add stableSort function

snippets/stableSort.md

@@ -0,0 +1,21 @@
+### stableSort
+
+Performs stable sorting of an array, preserving the initial indexes of items when their values are the same. 
+Does not mutate the original array, but returns a new array instead.
+
+Use `Array.map()` to pair each element of the input array with its corresponding index. 
+Use `Array.sort()` and a `compare` function to sort the list, preserving their initial order if the items compared are equal.
+Use `Array.map()` to convert back to the initial array items.
+
+```js
+const stableSort = (arr, compare) =>
+  arr
+    .map((item, index) => ({ item, index }))
+    .sort((a, b) => compare(a.item, b.item) || a.index - b.index)
+    .map(({ item }) => item);
+```
+
+```js
+const arr = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
+const stable = stableSort(arr, () => 0); // [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
+```

tag_database

@@ -233,6 +233,7 @@ sortedLastIndex:array,math
 sortedLastIndexBy:array,math,function
 splitLines:string
 spreadOver:adapter
+stableSort:array,sort,advanced
 standardDeviation:math,array
 stripHTMLTags:string,utility,regexp
 sum:math,array

test/stableSort/stableSort.js

@@ -0,0 +1,6 @@
+const stableSort = (arr, compare) =>
+arr
+.map((item, index) => ({ item, index }))
+.sort((a, b) => compare(a.item, b.item) || a.index - b.index)
+.map(({ item }) => item);
+module.exports = stableSort;

test/stableSort/stableSort.test.js

@@ -0,0 +1,17 @@
+const test = require('tape');
+const stableSort = require('./stableSort.js');
+
+test('Testing stableSort', (t) => {
+  //For more information on all the methods supported by tape
+  //Please go to https://github.com/substack/tape
+  t.true(typeof stableSort === 'function', 'stableSort is a Function');
+  //t.deepEqual(stableSort(args..), 'Expected');
+  //t.equal(stableSort(args..), 'Expected');
+  //t.false(stableSort(args..), 'Expected');
+  //t.throws(stableSort(args..), 'Expected');
+  
+  const arr = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
+  const compare = () => 0;
+  t.deepEqual(stableSort(arr, compare), arr, 'Array is properly sorted');
+  t.end();
+});