Better support for streaming over map entries or other logical pairs of elements

[jbduncan]

As discussed in #2591 (comment), I wonder if it'd be worth adding a map stream class to Guava 21.0+, in the spirit of OpenGamma Strata's MapStream (javadoc) or StreamEx's EntryStream (javadoc).

[jbduncan]

@cpovirk I believe this issue should have "platform: java 8" and "package: collect' labels? :)

[jbduncan]

Thanks for adding them @cpovirk! :)

[PhilippWendler]

I would also like such a class, though I would suggest to make it more general and not only focused on maps.

It could look like this:

public interface PairStream<A, B> {

  static <A, B> PairStream<A, B> empty();

  // Zip methods, with different handling of iterables of different length:
  // throwing exception, truncating, or padding with null
  static <A, B> PairStream<A, B> zip(Iterable<A> a, Iterable<B> b) { }
  static <A, B> PairStream<A, B> zipShorter(Iterable<A> a, Iterable<B> b) { }
  static <A, B> PairStream<A, B> zipPadded(Iterable<A> a, Iterable<B> b) { }

  static <T, A, B> PairStream<A, B> of(Iterable<T> it, Function<T, A> aFunc, Function<T, B> bFunc) { }

  // Additional Stream variants of factory methods where possible.

  // Maybe additional convenience method for maps?
  static <A, B> PairStream<A, B> of(Iterable<Map.Entry<A, B>> entryStream) { }
  static <A, B> PairStream<A, B> ofEntries(Map<A, B> map) { }

  <R> PairStream<R, B> mapLeft(BiFunction<A, B, R> f);
  <R> PairStream<A, R> mapRight(BiFunction<A, B, R> f);
  <R> Stream<R> map(BiFunction<A, B, R> f);

  // Maybe convenience methods for simple projections?
  Stream<A> toLeft();
  Stream<B> toRight();

  // flatMap(Left|Right) would pair each of the entries of the resulting stream
  // with the current element of the other side
  <R> PairStream<R, B> flatMapLeft(BiFunction<A, B, Iterable<R>> f);
  <R> PairStream<A, R> flatMapRight(BiFunction<A, B, Iterable<R>> f);

  <R, S> PairStream<R, S> flatMap(BiFunction<A, B, PairStream<R, S>> f);

  // Sorted keeps pairs together, also overrides with Comparators
  PairStream<A, B> sortedLeft();
  PairStream<A, B> sortedRight();

  // Instead of collectors:
  ImmutableMap<A, B> toMap();
  ImmutableMap<A, B> toMap(BinaryOperator<B> reducer);
  ImmutableMultimap<A, B> toMultimap();

  // Remaining Stream methods that can be adapted directly:

  PairStream<A, B> filter(BiPredicate<A, B> p);

  void forEach(BiConsumer<A, B> c);
  PairStream<A, B> peek(BiConsumer<A, B> c);

  PairStream<A, B> distinct();

  PairStream<A, B> limit(long maxSize);
  PairStream<A, B> skip(long n);
  long count();

  boolean anyMatch(BiPredicate<A, B> p);
  boolean allMatch(BiPredicate<A, B> p);
  boolean noneMatch(BiPredicate<A, B> p);
}

StreamEx's EntryStream seems to have a few nice additional methods that could be added here, too.

Besides the use case for maps, this PairStream would also be an elegant solution for the proposed Iterators.forEachPair (#677 (comment)).

It does not require any Pair class nor any new functional interfaces added to the API. Of course, the common argument against any Pair-related features is that pairs are bad and one should use "proper" classes instead, but I think specifically in this case the counterargument is that having a PairStream with methods that take BiFunctions and BiPredicates is nicer than having a Stream<MyDataClass>, because one can directly access both values in the lambdas.

[jbduncan]

For everyone's info, it seems that JOOQ JOOL is investigating something similar to @PhilippWendler's idea as a class called Seq2. Perhaps that might be a source of inspiration or things to avoid for this particular issue?

jOOQ/jOOL#172

[jbduncan]

Looks like a Streams.forEachPair() has been added as of 8f1a088.

[jbduncan]

I think @PhilippWendler's idea for a PairStream has merit, but if the name puts the Guava team off because of the association with Pair, then we could potentially name it DuoStream instead. :)

[jbduncan]

@perceptron8 I noticed that you down-voted the idea of a MapStream. I'd be interested to hear why you think it's not such a good idea. :)

[perceptron8]

@jbduncan It seems that I checked StreamEx's EntryStream only and I found it to be excessively complex, even bloated. I should've pay more attention to OpenGamma Strata's MapStream which is nice, simple and - I agree - could be useful.

It's great that you linked Seq2 PR. Flattened Pair is still a Pair, just implicit. PairStream, DuoStream, BiStream... different names, same mess.

I withdraw from down-voting the MapStream, as it is definitely worth considering. However, I'm still against EntryStream and any Pair/Tuple-involving ideas.

Thanks for asking :)

[jbduncan]

Looks like Google MµG has just released an implementation of a BiStream class.

It's not clear to me what the relationship between Guava and MµG is, so is it worth keeping this issue open now?

[kevinb9n]

There's no relationship. (Except that we like Ben and he's contributed more than a few cool things to Guava in the past.) MµG is basically a "personal playground" project, which I don't mean to sound derogatory (really, we should all have one of those).

Guava APIs have to jump through an infamous number of hoops before being approved; projects like this have essentially no hoops at all... each is good in its own way.

[fluentfuture]

+1 for adding this to Guava.

I intended Mug to be a niche library for things that seem to have potential but don't quite make Guava's "utility * ubiquity" bar.

If Guava gets a BiStream or something of that kind, Mug BiStream will be deprecated in favor of Guava.

I'd also volunteer to work on adding BiStream in Guava if the librarians aren't already working on it or plan to (and if the idea itself is approved).

[kevinb9n]

I see mostly just two main possibilities: BiStream, or we embrace Stream<Map.Entry> as the common idiom, despite its flaws, and add bits of help here and there to make that less painful. I can't see introducing a Pair or Pair-alike at this stage, and I can't really see just doing nothing about this either.

I do want to dig through the openjdk archives to discover why they dropped BiStream in the first place; that may yield useful intel.

One nice thing about BiStream is we could add stream() methods to Multimap and ImmutableMap that return it directly. That would be quite pleasant.