do a single pass in maxByFirstDiffering (#1824)

This cuts the runtime for hat allocation
in my tests by about 20%.

No functional changes.

I have not added any tests, but I have confirmed
that there are no functional changes
using my not-yet-submitted hat golden tests.

Part of the reason that the hat golden tests are not
yet ready for review is that they are way too slow.


## Checklist

- [/] I have added
[tests](https://www.cursorless.org/docs/contributing/test-case-recorder/)
- [/] I have updated the
[docs](https://github.com/cursorless-dev/cursorless/tree/main/docs) and
[cheatsheet](https://github.com/cursorless-dev/cursorless/tree/main/cursorless-talon/src/cheatsheet)
- [/] I have not broken the cheatsheet

Author: josharian

packages/cursorless-engine/src/util/allocateHats/maxByFirstDiffering.test.ts

@@ -0,0 +1,40 @@
+import * as assert from "assert";
+import { maxByAllowingTies } from "./maxByFirstDiffering";
+
+// known good but slow
+function goldenMaxByAllowingTies<T>(arr: T[], fn: (item: T) => number): T[] {
+  const max = Math.max(...arr.map(fn));
+  return arr.filter((item) => fn(item) === max);
+}
+
+suite("maxByFirstDiffering", () => {
+  test("maxByAllowingTies", () => {
+    const testCases: number[][] = [
+      [],
+      [0],
+      [1],
+      [-Infinity],
+      [+Infinity],
+      [0, 0],
+      [0, 1],
+      [1, 0],
+      [-Infinity, -Infinity],
+      [-Infinity, +Infinity],
+      [+Infinity, -Infinity],
+      [+Infinity, 0],
+      [0, +Infinity],
+      [-Infinity, 0],
+      [0, -Infinity],
+      [0, 1, 0, 1],
+      [1, 0, 1, 0],
+      [0, 1, 1, 0],
+      [1, 0, 0, 1],
+    ];
+
+    testCases.forEach((testCase) => {
+      const actual = maxByAllowingTies(testCase, (x) => x);
+      const expected = goldenMaxByAllowingTies(testCase, (x) => x);
+      assert.deepStrictEqual(actual, expected);
+    });
+  });
+});

packages/cursorless-engine/src/util/allocateHats/maxByFirstDiffering.ts

@@ -24,15 +24,45 @@ export function maxByFirstDiffering<T>(
     return undefined;
   }
   let remainingValues = arr;
-
   for (const fn of fns) {
     if (remainingValues.length === 1) {
       return remainingValues[0];
     }
-
-    const max = Math.max(...remainingValues.map(fn));
-    remainingValues = remainingValues.filter((item) => fn(item) === max);
+    remainingValues = maxByAllowingTies(remainingValues, fn);
   }
-
   return remainingValues[0];
 }
+
+/**
+ * Given an array of items and a function that returns a number for each item,
+ * return all items that share the maximum value according to that function.
+ * @param arr The array to find the max values of
+ * @param fn A function that returns a number for each item in the array
+ * @returns All items in the array that share the maximum value
+ **/
+export function maxByAllowingTies<T>(arr: T[], fn: (item: T) => number): T[] {
+  // This is equivalent to, but faster than:
+  //
+  // const max = Math.max(...arr.map(fn));
+  // return arr.filter((item) => fn(item) === max);
+  //
+  // It does only a single pass through the array, and allocates no
+  // intermediate arrays (in the common case).
+
+  // Accumulate all items with the single highest value,
+  // resetting whenever we find a new highest value.
+  let best: number = -Infinity;
+  const keep: T[] = [];
+  for (const item of arr) {
+    const value = fn(item);
+    if (value < best) {
+      continue;
+    }
+    if (value > best) {
+      best = value;
+      keep.length = 0;
+    }
+    keep.push(item);
+  }
+  return keep;
+}