Ordering (Guava: Google Core Libraries for Java 21.0 API)

java.lang.Object
- com.google.common.collect.Ordering<T>

All Implemented Interfaces:

Comparator<T>
```
@GwtCompatible
public abstract class Ordering<T>
extends Object
implements Comparator<T>
```
A comparator, with additional methods to support common operations. This is an "enriched" version of Comparator for pre-Java-8 users, in the same sense that FluentIterable is an enriched Iterable for pre-Java-8 users.
Three types of methods
Like other fluent types, there are three types of methods present: methods for acquiring, chaining, and using.
Acquiring

The common ways to get an instance of Ordering are:
- Subclass it and implement compare(T, T) instead of implementing Comparator directly
- Pass a pre-existing Comparator instance to from(Comparator)
- Use the natural ordering, natural()
Chaining

Then you can use the chaining methods to get an altered version of that Ordering, including:
Using

Finally, use the resulting Ordering anywhere a Comparator is required, or use any of its special operations, such as:
Understanding complex orderings

Complex chained orderings like the following example can be challenging to understand.
```
 Ordering<Foo> ordering =
     Ordering.natural()
         .nullsFirst()
         .onResultOf(getBarFunction)
         .nullsLast();
 
```
Note that each chaining method returns a new ordering instance which is backed by the previous instance, but has the chance to act on values before handing off to that backing instance. As a result, it usually helps to read chained ordering expressions backwards. For example, when compare is called on the above ordering:
1. First, if only one Foo is null, that null value is treated as greater
2. Next, non-null Foo values are passed to getBarFunction (we will be comparing Bar values from now on)
3. Next, if only one Bar is null, that null value is treated as lesser
4. Finally, natural ordering is used (i.e. the result of Bar.compareTo(Bar) is returned)
Alas, reverse() is a little different. As you read backwards through a chain and encounter a call to reverse, continue working backwards until a result is determined, and then reverse that result.
Additional notes

Except as noted, the orderings returned by the factory methods of this class are serializable if and only if the provided instances that back them are. For example, if ordering and function can themselves be serialized, then ordering.onResultOf(function) can as well.
For Java 8 users

If you are using Java 8, this class is now obsolete (pending a few August 2016 updates). Most of its functionality is now provided by Stream and by Comparator itself, and the rest can now be found as static methods in our new Comparators class. See each method below for further instructions. Whenever possible, you should change any references of type Ordering to be of type Comparator instead. However, at this time we have no plan to deprecate this class.
Many replacements involve adopting Stream, and these changes can sometimes make your code verbose. Whenever following this advice, you should check whether Stream could be adopted more comprehensively in your code; the end result may be quite a bit simpler.
See also

See the Guava User Guide article on Ordering.
Since:

2.0

Author:

Jesse Wilson, Kevin Bourrillion

Constructor Summary

Constructors
Modifier Constructor and Description

protected Ordering()
Constructs a new instance of this class (only invokable by the subclass constructor, typically implicit).

Constructors
Modifier	Constructor and Description
`protected`	`Ordering()` Constructs a new instance of this class (only invokable by the subclass constructor, typically implicit).

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and Description
`static Ordering<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<Object>`	`arbitrary()` Returns an arbitrary ordering over all objects, for which `compare(a, b) == 0` implies `a == b` (identity equality).
`int`	`binarySearch(List<? extends T> sortedList, T key)` Deprecated. Use `Collections.binarySearch(List, Object, Comparator)` directly. This method is scheduled for deletion in June 2018.
`abstract int`	`compare(T left, T right)`
`<U extends T> Ordering<U>`	`compound(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>`	`compound(Iterable<? extends 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.
`static <T> Ordering<T>`	`explicit(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(Comparator<T> comparator)` Returns an ordering based on an existing comparator instance.
`static <T> Ordering<T>`	`from(Ordering<T> ordering)` Deprecated. no need to use this
`<E extends T> List<E>`	`greatestOf(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> List<E>`	`greatestOf(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(Iterable<E> elements)` Returns an immutable list containing `elements` sorted by this ordering.
`boolean`	`isOrdered(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(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> List<E>`	`leastOf(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> List<E>`	`leastOf(Iterator<E> iterator, 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<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(Iterable<E> iterable)` Returns the greatest of the specified values according to this ordering.
`<E extends T> E`	`max(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(Iterable<E> iterable)` Returns the least of the specified values according to this ordering.
`<E extends T> E`	`min(Iterator<E> iterator)` Returns the least of the specified values according to this ordering.
`static <C extends 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> List<E>`	`sortedCopy(Iterable<E> elements)` Returns a mutable list containing `elements` sorted by this ordering; use this only when the resulting list may need further modification, or may contain `null`.
`static Ordering<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
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface java.util.Comparator
comparing, comparing, comparingDouble, comparingInt, comparingLong, equals, naturalOrder, nullsFirst, nullsLast, reversed, reverseOrder, thenComparing, thenComparing, thenComparing, thenComparingDouble, thenComparingInt, thenComparingLong

- Constructor Detail
  - Ordering
```
protected Ordering()
```
    Constructs a new instance of this class (only invokable by the subclass constructor, typically implicit).
- Method Detail
  - natural
```
@GwtCompatible(serializable=true)
public static <C extends 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.
    Java 8 users: use Comparator.naturalOrder() instead.
  - from
```
@GwtCompatible(serializable=true)
public static <T> Ordering<T> from(Comparator<T> comparator)
```
    Returns an ordering based on an existing comparator instance. Note that it is unnecessary to create a new anonymous inner class implementing Comparator just to pass it in here. Instead, simply subclass Ordering and implement its compare method directly.
    Java 8 users: this class is now obsolete as explained in the class documentation, so there is no need to use this method.
    
    Parameters:
    
    comparator - the comparator that defines the order
    
    Returns:
    
    comparator itself if it is already an Ordering; otherwise an ordering that wraps that comparator
  - from
```
@GwtCompatible(serializable=true)
 @Deprecated
public static <T> Ordering<T> from(Ordering<T> ordering)
```
    Deprecated. no need to use this
    
    Simply returns its argument.
  - explicit
```
@GwtCompatible(serializable=true)
public static <T> Ordering<T> explicit(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 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:
    
    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:
    
    NullPointerException - if any of the provided values is null
    
    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:
    
    NullPointerException - if any of the provided values is null
    
    IllegalArgumentException - if any duplicate values (according to Object.equals(Object)) are present among the method arguments
  - allEqual
```
@GwtCompatible(serializable=true)
public static Ordering<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] regardless 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.TreeSet(Comparator), where such consistency is expected.
    The returned comparator is serializable.
    Java 8 users: Use the lambda expression (a, b) -> 0 instead (in certain cases you may need to cast that to Comparator<YourType>).
    Since:
    
    13.0
  - usingToString
```
@GwtCompatible(serializable=true)
public static Ordering<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.
    Java 8 users: Use Comparator.comparing(Object::toString) instead.
  - arbitrary
```
public static Ordering<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 T> Ordering<S> reverse()
```
    Returns the reverse of this ordering; the Ordering equivalent to Collections.reverseOrder(Comparator).
    Java 8 users: Use thisComparator.reversed() instead.
  - nullsFirst
```
@GwtCompatible(serializable=true)
public <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.
    Java 8 users: Use Comparator.nullsFirst(thisComparator) instead.
  - nullsLast
```
@GwtCompatible(serializable=true)
public <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.
    Java 8 users: Use Comparator.nullsLast(thisComparator) instead.
  - 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())
 
```
    Java 8 users: Use Comparator.comparing(function, thisComparator) instead (you can omit the comparator if it is the natural order).
  - compound
```
@GwtCompatible(serializable=true)
public <U extends T> Ordering<U> compound(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.
    Java 8 users: Use thisComparator.thenComparing(secondaryComparator) instead. Depending on what secondaryComparator is, one of the other overloads of thenComparing may be even more useful.
  - compound
```
@GwtCompatible(serializable=true)
public static <T> Ordering<T> compound(Iterable<? extends 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.
    Java 8 users: Use a chain of calls to Comparator.thenComparing(Comparator), or comparatorCollection.stream().reduce(Comparator::thenComparing).get() (if the collection might be empty, also provide a default comparator as the identity parameter to reduce).
    
    Parameters:
    
    comparators - the comparators to try in order
  - lexicographical
```
@GwtCompatible(serializable=true)
public <S extends T> Ordering<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]).
    Java 8 users: Use Comparators.lexicographical(Comparator) instead.
    
    Since:
    
    2.0
  - compare
```
public abstract int compare(@Nullable
                            T left,
                            @Nullable
                            T right)
```
    Specified by:
    
    compare in interface Comparator<T>
  - min
```
public <E extends T> E min(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.
    Java 8 users: Continue to use this method for now. After the next release of Guava, use Streams.stream(iterator).min(thisComparator).get() instead (but note that it does not guarantee which tied minimum element is returned).
    
    Parameters:
    
    iterator - the iterator whose minimum element is to be determined
    
    Throws:
    
    NoSuchElementException - if iterator is empty
    
    ClassCastException - if the parameters are not mutually comparable under this ordering.
    
    Since:
    
    11.0
  - min
```
public <E extends T> E min(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.
    Java 8 users: If iterable is a Collection, use Collections.min(collection, thisComparator) instead. Otherwise, continue to use this method for now. After the next release of Guava, use Streams.stream(iterable).min(thisComparator).get() instead. Note that these alternatives do not guarantee which tied minimum element is returned)
    
    Parameters:
    
    iterable - the iterable whose minimum element is to be determined
    
    Throws:
    
    NoSuchElementException - if iterable is empty
    
    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.
    Java 8 users: Use Collections.min(Arrays.asList(a, b), thisComparator) instead (but note that it does not guarantee which tied maximum element is returned).
    
    Parameters:
    
    a - value to compare, returned if less than or equal to b.
    
    b - value to compare.
    
    Throws:
    
    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.
    Java 8 users: Use Collections.min(Arrays.asList(a, b, c...), thisComparator) instead (but note that it does not guarantee which tied maximum element 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:
    
    ClassCastException - if the parameters are not mutually comparable under this ordering.
  - max
```
public <E extends T> E max(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.
    Java 8 users: Continue to use this method for now. After the next release of Guava, use Streams.stream(iterator).max(thisComparator).get() instead (but note that it does not guarantee which tied maximum element is returned).
    
    Parameters:
    
    iterator - the iterator whose maximum element is to be determined
    
    Throws:
    
    NoSuchElementException - if iterator is empty
    
    ClassCastException - if the parameters are not mutually comparable under this ordering.
    
    Since:
    
    11.0
  - max
```
public <E extends T> E max(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.
    Java 8 users: If iterable is a Collection, use Collections.max(collection, thisComparator) instead. Otherwise, continue to use this method for now. After the next release of Guava, use Streams.stream(iterable).max(thisComparator).get() instead. Note that these alternatives do not guarantee which tied maximum element is returned)
    
    Parameters:
    
    iterable - the iterable whose maximum element is to be determined
    
    Throws:
    
    NoSuchElementException - if iterable is empty
    
    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.
    Java 8 users: Use Collections.max(Arrays.asList(a, b), thisComparator) instead (but note that it does not guarantee which tied maximum element is returned).
    
    Parameters:
    
    a - value to compare, returned if greater than or equal to b.
    
    b - value to compare.
    
    Throws:
    
    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.
    Java 8 users: Use Collections.max(Arrays.asList(a, b, c...), thisComparator) instead (but note that it does not guarantee which tied maximum element 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:
    
    ClassCastException - if the parameters are not mutually comparable under this ordering.
  - leastOf
```
public <E extends T> List<E> leastOf(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.
    Java 8 users: Use Streams.stream(iterable).collect(Comparators.least(k, thisComparator)) instead.
    
    Returns:
    
    an immutable RandomAccess list of the k least elements in ascending order
    
    Throws:
    
    IllegalArgumentException - if k is negative
    
    Since:
    
    8.0
  - leastOf
```
public <E extends T> List<E> leastOf(Iterator<E> iterator,
                                     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.
    Java 8 users: Continue to use this method for now. After the next release of Guava, use Streams.stream(iterator).collect(Comparators.least(k, thisComparator)) instead.
    
    Returns:
    
    an immutable RandomAccess list of the k least elements in ascending order
    
    Throws:
    
    IllegalArgumentException - if k is negative
    
    Since:
    
    14.0
  - greatestOf
```
public <E extends T> List<E> greatestOf(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.
    Java 8 users: Use Streams.stream(iterable).collect(Comparators.greatest(k, thisComparator)) instead.
    
    Returns:
    
    an immutable RandomAccess list of the k greatest elements in descending order
    
    Throws:
    
    IllegalArgumentException - if k is negative
    
    Since:
    
    8.0
  - greatestOf
```
public <E extends T> List<E> greatestOf(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.
    Java 8 users: Continue to use this method for now. After the next release of Guava, use Streams.stream(iterator).collect(Comparators.greatest(k, thisComparator)) instead.
    
    Returns:
    
    an immutable RandomAccess list of the k greatest elements in descending order
    
    Throws:
    
    IllegalArgumentException - if k is negative
    
    Since:
    
    14.0
  - sortedCopy
```
public <E extends T> List<E> sortedCopy(Iterable<E> elements)
```
    Returns a mutable list containing elements sorted by this ordering; use this only when the resulting list may need further modification, or may contain null. The input is not modified. The returned list is 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 returned list in the same order they appeared in elements.
    Performance note: According to our benchmarking on Open JDK 7, immutableSortedCopy(java.lang.Iterable<E>) generally performs better (in both time and space) than this method, and this method in turn generally performs better than copying the list and calling Collections.sort(List).
  - immutableSortedCopy
```
public <E extends T> ImmutableList<E> immutableSortedCopy(Iterable<E> elements)
```
    Returns an immutable list containing elements 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 returned list in the same order they appeared in elements.
    Performance note: According to our benchmarking on Open JDK 7, this method is the most efficient way to make a sorted copy of a collection.
    
    Throws:
    
    NullPointerException - if any of elements (or elements itself) is null
    
    Since:
    
    3.0
  - isOrdered
```
public boolean isOrdered(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.
    Java 8 users: Use the equivalent Comparators#isInOrder(Iterable) instead, since the rest of Ordering is mostly obsolete (as explained in the class documentation).
  - isStrictlyOrdered
```
public boolean isStrictlyOrdered(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.
    Java 8 users: Use the equivalent Comparators#isInStrictOrder(Iterable) instead, since the rest of Ordering is mostly obsolete (as explained in the class documentation).
  - binarySearch
```
@Deprecated
public int binarySearch(List<? extends T> sortedList,
                                    @Nullable
                                    T key)
```
    Deprecated. Use Collections.binarySearch(List, Object, Comparator) directly. This method is scheduled for deletion in June 2018.
    
    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

Class Ordering<T>

Three types of methods

Acquiring

Chaining

Using

Understanding complex orderings

Additional notes

For Java 8 users

See also

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Methods inherited from interface java.util.Comparator

Constructor Detail

Ordering

Method Detail

natural

from

from

explicit

explicit

allEqual

usingToString

arbitrary

reverse

nullsFirst

nullsLast

onResultOf

compound

compound

lexicographical

compare

min

min

min

min

max

max

max

max

leastOf

leastOf

greatestOf

greatestOf

sortedCopy

immutableSortedCopy

isOrdered

isStrictlyOrdered

binarySearch