Add alternateWith extension method on Iterable

[alexeyinkin]

There is a repeating feature request in Flutter to add separators for children of Row and Column:
flutter/flutter#16957
flutter/flutter#18917
flutter/flutter#55378
flutter/flutter#95263
flutter/flutter#95521

At its highest it got 117 thumbs-ups.
But it is declined over and over again because it can be solved outside of the framework with a few lines of code:

Iterable<T> alternateWith(Iterable<T> items, T separator) {
  return items
      .expand((item) sync* { yield separator; yield item; })
      .skip(1);
}

Can we add it to this package as an extension on Iterable? One could then do:

Column(
  children: <Widget>[
    Widget1(),
    Widget2(),
  ].alternateWith(separator).toList(),
),

One could easily make another package with this, as there are many. Yet they are unknown and may be poorly maintained. This package is widely used, endorsed, and can be referred to in Flutter docs thus ending the recurrance of the feature request or speeding up the debate should it occur again.

I can do it myself if approved.

[lrhn]

This is equivalent to dart-lang/sdk#49900.

The biggest problem is the typing. We can create an extension method like:

extension X<T> on Iterable<T> {
  Iterable<T> intersperse(T separator, {bool beforeFirst = false, bool afterLast = false}) sync* {
    bool empty = true;
    for (var e in this) {
      if (!empty || beforeFirst) yield separator;
      empty = false;
      yield e;
    }
    if (!empty && afterLast) yield separator;
  }
}

The problem is that if you have a [ButtonWidget(...), ButtonWidget(...)].intersperse(SpacerWidget(...), it won't work. You have to write <Widget>[ButtonWidget(...), ButtonWidget(...)].intersperse(SpacerWidget(...).
(If only we could write Iterable<S> intersperse<S super T>(S separator, ...).)

[lucavenir]

On the Flutter side, this has been resolved with e.g. spacing: 2 on Flex -like APIs.

On the Dart side, we could just add a .intersperse extension to pkg:collection.
#903 is a great start, but if we want to support inner, outer and prefixed, suffixed versions of this method, it needs some work, still.

So, before addressing that in the PR, I'm wondering:

1. Do we want this method into pkg:collection or are there any plans to let this thing be a built-in function? I'd vote for the former
2. Do we want four different methods (e.g. intersperseInner, intersperseOuter, etc.), or one method will a well-thought interface (e.g. intersperse({IntersperseMode mode=.inner, T? prefix, T? suffix})? I'd vote for the latter.

Hope this gets addressed soon, it should be a low hanging fruit if we delegate this to pkg:collection.

[lrhn]

The design space is large enough that I don't want to lock anyone into any choice.

For myself, I'd probably do a single function that can insert before, after and between, defaulting to between:

extension IterableSeparators<T> on Iterable<T>
  Iterable<T> separate(T separator, {bool before = false, bool after = false, bool between = true})  sync* {
    if (before) yield separator;
    var first = true;
    for (var element in this) {
      if (between && !first) yield separator;
      yield element;
      first = false;
    }
    if (after && !(first && before)) yield separator;
  }
}

But then I'd also have a different version if I want to build a list directly, instead of creating an intermediate
iterable.
Even a version that inserts separators into an existing list, like this one:

extension ListSeparators<T> on List<T> {
  void insertSeparators(T separator, {bool before = false, bool after = false, bool between = true}) {
    var length = this.length;
    if (length == 0) {
      if (before || after) add(separator);
      return;
    }
    if (!between) {
      if (before) insert(0, separator);
      if (after) add(separator);
      return;
   }
    var newLength = length * 2 - 1;
    if (before) newLength++;
    if (after) newLength++;
    var offset = before ? 1 : 0; 
    // New position of element at index i is i*2+offset.
    // Element at new position `index` is:
    // - element at ((index - offset) >> 1) if (index - offset).isEven
    // - separator if (index ^ offset).isOdd
    T newElementAt(int index) {
      var unoffset = index - offset; 
      return unoffset.isEven ? this[unoffset >> 1] : separator;
    }
    for (var i = length; i < newLength; i++) {
      add(newElementAt(i));
    }
    for (var i = length, min = offset ^ 1; i > min;) {
      i--;
      this[i] = newElementAt(i);
    }
  }
}

(Hardly tested, naturally. Not sure this is the desired behavior for before/after on an empty list.)

[lucavenir]

So, this issue can be closed, since it's not about the Dart SDK itself, and should the matter be transfered to pkg:collection?

But then I'd also have a different version if I want to build a list directly, instead of creating an intermediate
iterable.

Most of pkg:collection APIs could be "criticized" like that, but (imho) most of pkg:collection is about obtaining new smart iterables from existing ones.

[lrhn]

The issue is in the package:collection repo, so no transfer needed.

I'm not opposed to adding something to package:collection.
We don't want to add any possible iterable interaction as a function.
I'm also wary of adding something that solves too little, or is too inefficient.

I can see that "separator between any two elements" is a common use-case, and it's not well-supported by any other feature.
(I saw iterable.expand((a) => [a, separator]).toList()..removeLast(). It's clever, but a little wasteful.)

Is adding an element before the first element and/or after the last element also useful, or would that never be used? (And therefore be needless overhead.)
What would the strategy be for those on an empty input:

• Nothing
• One separator
• Two separators (probably not, then "separator" is not a good word any more.)

I'm guessing "Nothing". I could be wrong, and I don't want to implement a semantics that nobody would use anyway.

(I also go back and forth on what would be the best name, depending on which use-case is driving it.)

[alexeyinkin]

Is adding an element before the first element and/or after the last element also useful, or would that never be used? (And therefore be needless overhead.)

We don't need to decide on this right away because all 3 optional arguments can be added later without a breaking change. Adding to an interable in between seems to be the most requested thing.

what would be the best name

intersperse seems to be the most accepted name.

However, Flutter fixed that already for Row and Column with flutter/flutter#152890
So a huge part of the pressure to make this is gone.

[lucavenir]

I'm not opposed to adding something to package:collection.
We don't want to add any possible iterable interaction as a function.

I think we can all agree on that one 😄

I'm also wary of adding something that solves too little, or is too inefficient.

Maybe we can (again) take some inspiration from Flutter: to exploit composability!
I mean, instead of answering this question:

Is adding an element before the first element and/or after the last element also useful, or would that never be used? (And therefore be needless overhead.)

(which implies a lot of complexity - e.g. "how many separators on an empty list?")

... We can add three different extension methods, all of which can be used independently.

First, the "just in the middle" version, which is obvious (imho):

Iterable<T> intersperseWith(T separator) {
  // TODO implement the base case efficiently
}

And then:

Iterable<T> followedBy(T element) {
  // TODO implement the lazy version of [...this, element], efficiently
}

And finally:

Iterable<T> precededBy(T element) {
  // TODO implement the lazy version of [element, ...this], efficiently
}

With those three, we can answer every use case, composing lazy iterables (just like the rest of pkg:collection does), without particular headaches on the edge cases you've listed.

[lucavenir]

One final note. I want to remark that I strongly agree with

We don't want to add any possible iterable interaction as a function.

I'm not sure how you "keep track" or decide which interactions should be implemented, or not.

I can say that:

1. .intersperse was fairly requested because of Flutter's Flex layouts, but now that pressure is gone (good!)
2. Still, that could be of use in any other dart-related logic; .intersperse is implemented by this package (105k downloads), but I feel like our community would benefit from uniformity (this really, really looks like a pkg:collection's use case!)
3. I often end up implementing something similar to precededBy in my own codebases (business logic can be weird at times)
4. fast_immutable_collections has its own followedBy implementation, so you could say that's requested as well

Lastly, if anything, I'd gladly try and tackle this one on a PR, if that's of any interest