add pin methods, seal the interface

Author: Leonhard Bromoloron

src/main/java/io/jbock/util/Either.java

@@ -7,8 +7,8 @@
 
 /**
  * A class that acts as a container for a value of one of two types. An Either
- * can be either be a "Left", containing a LHS value or a "Right" containing a RHS value,
- * but it cannot be "neither" or "both".
+ * can be either be a "Left", containing an LHS value or a "Right" containing an RHS value,
+ * but it cannot be "neither" nor "both".
  *
  * <p>An Either can be used to express a success or failure case. By convention,
  * a Right contains the result of a successful computation,
@@ -17,7 +17,7 @@
  * @param <L> the type of the LHS value
  * @param <R> the type of the RHS value
  */
-public interface Either<L, R> {
+public sealed interface Either<L, R> permits Left, Right {
 
     /**
      * Returns a Left containing the given non-{@code null} LHS value.
@@ -48,7 +48,7 @@ static <L, R> Either<L, R> right(R value) {
     /**
      * If this is a Right, returns a Right containing the result of applying
      * the mapper function to the RHS value.
-     * Otherwise returns a Left containing the LHS value.
+     * Otherwise, returns a Left containing the LHS value.
      *
      * @param mapper the function to apply to the RHS value, if this is a Right
      * @param <R2> the new RHS type
@@ -61,7 +61,7 @@ <R2> Either<L, R2> map(
 
     /**
      * If this is a Right, returns the result of applying the mapper function to the RHS value.
-     * Otherwise returns a Left containing the LHS value.
+     * Otherwise, returns a Left containing the LHS value.
      *
      * @param mapper a mapper function
      * @param <R2> the new RHS type
@@ -86,7 +86,7 @@ Either<L, R> filter(
 
     /**
      * If this is a Left, returns a Left containing the result of applying the mapper function to the LHS value.
-     * Otherwise returns a Right containing the RHS value.
+     * Otherwise, returns a Right containing the RHS value.
      *
      * @param mapper the function to apply to the LHS value
      * @param <L2> the new LHS type
@@ -99,7 +99,7 @@ <L2> Either<L2, R> mapLeft(
 
     /**
      * If this is a Left, returns the result of applying the mapper function to the LHS value.
-     * Otherwise returns a Right containing the RHS value.
+     * Otherwise, returns a Right containing the RHS value.
      *
      * @param mapper a mapper function
      * @param <L2> the new LHS type
@@ -109,6 +109,24 @@ <L2> Either<L2, R> mapLeft(
     <L2> Either<L2, R> flatMapLeft(
             Function<? super L, ? extends Either<? extends L2, ? extends R>> mapper);
 
+    /**
+     * Returns the receiver object unchanged. This method should only be invoked
+     * if this is provably a Left.
+     *
+     * @return the same object
+     * @throws UnsupportedOperationException if this is a Right
+     */
+    <R2> Either<L, R2> pinLeft();
+
+    /**
+     * Returns the receiver object unchanged. This method should only be invoked
+     * if this is provably a Right.
+     *
+     * @return the same object
+     * @throws UnsupportedOperationException if this is a Left
+     */
+    <L2> Either<L2, R> pinRight();
+
     /**
      * If this is a Right, returns a Right containing the RHS value.
      * If this is a Left, applies the predicate function to the LHS value.
@@ -124,7 +142,7 @@ Either<L, R> filterLeft(
 
     /**
      * If this is a Left, returns the result of applying the {@code leftMapper} to the LHS value.
-     * Otherwise returns the result of applying the {@code rightMapper} to the RHS value.
+     * Otherwise, returns the result of applying the {@code rightMapper} to the RHS value.
      *
      * @param leftMapper the function to apply if this is a Left
      * @param rightMapper the function to apply if this is a Right
@@ -137,7 +155,7 @@ <U> U fold(
 
     /**
      * If this is a Left, performs the {@code leftAction} with the LHS value.
-     * Otherwise performs the {@code rightAction} with the RHS value.
+     * Otherwise, performs the {@code rightAction} with the RHS value.
      *
      * @param leftAction action to run if this is a Left
      * @param rightAction action to run if this is a Right
@@ -148,7 +166,7 @@ void ifLeftOrElse(
 
     /**
      * If this is a Right, returns the RHS value.
-     * Otherwise throws an exception produced by the exception supplying function.
+     * Otherwise, throws an exception produced by the exception supplying function.
      *
      * @param exceptionSupplier exception supplying function
      * @param <X> type of the exception
@@ -176,15 +194,15 @@ default boolean isRight() {
 
     /**
      * If this is a Left, returns an {@code Optional} containing the LHS value.
-     * Otherwise returns an empty {@code Optional}.
+     * Otherwise, returns an empty {@code Optional}.
      *
      * @return the LHS value if this is a Left, otherwise an empty {@code Optional}
      */
     Optional<L> getLeft();
 
     /**
      * If this is a Right, returns an {@code Optional} containing the RHS value.
-     * Otherwise returns an empty {@code Optional}.
+     * Otherwise, returns an empty {@code Optional}.
      *
      * @return the RHS value if this is a Right, otherwise an empty {@code Optional}
      */

src/main/java/io/jbock/util/Left.java

@@ -58,6 +58,18 @@ public <L2> Either<L2, R> flatMapLeft(Function<? super L, ? extends Either<? ext
         return result;
     }
 
+    @Override
+    public <R2> Either<L, R2> pinLeft() {
+        @SuppressWarnings("unchecked")
+        Left<L, R2> result = (Left<L, R2>) this;
+        return result;
+    }
+
+    @Override
+    public <L2> Either<L2, R> pinRight() {
+        throw new UnsupportedOperationException("not a Right");
+    }
+
     @Override
     public Either<L, R> filterLeft(Function<? super L, Optional<? extends R>> predicate) {
         Optional<? extends R> test = predicate.apply(value);

src/main/java/io/jbock/util/Right.java

@@ -62,6 +62,18 @@ public <L2> Either<L2, R> flatMapLeft(Function<? super L, ? extends Either<? ext
         return result;
     }
 
+    @Override
+    public <R2> Either<L, R2> pinLeft() {
+        throw new UnsupportedOperationException("not a Left");
+    }
+
+    @Override
+    public <L2> Either<L2, R> pinRight() {
+        @SuppressWarnings("unchecked")
+        Right<L2, R> result = (Right<L2, R>) this;
+        return result;
+    }
+
     @Override
     public Either<L, R> filterLeft(Function<? super L, Optional<? extends R>> predicate) {
         return this;

src/test/java/io/jbock/util/EitherTest.java

@@ -3,6 +3,7 @@
 import org.junit.jupiter.api.Test;
 
 import java.io.IOException;
+import java.time.LocalDate;
 import java.util.Objects;
 import java.util.Optional;
 
@@ -141,4 +142,16 @@ void testOrElseThrow() {
         Either<String, String> right = Either.right("2");
         assertEquals("2", right.orElseThrow(IllegalArgumentException::new));
     }
+
+    @Test
+    void testPin() {
+        Either<String, Integer> left = Either.left("1");
+        Either<String, LocalDate> left2 = left.pinLeft();
+        assertThrows(UnsupportedOperationException.class, left::pinRight);
+        assertEquals(Either.left("1"), left2);
+        Either<Integer, String> right = Either.right("2");
+        Either<LocalDate, String> right2 = right.pinRight();
+        assertThrows(UnsupportedOperationException.class, right::pinLeft);
+        assertEquals(Either.right("2"), right2);
+    }
 }