com.google.common.collect
Class Comparators

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

public final class Comparators
extends java.lang.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<java.lang.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(java.util.Comparator<? super T> first, java.util.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(java.util.Comparator<? super T> first, java.util.Comparator<? super T> second, java.util.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(java.util.Comparator<? super T> first, java.util.Comparator<? super T> second, java.util.Comparator<? super T> third, java.util.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(java.util.Comparator<? super T> first, java.util.Comparator<? super T> second, java.util.Comparator<? super T> third, java.util.Comparator<? super T> forth, java.util.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(java.lang.Iterable<? extends java.util.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 java.lang.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, java.util.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(java.util.List<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(java.util.Comparator<? super T> comparator, T a, T b) Returns the larger of the two values according to the specified comparator.
static <T extends java.lang.Comparable> T	max(T a, T b) Returns the larger of the two values, according to their natural ordering.
static <T> T	min(java.util.Comparator<? super T> comparator, T a, T b) Returns the smaller of the two values according to the specified comparator.
static <T extends java.lang.Comparable> T	min(T a, T b) Returns the smaller of the two values, according to their natural ordering.
static <T extends java.lang.Comparable> Ordering<T>	naturalOrder() Returns a comparator that uses the natural ordering of the values.
static <T extends java.lang.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(java.util.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 java.lang.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(java.util.Comparator<T> comparator) Returns a comparator that treats null as less than all other values and uses comparator to compare non-null values.

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<java.lang.Object> STRING_FORM_ORDER

A comparator that compares objects by the natural ordering of their string representations as returned by toString. Does not support null values.

Method Detail

naturalOrder

public static <T extends java.lang.Comparable> Ordering<T> naturalOrder()

Returns a comparator that uses the natural ordering of the values.

nullLeastOrder

public static <T> Ordering<T> nullLeastOrder(java.util.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 java.lang.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(java.util.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 java.lang.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(java.util.Comparator<? super T> first,
                                       java.util.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(java.util.Comparator<? super T> first,
                                       java.util.Comparator<? super T> second,
                                       java.util.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(java.util.Comparator<? super T> first,
                                       java.util.Comparator<? super T> second,
                                       java.util.Comparator<? super T> third,
                                       java.util.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(java.util.Comparator<? super T> first,
                                       java.util.Comparator<? super T> second,
                                       java.util.Comparator<? super T> third,
                                       java.util.Comparator<? super T> forth,
                                       java.util.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(java.lang.Iterable<? extends java.util.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 java.lang.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,
                                             java.util.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

min

public static <T extends java.lang.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:

java.lang.ClassCastException - if the parameters are not mutually comparable (for example, a string and an integer).

max

public static <T extends java.lang.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:

java.lang.ClassCastException - if the parameters are not mutually comparable (for example, a string and an integer).

min

public static <T> T min(java.util.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(java.util.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(java.util.List<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.

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:

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

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