Top Description Constructors Methods
com.google.common.collect

public final Class Comparators

extends Object
Class Inheritance
Annotations
@GwtCompatible
@ElementTypesAreNonnullByDefault
Static Imports
com.google.common.base.Preconditions.checkNotNull, com.google.common.collect.CollectPreconditions.checkNonnegative
Provides static methods for working with Comparator instances. For many other helpful comparator utilities, see either Comparator itself (for Java 8 or later), or com.google.common.collect.Ordering (otherwise).

Relationship to Ordering

In light of the significant enhancements to Comparator in Java 8, the overwhelming majority of usages of Ordering can be written using only built-in JDK APIs. This class is intended to "fill the gap" and provide those features of Ordering not already provided by the JDK.

Author
Louis Wasserman
Since
21.0

Constructor Summary

AccessConstructor and Description
private
Comparators()

Method Summary

Modifier and TypeMethod and Description
public static <T> Comparator<Optional<T>>
emptiesFirst(Comparator<? super T> valueComparator)

Returns a comparator of Optional values which treats Optional#empty as less than all other values, and orders the rest using valueComparator on the contained value.

public static <T> Comparator<Optional<T>>
emptiesLast(Comparator<? super T> valueComparator)

Returns a comparator of Optional values which treats Optional#empty as greater than all other values, and orders the rest using valueComparator on the contained value.

public static <T extends @Nullable Object> Collector<T, ?, List<T>>
greatest(int k, Comparator<? super T> comparator)

Returns a Collector that returns the k greatest (relative to the specified Comparator) input elements, in descending order, as an unmodifiable List.

public static <T extends @Nullable Object> boolean
isInOrder(Iterable<? extends T> iterable, Comparator<T> comparator)

Returns true if each element in iterable after the first is greater than or equal to the element that preceded it, according to the specified comparator.

public static <T extends @Nullable Object> boolean
isInStrictOrder(Iterable<? extends T> iterable, Comparator<T> comparator)

Returns true if each element in iterable after the first is strictly greater than the element that preceded it, according to the specified comparator.

public static <T extends @Nullable Object> Collector<T, ?, List<T>>
least(int k, Comparator<? super T> comparator)

Returns a Collector that returns the k smallest (relative to the specified Comparator) input elements, in ascending order, as an unmodifiable List.

public static <T extends @Nullable Object, S extends T> Comparator<Iterable<S>>
lexicographical(Comparator<T> comparator)

Returns a new comparator which sorts iterables by comparing corresponding elements pairwise until a nonzero result is found; imposes "dictionary order." If the end of one iterable is reached, but not the other, the shorter iterable is considered to be less than the longer one.

public static <T extends Comparable<? super T>> T
max(T
first value to compare, returned if greater than or equal to b.
a, T
second value to compare.
b)

Returns the maximum of the two values.

public static <T extends @Nullable Object> T
max(T
first value to compare, returned if greater than or equal to b.
a, T
second value to compare.
b, Comparator<T> comparator)

Returns the maximum of the two values, according to the given comparator.

public static <T extends Comparable<? super T>> T
min(T
first value to compare, returned if less than or equal to b.
a, T
second value to compare.
b)

Returns the minimum of the two values.

public static <T extends @Nullable Object> T
min(T
first value to compare, returned if less than or equal to b
a, T
second value to compare.
b, Comparator<T> comparator)

Returns the minimum of the two values, according to the given comparator.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Constructor Detail

Comparatorsback to summary
private Comparators()

Method Detail

emptiesFirstback to summary
public static <T> Comparator<Optional<T>> emptiesFirst(Comparator<? super T> valueComparator)

Returns a comparator of Optional values which treats Optional#empty as less than all other values, and orders the rest using valueComparator on the contained value.

Since
22.0
emptiesLastback to summary
public static <T> Comparator<Optional<T>> emptiesLast(Comparator<? super T> valueComparator)

Returns a comparator of Optional values which treats Optional#empty as greater than all other values, and orders the rest using valueComparator on the contained value.

Since
22.0
greatestback to summary
public static <T extends @Nullable Object> Collector<T, ?, List<T>> greatest(int k, Comparator<? super T> comparator)

Returns a Collector that returns the k greatest (relative to the specified Comparator) input elements, in descending order, as an unmodifiable List. Ties are broken arbitrarily.

For example: 

Stream.of("foo", "quux", "banana", "elephant")
    .collect(greatest(2, comparingInt(String::length)))
// returns {"elephant", "banana"}

This Collector uses O(k) memory and takes expected time O(n) (worst-case O(n log k)), as opposed to e.g. Stream.sorted(comparator.reversed()).limit(k), which currently takes O(n log n) time and O(n) space.

Exceptions
IllegalArgumentException:
if k < 0
Since
22.0
isInOrderback to summary
public static <T extends @Nullable Object> boolean isInOrder(Iterable<? extends T> iterable, Comparator<T> comparator)

Returns true if each element in iterable after the first is greater than or equal to the element that preceded it, according to the specified comparator. Note that this is always true when the iterable has fewer than two elements.

isInStrictOrderback to summary
public static <T extends @Nullable Object> boolean isInStrictOrder(Iterable<? extends T> iterable, Comparator<T> comparator)

Returns true if each element in iterable after the first is strictly greater than the element that preceded it, according to the specified comparator. Note that this is always true when the iterable has fewer than two elements.

leastback to summary
public static <T extends @Nullable Object> Collector<T, ?, List<T>> least(int k, Comparator<? super T> comparator)

Returns a Collector that returns the k smallest (relative to the specified Comparator) input elements, in ascending order, as an unmodifiable List. Ties are broken arbitrarily.

For example: 

Stream.of("foo", "quux", "banana", "elephant")
    .collect(least(2, comparingInt(String::length)))
// returns {"foo", "quux"}

This Collector uses O(k) memory and takes expected time O(n) (worst-case O(n log k)), as opposed to e.g. Stream.sorted(comparator).limit(k), which currently takes O(n log n) time and O(n) space.

Exceptions
IllegalArgumentException:
if k < 0
Since
22.0
lexicographicalback to summary
public static <T extends @Nullable Object, S extends T> Comparator<Iterable<S>> lexicographical(Comparator<T> comparator)

Returns a new comparator which sorts iterables by comparing corresponding elements pairwise until a nonzero result is found; imposes "dictionary order." If the end of one iterable is reached, but not the other, the shorter iterable is considered to be less than the longer one. For example, a lexicographical natural ordering over integers considers [] < [1] < [1, 1] < [1, 2] < [2].

Note that Collections.reverseOrder(lexicographical(comparator)) is not equivalent to lexicographical(Collections.reverseOrder(comparator)) (consider how each would order [1] and [1, 1]).

maxback to summary
public static <T extends Comparable<? super T>> T max(T a, T b)

Returns the maximum of the two values. If the values compare as 0, the first is returned.

The recommended solution for finding the maximum of some values depends on the type of your data and the number of elements you have. Read more in the Guava User Guide article on Comparators.

Parameters
a:T

first value to compare, returned if greater than or equal to b.

b:T

second value to compare.

Exceptions
ClassCastException:
if the parameters are not mutually comparable.
Since
30.0
maxback to summary
public static <T extends @Nullable Object> T max(T a, T b, Comparator<T> comparator)

Returns the maximum of the two values, according to the given comparator. If the values compare as equal, the first is returned.

The recommended solution for finding the maximum of some values depends on the type of your data and the number of elements you have. Read more in the Guava User Guide article on Comparators.

Parameters
a:T

first value to compare, returned if greater than or equal to b.

b:T

second value to compare.

Annotations
@ParametricNullness
Exceptions
ClassCastException:
if the parameters are not mutually comparable using the given comparator.
Since
30.0
minback to summary
public static <T extends Comparable<? super T>> T min(T a, T b)

Returns the minimum of the two values. If the values compare as 0, the first is returned.

The recommended solution for finding the minimum of some values depends on the type of your data and the number of elements you have. Read more in the Guava User Guide article on Comparators.

Parameters
a:T

first value to compare, returned if less than or equal to b.

b:T

second value to compare.

Exceptions
ClassCastException:
if the parameters are not mutually comparable.
Since
30.0
minback to summary
public static <T extends @Nullable Object> T min(T a, T b, Comparator<T> comparator)

Returns the minimum of the two values, according to the given comparator. If the values compare as equal, the first is returned.

The recommended solution for finding the minimum of some values depends on the type of your data and the number of elements you have. Read more in the Guava User Guide article on Comparators.

Parameters
a:T

first value to compare, returned if less than or equal to b

b:T

second value to compare.

Annotations
@ParametricNullness
Exceptions
ClassCastException:
if the parameters are not mutually comparable using the given comparator.
Since
30.0