Class ComparisonChain
- java.lang.Object
-
- com.google.common.collect.ComparisonChain
-
@GwtCompatible public abstract class ComparisonChain extends java.lang.Object
A utility for performing a chained comparison statement. Note: Java 8+ users should generally prefer the methods inComparator
; see below.Example usage of
ComparisonChain
:public int compareTo(Foo that) { return ComparisonChain.start() .compare(this.aString, that.aString) .compare(this.anInt, that.anInt) .compare(this.anEnum, that.anEnum, Ordering.natural().nullsLast()) .result(); }
The value of this expression will have the same sign as the first nonzero comparison result in the chain, or will be zero if every comparison result was zero.
Note:
ComparisonChain
instances are immutable. For this utility to work correctly, calls must be chained as illustrated above.Performance note: Even though the
ComparisonChain
caller always invokes itscompare
methods unconditionally, theComparisonChain
implementation stops calling its inputs'compareTo
andcompare
methods as soon as one of them returns a nonzero result. This optimization is typically important only in the presence of expensivecompareTo
andcompare
implementations.See the Guava User Guide article on
ComparisonChain
.Java 8+ equivalents
If you are using Java version 8 or greater, you should generally use the static methods inComparator
instead ofComparisonChain
. The example above can be implemented like this:import static java.util.Comparator.comparing; import static java.util.Comparator.nullsLast; import static java.util.Comparator.naturalOrder; ... private static final Comparator<Foo> COMPARATOR = comparing((Foo foo) -> foo.aString) .thenComparing(foo -> foo.anInt) .thenComparing(foo -> foo.anEnum, nullsLast(naturalOrder()));
@Override
public int compareTo(Foo that) { return COMPARATOR.compare(this, that); }
With method references it is more succinct:
comparing(Foo::aString)
for example.Using
Comparator
avoids certain types of bugs, for example when you meant to write.compare(a.foo, b.foo)
but you actually wrote.compare(a.foo, a.foo)
or.compare(a.foo, b.bar)
.ComparisonChain
also has a potential performance problem thatComparator
doesn't: it evaluates all the parameters of all the.compare
calls, even when the result of the comparison is already known from previous.compare
calls. That can be expensive.- Since:
- 2.0
- Author:
- Mark Davis, Kevin Bourrillion
-
-
Method Summary
All Methods Static Methods Instance Methods Abstract Methods Concrete Methods Deprecated Methods Modifier and Type Method Description abstract ComparisonChain
compare(double left, double right)
Compares twodouble
values as specified byDouble.compare(double, double)
, if the result of this comparison chain has not already been determined.abstract ComparisonChain
compare(float left, float right)
Compares twofloat
values as specified byFloat.compare(float, float)
, if the result of this comparison chain has not already been determined.abstract ComparisonChain
compare(int left, int right)
Compares twoint
values as specified byInts.compare(int, int)
, if the result of this comparison chain has not already been determined.abstract ComparisonChain
compare(long left, long right)
Compares twolong
values as specified byLongs.compare(long, long)
, if the result of this comparison chain has not already been determined.ComparisonChain
compare(java.lang.Boolean left, java.lang.Boolean right)
Deprecated.UsecompareFalseFirst(boolean, boolean)
; or, if the parameters passed are being either negated or reversed, undo the negation or reversal and usecompareTrueFirst(boolean, boolean)
.abstract ComparisonChain
compare(java.lang.Comparable<?> left, java.lang.Comparable<?> right)
Compares two comparable objects as specified byComparable.compareTo(T)
, if the result of this comparison chain has not already been determined.abstract <T extends @Nullable java.lang.Object>
ComparisonChaincompare(T left, T right, java.util.Comparator<T> comparator)
Compares two objects using a comparator, if the result of this comparison chain has not already been determined.abstract ComparisonChain
compareFalseFirst(boolean left, boolean right)
Compares twoboolean
values, consideringfalse
to be less thantrue
, if the result of this comparison chain has not already been determined.abstract ComparisonChain
compareTrueFirst(boolean left, boolean right)
Compares twoboolean
values, consideringtrue
to be less thanfalse
, if the result of this comparison chain has not already been determined.abstract int
result()
Ends this comparison chain and returns its result: a value having the same sign as the first nonzero comparison result in the chain, or zero if every result was zero.static ComparisonChain
start()
Begins a new chained comparison statement.
-
-
-
Method Detail
-
start
public static ComparisonChain start()
Begins a new chained comparison statement. See example in the class documentation.
-
compare
public abstract ComparisonChain compare(java.lang.Comparable<?> left, java.lang.Comparable<?> right)
Compares two comparable objects as specified byComparable.compareTo(T)
, if the result of this comparison chain has not already been determined.This method is declared to accept any 2
Comparable
objects, even if they are not mutually comparable. If you pass objects that are not mutually comparable, this method may throw an exception. (The reason for this decision is lost to time, but the reason might be that we wanted to support legacy classes that implement the raw typeComparable
(instead of implementingComparable<Foo>
) without producing warnings. If so, we would prefer today to produce warnings in that case, and we may change this method to do so in the future. Support for rawComparable
types in Guava in general is tracked as #989.)- Throws:
java.lang.ClassCastException
- if the parameters are not mutually comparable
-
compare
public abstract <T extends @Nullable java.lang.Object> ComparisonChain compare(T left, T right, java.util.Comparator<T> comparator)
Compares two objects using a comparator, if the result of this comparison chain has not already been determined.
-
compare
public abstract ComparisonChain compare(int left, int right)
Compares twoint
values as specified byInts.compare(int, int)
, if the result of this comparison chain has not already been determined.
-
compare
public abstract ComparisonChain compare(long left, long right)
Compares twolong
values as specified byLongs.compare(long, long)
, if the result of this comparison chain has not already been determined.
-
compare
public abstract ComparisonChain compare(float left, float right)
Compares twofloat
values as specified byFloat.compare(float, float)
, if the result of this comparison chain has not already been determined.
-
compare
public abstract ComparisonChain compare(double left, double right)
Compares twodouble
values as specified byDouble.compare(double, double)
, if the result of this comparison chain has not already been determined.
-
compare
@Deprecated public final ComparisonChain compare(java.lang.Boolean left, java.lang.Boolean right)
Deprecated.UsecompareFalseFirst(boolean, boolean)
; or, if the parameters passed are being either negated or reversed, undo the negation or reversal and usecompareTrueFirst(boolean, boolean)
.Discouraged synonym forcompareFalseFirst(boolean, boolean)
.- Since:
- 19.0
-
compareTrueFirst
public abstract ComparisonChain compareTrueFirst(boolean left, boolean right)
Compares twoboolean
values, consideringtrue
to be less thanfalse
, if the result of this comparison chain has not already been determined.Java 8+ users: you can get the equivalent from
Booleans.trueFirst()
. For example:Comparator.comparing(Foo::isBar,
Booleans.trueFirst()
)- Since:
- 12.0
-
compareFalseFirst
public abstract ComparisonChain compareFalseFirst(boolean left, boolean right)
Compares twoboolean
values, consideringfalse
to be less thantrue
, if the result of this comparison chain has not already been determined.Java 8+ users: you can get the equivalent from
Booleans.falseFirst()
. For example:Comparator.comparing(Foo::isBar,
Booleans.falseFirst()
)- Since:
- 12.0 (present as
compare
since 2.0)
-
result
public abstract int result()
Ends this comparison chain and returns its result: a value having the same sign as the first nonzero comparison result in the chain, or zero if every result was zero.
-
-