Add compose1, ..., composeN methods to FunctionN (#3016)

- [x] Add (generated) `composeN` method(s) to `Function`, adding a
composition function to the nth parameter
- `composeN` method name is numbered (e.g. `compose1`) to prevent
ambiguity
- [x] Add (generated) tests

Open considerations:
- `Function1#compose` now has a (virtually) duplicate `compose1`, is
this an issue?
- Should the input argument be `Function` or `Function1`?
- This pattern and naming scheme could also be used to add `curryN`,
`applyN` etc.,

---------

Co-authored-by: Grzegorz Piwowarek <gpiwowarek@gmail.com>

Author: bvkatwijk

vavr/generator/Generator.scala

@@ -1891,6 +1891,35 @@ def generateMainClasses(): Unit = {
                     return v -> apply(before.apply(v));
                 }
               """)}
+
+              ${(1 to i).gen(j => {
+                val fName = s"before$j"
+                val fGeneric = "S"
+                val applicationArgs = (1 to i).gen(k => if (k == j) s"$fGeneric ${fGeneric.toLowerCase}" else s"T$k t$k")(", ")
+                val generics = (1 to i).gen(k => if (k == j) "S" else s"T$k")(", ")
+                val resultFunctionArgs = (j+1 to i).gen(k => s"T$k t$k")(", ")
+                val applyArgs = (1 to i).gen(k => if (k ==j) s"$fName.apply(${fGeneric.toLowerCase})" else s"t$k")(", ")
+                val variableApplyArgs = (j+1 to i).gen(k => s"t$k")(", ")
+                val docAdd = i match
+                  case 1 => ""
+                  case 2 => " and the other argument"
+                  case _ => " and the other arguments"
+                xs"""
+                  /$javadoc
+                   * Returns a composed function that first applies the {@linkplain Function} {@code $fName} to the
+                   * ${j.ordinal} argument and then applies this $className to the result$docAdd.
+                   *
+                   * @param <$fGeneric> argument type of $fName
+                   * @param $fName the function applied before this
+                   * @return a function composed of $fName and this
+                   * @throws NullPointerException if $fName is null
+                   */
+                  default <S> $className<$generics, R> compose$j(Function1<? super $fGeneric, ? extends T$j> $fName) {
+                      Objects.requireNonNull($fName, "$fName is null");
+                      return ($applicationArgs) -> apply($applyArgs);
+                  }
+                """
+              })("\n\n")}
           }
 
           ${checked.gen(xs"""
@@ -3070,6 +3099,7 @@ def generateTestClasses(): Unit = {
       def genFunctionTest(name: String, checked: Boolean)(im: ImportManager, packageName: String, className: String): String = {
 
         val AtomicInteger = im.getType("java.util.concurrent.atomic.AtomicInteger")
+        val nested = im.getType("org.junit.jupiter.api.Nested")
 
         val functionArgsDecl = (1 to i).gen(j => s"Object o$j")(", ")
         val functionArgs = (1 to i).gen(j => s"o$j")(", ")
@@ -3414,15 +3444,27 @@ def generateTestClasses(): Unit = {
                   $assertThat(composed).isNotNull();
               }
 
-              ${(i == 1).gen(xs"""
-                @$test
-                public void shouldComposeWithCompose() {
-                    final $name$i<$generics> f = ($functionArgs) -> null;
-                    final ${name}1<Object, Object> before = o -> null;
-                    final $name$i<$generics> composed = f.compose(before);
-                    $assertThat(composed).isNotNull();
-                }
-              """)}
+              @Nested
+              class ComposeTests {
+                ${(1 to i).gen(j =>
+                  val genArgs = (1 to i).gen(k => "String")(", ")
+                  val params = (1 to i).gen(k => s"String s$k")(", ")
+                  val values = (1 to i).gen(k => if (k == j) "\"xx\"" else s"\"s$k\"")(", ")
+                  val expected = (1 to i).gen(k => if (k == j) "XX" else s"s$k")("")
+                  val concat = (1 to i).gen(k => s"s$k")(" + ")
+                  xs"""
+
+                  @$test
+                  public void shouldCompose$j() ${checked.gen(" throws Throwable ")}{
+                      final $name$i<$genArgs, String> concat = ($params) -> $concat;
+                      final Function1<String, String> toUpperCase = String::toUpperCase;
+                      assertThat(concat.compose$j(toUpperCase).apply($values)).isEqualTo(\"$expected\");
+                  }
+
+                  """
+                )}
+
+              }
 
               ${(i == 0).gen(xs"""
               @$test

vavr/src-gen/main/java/io/vavr/CheckedFunction1.java

@@ -298,6 +298,20 @@ default <V> CheckedFunction1<V, R> compose(CheckedFunction1<? super V, ? extends
         Objects.requireNonNull(before, "before is null");
         return v -> apply(before.apply(v));
     }
+
+    /**
+     * Returns a composed function that first applies the {@linkplain Function} {@code before1} to the
+     * 1st argument and then applies this CheckedFunction1 to the result.
+     *
+     * @param <S> argument type of before1
+     * @param before1 the function applied before this
+     * @return a function composed of before1 and this
+     * @throws NullPointerException if before1 is null
+     */
+    default <S> CheckedFunction1<S, R> compose1(Function1<? super S, ? extends T1> before1) {
+        Objects.requireNonNull(before1, "before1 is null");
+        return (S s) -> apply(before1.apply(s));
+    }
 }
 
 interface CheckedFunction1Module {

vavr/src-gen/main/java/io/vavr/CheckedFunction2.java

@@ -294,6 +294,33 @@ default <V> CheckedFunction2<T1, T2, V> andThen(CheckedFunction1<? super R, ? ex
         return (t1, t2) -> after.apply(apply(t1, t2));
     }
 
+    /**
+     * Returns a composed function that first applies the {@linkplain Function} {@code before1} to the
+     * 1st argument and then applies this CheckedFunction2 to the result and the other argument.
+     *
+     * @param <S> argument type of before1
+     * @param before1 the function applied before this
+     * @return a function composed of before1 and this
+     * @throws NullPointerException if before1 is null
+     */
+    default <S> CheckedFunction2<S, T2, R> compose1(Function1<? super S, ? extends T1> before1) {
+        Objects.requireNonNull(before1, "before1 is null");
+        return (S s, T2 t2) -> apply(before1.apply(s), t2);
+    }
+
+    /**
+     * Returns a composed function that first applies the {@linkplain Function} {@code before2} to the
+     * 2nd argument and then applies this CheckedFunction2 to the result and the other argument.
+     *
+     * @param <S> argument type of before2
+     * @param before2 the function applied before this
+     * @return a function composed of before2 and this
+     * @throws NullPointerException if before2 is null
+     */
+    default <S> CheckedFunction2<T1, S, R> compose2(Function1<? super S, ? extends T2> before2) {
+        Objects.requireNonNull(before2, "before2 is null");
+        return (T1 t1, S s) -> apply(t1, before2.apply(s));
+    }
 }
 
 interface CheckedFunction2Module {

vavr/src-gen/main/java/io/vavr/CheckedFunction3.java

@@ -311,6 +311,47 @@ default <V> CheckedFunction3<T1, T2, T3, V> andThen(CheckedFunction1<? super R,
         return (t1, t2, t3) -> after.apply(apply(t1, t2, t3));
     }
 
+    /**
+     * Returns a composed function that first applies the {@linkplain Function} {@code before1} to the
+     * 1st argument and then applies this CheckedFunction3 to the result and the other arguments.
+     *
+     * @param <S> argument type of before1
+     * @param before1 the function applied before this
+     * @return a function composed of before1 and this
+     * @throws NullPointerException if before1 is null
+     */
+    default <S> CheckedFunction3<S, T2, T3, R> compose1(Function1<? super S, ? extends T1> before1) {
+        Objects.requireNonNull(before1, "before1 is null");
+        return (S s, T2 t2, T3 t3) -> apply(before1.apply(s), t2, t3);
+    }
+
+    /**
+     * Returns a composed function that first applies the {@linkplain Function} {@code before2} to the
+     * 2nd argument and then applies this CheckedFunction3 to the result and the other arguments.
+     *
+     * @param <S> argument type of before2
+     * @param before2 the function applied before this
+     * @return a function composed of before2 and this
+     * @throws NullPointerException if before2 is null
+     */
+    default <S> CheckedFunction3<T1, S, T3, R> compose2(Function1<? super S, ? extends T2> before2) {
+        Objects.requireNonNull(before2, "before2 is null");
+        return (T1 t1, S s, T3 t3) -> apply(t1, before2.apply(s), t3);
+    }
+
+    /**
+     * Returns a composed function that first applies the {@linkplain Function} {@code before3} to the
+     * 3rd argument and then applies this CheckedFunction3 to the result and the other arguments.
+     *
+     * @param <S> argument type of before3
+     * @param before3 the function applied before this
+     * @return a function composed of before3 and this
+     * @throws NullPointerException if before3 is null
+     */
+    default <S> CheckedFunction3<T1, T2, S, R> compose3(Function1<? super S, ? extends T3> before3) {
+        Objects.requireNonNull(before3, "before3 is null");
+        return (T1 t1, T2 t2, S s) -> apply(t1, t2, before3.apply(s));
+    }
 }
 
 interface CheckedFunction3Module {

vavr/src-gen/main/java/io/vavr/CheckedFunction4.java

@@ -330,6 +330,61 @@ default <V> CheckedFunction4<T1, T2, T3, T4, V> andThen(CheckedFunction1<? super
         return (t1, t2, t3, t4) -> after.apply(apply(t1, t2, t3, t4));
     }
 
+    /**
+     * Returns a composed function that first applies the {@linkplain Function} {@code before1} to the
+     * 1st argument and then applies this CheckedFunction4 to the result and the other arguments.
+     *
+     * @param <S> argument type of before1
+     * @param before1 the function applied before this
+     * @return a function composed of before1 and this
+     * @throws NullPointerException if before1 is null
+     */
+    default <S> CheckedFunction4<S, T2, T3, T4, R> compose1(Function1<? super S, ? extends T1> before1) {
+        Objects.requireNonNull(before1, "before1 is null");
+        return (S s, T2 t2, T3 t3, T4 t4) -> apply(before1.apply(s), t2, t3, t4);
+    }
+
+    /**
+     * Returns a composed function that first applies the {@linkplain Function} {@code before2} to the
+     * 2nd argument and then applies this CheckedFunction4 to the result and the other arguments.
+     *
+     * @param <S> argument type of before2
+     * @param before2 the function applied before this
+     * @return a function composed of before2 and this
+     * @throws NullPointerException if before2 is null
+     */
+    default <S> CheckedFunction4<T1, S, T3, T4, R> compose2(Function1<? super S, ? extends T2> before2) {
+        Objects.requireNonNull(before2, "before2 is null");
+        return (T1 t1, S s, T3 t3, T4 t4) -> apply(t1, before2.apply(s), t3, t4);
+    }
+
+    /**
+     * Returns a composed function that first applies the {@linkplain Function} {@code before3} to the
+     * 3rd argument and then applies this CheckedFunction4 to the result and the other arguments.
+     *
+     * @param <S> argument type of before3
+     * @param before3 the function applied before this
+     * @return a function composed of before3 and this
+     * @throws NullPointerException if before3 is null
+     */
+    default <S> CheckedFunction4<T1, T2, S, T4, R> compose3(Function1<? super S, ? extends T3> before3) {
+        Objects.requireNonNull(before3, "before3 is null");
+        return (T1 t1, T2 t2, S s, T4 t4) -> apply(t1, t2, before3.apply(s), t4);
+    }
+
+    /**
+     * Returns a composed function that first applies the {@linkplain Function} {@code before4} to the
+     * 4th argument and then applies this CheckedFunction4 to the result and the other arguments.
+     *
+     * @param <S> argument type of before4
+     * @param before4 the function applied before this
+     * @return a function composed of before4 and this
+     * @throws NullPointerException if before4 is null
+     */
+    default <S> CheckedFunction4<T1, T2, T3, S, R> compose4(Function1<? super S, ? extends T4> before4) {
+        Objects.requireNonNull(before4, "before4 is null");
+        return (T1 t1, T2 t2, T3 t3, S s) -> apply(t1, t2, t3, before4.apply(s));
+    }
 }
 
 interface CheckedFunction4Module {

vavr/src-gen/main/java/io/vavr/CheckedFunction5.java

@@ -350,6 +350,75 @@ default <V> CheckedFunction5<T1, T2, T3, T4, T5, V> andThen(CheckedFunction1<? s
         return (t1, t2, t3, t4, t5) -> after.apply(apply(t1, t2, t3, t4, t5));
     }
 
+    /**
+     * Returns a composed function that first applies the {@linkplain Function} {@code before1} to the
+     * 1st argument and then applies this CheckedFunction5 to the result and the other arguments.
+     *
+     * @param <S> argument type of before1
+     * @param before1 the function applied before this
+     * @return a function composed of before1 and this
+     * @throws NullPointerException if before1 is null
+     */
+    default <S> CheckedFunction5<S, T2, T3, T4, T5, R> compose1(Function1<? super S, ? extends T1> before1) {
+        Objects.requireNonNull(before1, "before1 is null");
+        return (S s, T2 t2, T3 t3, T4 t4, T5 t5) -> apply(before1.apply(s), t2, t3, t4, t5);
+    }
+
+    /**
+     * Returns a composed function that first applies the {@linkplain Function} {@code before2} to the
+     * 2nd argument and then applies this CheckedFunction5 to the result and the other arguments.
+     *
+     * @param <S> argument type of before2
+     * @param before2 the function applied before this
+     * @return a function composed of before2 and this
+     * @throws NullPointerException if before2 is null
+     */
+    default <S> CheckedFunction5<T1, S, T3, T4, T5, R> compose2(Function1<? super S, ? extends T2> before2) {
+        Objects.requireNonNull(before2, "before2 is null");
+        return (T1 t1, S s, T3 t3, T4 t4, T5 t5) -> apply(t1, before2.apply(s), t3, t4, t5);
+    }
+
+    /**
+     * Returns a composed function that first applies the {@linkplain Function} {@code before3} to the
+     * 3rd argument and then applies this CheckedFunction5 to the result and the other arguments.
+     *
+     * @param <S> argument type of before3
+     * @param before3 the function applied before this
+     * @return a function composed of before3 and this
+     * @throws NullPointerException if before3 is null
+     */
+    default <S> CheckedFunction5<T1, T2, S, T4, T5, R> compose3(Function1<? super S, ? extends T3> before3) {
+        Objects.requireNonNull(before3, "before3 is null");
+        return (T1 t1, T2 t2, S s, T4 t4, T5 t5) -> apply(t1, t2, before3.apply(s), t4, t5);
+    }
+
+    /**
+     * Returns a composed function that first applies the {@linkplain Function} {@code before4} to the
+     * 4th argument and then applies this CheckedFunction5 to the result and the other arguments.
+     *
+     * @param <S> argument type of before4
+     * @param before4 the function applied before this
+     * @return a function composed of before4 and this
+     * @throws NullPointerException if before4 is null
+     */
+    default <S> CheckedFunction5<T1, T2, T3, S, T5, R> compose4(Function1<? super S, ? extends T4> before4) {
+        Objects.requireNonNull(before4, "before4 is null");
+        return (T1 t1, T2 t2, T3 t3, S s, T5 t5) -> apply(t1, t2, t3, before4.apply(s), t5);
+    }
+
+    /**
+     * Returns a composed function that first applies the {@linkplain Function} {@code before5} to the
+     * 5th argument and then applies this CheckedFunction5 to the result and the other arguments.
+     *
+     * @param <S> argument type of before5
+     * @param before5 the function applied before this
+     * @return a function composed of before5 and this
+     * @throws NullPointerException if before5 is null
+     */
+    default <S> CheckedFunction5<T1, T2, T3, T4, S, R> compose5(Function1<? super S, ? extends T5> before5) {
+        Objects.requireNonNull(before5, "before5 is null");
+        return (T1 t1, T2 t2, T3 t3, T4 t4, S s) -> apply(t1, t2, t3, t4, before5.apply(s));
+    }
 }
 
 interface CheckedFunction5Module {