@thi.ng/arrays 2.1.1 → 2.2.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2021-11-19T07:59:50Z
+- **Last updated**: 2022-03-11T12:13:49Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,21 @@ See [Conventional Commits](https://conventionalcommits.org/) for commit guidelin
 **Note:** Unlisted _patch_ versions only involve non-code or otherwise excluded changes
 and/or version bumps of transitive dependencies.
 
+## [2.2.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/arrays@2.2.0) (2022-03-11)
+
+#### 🚀 Features
+
+- add argSort() ([4b65c36](https://github.com/thi-ng/umbrella/commit/4b65c36))
+
+### [2.1.3](https://github.com/thi-ng/umbrella/tree/@thi.ng/arrays@2.1.3) (2021-12-13)
+
+#### 🩹 Bug fixes
+
+- off-by-one error in shuffleRange() ([f832d2f](https://github.com/thi-ng/umbrella/commit/f832d2f))
+  - existing shuffle would keep some indices untouched, resulting in
+    still perceivable ordering
+  - update tests
+
 ## [2.1.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/arrays@2.1.0) (2021-11-17)
 
 #### 🚀 Features

package/README.md

@@ -51,7 +51,7 @@ node --experimental-repl-await
 > const arrays = await import("@thi.ng/arrays");
 ```
 
-Package sizes (gzipped, pre-treeshake): ESM: 2.24 KB
+Package sizes (gzipped, pre-treeshake): ESM: 2.30 KB
 
 ## Dependencies
 
@@ -67,6 +67,7 @@ Package sizes (gzipped, pre-treeshake): ESM: 2.24 KB
 [Generated API docs](https://docs.thi.ng/umbrella/arrays/)
 
 - [arrayIterator()](https://github.com/thi-ng/umbrella/tree/develop/packages/arrays/src/iterator.ts)
+- [argSort()](https://github.com/thi-ng/umbrella/tree/develop/packages/arrays/src/arg-sort.ts)
 - [binarySearch()](https://github.com/thi-ng/umbrella/tree/develop/packages/arrays/src/binary-search.ts)
 - [bisect()](https://github.com/thi-ng/umbrella/tree/develop/packages/arrays/src/bisect.ts)
 - [endsWith()](https://github.com/thi-ng/umbrella/tree/develop/packages/arrays/src/ends-with.ts)
@@ -134,4 +135,4 @@ If this project contributes to an academic publication, please cite it as:
 
 ## License
 
-© 2018 - 2021 Karsten Schmidt // Apache Software License 2.0
+© 2018 - 2022 Karsten Schmidt // Apache Software License 2.0

package/arg-sort.d.ts

@@ -0,0 +1,29 @@
+/**
+ * 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 declare const argSort: <T>(src: T[], cmp?: (a: any, b: any) => number) => any[];
+//# sourceMappingURL=arg-sort.d.ts.map

package/arg-sort.js

@@ -0,0 +1,31 @@
+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 = (src, cmp = compare) => sortByCachedKey(fillRange(new Array(src.length)), src.slice(), cmp);

package/binary-search.d.ts

@@ -47,32 +47,32 @@ export declare const binarySearch2: (buf: ArrayLike<number>, x: number) => numbe
  * Non-recursive, optimized binary search for fixed size numeric arrays of 4
  * values. Returns index of `x` or `-index-1` if not found.
  *
- * @param buf
- * @param x
+ * @param buf -
+ * @param x -
  */
 export declare const binarySearch4: (buf: ArrayLike<number>, x: number) => number;
 /**
  * Non-recursive, optimized binary search for fixed size numeric arrays of 8
  * values. Returns index of `x` or `-index-1` if not found.
  *
- * @param buf
- * @param x
+ * @param buf -
+ * @param x -
  */
 export declare const binarySearch8: (buf: ArrayLike<number>, x: number) => number;
 /**
  * Non-recursive, optimized binary search for fixed size numeric arrays of 16
  * values. Returns index of `x` or `-index-1` if not found.
  *
- * @param buf
- * @param x
+ * @param buf -
+ * @param x -
  */
 export declare const binarySearch16: (buf: ArrayLike<number>, x: number) => number;
 /**
  * Non-recursive, optimized binary search for fixed size numeric arrays of 32
  * values. Returns index of `x` or `-index-1` if not found.
  *
- * @param buf
- * @param x
+ * @param buf -
+ * @param x -
  */
 export declare const binarySearch32: (buf: ArrayLike<number>, x: number) => number;
 /**

package/binary-search.js

@@ -82,8 +82,8 @@ export const binarySearch2 = (buf, x) => {
  * Non-recursive, optimized binary search for fixed size numeric arrays of 4
  * values. Returns index of `x` or `-index-1` if not found.
  *
- * @param buf
- * @param x
+ * @param buf -
+ * @param x -
  */
 export const binarySearch4 = (buf, x) => {
     let idx = buf[2] <= x ? 2 : 0;
@@ -94,8 +94,8 @@ export const binarySearch4 = (buf, x) => {
  * Non-recursive, optimized binary search for fixed size numeric arrays of 8
  * values. Returns index of `x` or `-index-1` if not found.
  *
- * @param buf
- * @param x
+ * @param buf -
+ * @param x -
  */
 export const binarySearch8 = (buf, x) => {
     let idx = buf[4] <= x ? 4 : 0;
@@ -107,8 +107,8 @@ export const binarySearch8 = (buf, x) => {
  * Non-recursive, optimized binary search for fixed size numeric arrays of 16
  * values. Returns index of `x` or `-index-1` if not found.
  *
- * @param buf
- * @param x
+ * @param buf -
+ * @param x -
  */
 export const binarySearch16 = (buf, x) => {
     let idx = buf[8] <= x ? 8 : 0;
@@ -121,8 +121,8 @@ export const binarySearch16 = (buf, x) => {
  * Non-recursive, optimized binary search for fixed size numeric arrays of 32
  * values. Returns index of `x` or `-index-1` if not found.
  *
- * @param buf
- * @param x
+ * @param buf -
+ * @param x -
  */
 export const binarySearch32 = (buf, x) => {
     let idx = buf[16] <= x ? 16 : 0;

package/bisect.d.ts

@@ -2,8 +2,8 @@ import type { Predicate } from "@thi.ng/api";
 /**
  * Splits array at given index (default: floor(src.length/2)) and returns tuple of [lhs, rhs].
  *
- * @param src
- * @param i
+ * @param src -
+ * @param i -
  */
 export declare const bisect: <T>(src: T[], i?: number) => T[][];
 /**
@@ -12,8 +12,8 @@ export declare const bisect: <T>(src: T[], i?: number) => T[][];
  * will be the first item in the RHS array. If the predicate never succeeds, the
  * function returns `[src, []]`, i.e. all items will remain in the LHS.
  *
- * @param src
- * @param pred
+ * @param src -
+ * @param pred -
  */
 export declare const bisectWith: <T>(src: T[], pred: Predicate<T>) => T[][];
 //# sourceMappingURL=bisect.d.ts.map

package/bisect.js

@@ -1,8 +1,8 @@
 /**
  * Splits array at given index (default: floor(src.length/2)) and returns tuple of [lhs, rhs].
  *
- * @param src
- * @param i
+ * @param src -
+ * @param i -
  */
 export const bisect = (src, i = src.length >>> 1) => [
     src.slice(0, i),
@@ -14,8 +14,8 @@ export const bisect = (src, i = src.length >>> 1) => [
  * will be the first item in the RHS array. If the predicate never succeeds, the
  * function returns `[src, []]`, i.e. all items will remain in the LHS.
  *
- * @param src
- * @param pred
+ * @param src -
+ * @param pred -
  */
 export const bisectWith = (src, pred) => {
     const i = src.findIndex(pred);

package/index.d.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";

package/index.js

@@ -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";

package/insert.d.ts

@@ -12,19 +12,19 @@
  * faster than `Array.prototype.splice()` (for sizes < ~32). See
  * `/bench/insert.ts`
  *
- * @param buf
- * @param x
- * @param i
- * @param k
+ * @param buf -
+ * @param x -
+ * @param i -
+ * @param k -
  */
 export declare const insert: <T>(buf: T[], x: T, i: number, k?: number) => T[];
 /**
  * Same as {@link insert} but without any bounds/index checks.
  *
- * @param buf
- * @param x
- * @param i
- * @param k
+ * @param buf -
+ * @param x -
+ * @param i -
+ * @param k -
  */
 export declare const insertUnsafe: <T>(buf: T[], x: T, i: number, k?: number) => T[];
 //# sourceMappingURL=insert.d.ts.map

package/insert.js

@@ -12,19 +12,19 @@
  * faster than `Array.prototype.splice()` (for sizes < ~32). See
  * `/bench/insert.ts`
  *
- * @param buf
- * @param x
- * @param i
- * @param k
+ * @param buf -
+ * @param x -
+ * @param i -
+ * @param k -
  */
 export const insert = (buf, x, i, k = Infinity) => i < 0 || i >= k || k < 1 ? buf : insertUnsafe(buf, x, i, k);
 /**
  * Same as {@link insert} but without any bounds/index checks.
  *
- * @param buf
- * @param x
- * @param i
- * @param k
+ * @param buf -
+ * @param x -
+ * @param i -
+ * @param k -
  */
 export const insertUnsafe = (buf, x, i, k = Infinity) => {
     let j = buf.length < k ? buf.length + 1 : k;

package/into.d.ts

@@ -2,9 +2,9 @@
  * Appends `max` items (default: all) from `src` iterable to `dest` array.
  * Returns `dest`.
  *
- * @param dest
- * @param src
- * @param max
+ * @param dest -
+ * @param src -
+ * @param max -
  */
 export declare const into: <T>(dest: T[], src: Iterable<T>, max?: number) => T[];
 //# sourceMappingURL=into.d.ts.map

package/into.js

@@ -2,9 +2,9 @@
  * Appends `max` items (default: all) from `src` iterable to `dest` array.
  * Returns `dest`.
  *
- * @param dest
- * @param src
- * @param max
+ * @param dest -
+ * @param src -
+ * @param max -
  */
 export const into = (dest, src, max = Infinity) => {
     for (let x of src) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/arrays",
-  "version": "2.1.1",
+  "version": "2.2.0",
   "description": "Array / Arraylike utilities",
   "type": "module",
   "module": "./index.js",
@@ -34,20 +34,20 @@
     "test": "testament test"
   },
   "dependencies": {
-    "@thi.ng/api": "^8.3.1",
-    "@thi.ng/checks": "^3.1.1",
-    "@thi.ng/compare": "^2.1.1",
-    "@thi.ng/equiv": "^2.1.1",
-    "@thi.ng/errors": "^2.1.1",
-    "@thi.ng/random": "^3.2.1"
+    "@thi.ng/api": "^8.3.4",
+    "@thi.ng/checks": "^3.1.4",
+    "@thi.ng/compare": "^2.1.4",
+    "@thi.ng/equiv": "^2.1.4",
+    "@thi.ng/errors": "^2.1.4",
+    "@thi.ng/random": "^3.2.4"
   },
   "devDependencies": {
-    "@microsoft/api-extractor": "^7.18.19",
-    "@thi.ng/testament": "^0.2.1",
+    "@microsoft/api-extractor": "^7.19.4",
+    "@thi.ng/testament": "^0.2.4",
     "rimraf": "^3.0.2",
     "tools": "^0.0.1",
-    "typedoc": "^0.22.9",
-    "typescript": "^4.5.2"
+    "typedoc": "^0.22.13",
+    "typescript": "^4.6.2"
   },
   "keywords": [
     "aos",
@@ -76,6 +76,9 @@
     "./api": {
       "import": "./api.js"
     },
+    "./arg-sort": {
+      "import": "./arg-sort.js"
+    },
     "./binary-search": {
       "import": "./binary-search.js"
     },
@@ -140,5 +143,5 @@
   "thi.ng": {
     "year": 2018
   },
-  "gitHead": "8bd27c8bde0b770e7c001943f11c951cd345d668\n"
+  "gitHead": "0fc692a3225c068aacafdc4cb6140cf603c67ad8\n"
 }

package/shuffle.js

@@ -16,15 +16,12 @@ import { SYSTEM } from "@thi.ng/random/system";
  */
 export const shuffleRange = (buf, start = 0, end = buf.length, rnd = SYSTEM) => {
     assert(start >= 0 && end >= start && end <= buf.length, `illegal range ${start}..${end}`);
-    let n = end - start;
-    const l = n;
-    if (l > 1) {
-        while (n-- > 0) {
-            const a = (start + rnd.float(l)) | 0;
-            const b = (start + rnd.float(l)) | 0;
+    if (end - start > 1) {
+        for (let i = end; i-- > start;) {
+            const a = rnd.minmax(start, i + 1) | 0;
             const t = buf[a];
-            buf[a] = buf[b];
-            buf[b] = t;
+            buf[a] = buf[i];
+            buf[i] = t;
         }
     }
     return buf;

package/sort-cached.d.ts

@@ -22,9 +22,9 @@ import type { Comparator, Fn } from "@thi.ng/api";
  * // [ 'd', 'c', 'b', 'a' ]
  * ```
  *
- * @param src
- * @param key
- * @param cmp
+ * @param src -
+ * @param key -
+ * @param cmp -
  */
 export declare const sortByCachedKey: <T, K>(src: T[], key: Fn<T, K> | K[], cmp?: Comparator<K>) => T[];
 //# sourceMappingURL=sort-cached.d.ts.map

package/sort-cached.js

@@ -26,9 +26,9 @@ import { multiSwap } from "./swap.js";
  * // [ 'd', 'c', 'b', 'a' ]
  * ```
  *
- * @param src
- * @param key
- * @param cmp
+ * @param src -
+ * @param key -
+ * @param cmp -
  */
 export const sortByCachedKey = (src, key, cmp = compare) => {
     const keys = isFunction(key) ? src.map(key) : key;