com.google.common.collect
Class Comparators

java.lang.Object
  extended by com.google.common.collect.Comparators

public final class Comparators
extends Object

Standard comparators and utilities for creating and working with comparators.

Some of these methods return an Ordering, a serializable class that implements Comparator and includes many additional methods.

Several method signatures include <C extends Comparable> with a raw Comparable, instead of <C extends Comparable<? super C>. That's necessary to support classes defined without generics.

Author:
Jared Levy, Kevin Bourrillion, Mike Bostock

Field Summary
static Ordering<Object> STRING_FORM_ORDER
          A comparator that compares objects by the natural ordering of their string representations as returned by toString().
 
Method Summary
static int compare(boolean a, boolean b)
          Compares the two specified boolean values.
static int compare(byte a, byte b)
          Compares the two specified byte values.
static int compare(char a, char b)
          Compares the two specified char values.
static int compare(double a, double b)
          Compares the two specified double values.
static int compare(float a, float b)
          Compares the two specified float values.
static int compare(int a, int b)
          Compares the two specified int values.
static int compare(long a, long b)
          Compares the two specified long values.
static int compare(short a, short b)
          Compares the two specified short values.
static
<T> Ordering<T>
compound(Comparator<? super T> first, Comparator<? super T> second)
          Returns a comparator which tries two comparators in order until a non-zero result is found, returning that result, and returning zero only if both comparators return zero.
static
<T> Ordering<T>
compound(Comparator<? super T> first, Comparator<? super T> second, Comparator<? super T> third)
          Returns a comparator which tries three comparators 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>
compound(Comparator<? super T> first, Comparator<? super T> second, Comparator<? super T> third, Comparator<? super T> forth)
          Returns a comparator which tries four comparators 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>
compound(Comparator<? super T> first, Comparator<? super T> second, Comparator<? super T> third, Comparator<? super T> forth, Comparator<? super T>... rest)
          Returns a comparator 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>
compound(Iterable<? extends Comparator<? super T>> comparators)
          Returns a comparator 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
<F,T extends Comparable>
Ordering<F>
fromFunction(Function<F,T> function)
          Creates a comparator that compares any two items by applying a function to each of them and using the natural ordering of the results.
static
<F,T> Ordering<F>
fromFunction(Function<F,T> function, Comparator<? super T> comparator)
          Creates a comparator that compares any two items by applying a function to each of them and using the supplied comparator to compare the results.
static
<T> Ordering<T>
givenOrder(List<? extends T> valuesInOrder)
          Returns a comparator that compares objects according to the order in which they appear in the given list.
static
<T> Ordering<T>
givenOrder(T leastValue, T... remainingValuesInOrder)
          Returns the comparator that compares objects according to the order in which they are given to this method.
static
<T> T
max(Comparator<? super T> comparator, T a, T b)
          Returns the larger of the two values according to the specified comparator.
static
<T extends Comparable>
T
max(T a, T b)
          Returns the larger of the two values, according to their natural ordering.
static
<T> T
min(Comparator<? super T> comparator, T a, T b)
          Returns the smaller of the two values according to the specified comparator.
static
<T extends Comparable>
T
min(T a, T b)
          Returns the smaller of the two values, according to their natural ordering.
static
<T extends Comparable>
Ordering<T>
naturalOrder()
          Returns a comparator that uses the natural ordering of the values.
static
<T extends Comparable>
Ordering<T>
nullGreatestOrder()
          Returns a comparator that uses the natural ordering of the values, but also handles null values, treating them as greater than all other values.
static
<T> Ordering<T>
nullGreatestOrder(Comparator<T> comparator)
          Returns a comparator that treats null as greater than all other values and uses the given comparator to compare non-null values.
static
<T extends Comparable>
Ordering<T>
nullLeastOrder()
          Returns a comparator that uses the natural ordering of the values, but also handles null values, treating them as less than all other values.
static
<T> Ordering<T>
nullLeastOrder(Comparator<T> comparator)
          Returns a comparator that treats null as less than all other values and uses comparator to compare non-null values.
static
<T> Ordering<T>
toStringOrder()
          Returns a comparator 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
 

Field Detail

STRING_FORM_ORDER

public static final Ordering<Object> STRING_FORM_ORDER
A comparator that compares objects by the natural ordering of their string representations as returned by toString(). It does not support null values.

TODO: Deprecate this in favor of toStringOrder().

Method Detail

naturalOrder

public static <T extends Comparable> Ordering<T> naturalOrder()
Returns a comparator that uses the natural ordering of the values. The comparator throws a NullPointerException when passed a null parameter.


nullLeastOrder

public static <T> Ordering<T> nullLeastOrder(Comparator<T> comparator)
Returns a comparator that treats null as less than all other values and uses comparator to compare non-null values.


nullLeastOrder

public static <T extends Comparable> Ordering<T> nullLeastOrder()
Returns a comparator that uses the natural ordering of the values, but also handles null values, treating them as less than all other values.


nullGreatestOrder

public static <T> Ordering<T> nullGreatestOrder(Comparator<T> comparator)
Returns a comparator that treats null as greater than all other values and uses the given comparator to compare non-null values.


nullGreatestOrder

public static <T extends Comparable> Ordering<T> nullGreatestOrder()
Returns a comparator that uses the natural ordering of the values, but also handles null values, treating them as greater than all other values.


compound

public static <T> Ordering<T> compound(Comparator<? super T> first,
                                       Comparator<? super T> second)
Returns a comparator which tries two comparators in order until a non-zero result is found, returning that result, and returning zero only if both comparators return zero.

Parameters:
first - the first comparator to invoke
second - the second comparator to invoke
See Also:
compound(Iterable)

compound

public static <T> Ordering<T> compound(Comparator<? super T> first,
                                       Comparator<? super T> second,
                                       Comparator<? super T> third)
Returns a comparator which tries three comparators in order until a non-zero result is found, returning that result, and returning zero only if all comparators return zero.

Parameters:
first - the first comparator to invoke
second - the second comparator to invoke
third - the third comparator to invoke
See Also:
compound(Iterable)

compound

public static <T> Ordering<T> compound(Comparator<? super T> first,
                                       Comparator<? super T> second,
                                       Comparator<? super T> third,
                                       Comparator<? super T> forth)
Returns a comparator which tries four comparators in order until a non-zero result is found, returning that result, and returning zero only if all comparators return zero.

Parameters:
first - the first comparator to invoke
second - the second comparator to invoke
third - the third comparator to invoke
forth - the fourth comparator to invoke
See Also:
compound(Iterable)

compound

public static <T> Ordering<T> compound(Comparator<? super T> first,
                                       Comparator<? super T> second,
                                       Comparator<? super T> third,
                                       Comparator<? super T> forth,
                                       Comparator<? super T>... rest)
Returns a comparator 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.

Subsequent changes to the rest array do not affect the behavior of the returned comparator.

Parameters:
first - the first comparator to invoke
second - the second comparator to invoke
third - the third comparator to invoke
forth - the fourth comparator to invoke
rest - additional comparators to invoke as necessary
See Also:
compound(Iterable)

compound

public static <T> Ordering<T> compound(Iterable<? extends Comparator<? super T>> comparators)
Returns a comparator 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 comparator is a "view" of the specified Iterable instance; changes to the iterable will be reflected in the behavior of the returned comparator.

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

fromFunction

public static <F,T extends Comparable> Ordering<F> fromFunction(Function<F,T> function)
Creates a comparator that compares any two items by applying a function to each of them and using the natural ordering of the results.

Parameters:
function - the function returning the value to compare. The function should never return null.
Returns:
the generated comparator

fromFunction

public static <F,T> Ordering<F> fromFunction(Function<F,T> function,
                                             Comparator<? super T> comparator)
Creates a comparator that compares any two items by applying a function to each of them and using the supplied comparator to compare the results.

Parameters:
function - the function returning the value to compare
comparator - the comparator that receives the function output
Returns:
the generated comparator

toStringOrder

public static final <T> Ordering<T> toStringOrder()
Returns a comparator that compares objects by the natural ordering of their string representations as returned by toString(). It does not support null values.


min

public static <T extends Comparable> T min(T a,
                                           T b)
Returns the smaller of the two values, according to their natural ordering. If the values are equal, the first is returned.

To handle more than two values, call Ordering.min(Object, Object, Object, Object...) or Ordering.min(Iterable) on the Ordering returned by Ordering.natural().

Parameters:
a - non-null value to compare, returned if less than or equal to b.
b - non-null value to compare.
Throws:
ClassCastException - if the parameters are not mutually comparable (for example, a string and an integer).

max

public static <T extends Comparable> T max(T a,
                                           T b)
Returns the larger of the two values, according to their natural ordering. If the values are equal, the first is returned.

To handle more than two values, call Ordering.max(Object, Object, Object, Object...) or Ordering.max(Iterable) on the Ordering returned by Ordering.natural().

Parameters:
a - non-null value to compare, returned if greater than or equal to b.
b - non-null value to compare.
Throws:
ClassCastException - if the parameters are not mutually comparable (for example, a string and an integer).

min

public static <T> T min(Comparator<? super T> comparator,
                        @Nullable
                        T a,
                        @Nullable
                        T b)
Returns the smaller of the two values according to the specified comparator. If the values are equal, the first is returned. Null values are allowed if the comparator supports them.

To handle more than two values, call Ordering.min(Object, Object, Object, Object...) or Ordering.min(Iterable) on the Ordering returned by Ordering.forComparator(Comparator).

Parameters:
comparator - comparator that compares the two values
a - value to compare, returned if less than or equal to b
b - value to compare

max

public static <T> T max(Comparator<? super T> comparator,
                        @Nullable
                        T a,
                        @Nullable
                        T b)
Returns the larger of the two values according to the specified comparator. If the values are equal, the first is returned. Null values are allowed if the comparator supports them.

To handle more than two values, call Ordering.max(Object, Object, Object, Object...) or Ordering.max(Iterable) on the Ordering returned by Ordering.forComparator(Comparator).

Parameters:
comparator - comparator that compares the two values
a - value to compare, returned if greater than or equal to b
b - value to compare

givenOrder

public static <T> Ordering<T> givenOrder(List<? extends T> valuesInOrder)
Returns a comparator 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 supported.

The returned comparator throws an ClassCastException when it receives an input parameter that isn't in valuesInOrder.

Parameters:
valuesInOrder - the values that the returned comparator will be able to compare, in the order the comparator should follow
Returns:
the comparator described above
Throws:
IllegalArgumentException - if valuesInOrder contains any non-consecutive duplicate values (according to Object.equals(java.lang.Object))

givenOrder

public static <T> Ordering<T> givenOrder(@Nullable
                                         T leastValue,
                                         T... remainingValuesInOrder)
Returns the comparator 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 supported.

The returned comparator throws a ClassCastException when it receives an input parameter that isn't equal to leastValue or in remainingValuesInOrder.

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:
IllegalArgumentException - if any non-consecutive duplicate values (according to Object.equals(java.lang.Object)) are present among the method arguments

compare

public static int compare(byte a,
                          byte b)
Compares the two specified byte values. The sign of the value returned is the same as that of the value that would be returned by the call:
  Byte.valueOf(a).compareTo(Byte.valueOf(b))

Parameters:
a - the first byte to compare
b - the second byte to compare
Returns:
a negative value if a is less than b; a positive value if a is greater than b; otherwise zero.

compare

public static int compare(char a,
                          char b)
Compares the two specified char values. The sign of the value returned is the same as that of the value that would be returned by the call:
  Character.valueOf(a).compareTo(Character.valueOf(b))

Parameters:
a - the first char to compare
b - the second char to compare
Returns:
a negative value if a is less than b; a positive value if a is greater than b; otherwise zero.

compare

public static int compare(short a,
                          short b)
Compares the two specified short values. The sign of the value returned is the same as that of the value that would be returned by the call:
  Short.valueOf(a).compareTo(Short.valueOf(b))

Parameters:
a - the first short to compare
b - the second short to compare
Returns:
a negative value if a is less than b; a positive value if a is greater than b; otherwise zero.

compare

public static int compare(int a,
                          int b)
Compares the two specified int values. The sign of the value returned is the same as that of the value that would be returned by the call:
  Integer.valueOf(a).compareTo(Integer.valueOf(b))

Parameters:
a - the first int to compare
b - the second int to compare
Returns:
a negative value if a is less than b; a positive value if a is greater than b; otherwise zero.

compare

public static int compare(long a,
                          long b)
Compares the two specified long values. The sign of the value returned is the same as that of the value that would be returned by the call:
  Long.valueOf(a).compareTo(Long.valueOf(b))

Parameters:
a - the first long to compare
b - the second long to compare
Returns:
a negative value if a is less than b; a positive value if a is greater than b; otherwise zero.

compare

public static int compare(double a,
                          double b)
Compares the two specified double values. The sign of the value returned is the same as that of the value that would be returned by the call:
  Double.valueOf(a).compareTo(Double.valueOf(b))

Parameters:
a - the first double to compare
b - the second double to compare
Returns:
a negative value if a is less than b; a positive value if a is greater than b; otherwise zero.
See Also:
Double.compare(double, double)

compare

public static int compare(float a,
                          float b)
Compares the two specified float values. The sign of the value returned is the same as that of the value that would be returned by the call:
  Float.valueOf(a).compareTo(Float.valueOf(b))

Parameters:
a - the first float to compare
b - the second float to compare
Returns:
a negative value if a is less than b; a positive value if a is greater than b; otherwise zero.
See Also:
Float.compare(float, float)

compare

public static int compare(boolean a,
                          boolean b)
Compares the two specified boolean values. The sign of the value returned is the same as that of the value that would be returned by the call:
  Boolean.valueOf(a).compareTo(Boolean.valueOf(b))

Parameters:
a - the first boolean to compare
b - the second boolean to compare
Returns:
a negative value if a is false and b is true; a positive value if a is true and b is false; otherwise zero.