Introduce leftJoin on Seq (#2719)

Author: tnagelkerke

src/main/java/io/vavr/collection/Seq.java

@@ -89,6 +89,7 @@
  * <li>{@link #combinations()}</li>
  * <li>{@link #combinations(int)}</li>
  * <li>{@link #intersperse(Object)}</li>
+ * <li>{@link #leftJoin(Traversable, Function, Function)}</li>
  * <li>{@link #padTo(int, Object)}</li>
  * <li>{@link #permutations()}</li>
  * <li>{@link #reverse()}</li>
@@ -630,6 +631,33 @@ default Option<Integer> lastIndexWhereOption(Predicate<? super T> predicate, int
         return Collections.indexOption(lastIndexWhere(predicate, end));
     }
 
+    /**
+     * Perform a left join operation, which returns all the elements of {@code this} matched with
+     * an {@link Option}al element from the {@code right} {@link Traversable}. Matching is done
+     * using keys that are extracted from each element with the given functions. If the keys are
+     * not unique, only the first element from {@code right} will be considered.
+     *
+     * @param right       The {@link Traversable} to join with.
+     * @param getKeyLeft  Mapper from T to the key used for matching.
+     * @param getKeyRight Mapper from U to the key used for matching.
+     * @param <K>         The key type.
+     * @param <U>         The type of the right {@link Traversable}.
+     * @return A {@link Seq} of {@link Tuple2}s with T on the left and an {@link Option} element
+     * on the right.
+     */
+    default <K, U> Seq<Tuple2<T, Option<U>>> leftJoin(
+        Traversable<U> right,
+        Function<? super T, ? extends K> getKeyLeft,
+        Function<? super U, ? extends K> getKeyRight) {
+        Traversable<Tuple2<K, U>> rightWithKey =
+            right.map(u -> Tuple.of(getKeyRight.apply(u), u));
+        return this.map(t -> Tuple.of(getKeyLeft.apply(t), t))
+            .map(lt -> Tuple.of(
+                lt._2,
+                rightWithKey.find(rt -> lt._1.equals(rt._1)).map(t1 -> t1._2)
+            ));
+    }
+
     /**
      * Turns this sequence into a plain function returning an Option result.
      *

src/test/java/io/vavr/collection/AbstractSeqTest.java

@@ -2357,4 +2357,53 @@ enum OneEnum implements SomeInterface {
     enum SecondEnum implements SomeInterface {
         A1, A2, A3;
     }
+
+
+    @Test
+    public void shouldLeftJoinNotIncludeRightKeysThatDontExistOnTheLeft() {
+        Seq<Integer> left = of(1, 2, 5);
+        Seq<String> right = of("1", "2", "6");
+        Seq<Tuple2<Integer, Option<String>>> joined =
+            left.leftJoin(right, Function.identity(), Integer::parseInt);
+        assertThat(joined).containsExactly(
+            Tuple.of(1, Option.of("1")),
+            Tuple.of(2, Option.of("2")),
+            Tuple.of(5, Option.none())
+        );
+    }
+
+    @Test
+    public void shouldLeftJoinOnlyIncludeTheFirstMatchingKeyFromTheRight() {
+        Seq<Integer> left = of(1, 2, 5);
+        Seq<String> right = of("1", "2", "55", "5");
+        Seq<Tuple2<Integer, Option<String>>> joined =
+            left.leftJoin(right, Function.identity(), s -> Integer.parseInt(s.substring(0, 1)));
+        assertThat(joined).containsExactly(
+            Tuple.of(1, Option.of("1")),
+            Tuple.of(2, Option.of("2")),
+            Tuple.of(5, Option.of("55"))
+        );
+    }
+
+    @Test
+    public void shouldLeftJoinNotHaveAnyRightElementsWhenRightIsEmpty() {
+        Seq<Integer> left = of(1, 2, 5);
+        Seq<String> right = empty();
+        Seq<Tuple2<Integer, Option<String>>> joined =
+            left.leftJoin(right, Function.identity(), s -> Integer.parseInt(s.substring(0, 1)));
+        assertThat(joined).containsExactly(
+            Tuple.of(1, Option.none()),
+            Tuple.of(2, Option.none()),
+            Tuple.of(5, Option.none())
+        );
+    }
+
+    @Test
+    public void shouldLeftJoinReturnEmptySeqWhenLeftIsEmpty() {
+        Seq<Integer> left = empty();
+        Seq<String> right = of("1", "2", "6");
+        Seq<Tuple2<Integer, Option<String>>> joined =
+            left.leftJoin(right, Function.identity(), Integer::parseInt);
+        assertThat(joined).isEmpty();
+    }
 }