algorithms: Add setUnion, operating on sets implemented as sorted lists

Transcribed from the same-named function in zulip-mobile: see
src/immutableUtils.js.

Author: chrisbobbe

lib/model/algorithms.dart

@@ -1,4 +1,6 @@
 
+import 'package:collection/collection.dart';
+
 /// Returns the index in [sortedList] of an element matching the given [key],
 /// if there is one.
 ///
@@ -41,3 +43,60 @@ int binarySearchByKey<E, K>(
   }
   return -1;
 }
+
+/// The union of sets, represented as sorted lists.
+///
+/// The inputs must be sorted (by `<`) and without duplicates (by `==`).
+///
+/// The output will contain all the elements found in either input, again
+/// sorted and without duplicates.
+// When implementing this, it was convenient to have it return a [QueueList].
+// We can make it more general if needed:
+//   https://chat.zulip.org/#narrow/stream/243-mobile-team/topic/flutter.3A.20unreads.20model/near/1647754
+QueueList<int> setUnion(Iterable<int> xs, Iterable<int> ys) {
+  // This will overshoot by the number of elements that occur in both lists.
+  // That may make this optimization less effective, but it will not cause
+  // incorrectness.
+  final capacity = xs is List && ys is List // [List]s should have efficient `.length`
+    ? xs.length + ys.length
+    : null;
+  final result = QueueList<int>(capacity);
+
+  final iterX = xs.iterator;
+  final iterY = ys.iterator;
+  late bool xHasElement;
+  void moveX() => xHasElement = iterX.moveNext();
+  late bool yHasElement;
+  void moveY() => yHasElement = iterY.moveNext();
+
+  moveX();
+  moveY();
+  while (true) {
+    if (!xHasElement || !yHasElement) {
+      break;
+    }
+
+    int x = iterX.current;
+    int y = iterY.current;
+    if (x < y) {
+      result.add(x);
+      moveX();
+    } else if (x != y) {
+      result.add(y);
+      moveY();
+    } else { // x == y
+      result.add(x);
+      moveX();
+      moveY();
+    }
+  }
+  while (xHasElement) {
+    result.add(iterX.current);
+    moveX();
+  }
+  while (yHasElement) {
+    result.add(iterY.current);
+    moveY();
+  }
+  return result;
+}

test/model/algorithms_test.dart

@@ -36,4 +36,23 @@ void main() {
       check(search(7)).equals(-1);
     });
   });
+
+  group('setUnion', () {
+    for (final (String desc, Iterable<int> xs, Iterable<int> ys) in [
+      ('empty', [], []),
+      ('nonempty, empty', [1, 2], []),
+      ('empty, nonempty', [], [1, 2]),
+      ('in order', [1, 2], [3, 4]),
+      ('reversed', [3, 4], [1, 2]),
+      ('interleaved', [1, 3], [2, 4]),
+      ('all dupes', [1, 2], [1, 2]),
+      ('some dupes', [1, 2], [2, 3]),
+      ('comparison is numeric, not lexicographic', [11], [2]),
+    ]) {
+      test(desc, () {
+        final expected = Set.of(xs.followedBy(ys)).toList()..sort();
+        check(setUnion(xs, ys)).deepEquals(expected);
+      });
+    }
+  });
 }