Add a zipLongest function and padLeft/padRight extensions on Iterable

Add a `zipLongest` function that is like `zip` from `package:quiver`
(or like `IterableZip` from `package:collection`) but that stops when
the longest `Iterable` is exhausted instead of the shortest.

My initial implementation involved padding the input `Iterables` to
have equal lengths and leveraging `zip` or `IterableZip`, leading me
to add an `Iterable.padRight` extension method (and an `padLeft` one
for symmetry).  However, I changed my mind because I wanted to
support `Iterable`s of infinite length.  Meanwhile, `padLeft` and
`padRight` might be useful for other cases, so I'm leaving them in.

Author: jamesderlin

CHANGELOG.md

@@ -1,6 +1,10 @@
 ## 0.9.0
 
-* Enabled lints introduced by Dart 3.4.0.
+* Require Dart 3.4.0 and enable new lints.
+
+* Added `padLeft` and `padRight` extension methods on `Iterable`.
+
+* Added a `zipLongest` function.
 
 * Replaced the `identityType<T>()` function with an `IdentityType<T>`
   `typedef`.

README.md

@@ -28,6 +28,12 @@ rain
 * `Iterable.startsWith` returns whether one `Iterable` starts with the same
   sequence of elements as another `Iterable`.
 
+* `Iterable.padLeft` and `Iterable.padRight` add elements to an `Iterable` to
+  have a specified length.
+
+* `zipLongest` is a version of [`zip`] that stops only after the longest
+  `Iterable` is exhausted instead of the shortest.
+
 * `LinkedHashMap.sort`.
 
 * `mergeMaps`s combines an `Iterable` of `Map`s into a single `Map`.
@@ -168,3 +174,4 @@ rain
 [readable_numbers]: https://pub.dev/documentation/dartbag/latest/readable_numbers/readable_numbers-library.html
 [timer]: https://pub.dev/documentation/dartbag/latest/timer/timer-library.html
 [tty]: https://pub.dev/documentation/dartbag/latest/tty/tty-library.html
+[zip]: https://pub.dev/documentation/quiver/latest/quiver.iterables/zip.html

lib/collection.dart

@@ -19,6 +19,47 @@ Iterable<T> flattenDeep<T>(Iterable<Object?> list) sync* {
   }
 }
 
+/// Like [`zip`] or [`IterableZip`] except that `zip_longest` stops only after
+/// the longest `Iterable` is exhausted instead of the shortest.
+///
+/// All [Iterable]s shorter than the longest [Iterable] will be padded with
+/// [fillValue].
+///
+/// If any of the input [Iterable]s is infinitely long, the returned [Iterable]
+/// also will be infinitely long.
+///
+/// [zip]: https://pub.dev/documentation/quiver/latest/quiver.iterables/zip.html
+///
+// N.B.: It'd be nice if we could leverage [zip] or [IterableZip] by using the
+// [Iterable.padRight] extension method, but doing so would require determining
+// the length of the input [Iterable]s, which cannot work on ones that are
+// infinitely long.
+Iterable<List<E>> zipLongest<E>(
+  Iterable<Iterable<E>> iterables,
+  E fillValue,
+) sync* {
+  var iterators = [for (var iterable in iterables) iterable.iterator];
+
+  while (true) {
+    var exhaustedCount = 0;
+    var current = <E>[];
+    for (var i = 0; i < iterators.length; i += 1) {
+      if (iterators[i].moveNext()) {
+        current.add(iterators[i].current);
+        continue;
+      }
+
+      exhaustedCount += 1;
+      if (exhaustedCount == iterators.length) {
+        return;
+      }
+      current.add(fillValue);
+    }
+
+    yield current;
+  }
+}
+
 /// Extension methods on [List] that do work in-place.
 extension InPlaceOperations<E> on List<E> {
   /// Reverses the [List] in-place.
@@ -137,6 +178,40 @@ extension IterableUtils<E> on Iterable<E> {
       }
     }
   }
+
+  /// Pads elements to the beginning of this [Iterable] to make it have the
+  /// specified length.
+  ///
+  /// If the [length] of this [Iterable] is already [totalLength] or greater,
+  /// returns this [Iterable].
+  Iterable<E> padLeft(int totalLength, {required E padValue}) {
+    if (totalLength <= length) {
+      return this;
+    }
+
+    return Iterable<E>.generate(
+      totalLength - length,
+      (_) => padValue,
+    ).followedBy(this);
+  }
+
+  /// Pads elements to the end of this [Iterable] to make it have the specified
+  /// length.
+  ///
+  /// If the [length] of this [Iterable] is already [totalLength] or greater,
+  /// returns this [Iterable].
+  Iterable<E> padRight(int totalLength, {required E padValue}) {
+    if (totalLength <= length) {
+      return this;
+    }
+
+    return followedBy(
+      Iterable<E>.generate(
+        totalLength - length,
+        (_) => padValue,
+      ),
+    );
+  }
 }
 
 /// Provides a [sort] extension method on [LinkedHashMap].

test/collection_test.dart

@@ -7,14 +7,22 @@ import 'package:dartbag/readable_numbers.dart';
 import 'package:test/test.dart';
 
 extension<E> on List<E> {
-  void rotateLeftSlow(
+  List<E> rotateLeftCopy(
     int shiftAmount, {
     int? start,
     int? end,
   }) {
-    for (var i = 0; i < shiftAmount; i += 1) {
-      rotateLeft(1, start: start, end: end);
+    var copy = toList();
+
+    start ??= 0;
+    end ??= length;
+
+    var rotatedLength = end - start;
+    for (var i = 0; i < rotatedLength; i += 1) {
+      copy[i + start] = this[(i + shiftAmount) % rotatedLength + start];
     }
+
+    return copy;
   }
 }
 
@@ -102,7 +110,7 @@ void main() {
         for (var i = 0; i < list.length; i += 1) {
           expect(
             [...list]..rotateLeft(i),
-            [...list]..rotateLeftSlow(i),
+            [...list].rotateLeftCopy(i),
             reason: 'shiftAmount: $i',
           );
         }
@@ -123,7 +131,7 @@ void main() {
         for (var i = 0; i < list.length; i += 1) {
           expect(
             [...list]..rotateLeft(-i),
-            [...list]..rotateLeft(list.length - i),
+            [...list].rotateLeftCopy(-i),
             reason: 'shiftAmount: -$i',
           );
         }
@@ -293,6 +301,219 @@ void main() {
     });
   });
 
+  test('Iterable.padLeft:', () {
+    const padValue = -48;
+
+    expect(<int>[].padLeft(0, padValue: padValue).toList(), <int>[]);
+    expect(<int>[].padLeft(1, padValue: padValue).toList(), [padValue]);
+    expect(
+      <int>[].padLeft(2, padValue: padValue).toList(),
+      [padValue, padValue],
+    );
+    expect(<int>[].padLeft(2, padValue: padValue).length, 2);
+    expect([0].padLeft(0, padValue: padValue).toList(), [0]);
+    expect([0].padLeft(1, padValue: padValue).toList(), [0]);
+    expect([0].padLeft(2, padValue: padValue).toList(), [padValue, 0]);
+    expect(
+      [0].padLeft(3, padValue: padValue).toList(),
+      [padValue, padValue, 0],
+    );
+    expect([0, 1].padLeft(0, padValue: padValue).toList(), [0, 1]);
+    expect([0, 1].padLeft(1, padValue: padValue).toList(), [0, 1]);
+    expect([0, 1].padLeft(2, padValue: padValue).toList(), [0, 1]);
+    expect([0, 1].padLeft(3, padValue: padValue).toList(), [padValue, 0, 1]);
+    expect([0, 1].padLeft(3, padValue: padValue).length, 3);
+  });
+
+  test('Iterable.padRight:', () {
+    const padValue = -48;
+
+    expect(<int>[].padRight(0, padValue: 0).toList(), <int>[]);
+    expect(<int>[].padRight(1, padValue: padValue).toList(), [padValue]);
+    expect(
+      <int>[].padRight(2, padValue: padValue).toList(),
+      [padValue, padValue],
+    );
+    expect(<int>[].padRight(2, padValue: padValue).length, 2);
+    expect([0].padRight(0, padValue: padValue).toList(), [0]);
+    expect([0].padRight(1, padValue: padValue).toList(), [0]);
+    expect([0].padRight(2, padValue: padValue).toList(), [0, padValue]);
+    expect(
+      [0].padRight(3, padValue: padValue).toList(),
+      [0, padValue, padValue],
+    );
+    expect([0, 1].padRight(0, padValue: padValue).toList(), [0, 1]);
+    expect([0, 1].padRight(1, padValue: padValue).toList(), [0, 1]);
+    expect([0, 1].padRight(2, padValue: padValue).toList(), [0, 1]);
+    expect([0, 1].padRight(3, padValue: padValue).toList(), [0, 1, padValue]);
+    expect([0, 1].padRight(3, padValue: padValue).length, 3);
+  });
+
+  group('zipLongest', () {
+    const padValue = -48;
+
+    test('Works with finite iterables', () {
+      expect(zipLongest([<int>[]], padValue).toList(), <List<int>>[]);
+      expect(
+          zipLongest(
+            [
+              <int>[],
+              [1],
+            ],
+            padValue,
+          ).toList(),
+          [
+            [padValue, 1],
+          ]);
+      expect(
+          zipLongest(
+            [
+              [1],
+              <int>[],
+            ],
+            padValue,
+          ).toList(),
+          [
+            [1, padValue],
+          ]);
+      expect(
+          zipLongest(
+            [
+              <int>[],
+              [1],
+              <int>[],
+            ],
+            padValue,
+          ).toList(),
+          [
+            [padValue, 1, padValue],
+          ]);
+
+      expect(
+          zipLongest(
+            [
+              [1, 2, 3],
+            ],
+            padValue,
+          ).toList(),
+          [
+            [1],
+            [2],
+            [3],
+          ]);
+      expect(
+          zipLongest(
+            [
+              <int>[],
+              [1, 2, 3],
+            ],
+            padValue,
+          ).toList(),
+          [
+            [padValue, 1],
+            [padValue, 2],
+            [padValue, 3],
+          ]);
+      expect(
+          zipLongest(
+            [
+              [1, 2, 3],
+              <int>[],
+            ],
+            padValue,
+          ).toList(),
+          [
+            [1, padValue],
+            [2, padValue],
+            [3, padValue],
+          ]);
+
+      expect(
+          zipLongest(
+            [
+              [1, 2, 3],
+              [4, 5],
+              [6],
+            ],
+            padValue,
+          ).toList(),
+          [
+            [1, 4, 6],
+            [2, 5, padValue],
+            [3, padValue, padValue],
+          ]);
+    });
+
+    test('Works with infinite iterables', () {
+      expect(
+        zipLongest(
+          [
+            _naturalNumbers,
+          ],
+          padValue,
+        ).take(5).toList(),
+        [
+          [1],
+          [2],
+          [3],
+          [4],
+          [5],
+        ],
+      );
+
+      expect(
+        zipLongest(
+          [
+            _naturalNumbers,
+            <int>[],
+          ],
+          padValue,
+        ).take(5).toList(),
+        [
+          [1, padValue],
+          [2, padValue],
+          [3, padValue],
+          [4, padValue],
+          [5, padValue],
+        ],
+      );
+
+      expect(
+        zipLongest(
+          [
+            <int>[],
+            _naturalNumbers,
+          ],
+          padValue,
+        ).take(5).toList(),
+        [
+          [padValue, 1],
+          [padValue, 2],
+          [padValue, 3],
+          [padValue, 4],
+          [padValue, 5],
+        ],
+      );
+
+      expect(
+        zipLongest(
+          [
+            [-1, -2, -3],
+            _naturalNumbers,
+          ],
+          padValue,
+        ).take(5).toList(),
+        [
+          [-1, 1],
+          [-2, 2],
+          [-3, 3],
+          [padValue, 4],
+          [padValue, 5],
+        ],
+      );
+    });
+  });
+
   test('LinkedHashMap.sort', () {
     final random = Random(0);
 
@@ -462,3 +683,12 @@ bool _isSorted<E extends Comparable<Object>>(Iterable<E> iterable) {
   }
   return true;
 }
+
+/// Returns an infinite [Iterable] of the natural numbers.
+Iterable<int> get _naturalNumbers sync* {
+  var i = 1;
+  while (true) {
+    yield i;
+    i += 1;
+  }
+}