From 4b65c368ec0358a7828f09f8f5e231306e2b2a38 Mon Sep 17 00:00:00 2001
From: Karsten Schmidt <k@thi.ng>
Date: Wed, 9 Mar 2022 17:28:29 +0100
Subject: [PATCH] feat(arrays): add argSort()

---
 packages/arrays/src/arg-sort.ts | 33 +++++++++++++++++++++++++++++++++
 packages/arrays/src/index.ts    |  1 +
 2 files changed, 34 insertions(+)
 create mode 100644 packages/arrays/src/arg-sort.ts

diff --git a/packages/arrays/src/arg-sort.ts b/packages/arrays/src/arg-sort.ts
new file mode 100644
index 0000000000..ee175b2026
--- /dev/null
+++ b/packages/arrays/src/arg-sort.ts
@@ -0,0 +1,33 @@
+import { compare } from "@thi.ng/compare/compare";
+import { fillRange } from "./fill-range.js";
+import { sortByCachedKey } from "./sort-cached.js";
+
+/**
+ * Returns a new array of numeric indices in same order as sorted values of
+ * `src` using given (optional) comparator (default: thi.ng/compare). The `src`
+ * array will remain unmodified.
+ *
+ * @remarks
+ * Also see {@link swizzle} to read an array in custom order.
+ *
+ * @example
+ * ```ts
+ * const src = ["a", "c", "d", "b"];
+ *
+ * argSort(src)
+ * // [ 0, 3, 1, 2 ]
+ *
+ * // src[0] => "a"
+ * // src[3] => "b"
+ * // src[1] => "c"
+ * // src[2] => "d"
+ *
+ * swizzle(argSort(src))(src)
+ * // [ 'a', 'b', 'c', 'd' ]
+ * ```
+ *
+ * @param src -
+ * @param cmp -
+ */
+export const argSort = <T>(src: T[], cmp = compare) =>
+    sortByCachedKey(fillRange(new Array(src.length)), src.slice(), cmp);
diff --git a/packages/arrays/src/index.ts b/packages/arrays/src/index.ts
index c165b9366f..7818fea037 100644
--- a/packages/arrays/src/index.ts
+++ b/packages/arrays/src/index.ts
@@ -1,4 +1,5 @@
 export * from "./api.js";
+export * from "./arg-sort.js";
 export * from "./binary-search.js";
 export * from "./bisect.js";
 export * from "./ends-with.js";