A utility for performing a chained comparison statement

Note

Java 8+ users should generally prefer the methods in Comparator; 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 its compare methods unconditionally, the ComparisonChain implementation stops calling its inputs' compareTo and compare methods as soon as one of them returns a nonzero result. This optimization is typically important only in the presence of expensive compareTo and compare 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 in Comparator instead of ComparisonChain. 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()));

  @Overridepublic 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 that Comparator 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.

Nested and Inner Type Summary

Modifier and Type	Class and Description
private static class	ComparisonChain.InactiveComparisonChain

Field Summary

Modifier and Type	Field and Description
private static final ComparisonChain	ACTIVE
private static final ComparisonChain	GREATER
private static final ComparisonChain	LESS

Constructor Summary

Access	Constructor and Description
private	ComparisonChain()

Method Summary

Modifier and Type	Method and Description
public abstract ComparisonChain	compare(Comparable<?> left, Comparable<?> right) Compares two comparable objects as specified by `Comparable#compareTo`, if the result of this comparison chain has not already been determined.
public abstract <T extends @Nullable Object> ComparisonChain	compare(T left, T right, Comparator<T> comparator) Compares two objects using a comparator, if the result of this comparison chain has not already been determined.
public abstract ComparisonChain	compare(int left, int right) Compares two `int` values as specified by `Ints#compare`, if the result of this comparison chain has not already been determined.
public abstract ComparisonChain	compare(long left, long right) Compares two `long` values as specified by `Longs#compare`, if the result of this comparison chain has not already been determined.
public abstract ComparisonChain	compare(float left, float right) Compares two `float` values as specified by `Float#compare`, if the result of this comparison chain has not already been determined.
public abstract ComparisonChain	compare(double left, double right) Compares two `double` values as specified by `Double#compare`, if the result of this comparison chain has not already been determined.
public final ComparisonChain	compare(Boolean left, Boolean right) Deprecated Use `compareFalseFirst`; or, if the parameters passed are being either negated or reversed, undo the negation or reversal and use `compareTrueFirst`. Discouraged synonym for `compareFalseFirst`.
public abstract ComparisonChain	compareFalseFirst(boolean left, boolean right) Compares two `boolean` values, considering `false` to be less than `true`, if the result of this comparison chain has not already been determined.
public abstract ComparisonChain	compareTrueFirst(boolean left, boolean right) Compares two `boolean` values, considering `true` to be less than `false`, if the result of this comparison chain has not already been determined.
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.
public static ComparisonChain	start() Begins a new chained comparison statement.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

ACTIVE	back to summary
private static final ComparisonChain ACTIVE

GREATER	back to summary
private static final ComparisonChain GREATER

LESS	back to summary
private static final ComparisonChain LESS

Constructor Detail

ComparisonChain	back to summary
private ComparisonChain()

Method Detail

compare back to summary

compare	back to summary
public abstract ComparisonChain compare(Comparable<?> left, Comparable<?> right) Compares two comparable objects as specified by `Comparable#compareTo`, 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 type `Comparable` (instead of implementing `Comparable<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 raw `Comparable` types in Guava in general is tracked as #989.) Exceptions ClassCastException: if the parameters are not mutually comparable

public abstract ComparisonChain compare(Comparable<?> left, Comparable<?> right)

Compares two comparable objects as specified by Comparable#compareTo, 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 type Comparable (instead of implementing Comparable<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 raw Comparable types in Guava in general is tracked as #989.)

Exceptions

ClassCastException:: if the parameters are not mutually comparable

compare	back to summary
public abstract <T extends @Nullable Object> ComparisonChain compare(T left, T right, Comparator<T> comparator) Compares two objects using a comparator, if the result of this comparison chain has not already been determined.

compare	back to summary
public abstract ComparisonChain compare(int left, int right) Compares two `int` values as specified by `Ints#compare`, if the result of this comparison chain has not already been determined.

compare	back to summary
public abstract ComparisonChain compare(long left, long right) Compares two `long` values as specified by `Longs#compare`, if the result of this comparison chain has not already been determined.

compare	back to summary
public abstract ComparisonChain compare(float left, float right) Compares two `float` values as specified by `Float#compare`, if the result of this comparison chain has not already been determined.

compare	back to summary
public abstract ComparisonChain compare(double left, double right) Compares two `double` values as specified by `Double#compare`, if the result of this comparison chain has not already been determined.

compare back to summary

compare	back to summary
public final ComparisonChain compare(Boolean left, Boolean right) Deprecated Use `compareFalseFirst`; or, if the parameters passed are being either negated or reversed, undo the negation or reversal and use `compareTrueFirst`. Discouraged synonym for `compareFalseFirst`. Annotations @Deprecated Since 19.0

public final ComparisonChain compare(Boolean left, Boolean right)

Deprecated

Use compareFalseFirst; or, if the parameters passed are being either negated or reversed, undo the negation or reversal and use compareTrueFirst.

Discouraged synonym for compareFalseFirst.

Annotations

@Deprecated

Since

19.0

compareFalseFirst back to summary

compareFalseFirst	back to summary
public abstract ComparisonChain compareFalseFirst(boolean left, boolean right) Compares two `boolean` values, considering `false` to be less than `true`, 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)

public abstract ComparisonChain compareFalseFirst(boolean left, boolean right)

Compares two boolean values, considering false to be less than true, 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)

compareTrueFirst back to summary

compareTrueFirst	back to summary
public abstract ComparisonChain compareTrueFirst(boolean left, boolean right) Compares two `boolean` values, considering `true` to be less than `false`, 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

public abstract ComparisonChain compareTrueFirst(boolean left, boolean right)

Compares two boolean values, considering true to be less than false, 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

result	back to summary
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.

start	back to summary
public static ComparisonChain start() Begins a new chained comparison statement. See example in the class documentation.

com.google.common.collect back to summary

private final Class ComparisonChain.InactiveComparisonChain

Class Inheritance

extends ComparisonChain

java.lang.Object
com.google.common.collect.ComparisonChain
com.google.common.collect.ComparisonChain.InactiveComparisonChain

Field Summary

Modifier and Type	Field and Description
pack-priv final int	result

Constructor Summary

Access	Constructor and Description
pack-priv	InactiveComparisonChain(int result)

Method Summary

Modifier and Type	Method and Description
public ComparisonChain	compare(Comparable<?> left, Comparable<?> right) Implements abstract com.google.common.collect.ComparisonChain.compare. Compares two comparable objects as specified by `Comparable#compareTo`, if the result of this comparison chain has not already been determined.
public <T extends @Nullable Object> ComparisonChain	compare(T left, T right, Comparator<T> comparator) Implements abstract com.google.common.collect.ComparisonChain.compare. Compares two objects using a comparator, if the result of this comparison chain has not already been determined.
public ComparisonChain	compare(int left, int right) Implements abstract com.google.common.collect.ComparisonChain.compare. Compares two `int` values as specified by `Ints#compare`, if the result of this comparison chain has not already been determined.
public ComparisonChain	compare(long left, long right) Implements abstract com.google.common.collect.ComparisonChain.compare. Compares two `long` values as specified by `Longs#compare`, if the result of this comparison chain has not already been determined.
public ComparisonChain	compare(float left, float right) Implements abstract com.google.common.collect.ComparisonChain.compare. Compares two `float` values as specified by `Float#compare`, if the result of this comparison chain has not already been determined.
public ComparisonChain	compare(double left, double right) Implements abstract com.google.common.collect.ComparisonChain.compare. Compares two `double` values as specified by `Double#compare`, if the result of this comparison chain has not already been determined.
public ComparisonChain	compareFalseFirst(boolean left, boolean right) Implements abstract com.google.common.collect.ComparisonChain.compareFalseFirst. Compares two `boolean` values, considering `false` to be less than `true`, if the result of this comparison chain has not already been determined.
public ComparisonChain	compareTrueFirst(boolean left, boolean right) Implements abstract com.google.common.collect.ComparisonChain.compareTrueFirst. Compares two `boolean` values, considering `true` to be less than `false`, if the result of this comparison chain has not already been determined.
public int	result() Implements abstract com.google.common.collect.ComparisonChain.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.

Inherited from com.google.common.collect.ComparisonChain:: compare start

Field Detail

result	back to summary
pack-priv final int result

Constructor Detail

InactiveComparisonChain	back to summary
pack-priv InactiveComparisonChain(int result)

Method Detail

compare back to summary

compare	back to summary
public ComparisonChain compare(Comparable<?> left, Comparable<?> right) Implements abstract com.google.common.collect.ComparisonChain.compare. Doc from com.google.common.collect.ComparisonChain.compare. Compares two comparable objects as specified by `Comparable#compareTo`, 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 type `Comparable` (instead of implementing `Comparable<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 raw `Comparable` types in Guava in general is tracked as #989.) Annotations @Override

public ComparisonChain compare(Comparable<?> left, Comparable<?> right)

Implements abstract com.google.common.collect.ComparisonChain.compare.

Doc from com.google.common.collect.ComparisonChain.compare.

Compares two comparable objects as specified by Comparable#compareTo, if the result of this comparison chain has not already been determined.

Annotations

@Override

compare	back to summary
public <T extends @Nullable Object> ComparisonChain compare(T left, T right, Comparator<T> comparator) Implements abstract com.google.common.collect.ComparisonChain.compare. Doc from com.google.common.collect.ComparisonChain.compare. Compares two objects using a comparator, if the result of this comparison chain has not already been determined. Annotations @Override

compare

back to summary

public <T extends @Nullable Object> ComparisonChain compare(T left, T right, Comparator<T> comparator)

Implements abstract com.google.common.collect.ComparisonChain.compare.

Doc from com.google.common.collect.ComparisonChain.compare.

Compares two objects using a comparator, if the result of this comparison chain has not already been determined.

Annotations

@Override

compare back to summary

compare	back to summary
public ComparisonChain compare(int left, int right) Implements abstract com.google.common.collect.ComparisonChain.compare. Doc from com.google.common.collect.ComparisonChain.compare. Compares two `int` values as specified by `Ints#compare`, if the result of this comparison chain has not already been determined. Annotations @Override

public ComparisonChain compare(int left, int right)

Implements abstract com.google.common.collect.ComparisonChain.compare.

Doc from com.google.common.collect.ComparisonChain.compare.

Compares two int values as specified by Ints#compare, if the result of this comparison chain has not already been determined.

Annotations

@Override

compare back to summary

compare	back to summary
public ComparisonChain compare(long left, long right) Implements abstract com.google.common.collect.ComparisonChain.compare. Doc from com.google.common.collect.ComparisonChain.compare. Compares two `long` values as specified by `Longs#compare`, if the result of this comparison chain has not already been determined. Annotations @Override

public ComparisonChain compare(long left, long right)

Implements abstract com.google.common.collect.ComparisonChain.compare.

Doc from com.google.common.collect.ComparisonChain.compare.

Compares two long values as specified by Longs#compare, if the result of this comparison chain has not already been determined.

Annotations

@Override

compare back to summary

compare	back to summary
public ComparisonChain compare(float left, float right) Implements abstract com.google.common.collect.ComparisonChain.compare. Doc from com.google.common.collect.ComparisonChain.compare. Compares two `float` values as specified by `Float#compare`, if the result of this comparison chain has not already been determined. Annotations @Override

public ComparisonChain compare(float left, float right)

Implements abstract com.google.common.collect.ComparisonChain.compare.

Doc from com.google.common.collect.ComparisonChain.compare.

Compares two float values as specified by Float#compare, if the result of this comparison chain has not already been determined.

Annotations

@Override

compare back to summary

compare	back to summary
public ComparisonChain compare(double left, double right) Implements abstract com.google.common.collect.ComparisonChain.compare. Doc from com.google.common.collect.ComparisonChain.compare. Compares two `double` values as specified by `Double#compare`, if the result of this comparison chain has not already been determined. Annotations @Override

public ComparisonChain compare(double left, double right)

Implements abstract com.google.common.collect.ComparisonChain.compare.

Doc from com.google.common.collect.ComparisonChain.compare.

Compares two double values as specified by Double#compare, if the result of this comparison chain has not already been determined.

Annotations

@Override

compareFalseFirst back to summary

compareFalseFirst	back to summary
public ComparisonChain compareFalseFirst(boolean left, boolean right) Implements abstract com.google.common.collect.ComparisonChain.compareFalseFirst. Doc from com.google.common.collect.ComparisonChain.compareFalseFirst. Compares two `boolean` values, considering `false` to be less than `true`, 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()`) Annotations @Override

public ComparisonChain compareFalseFirst(boolean left, boolean right)

Implements abstract com.google.common.collect.ComparisonChain.compareFalseFirst.

Doc from com.google.common.collect.ComparisonChain.compareFalseFirst.

Compares two boolean values, considering false to be less than true, 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())

Annotations

@Override

compareTrueFirst back to summary

compareTrueFirst	back to summary
public ComparisonChain compareTrueFirst(boolean left, boolean right) Implements abstract com.google.common.collect.ComparisonChain.compareTrueFirst. Doc from com.google.common.collect.ComparisonChain.compareTrueFirst. Compares two `boolean` values, considering `true` to be less than `false`, 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()`) Annotations @Override

public ComparisonChain compareTrueFirst(boolean left, boolean right)

Implements abstract com.google.common.collect.ComparisonChain.compareTrueFirst.

Doc from com.google.common.collect.ComparisonChain.compareTrueFirst.

Compares two boolean values, considering true to be less than false, 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())

Annotations

@Override

result	back to summary
public int result() Implements abstract com.google.common.collect.ComparisonChain.result. Doc from com.google.common.collect.ComparisonChain.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. Annotations @Override

result

back to summary

public int result()

Implements abstract com.google.common.collect.ComparisonChain.result.

Doc from com.google.common.collect.ComparisonChain.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.

Annotations

@Override

public abstract Class ComparisonChain

Java 8+ equivalents

Nested and Inner Type Summary

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

private final Class ComparisonChain.InactiveComparisonChain

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail