Class ComparisonChain

java.lang.Object
cloud.opencode.base.collections.ComparisonChain
public abstract class ComparisonChain extends Object
ComparisonChain - Fluent comparator chain for multi-field comparisons ComparisonChain - 用于多字段比较的流式比较器链

A utility for performing chained comparisons within compareTo() methods. Once a non-zero comparison result is found, all subsequent comparisons are short-circuited.

用于在 compareTo() 方法中执行链式比较的工具类。 一旦找到非零比较结果，所有后续比较将被短路跳过。

Features | 主要功能:

  • Short-circuit evaluation on first difference - 第一个差异处短路求值
  • Supports all primitives (int, long, float, double, boolean) - 支持所有基本类型
  • Custom Comparator support - 支持自定义 Comparator
  • Boolean ordering: true-first or false-first - 布尔排序: true 优先或 false 优先

Usage Examples | 使用示例:

// Multi-field comparison in compareTo() - compareTo() 中的多字段比较
public int compareTo(Person other) {
    return ComparisonChain.start()
        .compare(this.lastName, other.lastName)
        .compare(this.firstName, other.firstName)
        .compare(this.age, other.age)
        .result();
}

Performance | 性能特性:

  • Time complexity: O(1) per chained call after short-circuit - 短路后每次链式调用 O(1)
  • No heap allocations after short-circuit (singleton reuse) - 短路后无堆分配（单例复用）

Security | 安全性:

  • Thread-safe: Yes (immutable singletons) - 线程安全: 是（不可变单例）
  • Null-safe: No (null arguments cause NullPointerException) - 空值安全: 否（null 参数导致 NullPointerException）
Since:
JDK 25, opencode-base-collections V1.0.3
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Method Details

    • start

      public static ComparisonChain start()
      Starts a new comparison chain. 启动一个新的比较链。
      Returns:
      the active comparison chain - 活动的比较链

    • compare

      public abstract ComparisonChain compare(Comparable<?> left, Comparable<?> right)
      Compares two Comparable values using their natural ordering. 使用自然排序比较两个 Comparable 值。
      Parameters:
      left - the left value - 左值
      right - the right value - 右值
      Returns:
      this chain for fluent chaining - 用于流式链接的此链

    • compare

      public abstract <T> ComparisonChain compare(T left, T right, Comparator<T> comparator)
      Compares two values using the specified Comparator. 使用指定的 Comparator 比较两个值。
      Type Parameters:
      T - the type of values being compared - 被比较值的类型
      Parameters:
      left - the left value - 左值
      right - the right value - 右值
      comparator - the comparator to use - 使用的比较器
      Returns:
      this chain for fluent chaining - 用于流式链接的此链

    • compare

      public abstract ComparisonChain compare(int left, int right)
      Compares two int values. 比较两个 int 值。
      Parameters:
      left - the left value - 左值
      right - the right value - 右值
      Returns:
      this chain for fluent chaining - 用于流式链接的此链

    • compare

      public abstract ComparisonChain compare(long left, long right)
      Compares two long values. 比较两个 long 值。
      Parameters:
      left - the left value - 左值
      right - the right value - 右值
      Returns:
      this chain for fluent chaining - 用于流式链接的此链

    • compare

      public abstract ComparisonChain compare(double left, double right)
      Compares two double values. 比较两个 double 值。
      Parameters:
      left - the left value - 左值
      right - the right value - 右值
      Returns:
      this chain for fluent chaining - 用于流式链接的此链

    • compare

      public abstract ComparisonChain compare(float left, float right)
      Compares two float values. 比较两个 float 值。
      Parameters:
      left - the left value - 左值
      right - the right value - 右值
      Returns:
      this chain for fluent chaining - 用于流式链接的此链

    • compareTrueFirst

      public abstract ComparisonChain compareTrueFirst(boolean left, boolean right)
      Compares two booleans, sorting true before false. 比较两个布尔值，true 排在 false 之前。
      Parameters:
      left - the left value - 左值
      right - the right value - 右值
      Returns:
      this chain for fluent chaining - 用于流式链接的此链

    • compareFalseFirst

      public abstract ComparisonChain compareFalseFirst(boolean left, boolean right)
      Compares two booleans, sorting false before true. 比较两个布尔值，false 排在 true 之前。
      Parameters:
      left - the left value - 左值
      right - the right value - 右值
      Returns:
      this chain for fluent chaining - 用于流式链接的此链

    • result

      public abstract int result()
      Returns the final comparison result. 返回最终比较结果。
      Returns:
      a negative integer, zero, or a positive integer as the first differing comparison was less than, equal to, or greater than 负整数、零或正整数，取决于第一个不同比较的结果