Class Comparators
 java.lang.Object

 com.google.common.collect.Comparators

@GwtCompatible public final class Comparators extends Object
Provides static methods for working withComparator
instances. For many other helpful comparator utilities, see eitherComparator
itself (for Java 8 or later), orcom.google.common.collect.Ordering
(otherwise).Relationship to
Ordering
In light of the significant enhancements to
Comparator
in Java 8, the overwhelming majority of usages ofOrdering
can be written using only builtin JDK APIs. This class is intended to "fill the gap" and provide those features ofOrdering
not already provided by the JDK. Since:
 21.0
 Author:
 Louis Wasserman


Method Summary
All Methods Static Methods Concrete Methods Modifier and Type Method Description static <T> Comparator<Optional<T>>
emptiesFirst(Comparator<? super T> valueComparator)
Returns a comparator ofOptional
values which treatsOptional.empty()
as less than all other values, and orders the rest usingvalueComparator
on the contained value.static <T> Comparator<Optional<T>>
emptiesLast(Comparator<? super T> valueComparator)
Returns a comparator ofOptional
values which treatsOptional.empty()
as greater than all other values, and orders the rest usingvalueComparator
on the contained value.static <T extends @Nullable Object>
Collector<T,?,List<T>>greatest(int k, Comparator<? super T> comparator)
Returns aCollector
that returns thek
greatest (relative to the specifiedComparator
) input elements, in descending order, as an unmodifiableList
.static <T extends @Nullable Object>
booleanisInOrder(Iterable<? extends T> iterable, Comparator<T> comparator)
Returnstrue
if each element initerable
after the first is greater than or equal to the element that preceded it, according to the specified comparator.static <T extends @Nullable Object>
booleanisInStrictOrder(Iterable<? extends T> iterable, Comparator<T> comparator)
Returnstrue
if each element initerable
after the first is strictly greater than the element that preceded it, according to the specified comparator.static <T extends @Nullable Object>
Collector<T,?,List<T>>least(int k, Comparator<? super T> comparator)
Returns aCollector
that returns thek
smallest (relative to the specifiedComparator
) input elements, in ascending order, as an unmodifiableList
.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.static <T extends Comparable<? super T>>
Tmax(T a, T b)
Returns the maximum of the two values.static <T extends @Nullable Object>
Tmax(T a, T b, Comparator<T> comparator)
Returns the maximum of the two values, according to the given comparator.static <T extends Comparable<? super T>>
Tmin(T a, T b)
Returns the minimum of the two values.static <T extends @Nullable Object>
Tmin(T a, T b, Comparator<T> comparator)
Returns the minimum of the two values, according to the given comparator.



Method Detail

lexicographical
@Beta 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 tolexicographical(Collections.reverseOrder(comparator))
(consider how each would order[1]
and[1, 1]
).

isInOrder
@Beta public static <T extends @Nullable Object> boolean isInOrder(Iterable<? extends T> iterable, Comparator<T> comparator)
Returnstrue
if each element initerable
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.

isInStrictOrder
@Beta public static <T extends @Nullable Object> boolean isInStrictOrder(Iterable<? extends T> iterable, Comparator<T> comparator)
Returnstrue
if each element initerable
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.

least
public static <T extends @Nullable Object> Collector<T,?,List<T>> least(int k, Comparator<? super T> comparator)
Returns aCollector
that returns thek
smallest (relative to the specifiedComparator
) input elements, in ascending order, as an unmodifiableList
. 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) (worstcase 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. Throws:
IllegalArgumentException
 ifk < 0
 Since:
 22.0

greatest
public static <T extends @Nullable Object> Collector<T,?,List<T>> greatest(int k, Comparator<? super T> comparator)
Returns aCollector
that returns thek
greatest (relative to the specifiedComparator
) input elements, in descending order, as an unmodifiableList
. 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) (worstcase 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. Throws:
IllegalArgumentException
 ifk < 0
 Since:
 22.0

emptiesFirst
@Beta public static <T> Comparator<Optional<T>> emptiesFirst(Comparator<? super T> valueComparator)
Returns a comparator ofOptional
values which treatsOptional.empty()
as less than all other values, and orders the rest usingvalueComparator
on the contained value. Since:
 22.0

emptiesLast
@Beta public static <T> Comparator<Optional<T>> emptiesLast(Comparator<? super T> valueComparator)
Returns a comparator ofOptional
values which treatsOptional.empty()
as greater than all other values, and orders the rest usingvalueComparator
on the contained value. Since:
 22.0

min
@Beta 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 onComparators
. Parameters:
a
 first value to compare, returned if less than or equal to b.b
 second value to compare. Throws:
ClassCastException
 if the parameters are not mutually comparable. Since:
 30.0

min
@Beta 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 onComparators
. Parameters:
a
 first value to compare, returned if less than or equal to bb
 second value to compare. Throws:
ClassCastException
 if the parameters are not mutually comparable using the given comparator. Since:
 30.0

max
@Beta 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 onComparators
. Parameters:
a
 first value to compare, returned if greater than or equal to b.b
 second value to compare. Throws:
ClassCastException
 if the parameters are not mutually comparable. Since:
 30.0

max
@Beta 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 onComparators
. Parameters:
a
 first value to compare, returned if greater than or equal to b.b
 second value to compare. Throws:
ClassCastException
 if the parameters are not mutually comparable using the given comparator. Since:
 30.0

