Class Comparators


  • @Beta
    @GwtCompatible
    public final class Comparators
    extends java.lang.Object
    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.

    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 of Optional values which treats Optional.empty() as less than all other values, and orders the rest using valueComparator on the contained value.
      static <T> java.util.Comparator<java.util.Optional<T>> emptiesLast​(java.util.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.
      static <T> java.util.stream.Collector<T,​?,​java.util.List<T>> greatest​(int k, java.util.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.
      static <T> boolean isInOrder​(java.lang.Iterable<? extends T> iterable, java.util.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.
      static <T> boolean isInStrictOrder​(java.lang.Iterable<? extends T> iterable, java.util.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.
      static <T> java.util.stream.Collector<T,​?,​java.util.List<T>> least​(int k, java.util.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.
      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.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Constructor Detail

      • Comparators

        private Comparators()
    • Method Detail

      • lexicographical

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

      • isInOrder

        public static <T> boolean isInOrder​(java.lang.Iterable<? extends T> iterable,
                                            java.util.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.
      • isInStrictOrder

        public static <T> boolean isInStrictOrder​(java.lang.Iterable<? extends T> iterable,
                                                  java.util.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.
      • least

        public static <T> java.util.stream.Collector<T,​?,​java.util.List<T>> least​(int k,
                                                                                              java.util.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.

        Throws:
        java.lang.IllegalArgumentException - if k < 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 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.

        Throws:
        java.lang.IllegalArgumentException - if k < 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 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
      • emptiesLast

        @Beta
        public static <T> java.util.Comparator<java.util.Optional<T>> emptiesLast​(java.util.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