Interface Either<L,R>

Type Parameters:
L - left type (typically error) - 左类型（通常为错误）
R - right type (typically success) - 右类型（通常为成功）
All Known Implementing Classes:
Either.Left, Either.Right
public sealed interface Either<L,R> permits Either.Left<L,R>, Either.Right<L,R>
Either Monad - Represents one of two possible values (Left or Right) Either Monad - 表示两种可能值之一（Left 或 Right）

A sealed type that contains either a Left value (typically for errors) or a Right value (typically for success). By convention, Right is the "happy path".

一个密封类型，包含 Left 值（通常表示错误）或 Right 值（通常表示成功）。 按照惯例，Right 是"正常路径"。

Features | 主要功能:

  • Type-safe error handling - 类型安全的错误处理
  • Right-biased operations - Right 倾向的操作
  • Monadic operations (map, flatMap) - Monad 操作
  • Folding/pattern matching - 折叠/模式匹配
  • Swap operation - 交换操作

Usage Examples | 使用示例:

// Creating Either values
Either<String, User> success = Either.right(user);
Either<String, User> error = Either.left("User not found");

// Returning from methods
public Either<String, User> findUser(Long id) {
    User user = userRepository.findById(id);
    return user == null
        ? Either.left("User not found: " + id)
        : Either.right(user);
}

// Using the result
findUser(1L)
    .map(User::getName)
    .fold(
        error -> log.error(error),
        name -> log.info("Found: " + name)
    );

Security | 安全性:

  • Thread-safe: Yes (immutable) - 线程安全: 是 (不可变)
  • Null-safe: Allows null values - 空值安全: 允许 null 值
Since:
JDK 25, opencode-base-functional V1.0.0
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static final class 
    Either.Left<L,R>
    Left - Represents the left case (typically error) Left - 表示左情况（通常为错误）
    static final class 
    Either.Right<L,R>
    Right - Represents the right case (typically success) Right - 表示右情况（通常为成功）

  • Method Summary

    Modifier and Type
    Method
    Description
    <L2,R2> Either<L2,R2>
    bimap(Function<? super L, ? extends L2> leftMapper, Function<? super R, ? extends R2> rightMapper)
    Transform both sides 转换两侧的值
    default boolean
    contains(R value)
    Check if this is a Right containing the given value.
    default boolean
    exists(Predicate<? super R> predicate)
    Check if this is a Right and the predicate matches the value.
    default Either<L,R>
    filterOrElse(Predicate<? super R> predicate, Supplier<? extends L> orElse)
    Filter the Right value with a predicate, converting to Left if it fails.
    <U> Either<L,U>
    flatMap(Function<? super R, Either<L,U>> mapper)
    Transform the Right value to another Either 将 Right 值转换为另一个 Either
    <T> T
    fold(Function<? super L, ? extends T> leftMapper, Function<? super R, ? extends T> rightMapper)
    Fold both cases to a single result 将两种情况折叠为单一结果
    default boolean
    forAll(Predicate<? super R> predicate)
    Check if this is a Left (vacuously true) or the predicate matches the Right value.
    Optional<L>
    getLeft()
    Get the Left value if present 获取 Left 值（如果存在）
    R
    getOrElse(R defaultValue)
    Get Right value or default if Left 获取 Right 值或默认值（如果是 Left）
    Optional<R>
    getRight()
    Get the Right value if present 获取 Right 值（如果存在）
    boolean
    isLeft()
    Check if this is a Left 检查是否为 Left
    boolean
    isRight()
    Check if this is a Right 检查是否为 Right
    static <L,R> Either<L,R>
    left(L value)
    Create a Left Either 创建 Left Either
    <U> Either<L,U>
    map(Function<? super R, ? extends U> mapper)
    Transform the Right value 转换 Right 值
    <U> Either<U,R>
    mapLeft(Function<? super L, ? extends U> mapper)
    Transform the Left value 转换 Left 值
    Either<L,R>
    orElse(Either<L,R> other)
    Return this or other Either if Left 返回本 Either 或其他 Either（如果是 Left）
    Either<L,R>
    peek(Consumer<? super R> action)
    Execute action on Right value 对 Right 值执行操作
    Either<L,R>
    peekLeft(Consumer<? super L> action)
    Execute action on Left value 对 Left 值执行操作
    static <L,R> Either<L,R>
    right(R value)
    Create a Right Either 创建 Right Either
    default Stream<R>
    stream()
    Convert to Stream: Right becomes a single-element Stream, Left becomes empty.
    Either<R,L>
    swap()
    Swap Left and Right 交换 Left 和 Right
    default Option<R>
    toOption()
    Convert to Option: Right becomes Some, Left becomes None.
    default Try<R>
    toTry()
    Convert to Try: Right becomes Success, Left becomes Failure.
    default Validation<L,R>
    toValidation()
    Convert to Validation: Right becomes Valid, Left becomes Invalid.

  • Method Details

    • left

      static <L,R> Either<L,R> left(L value)
      Create a Left Either 创建 Left Either
      Type Parameters:
      L - left type - 左类型
      R - right type - 右类型
      Parameters:
      value - left value - 左值
      Returns:
      Left Either

    • right

      static <L,R> Either<L,R> right(R value)
      Create a Right Either 创建 Right Either
      Type Parameters:
      L - left type - 左类型
      R - right type - 右类型
      Parameters:
      value - right value - 右值
      Returns:
      Right Either

    • isLeft

      boolean isLeft()
      Check if this is a Left 检查是否为 Left
      Returns:
      true if Left - 如果是 Left 返回 true

    • isRight

      boolean isRight()
      Check if this is a Right 检查是否为 Right
      Returns:
      true if Right - 如果是 Right 返回 true

    • getLeft

      Optional<L> getLeft()
      Get the Left value if present 获取 Left 值（如果存在）
      Returns:
      Optional containing Left value

    • getRight

      Optional<R> getRight()
      Get the Right value if present 获取 Right 值（如果存在）
      Returns:
      Optional containing Right value

    • map

      <U> Either<L,U> map(Function<? super R, ? extends U> mapper)
      Transform the Right value 转换 Right 值
      Type Parameters:
      U - result type - 结果类型
      Parameters:
      mapper - transformation function - 转换函数
      Returns:
      transformed Either

    • flatMap

      <U> Either<L,U> flatMap(Function<? super R, Either<L,U>> mapper)
      Transform the Right value to another Either 将 Right 值转换为另一个 Either
      Type Parameters:
      U - result type - 结果类型
      Parameters:
      mapper - transformation function returning Either - 返回 Either 的转换函数
      Returns:
      resulting Either

    • mapLeft

      <U> Either<U,R> mapLeft(Function<? super L, ? extends U> mapper)
      Transform the Left value 转换 Left 值
      Type Parameters:
      U - result type - 结果类型
      Parameters:
      mapper - transformation function - 转换函数
      Returns:
      transformed Either

    • bimap

      <L2,R2> Either<L2,R2> bimap(Function<? super L, ? extends L2> leftMapper, Function<? super R, ? extends R2> rightMapper)
      Transform both sides 转换两侧的值
      Type Parameters:
      L2 - new left type - 新的左类型
      R2 - new right type - 新的右类型
      Parameters:
      leftMapper - transformation for Left - Left 的转换函数
      rightMapper - transformation for Right - Right 的转换函数
      Returns:
      transformed Either

    • getOrElse

      R getOrElse(R defaultValue)
      Get Right value or default if Left 获取 Right 值或默认值（如果是 Left）
      Parameters:
      defaultValue - default value - 默认值
      Returns:
      Right value or default

    • orElse

      Either<L,R> orElse(Either<L,R> other)
      Return this or other Either if Left 返回本 Either 或其他 Either（如果是 Left）
      Parameters:
      other - alternative Either - 备选 Either
      Returns:
      this if Right, other if Left

    • fold

      <T> T fold(Function<? super L, ? extends T> leftMapper, Function<? super R, ? extends T> rightMapper)
      Fold both cases to a single result 将两种情况折叠为单一结果
      Type Parameters:
      T - result type - 结果类型
      Parameters:
      leftMapper - function for Left - Left 的函数
      rightMapper - function for Right - Right 的函数
      Returns:
      folded result

    • swap

      Either<R,L> swap()
      Swap Left and Right 交换 Left 和 Right
      Returns:
      swapped Either

    • peek

      Either<L,R> peek(Consumer<? super R> action)
      Execute action on Right value 对 Right 值执行操作
      Parameters:
      action - action to execute - 要执行的操作
      Returns:
      this Either for chaining

    • peekLeft

      Either<L,R> peekLeft(Consumer<? super L> action)
      Execute action on Left value 对 Left 值执行操作
      Parameters:
      action - action to execute - 要执行的操作
      Returns:
      this Either for chaining

    • filterOrElse

      default Either<L,R> filterOrElse(Predicate<? super R> predicate, Supplier<? extends L> orElse)
      Filter the Right value with a predicate, converting to Left if it fails. 用谓词过滤 Right 值，如果不满足则转换为 Left。

      If this is a Right and the predicate matches, returns this. If this is a Right but the predicate fails, returns Left with the orElse value. If this is a Left, returns this unchanged.

      如果是 Right 且谓词匹配，返回 this。 如果是 Right 但谓词不匹配，返回包含 orElse 值的 Left。 如果是 Left，原样返回。

      Parameters:
      predicate - the predicate to test the Right value | 用于测试 Right 值的谓词
      orElse - supplier for the Left value if predicate fails | 谓词不满足时的 Left 值提供者
      Returns:
      filtered Either | 过滤后的 Either

    • toOption

      default Option<R> toOption()
      Convert to Option: Right becomes Some, Left becomes None. 转换为 Option：Right 变为 Some，Left 变为 None。
      Returns:
      Option containing the Right value, or empty | 包含 Right 值的 Option，或为空

    • toTry

      default Try<R> toTry()
      Convert to Try: Right becomes Success, Left becomes Failure. 转换为 Try：Right 变为 Success，Left 变为 Failure。

      For Left: if the value is a Throwable, it is used directly; otherwise an OpenFunctionalException wrapping it is created.

      对于 Left：如果值是 Throwable，则直接使用； 否则创建包装它的 OpenFunctionalException。

      Returns:
      Try containing the Right value or the Left error | 包含 Right 值或 Left 错误的 Try

    • toValidation

      default Validation<L,R> toValidation()
      Convert to Validation: Right becomes Valid, Left becomes Invalid. 转换为 Validation：Right 变为 Valid，Left 变为 Invalid。
      Returns:
      Validation containing the Right value or the Left error | 包含 Right 值或 Left 错误的 Validation

    • stream

      default Stream<R> stream()
      Convert to Stream: Right becomes a single-element Stream, Left becomes empty. 转换为 Stream：Right 变为单元素 Stream，Left 变为空 Stream。
      Returns:
      Stream containing the Right value, or empty | 包含 Right 值的 Stream，或为空

    • contains

      default boolean contains(R value)
      Check if this is a Right containing the given value. 检查是否为包含给定值的 Right。
      Parameters:
      value - the value to compare | 要比较的值
      Returns:
      true if Right and value equals contained value | 如果是 Right 且值相等返回 true

    • exists

      default boolean exists(Predicate<? super R> predicate)
      Check if this is a Right and the predicate matches the value. 检查是否为 Right 且谓词匹配该值。
      Parameters:
      predicate - the predicate to test | 要测试的谓词
      Returns:
      true if Right and predicate matches | 如果是 Right 且谓词匹配返回 true

    • forAll

      default boolean forAll(Predicate<? super R> predicate)
      Check if this is a Left (vacuously true) or the predicate matches the Right value. 检查是否为 Left（空真）或谓词匹配 Right 值。
      Parameters:
      predicate - the predicate to test | 要测试的谓词
      Returns:
      true if Left or predicate matches Right value | 如果是 Left 或谓词匹配 Right 值返回 true