@thi.ng/arrays 2.4.7 → 2.5.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2022-12-22T21:47:07Z
+- **Last updated**: 2022-12-29T20:56:59Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,12 @@ 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.5.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/arrays@2.5.0) (2022-12-29)
+
+#### 🚀 Features
+
+- add Floyd-Rivest impl, update readme ([7773d59](https://github.com/thi-ng/umbrella/commit/7773d59))
+
 ## [2.4.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/arrays@2.4.0) (2022-10-31)
 
 #### 🚀 Features

package/README.md

@@ -48,7 +48,7 @@ For Node.js REPL:
 const arrays = await import("@thi.ng/arrays");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 2.40 KB
+Package sizes (brotli'd, pre-treeshake): ESM: 2.61 KB
 
 ## Dependencies
 
@@ -73,6 +73,7 @@ Package sizes (brotli'd, pre-treeshake): ESM: 2.40 KB
 - [ensureIterable()](https://github.com/thi-ng/umbrella/tree/develop/packages/arrays/src/ensure-iterable.ts)
 - [fillRange()](https://github.com/thi-ng/umbrella/tree/develop/packages/arrays/src/fill-range.ts)
 - [find()](https://github.com/thi-ng/umbrella/tree/develop/packages/arrays/src/find.ts)
+- [floydRivest()](https://github.com/thi-ng/umbrella/tree/develop/packages/arrays/src/floyd-rivest.ts)
 - [fuzzyMatch()](https://github.com/thi-ng/umbrella/tree/develop/packages/arrays/src/fuzzy-match.ts)
 - [insert()](https://github.com/thi-ng/umbrella/tree/develop/packages/arrays/src/insert.ts)
 - [into()](https://github.com/thi-ng/umbrella/tree/develop/packages/arrays/src/into.ts)

package/floyd-rivest.d.ts

@@ -0,0 +1,30 @@
+import type { Comparator } from "@thi.ng/api";
+/**
+ * Implementation of the Floyd-Rivest selection algorithm to partially find &
+ * sort the `k`th smallest elements in given array, according to supplied
+ * comparator.
+ *
+ * @remarks
+ * `k` is the desired index value, where `buf[k]` is the `(k+1)`th smallest
+ * element when `left=0` (default).
+ *
+ * **IMPORTANT:** Mutates (partially sorts) given array such that all items in
+ * the `[left, k]` interval are the smallest.
+ *
+ * @example
+ * ```ts
+ * floydRivest([5, 3, -1, -10, 20, 7, 0, 4, 2], 3);
+ * // [ -10, 0, -1, 2, 3,  4, 5, 20, 7 ]
+ * ```
+ *
+ * Based on pseudo-code from:
+ * - https://en.wikipedia.org/wiki/Floyd%E2%80%93Rivest_algorithm
+ *
+ * @param buf
+ * @param k
+ * @param cmp
+ * @param left
+ * @param right
+ */
+export declare const floydRivest: <T>(buf: T[], k?: number, cmp?: Comparator<T>, left?: number, right?: number) => T[];
+//# sourceMappingURL=floyd-rivest.d.ts.map

package/floyd-rivest.js

@@ -0,0 +1,69 @@
+import { compare } from "@thi.ng/compare/compare";
+import { swap } from "./swap.js";
+/**
+ * Implementation of the Floyd-Rivest selection algorithm to partially find &
+ * sort the `k`th smallest elements in given array, according to supplied
+ * comparator.
+ *
+ * @remarks
+ * `k` is the desired index value, where `buf[k]` is the `(k+1)`th smallest
+ * element when `left=0` (default).
+ *
+ * **IMPORTANT:** Mutates (partially sorts) given array such that all items in
+ * the `[left, k]` interval are the smallest.
+ *
+ * @example
+ * ```ts
+ * floydRivest([5, 3, -1, -10, 20, 7, 0, 4, 2], 3);
+ * // [ -10, 0, -1, 2, 3,  4, 5, 20, 7 ]
+ * ```
+ *
+ * Based on pseudo-code from:
+ * - https://en.wikipedia.org/wiki/Floyd%E2%80%93Rivest_algorithm
+ *
+ * @param buf
+ * @param k
+ * @param cmp
+ * @param left
+ * @param right
+ */
+export const floydRivest = (buf, k = 1, cmp = compare, left = 0, right = buf.length - 1) => {
+    while (right > left) {
+        // constants 600 & 0.5 are from original paper
+        if (right - left > 600) {
+            const n = right - left + 1;
+            const i = k - left + 1;
+            const z = Math.log(n);
+            const s = 0.5 * Math.exp(z * (2 / 3));
+            const sd = 0.5 * Math.sqrt(z * s * ((n - s) / n)) * Math.sign(i - n / 2);
+            floydRivest(buf, k, cmp, Math.max(left, (k - (i * s) / n + sd) | 0), Math.min(right, (k + ((n - i) * s) / n + sd) | 0));
+        }
+        const t = buf[k];
+        let i = left;
+        let j = right;
+        swap(buf, left, k);
+        if (cmp(buf[right], t) > 0)
+            swap(buf, right, left);
+        while (i < j) {
+            swap(buf, i, j);
+            i++;
+            j--;
+            while (compare(buf[i], t) < 0)
+                i++;
+            while (compare(buf[j], t) > 0)
+                j--;
+        }
+        if (compare(buf[left], t) === 0) {
+            swap(buf, left, j);
+        }
+        else {
+            j++;
+            swap(buf, j, right);
+        }
+        if (j <= k)
+            left = j + 1;
+        if (k <= j)
+            right = j - 1;
+    }
+    return buf;
+};

package/index.d.ts

@@ -8,6 +8,7 @@ export * from "./ensure-array.js";
 export * from "./ensure-iterable.js";
 export * from "./find.js";
 export * from "./fill-range.js";
+export * from "./floyd-rivest.js";
 export * from "./fuzzy-match.js";
 export * from "./is-sorted.js";
 export * from "./insert.js";

package/index.js

@@ -8,6 +8,7 @@ export * from "./ensure-array.js";
 export * from "./ensure-iterable.js";
 export * from "./find.js";
 export * from "./fill-range.js";
+export * from "./floyd-rivest.js";
 export * from "./fuzzy-match.js";
 export * from "./is-sorted.js";
 export * from "./insert.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/arrays",
-  "version": "2.4.7",
+  "version": "2.5.0",
   "description": "Array / Arraylike utilities",
   "type": "module",
   "module": "./index.js",
@@ -107,6 +107,9 @@
     "./find": {
       "default": "./find.js"
     },
+    "./floyd-rivest": {
+      "default": "./floyd-rivest.js"
+    },
     "./fuzzy-match": {
       "default": "./fuzzy-match.js"
     },
@@ -153,5 +156,5 @@
   "thi.ng": {
     "year": 2018
   },
-  "gitHead": "bc6f7f5e2765bb96fe64db804eaf4b2443b47fc6\n"
+  "gitHead": "28bb74c67217a352d673b6efdab234921d4a370e\n"
 }