Class Comparators
- java.lang.Object
-
- com.google.common.collect.Comparators
-
@GwtCompatible public final class Comparators extends java.lang.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 built-in JDK APIs. This class is intended to "fill the gap" and provide those features ofOrdering
not already provided by the JDK.- Since:
- 21.0
-
-
Constructor Summary
Constructors Modifier Constructor Description private
Comparators()
-
Method Summary
All Methods Static Methods Concrete Methods Modifier and Type Method Description static <T> java.util.Comparator<java.util.Optional<T>>
emptiesFirst(java.util.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> java.util.Comparator<java.util.Optional<T>>
emptiesLast(java.util.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> java.util.stream.Collector<T,?,java.util.List<T>>
greatest(int k, java.util.Comparator<? super T> comparator)
Returns aCollector
that returns thek
greatest (relative to the specifiedComparator
) input elements, in descending order, as an unmodifiableList
.static <T> boolean
isInOrder(java.lang.Iterable<? extends T> iterable, java.util.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> boolean
isInStrictOrder(java.lang.Iterable<? extends T> iterable, java.util.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> java.util.stream.Collector<T,?,java.util.List<T>>
least(int k, java.util.Comparator<? super T> comparator)
Returns aCollector
that returns thek
smallest (relative to the specifiedComparator
) input elements, in ascending order, as an unmodifiableList
.static <T,S extends T>
java.util.Comparator<java.lang.Iterable<S>>lexicographical(java.util.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.
-
-
-
Method Detail
-
lexicographical
@Beta public static <T,S extends T> java.util.Comparator<java.lang.Iterable<S>> lexicographical(java.util.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> boolean isInOrder(java.lang.Iterable<? extends T> iterable, java.util.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> boolean isInStrictOrder(java.lang.Iterable<? extends T> iterable, java.util.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> java.util.stream.Collector<T,?,java.util.List<T>> least(int k, java.util.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) (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.- Throws:
java.lang.IllegalArgumentException
- ifk < 0
- Since:
- 22.0
-
greatest
public static <T> java.util.stream.Collector<T,?,java.util.List<T>> greatest(int k, java.util.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) (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.- Throws:
java.lang.IllegalArgumentException
- ifk < 0
- Since:
- 22.0
-
emptiesFirst
@Beta public static <T> java.util.Comparator<java.util.Optional<T>> emptiesFirst(java.util.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> java.util.Comparator<java.util.Optional<T>> emptiesLast(java.util.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
-
-