com.google.common.collect
Class Comparators

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

public final class Comparators
extends Object

Standard comparators and utilities for creating and working with comparators.

Comparator instances returned by this class are serializable.

Author:

Jared Levy, Kevin Bourrillion, Mike Bostock

Field Summary

static Comparator<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> Comparator<T>	compound(Comparator<? super T> primary, Comparator<? super T> secondary, Comparator<? super T>... rest) Returns a comparator which tries each given comparator in order until a non-zero result is found, returning this result, and returning zero only if all comparators return zero.
static <T> Comparator<T>	compound(List<? extends Comparator<? super T>> comparators) Returns a comparator which tries each given comparator in order until a non-zero result is found, returning this result, and returning zero only if all comparators return zero.
static <F,T extends Comparable> Comparator<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> Comparator<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> Comparator<T>	givenOrder(List<T> valuesInOrder) Returns a comparator that compares objects by the order in which they appear in a given list.
static <T> Comparator<T>	givenOrder(T leastValue, T... remainingValuesInOrder) Returns a comparator that compares objects by 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 <C extends Comparable> Comparator<C>	naturalOrder() Returns a comparator that uses the natural ordering of values as defined by Comparable.
static <C extends Comparable> Comparator<C>	nullGreatestOrder() Returns a comparator that uses the natural ordering of values, but also handles null values, treating them as greater than all other values.
static <T> Comparator<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 <C extends Comparable> Comparator<C>	nullLeastOrder() Returns a comparator that uses the natural ordering of values, but also handles null values, treating them as less than all other values.
static <T> Comparator<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.

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 Comparator<Object> STRING_FORM_ORDER

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

Method Detail

naturalOrder

public static <C extends Comparable> Comparator<C> naturalOrder()

Returns a comparator that uses the natural ordering of values as defined by Comparable.

See Also:

Collections.reverseOrder()

nullLeastOrder

public static <T> Comparator<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 <C extends Comparable> Comparator<C> nullLeastOrder()

Returns a comparator that uses the natural ordering of values, but also handles null values, treating them as less than all other values.

nullGreatestOrder

public static <T> Comparator<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 <C extends Comparable> Comparator<C> nullGreatestOrder()

Returns a comparator that uses the natural ordering of values, but also handles null values, treating them as greater than all other values.

compound

public static <T> Comparator<T> compound(Comparator<? super T> primary,
                                         Comparator<? super T> secondary,
                                         Comparator<? super T>... rest)

Returns a comparator which tries each given comparator in order until a non-zero result is found, returning this result, and returning zero only if all comparators return zero.

The returned comparator is a "view" of the specified rest array; changes to the array will be reflected in the behavior of the returned comparator.

Parameters:

primary - the primary comparator

secondary - the secondary comparator

rest - additional comparators to invoke as necessary

See Also:

compound(List)

compound

public static <T> Comparator<T> compound(List<? extends Comparator<? super T>> comparators)

Returns a comparator which tries each given comparator in order until a non-zero result is found, returning this result, and returning zero only if all comparators return zero.

The returned comparator is a "view" of the specified List instance; changes to the collection of comparators will be reflected in the behavior of the returned comparator.

Parameters:

comparators - a collection of comparators to try in order

fromFunction

public static <F,T extends Comparable> Comparator<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. The returned comparator will generally fail if the function returns null.

Parameters:

function - the function returning the value to compare

Returns:

the generated comparator

fromFunction

public static <F,T> Comparator<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

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.

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, strings and integers).

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.

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, strings and integers).

min

public static <T> T min(Comparator<? super T> comparator,
                        T a,
                        T b)

Returns the smaller of the two values according to the specified comparator. If the values are equal, the first is returned.

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 using the specified comparator.

max

public static <T> T max(Comparator<? super T> comparator,
                        T a,
                        T b)

Returns the larger of the two values according to the specified comparator. If the values are equal, the first is returned.

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 using the specified comparator.

givenOrder

public static <T> Comparator<T> givenOrder(List<T> valuesInOrder)

Returns a comparator that compares objects by the order in which they appear in a 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.

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 duplicate values (according to Object.equals(java.lang.Object))

givenOrder

public static <T> Comparator<T> givenOrder(@Nullable
                                           T leastValue,
                                           T... remainingValuesInOrder)

Returns a comparator that compares objects by 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.

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 duplicate values (according to Object.equals(java.lang.Object)) are present among leastValue and remainingValuesInOrder

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:

  new Byte(a).compareTo(new Byte(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:

  new Character(a).compareTo(new Character(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:

  new Short(a).compareTo(new Short(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:

  new Integer(a).compareTo(new Integer(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:

  new Long(a).compareTo(new Long(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:

  new Double(a).compareTo(new Double(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:

  new Float(a).compareTo(new Float(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:

  new Boolean(a).compareTo(new Boolean(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.