Class Ordering<T>

    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      static Ordering<java.lang.Object> allEqual()
      Returns an ordering which treats all values as equal, indicating "no ordering." Passing this ordering to any stable sort algorithm results in no change to the order of elements.
      static Ordering<java.lang.Object> arbitrary()
      Returns an arbitrary ordering over all objects, for which compare(a, b) == 0 implies a == b (identity equality).
      int binarySearch​(java.util.List<? extends T> sortedList, T key)
      Searches sortedList for key using the binary search algorithm.
      abstract int compare​(T left, T right)  
      static <T> Ordering<T> compound​(java.lang.Iterable<? extends java.util.Comparator<? super T>> comparators)
      Returns an ordering which tries each given comparator in order until a non-zero result is found, returning that result, and returning zero only if all comparators return zero.
      <U extends T>
      Ordering<U>
      compound​(java.util.Comparator<? super U> secondaryComparator)
      Returns an ordering which first uses the ordering this, but which in the event of a "tie", then delegates to secondaryComparator.
      static <T> Ordering<T> explicit​(java.util.List<T> valuesInOrder)
      Returns an ordering that compares objects according to the order in which they appear in the given list.
      static <T> Ordering<T> explicit​(T leastValue, T... remainingValuesInOrder)
      Returns an ordering that compares objects according to the order in which they are given to this method.
      static <T> Ordering<T> from​(Ordering<T> ordering)
      Deprecated.
      no need to use this
      static <T> Ordering<T> from​(java.util.Comparator<T> comparator)
      Returns an ordering based on an existing comparator instance.
      <E extends T>
      java.util.List<E>
      greatestOf​(java.lang.Iterable<E> iterable, int k)
      Returns the k greatest elements of the given iterable according to this ordering, in order from greatest to least.
      <E extends T>
      java.util.List<E>
      greatestOf​(java.util.Iterator<E> iterator, int k)
      Returns the k greatest elements from the given iterator according to this ordering, in order from greatest to least.
      <E extends T>
      ImmutableList<E>
      immutableSortedCopy​(java.lang.Iterable<E> iterable)
      Returns an immutable copy of the given iterable sorted by this ordering.
      boolean isOrdered​(java.lang.Iterable<? extends T> iterable)
      Returns true if each element in iterable after the first is greater than or equal to the element that preceded it, according to this ordering.
      boolean isStrictlyOrdered​(java.lang.Iterable<? extends T> iterable)
      Returns true if each element in iterable after the first is strictly greater than the element that preceded it, according to this ordering.
      <E extends T>
      java.util.List<E>
      leastOf​(java.lang.Iterable<E> iterable, int k)
      Returns the k least elements of the given iterable according to this ordering, in order from least to greatest.
      <E extends T>
      java.util.List<E>
      leastOf​(java.util.Iterator<E> elements, int k)
      Returns the k least elements from the given iterator according to this ordering, in order from least to greatest.
      <S extends T>
      Ordering<java.lang.Iterable<S>>
      lexicographical()
      Returns a new ordering which sorts iterables by comparing corresponding elements pairwise until a nonzero result is found; imposes "dictionary order".
      <E extends T>
      E
      max​(E a, E b)
      Returns the greater of the two values according to this ordering.
      <E extends T>
      E
      max​(E a, E b, E c, E... rest)
      Returns the greatest of the specified values according to this ordering.
      <E extends T>
      E
      max​(java.lang.Iterable<E> iterable)
      Returns the greatest of the specified values according to this ordering.
      <E extends T>
      E
      max​(java.util.Iterator<E> iterator)
      Returns the greatest of the specified values according to this ordering.
      <E extends T>
      E
      min​(E a, E b)
      Returns the lesser of the two values according to this ordering.
      <E extends T>
      E
      min​(E a, E b, E c, E... rest)
      Returns the least of the specified values according to this ordering.
      <E extends T>
      E
      min​(java.lang.Iterable<E> iterable)
      Returns the least of the specified values according to this ordering.
      <E extends T>
      E
      min​(java.util.Iterator<E> iterator)
      Returns the least of the specified values according to this ordering.
      static <C extends java.lang.Comparable>
      Ordering<C>
      natural()
      Returns a serializable ordering that uses the natural order of the values.
      <S extends T>
      Ordering<S>
      nullsFirst()
      Returns an ordering that treats null as less than all other values and uses this to compare non-null values.
      <S extends T>
      Ordering<S>
      nullsLast()
      Returns an ordering that treats null as greater than all other values and uses this ordering to compare non-null values.
      <F> Ordering<F> onResultOf​(Function<F,​? extends T> function)
      Returns a new ordering on F which orders elements by first applying a function to them, then comparing those results using this.
      <S extends T>
      Ordering<S>
      reverse()
      Returns the reverse of this ordering; the Ordering equivalent to Collections.reverseOrder(Comparator).
      <E extends T>
      java.util.List<E>
      sortedCopy​(java.lang.Iterable<E> iterable)
      Returns a copy of the given iterable sorted by this ordering.
      static Ordering<java.lang.Object> usingToString()
      Returns an ordering that compares objects by the natural ordering of their string representations as returned by toString().
      • Methods inherited from class java.lang.Object

        equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
      • Methods inherited from interface java.util.Comparator

        equals, reversed, thenComparing, thenComparing, thenComparing, thenComparingDouble, thenComparingInt, thenComparingLong
    • Method Detail

      • natural

        @GwtCompatible(serializable=true)
        public static <C extends java.lang.Comparable> Ordering<C> natural()
        Returns a serializable ordering that uses the natural order of the values. The ordering throws a NullPointerException when passed a null parameter.

        The type specification is <C extends Comparable>, instead of the technically correct <C extends Comparable<? super C>>, to support legacy types from before Java 5.

      • from

        @GwtCompatible(serializable=true)
        public static <T> Ordering<T> from​(java.util.Comparator<T> comparator)
        Returns an ordering based on an existing comparator instance. Note that there's no need to create a new comparator just to pass it in here; simply subclass Ordering and implement its compare method directly instead.
        Parameters:
        comparator - the comparator that defines the order
        Returns:
        comparator itself if it is already an Ordering; otherwise an ordering that wraps that comparator
      • explicit

        @GwtCompatible(serializable=true)
        public static <T> Ordering<T> explicit​(java.util.List<T> valuesInOrder)
        Returns an ordering that compares objects according to the order in which they appear in the given list. Only objects present in the list (according to Object.equals(java.lang.Object)) may be compared. This comparator imposes a "partial ordering" over the type T. Subsequent changes to the valuesInOrder list will have no effect on the returned comparator. Null values in the list are not supported.

        The returned comparator throws an ClassCastException when it receives an input parameter that isn't among the provided values.

        The generated comparator is serializable if all the provided values are serializable.

        Parameters:
        valuesInOrder - the values that the returned comparator will be able to compare, in the order the comparator should induce
        Returns:
        the comparator described above
        Throws:
        java.lang.NullPointerException - if any of the provided values is null
        java.lang.IllegalArgumentException - if valuesInOrder contains any duplicate values (according to Object.equals(java.lang.Object))
      • explicit

        @GwtCompatible(serializable=true)
        public static <T> Ordering<T> explicit​(T leastValue,
                                               T... remainingValuesInOrder)
        Returns an ordering that compares objects according to the order in which they are given to this method. Only objects present in the argument list (according to Object.equals(java.lang.Object)) may be compared. This comparator imposes a "partial ordering" over the type T. Null values in the argument list are not supported.

        The returned comparator throws a ClassCastException when it receives an input parameter that isn't among the provided values.

        The generated comparator is serializable if all the provided values are serializable.

        Parameters:
        leastValue - the value which the returned comparator should consider the "least" of all values
        remainingValuesInOrder - the rest of the values that the returned comparator will be able to compare, in the order the comparator should follow
        Returns:
        the comparator described above
        Throws:
        java.lang.NullPointerException - if any of the provided values is null
        java.lang.IllegalArgumentException - if any duplicate values (according to Object.equals(Object)) are present among the method arguments
      • allEqual

        @GwtCompatible(serializable=true)
        public static Ordering<java.lang.Object> allEqual()
        Returns an ordering which treats all values as equal, indicating "no ordering." Passing this ordering to any stable sort algorithm results in no change to the order of elements. Note especially that sortedCopy(java.lang.Iterable<E>) and immutableSortedCopy(java.lang.Iterable<E>) are stable, and in the returned instance these are implemented by simply copying the source list.

        Example:

           
        
           Ordering.allEqual().nullsLast().sortedCopy(
               asList(t, null, e, s, null, t, null))

        Assuming t, e and s are non-null, this returns [t, e, s, t, null, null, null] regardlesss of the true comparison order of those three values (which might not even implement Comparable at all).

        Warning: by definition, this comparator is not consistent with equals (as defined here). Avoid its use in APIs, such as TreeSet(Comparator), where such consistency is expected.

        The returned comparator is serializable.

      • usingToString

        @GwtCompatible(serializable=true)
        public static Ordering<java.lang.Object> usingToString()
        Returns an ordering that compares objects by the natural ordering of their string representations as returned by toString(). It does not support null values.

        The comparator is serializable.

      • arbitrary

        public static Ordering<java.lang.Object> arbitrary()
        Returns an arbitrary ordering over all objects, for which compare(a, b) == 0 implies a == b (identity equality). There is no meaning whatsoever to the order imposed, but it is constant for the life of the VM.

        Because the ordering is identity-based, it is not "consistent with Object.equals(Object)" as defined by Comparator. Use caution when building a SortedSet or SortedMap from it, as the resulting collection will not behave exactly according to spec.

        This ordering is not serializable, as its implementation relies on System.identityHashCode(Object), so its behavior cannot be preserved across serialization.

        Since:
        2.0
      • reverse

        @GwtCompatible(serializable=true)
        public <S extends TOrdering<S> reverse()
        Returns the reverse of this ordering; the Ordering equivalent to Collections.reverseOrder(Comparator).
      • nullsFirst

        @GwtCompatible(serializable=true)
        public <S extends TOrdering<S> nullsFirst()
        Returns an ordering that treats null as less than all other values and uses this to compare non-null values.
      • nullsLast

        @GwtCompatible(serializable=true)
        public <S extends TOrdering<S> nullsLast()
        Returns an ordering that treats null as greater than all other values and uses this ordering to compare non-null values.
      • onResultOf

        @GwtCompatible(serializable=true)
        public <F> Ordering<F> onResultOf​(Function<F,​? extends T> function)
        Returns a new ordering on F which orders elements by first applying a function to them, then comparing those results using this. For example, to compare objects by their string forms, in a case-insensitive manner, use:
           
        
           Ordering.from(String.CASE_INSENSITIVE_ORDER)
               .onResultOf(Functions.toStringFunction())
      • compound

        @GwtCompatible(serializable=true)
        public <U extends TOrdering<U> compound​(java.util.Comparator<? super U> secondaryComparator)
        Returns an ordering which first uses the ordering this, but which in the event of a "tie", then delegates to secondaryComparator. For example, to sort a bug list first by status and second by priority, you might use byStatus.compound(byPriority). For a compound ordering with three or more components, simply chain multiple calls to this method.

        An ordering produced by this method, or a chain of calls to this method, is equivalent to one created using compound(Iterable) on the same component comparators.

      • compound

        @GwtCompatible(serializable=true)
        public static <T> Ordering<T> compound​(java.lang.Iterable<? extends java.util.Comparator<? super T>> comparators)
        Returns an ordering which tries each given comparator in order until a non-zero result is found, returning that result, and returning zero only if all comparators return zero. The returned ordering is based on the state of the comparators iterable at the time it was provided to this method.

        The returned ordering is equivalent to that produced using Ordering.from(comp1).compound(comp2).compound(comp3) . . ..

        Warning: Supplying an argument with undefined iteration order, such as a HashSet, will produce non-deterministic results.

        Parameters:
        comparators - the comparators to try in order
      • lexicographical

        @GwtCompatible(serializable=true)
        public <S extends TOrdering<java.lang.Iterable<S>> lexicographical()
        Returns a new ordering 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 ordering.lexicographical().reverse() is not equivalent to ordering.reverse().lexicographical() (consider how each would order [1] and [1, 1]).

        Since:
        2.0
      • compare

        public abstract int compare​(@Nullable
                                    T left,
                                    @Nullable
                                    T right)
        Specified by:
        compare in interface java.util.Comparator<T>
      • min

        public <E extends T> E min​(java.util.Iterator<E> iterator)
        Returns the least of the specified values according to this ordering. If there are multiple least values, the first of those is returned. The iterator will be left exhausted: its hasNext() method will return false.
        Parameters:
        iterator - the iterator whose minimum element is to be determined
        Throws:
        java.util.NoSuchElementException - if iterator is empty
        java.lang.ClassCastException - if the parameters are not mutually comparable under this ordering.
        Since:
        11.0
      • min

        public <E extends T> E min​(java.lang.Iterable<E> iterable)
        Returns the least of the specified values according to this ordering. If there are multiple least values, the first of those is returned.
        Parameters:
        iterable - the iterable whose minimum element is to be determined
        Throws:
        java.util.NoSuchElementException - if iterable is empty
        java.lang.ClassCastException - if the parameters are not mutually comparable under this ordering.
      • min

        public <E extends T> E min​(@Nullable
                                   E a,
                                   @Nullable
                                   E b)
        Returns the lesser of the two values according to this ordering. If the values compare as 0, the first is returned.

        Implementation note: this method is invoked by the default implementations of the other min overloads, so overriding it will affect their behavior.

        Parameters:
        a - value to compare, returned if less than or equal to b.
        b - value to compare.
        Throws:
        java.lang.ClassCastException - if the parameters are not mutually comparable under this ordering.
      • min

        public <E extends T> E min​(@Nullable
                                   E a,
                                   @Nullable
                                   E b,
                                   @Nullable
                                   E c,
                                   E... rest)
        Returns the least of the specified values according to this ordering. If there are multiple least values, the first of those is returned.
        Parameters:
        a - value to compare, returned if less than or equal to the rest.
        b - value to compare
        c - value to compare
        rest - values to compare
        Throws:
        java.lang.ClassCastException - if the parameters are not mutually comparable under this ordering.
      • max

        public <E extends T> E max​(java.util.Iterator<E> iterator)
        Returns the greatest of the specified values according to this ordering. If there are multiple greatest values, the first of those is returned. The iterator will be left exhausted: its hasNext() method will return false.
        Parameters:
        iterator - the iterator whose maximum element is to be determined
        Throws:
        java.util.NoSuchElementException - if iterator is empty
        java.lang.ClassCastException - if the parameters are not mutually comparable under this ordering.
        Since:
        11.0
      • max

        public <E extends T> E max​(java.lang.Iterable<E> iterable)
        Returns the greatest of the specified values according to this ordering. If there are multiple greatest values, the first of those is returned.
        Parameters:
        iterable - the iterable whose maximum element is to be determined
        Throws:
        java.util.NoSuchElementException - if iterable is empty
        java.lang.ClassCastException - if the parameters are not mutually comparable under this ordering.
      • max

        public <E extends T> E max​(@Nullable
                                   E a,
                                   @Nullable
                                   E b)
        Returns the greater of the two values according to this ordering. If the values compare as 0, the first is returned.

        Implementation note: this method is invoked by the default implementations of the other max overloads, so overriding it will affect their behavior.

        Parameters:
        a - value to compare, returned if greater than or equal to b.
        b - value to compare.
        Throws:
        java.lang.ClassCastException - if the parameters are not mutually comparable under this ordering.
      • max

        public <E extends T> E max​(@Nullable
                                   E a,
                                   @Nullable
                                   E b,
                                   @Nullable
                                   E c,
                                   E... rest)
        Returns the greatest of the specified values according to this ordering. If there are multiple greatest values, the first of those is returned.
        Parameters:
        a - value to compare, returned if greater than or equal to the rest.
        b - value to compare
        c - value to compare
        rest - values to compare
        Throws:
        java.lang.ClassCastException - if the parameters are not mutually comparable under this ordering.
      • leastOf

        public <E extends T> java.util.List<E> leastOf​(java.lang.Iterable<E> iterable,
                                                       int k)
        Returns the k least elements of the given iterable according to this ordering, in order from least to greatest. If there are fewer than k elements present, all will be included.

        The implementation does not necessarily use a stable sorting algorithm; when multiple elements are equivalent, it is undefined which will come first.

        Returns:
        an immutable RandomAccess list of the k least elements in ascending order
        Throws:
        java.lang.IllegalArgumentException - if k is negative
        Since:
        8.0
      • leastOf

        public <E extends T> java.util.List<E> leastOf​(java.util.Iterator<E> elements,
                                                       int k)
        Returns the k least elements from the given iterator according to this ordering, in order from least to greatest. If there are fewer than k elements present, all will be included.

        The implementation does not necessarily use a stable sorting algorithm; when multiple elements are equivalent, it is undefined which will come first.

        Returns:
        an immutable RandomAccess list of the k least elements in ascending order
        Throws:
        java.lang.IllegalArgumentException - if k is negative
        Since:
        14.0
      • greatestOf

        public <E extends T> java.util.List<E> greatestOf​(java.lang.Iterable<E> iterable,
                                                          int k)
        Returns the k greatest elements of the given iterable according to this ordering, in order from greatest to least. If there are fewer than k elements present, all will be included.

        The implementation does not necessarily use a stable sorting algorithm; when multiple elements are equivalent, it is undefined which will come first.

        Returns:
        an immutable RandomAccess list of the k greatest elements in descending order
        Throws:
        java.lang.IllegalArgumentException - if k is negative
        Since:
        8.0
      • greatestOf

        public <E extends T> java.util.List<E> greatestOf​(java.util.Iterator<E> iterator,
                                                          int k)
        Returns the k greatest elements from the given iterator according to this ordering, in order from greatest to least. If there are fewer than k elements present, all will be included.

        The implementation does not necessarily use a stable sorting algorithm; when multiple elements are equivalent, it is undefined which will come first.

        Returns:
        an immutable RandomAccess list of the k greatest elements in descending order
        Throws:
        java.lang.IllegalArgumentException - if k is negative
        Since:
        14.0
      • sortedCopy

        public <E extends T> java.util.List<E> sortedCopy​(java.lang.Iterable<E> iterable)
        Returns a copy of the given iterable sorted by this ordering. The input is not modified. The returned list is modifiable, serializable, and has random access.

        Unlike Sets.newTreeSet(Iterable), this method does not discard elements that are duplicates according to the comparator. The sort performed is stable, meaning that such elements will appear in the resulting list in the same order they appeared in the input.

        Parameters:
        iterable - the elements to be copied and sorted
        Returns:
        a new list containing the given elements in sorted order
      • immutableSortedCopy

        public <E extends TImmutableList<E> immutableSortedCopy​(java.lang.Iterable<E> iterable)
        Returns an immutable copy of the given iterable sorted by this ordering. The input is not modified.

        Unlike Sets.newTreeSet(Iterable), this method does not discard elements that are duplicates according to the comparator. The sort performed is stable, meaning that such elements will appear in the resulting list in the same order they appeared in the input.

        Parameters:
        iterable - the elements to be copied and sorted
        Returns:
        a new immutable list containing the given elements in sorted order
        Throws:
        java.lang.NullPointerException - if iterable or any of its elements is null
        Since:
        3.0
      • isOrdered

        public boolean isOrdered​(java.lang.Iterable<? extends T> iterable)
        Returns true if each element in iterable after the first is greater than or equal to the element that preceded it, according to this ordering. Note that this is always true when the iterable has fewer than two elements.
      • isStrictlyOrdered

        public boolean isStrictlyOrdered​(java.lang.Iterable<? extends T> iterable)
        Returns true if each element in iterable after the first is strictly greater than the element that preceded it, according to this ordering. Note that this is always true when the iterable has fewer than two elements.
      • binarySearch

        public int binarySearch​(java.util.List<? extends T> sortedList,
                                @Nullable
                                T key)
        Searches sortedList for key using the binary search algorithm. The list must be sorted using this ordering.
        Parameters:
        sortedList - the list to be searched
        key - the key to be searched for