algorithms: Add bucketSort, for stable, linear-time sorting

Specifically the sort takes linear time so long as there aren't
more than linearly-many buckets.  For our immediate use case of
ranking emoji-autocomplete results, we'll in fact stick to a
constant number of buckets.

Author: gnprice

lib/model/algorithms.dart

@@ -116,3 +116,67 @@ QueueList<int> setUnion(Iterable<int> xs, Iterable<int> ys) {
   }
   return result;
 }
+
+/// Sort the items by bucket, stably,
+/// and if the buckets are few then in linear time.
+///
+/// The returned list will have the same elements as [xs], ordered by bucket,
+/// and elements in each bucket will appear in the same order as in [xs].
+/// In other words, the list is the result of a stable sort of [xs] by bucket.
+/// (By contrast, Dart's [List.sort] is not guaranteed to be stable.)
+///
+/// For each element of [xs], the bucket identified by [bucketOf]
+/// must be in the range `0 <= bucket < numBuckets`.
+/// Repeated calls to [bucketOf] on the same element must return the same value.
+///
+/// If [bucketOf] returns different answers when called twice for some element,
+/// this function's behavior is undefined:
+/// it may throw, or may return an arbitrary list.
+///
+/// The cost of this function is linear in `xs.length` plus [numBuckets].
+/// In particular if [numBuckets] is a constant
+/// (or more generally is at most a constant multiple of `xs.length`),
+/// then this function sorts the items in linear time, O(n).
+/// On the other hand if there are many more buckets than elements,
+/// consider using a different sorting algorithm.
+List<T> bucketSort<T>(Iterable<T> xs, int Function(T) bucketOf, {
+  required int numBuckets,
+}) {
+  if (xs.isEmpty) return [];
+  if (numBuckets <= 0) throw StateError("bucketSort: non-positive numBuckets");
+
+  final counts = List.generate(numBuckets, (_) => 0);
+  for (final x in xs) {
+    final key = bucketOf(x);
+    _checkBucket(key, numBuckets);
+    counts[key]++;
+  }
+  // Now counts[k] is the number of values with key k.
+
+  var partialSum = 0;
+  for (var k = 0; k < numBuckets; k++) {
+    final count = counts[k];
+    counts[k] = partialSum;
+    partialSum += count;
+  }
+  assert(partialSum == xs.length);
+  // Now counts[k] is the index where the first value with key k should go.
+
+  final result = List.generate(xs.length, (_) => xs.first);
+  for (final x in xs) {
+    // Each counts[k] is the index where the next value with key k should go.
+    final key = bucketOf(x);
+    _checkBucket(key, numBuckets);
+    final index = counts[key]++;
+    if (index >= result.length) {
+      throw StateError("bucketSort: bucketOf gave varying answers on same value");
+    }
+    result[index] = x;
+  }
+  return result;
+}
+
+void _checkBucket(int key, int numBuckets) {
+  if (key < 0) throw StateError("bucketSort: negative bucket");
+  if (key >= numBuckets) throw StateError("bucketSort: bucket out of range");
+}

test/model/algorithms_test.dart

@@ -1,5 +1,7 @@
+import 'dart:math';
 
 import 'package:checks/checks.dart';
+import 'package:collection/collection.dart';
 import 'package:test/scaffolding.dart';
 import 'package:zulip/model/algorithms.dart';
 
@@ -55,4 +57,95 @@ void main() {
       });
     }
   });
+
+  group('bucketSort', () {
+    /// Same spec as [bucketSort], except slow: N * B time instead of N + B.
+    List<T> simpleBucketSort<T>(Iterable<T> xs, int Function(T) bucketOf, {
+      required int numBuckets,
+    }) {
+      return Iterable.generate(numBuckets,
+        (k) => xs.where((s) => bucketOf(s) == k)).flattenedToList;
+    }
+
+    void checkBucketSort<T>(Iterable<T> xs, {
+      required int Function(T) bucketOf, required int numBuckets,
+    }) {
+      check(bucketSort(xs, bucketOf, numBuckets: numBuckets)).deepEquals(
+        simpleBucketSort<T>(xs, bucketOf, numBuckets: numBuckets));
+    }
+
+    int stringBucket(String s) => s.codeUnits.last - '0'.codeUnits.single;
+
+    test('explicit result, interleaved: 4 elements, 2 buckets', () {
+      check(bucketSort(['a1', 'd0', 'c1', 'b0'], stringBucket, numBuckets: 2))
+        .deepEquals(['d0', 'b0', 'a1', 'c1']);
+    });
+
+    List<_SortablePair> generatePairs(Iterable<int> keys) {
+      var token = 0;
+      return keys.map((k) => _SortablePair(k, "${token++}")).toList();
+    }
+
+    void checkSortPairs(int numBuckets, Iterable<int> keys) {
+      checkBucketSort(numBuckets: numBuckets, bucketOf: (p) => p.key,
+        generatePairs(keys));
+    }
+
+    test('empty list, zero buckets', () {
+      checkSortPairs(0, []);
+    });
+
+    test('empty, some buckets', () {
+      checkSortPairs(3, []);
+    });
+
+    test('interleaved: 4 elements, 2 buckets', () {
+      checkSortPairs(2, [1, 0, 1, 0]);
+    });
+
+    test('some buckets empty: 10 elements in 3 of 10 buckets', () {
+      checkSortPairs(10, [9, 9, 9, 5, 5, 5, 1, 1, 1, 1]);
+    });
+
+    test('one big bucket', () {
+      checkSortPairs(1, Iterable.generate(100, (_) => 0));
+    });
+
+    const seed = 4321;
+
+    Iterable<int> randomKeys({required int numBuckets, required int length}) {
+      final rand = Random(seed);
+      return Iterable.generate(length, (_) => rand.nextInt(numBuckets));
+    }
+
+    test('long random list, 1000 in 2 buckets', () {
+      checkSortPairs(2, randomKeys(numBuckets: 2, length: 1000));
+    });
+
+    test('long random list, 1000 in 1000 buckets', () {
+      checkSortPairs(1000, randomKeys(numBuckets: 1000, length: 1000));
+    });
+
+    test('sparse random list, 100 in 1000 buckets', () {
+      checkSortPairs(1000, randomKeys(numBuckets: 1000, length: 100));
+    });
+  });
+}
+
+class _SortablePair {
+  _SortablePair(this.key, this.tag);
+
+  final int key;
+  final String tag;
+
+  @override
+  bool operator ==(Object other) {
+    return other is _SortablePair && key == other.key && tag == other.tag;
+  }
+
+  @override
+  int get hashCode => Object.hash(key, tag);
+
+  @override
+  String toString() => "$tag:$key";
 }