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 instead of implementing Comparator directly
• Pass a pre-existing Comparator instance to from(Comparator)
• Use the natural ordering, Ordering#natural

Chaining

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

• reverse
• compound(Comparator)
• onResultOf(Function)
• nullsFirst / nullsLast

Using

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

• immutableSortedCopy
• isOrdered / isStrictlyOrdered
• min / max

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. 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.