New feature: Try.toEither(Throwable -> L) (#3088)

Allows:
```
Either<String, Locale> either = Try.ofSupplier(() -> Locale.forLanguageTag("non-existing"))
  .toEither(exception -> "This was an unsupported language");
```

This is a rework of #2724, which was initially suggested and developed by @eslep


Co-authored-by: Eric Slep <eric.slep@zenjob.co>

Author: adamkopec

vavr/src/main/java/io/vavr/control/Try.java

@@ -1061,6 +1061,24 @@ default Either<Throwable, T> toEither() {
         }
     }
 
+    /**
+     * Converts this {@code Try} to an {@link Either}, converting the Throwable (in the failure case)
+     * to a left value using the passed {@link Function}.
+     *
+     * @param <L> left type of the resulting Either
+     * @param throwableMapper A transformation from throwable to the left type of the new {@code Either}
+     * @return A new {@code Either}
+     * @throws NullPointerException if the given {@code throwableMapper} is null
+     */
+    default <L> Either<L, T> toEither(Function<? super Throwable, ? extends L> throwableMapper) {
+        Objects.requireNonNull(throwableMapper, "throwableMapper is null");
+        if (isFailure()) {
+            return Either.left(throwableMapper.apply(getCause()));
+        } else {
+            return Either.right(get());
+        }
+    }
+
     /**
      * Converts this {@code Try} to a {@link Validation}.
      *
@@ -1071,8 +1089,8 @@ default Validation<Throwable, T> toValidation() {
     }
 
     /**
-     * Converts this {@code Try} to a {@link Validation}, converting the Throwable (if present)
-     * to another object using passed {@link Function}.
+     * Converts this {@code Try} to a {@link Validation}, converting the Throwable (in the failure case)
+     * to another object using the passed {@link Function}.
      *
      * <pre>{@code
      * Validation<String, Integer> = Try.of(() -> 1/0).toValidation(Throwable::getMessage));

vavr/src/test/java/io/vavr/control/TryTest.java

@@ -1065,6 +1065,41 @@ public void shouldConvertFailureToEither() {
         assertThat(failure().toEither().isLeft()).isTrue();
     }
 
+    @Test
+    public void shouldConvertFailureToEitherUsingMapper() {
+        Either<String, Object> converted = failure().toEither(
+            exception -> "error string"
+        );
+        assertThat(converted.isLeft()).isTrue();
+        assertThat(converted.getLeft()).isEqualTo("error string");
+    }
+
+    @Test
+    public void shouldConvertSuccessToEitherUsingMapper() {
+        Either<String, String> converted = success().toEither(
+            exception -> "another error"
+        );
+        assertThat(converted.isRight()).isTrue();
+        assertThat(converted.get()).isEqualTo(success().get());
+    }
+
+    @Test
+    public void shouldExecuteToEitherMapperLazilyOnlyWhenFailure() {
+        Either<String, String> converted = success().toEither(
+            exception -> {
+                throw new RuntimeException();
+            }
+        );
+        assertThat(converted.isRight()).isTrue();
+        assertThat(converted.get()).isEqualTo(success().get());
+    }
+
+    @Test
+    public void shouldNotAcceptNullAsThrowableMapperForToEither() {
+        Function<Throwable, String> mapper = null;
+        assertThrows(NullPointerException.class, () -> failure().toEither(mapper));
+    }
+
     @Test
     public void shouldConvertFailureToEitherLeft() {
         assertThat(failure().toEither("test").isLeft()).isTrue();