java8.util

Class Comparators

java.lang.Object

java8.util.Comparators

public final class Comparators
extends java.lang.Object

A place for static default implementations of the new Java 8 default interface methods and static interface methods in the Comparator interface.

Method Summary

Modifier and Type	Method and Description
static <T,U extends java.lang.Comparable<? super U>> java.util.Comparator<T>	comparing(Function<? super T,? extends U> keyExtractor) Accepts a function that extracts a Comparable sort key from a type T, and returns a Comparator<T> that compares by that sort key.
static <T,U> java.util.Comparator<T>	comparing(Function<? super T,? extends U> keyExtractor, java.util.Comparator<? super U> keyComparator) Accepts a function that extracts a sort key from a type T, and returns a Comparator<T> that compares by that sort key using the specified Comparator.
static <T> java.util.Comparator<T>	comparingDouble(ToDoubleFunction<? super T> keyExtractor) Accepts a function that extracts a double sort key from a type T, and returns a Comparator<T> that compares by that sort key.
static <T> java.util.Comparator<T>	comparingInt(ToIntFunction<? super T> keyExtractor) Accepts a function that extracts an int sort key from a type T, and returns a Comparator<T> that compares by that sort key.
static <T> java.util.Comparator<T>	comparingLong(ToLongFunction<? super T> keyExtractor) Accepts a function that extracts a long sort key from a type T, and returns a Comparator<T> that compares by that sort key.
static <T extends java.lang.Comparable<? super T>> java.util.Comparator<T>	naturalOrder() Returns a comparator that compares Comparable objects in natural order.
static <T> java.util.Comparator<T>	nullsFirst(java.util.Comparator<? super T> comparator) Returns a null-friendly comparator that considers null to be less than non-null.
static <T> java.util.Comparator<T>	nullsLast(java.util.Comparator<? super T> comparator) Returns a null-friendly comparator that considers null to be greater than non-null.
static <T> java.util.Comparator<T>	reversed(java.util.Comparator<T> comparator) Returns a comparator that imposes the reverse ordering of the passed comparator.
static <T extends java.lang.Comparable<? super T>> java.util.Comparator<T>	reverseOrder() Returns a comparator that imposes the reverse of the natural ordering.
static <T> java.util.Comparator<T>	thenComparing(java.util.Comparator<? super T> this_, java.util.Comparator<? super T> other) Returns a lexicographic-order comparator with another comparator.
static <T,U extends java.lang.Comparable<? super U>> java.util.Comparator<T>	thenComparing(java.util.Comparator<? super T> this_, Function<? super T,? extends U> keyExtractor) Returns a lexicographic-order comparator with a function that extracts a Comparable sort key.
static <T,U> java.util.Comparator<T>	thenComparing(java.util.Comparator<? super T> this_, Function<? super T,? extends U> keyExtractor, java.util.Comparator<? super U> keyComparator) Returns a lexicographic-order comparator with a function that extracts a key to be compared with the given Comparator.
static <T> java.util.Comparator<T>	thenComparingDouble(java.util.Comparator<? super T> this_, ToDoubleFunction<? super T> keyExtractor) Returns a lexicographic-order comparator with a function that extracts a double sort key.
static <T> java.util.Comparator<T>	thenComparingInt(java.util.Comparator<? super T> this_, ToIntFunction<? super T> keyExtractor) Returns a lexicographic-order comparator with a function that extracts a int sort key.
static <T> java.util.Comparator<T>	thenComparingLong(java.util.Comparator<? super T> this_, ToLongFunction<? super T> keyExtractor) Returns a lexicographic-order comparator with a function that extracts a long sort key.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

reverseOrder

public static <T extends java.lang.Comparable<? super T>> java.util.Comparator<T> reverseOrder()

Returns a comparator that imposes the reverse of the natural ordering.

The returned comparator is serializable and throws NullPointerException when comparing null.

Type Parameters:

T - the Comparable type of element to be compared

Returns:

a comparator that imposes the reverse of the natural ordering on Comparable objects.

Since:

1.8

See Also:

Comparable

naturalOrder

public static <T extends java.lang.Comparable<? super T>> java.util.Comparator<T> naturalOrder()

Returns a comparator that compares Comparable objects in natural order.

The returned comparator is serializable and throws NullPointerException when comparing null.

Type Parameters:

T - the Comparable type of element to be compared

Returns:

a comparator that imposes the natural ordering on Comparable objects.

Since:

1.8

See Also:

Comparable

comparing

public static <T,U> java.util.Comparator<T> comparing(Function<? super T,? extends U> keyExtractor,
                                                      java.util.Comparator<? super U> keyComparator)

Accepts a function that extracts a sort key from a type T, and returns a Comparator<T> that compares by that sort key using the specified Comparator.

The returned comparator is serializable if the specified function and comparator are both serializable.

API Note:
For example, to obtain a Comparator that compares Person objects by their last name ignoring case differences,

     Comparator<Person> cmp = Comparator.comparing(
             Person::getLastName,
             String.CASE_INSENSITIVE_ORDER);
 

Type Parameters:

T - the type of element to be compared

U - the type of the sort key

Parameters:

keyExtractor - the function used to extract the sort key

keyComparator - the Comparator used to compare the sort key

Returns:

a comparator that compares by an extracted key using the specified Comparator

Throws:

java.lang.NullPointerException - if either argument is null

Since:

1.8

comparing

public static <T,U extends java.lang.Comparable<? super U>> java.util.Comparator<T> comparing(Function<? super T,? extends U> keyExtractor)

Accepts a function that extracts a Comparable sort key from a type T, and returns a Comparator<T> that compares by that sort key.

The returned comparator is serializable if the specified function is also serializable.

API Note:
For example, to obtain a Comparator that compares Person objects by their last name,

     Comparator<Person> byLastName = Comparator.comparing(Person::getLastName);
 

Type Parameters:

T - the type of element to be compared

U - the type of the Comparable sort key

Parameters:

keyExtractor - the function used to extract the Comparable sort key

Returns:

a comparator that compares by an extracted key

Throws:

java.lang.NullPointerException - if the argument is null

Since:

1.8

comparingInt

public static <T> java.util.Comparator<T> comparingInt(ToIntFunction<? super T> keyExtractor)

Accepts a function that extracts an int sort key from a type T, and returns a Comparator<T> that compares by that sort key.

The returned comparator is serializable if the specified function is also serializable.

Type Parameters:

T - the type of element to be compared

Parameters:

keyExtractor - the function used to extract the integer sort key

Returns:

a comparator that compares by an extracted key

Throws:

java.lang.NullPointerException - if the argument is null

Since:

1.8

See Also:

comparing(Function)

comparingLong

public static <T> java.util.Comparator<T> comparingLong(ToLongFunction<? super T> keyExtractor)

Accepts a function that extracts a long sort key from a type T, and returns a Comparator<T> that compares by that sort key.

The returned comparator is serializable if the specified function is also serializable.

Type Parameters:

T - the type of element to be compared

Parameters:

keyExtractor - the function used to extract the long sort key

Returns:

a comparator that compares by an extracted key

Throws:

java.lang.NullPointerException - if the argument is null

Since:

1.8

See Also:

comparing(Function)

comparingDouble

public static <T> java.util.Comparator<T> comparingDouble(ToDoubleFunction<? super T> keyExtractor)

Accepts a function that extracts a double sort key from a type T, and returns a Comparator<T> that compares by that sort key.

The returned comparator is serializable if the specified function is also serializable.

Type Parameters:

T - the type of element to be compared

Parameters:

keyExtractor - the function used to extract the double sort key

Returns:

a comparator that compares by an extracted key

Throws:

java.lang.NullPointerException - if the argument is null

Since:

1.8

See Also:

comparing(Function)

thenComparing

public static <T> java.util.Comparator<T> thenComparing(java.util.Comparator<? super T> this_,
                                                        java.util.Comparator<? super T> other)

Returns a lexicographic-order comparator with another comparator. If the this_ Comparator considers two elements equal, i.e. compare(a, b) == 0, other is used to determine the order.

The returned comparator is serializable if the specified comparators are also serializable.

API Note:
For example, to sort a collection of String based on the length and then case-insensitive natural ordering, the comparators can be composed using following code,

     Comparator<String> cmp = Comparators.thenComparing(Comparator.comparingInt(String::length),
                        String.CASE_INSENSITIVE_ORDER);
 

Type Parameters:

T - the type of objects that may be compared by the passed comparators

Parameters:

this_ - the comparator to be used first

other - the other comparator to be used when the this_ comparator compares two objects that are equal.

Returns:

a lexicographic-order comparator composed of the this_ and then the other comparator

Throws:

java.lang.NullPointerException - if this_ is null.

java.lang.NullPointerException - if other is null.

Since:

1.8

thenComparing

public static <T,U> java.util.Comparator<T> thenComparing(java.util.Comparator<? super T> this_,
                                                          Function<? super T,? extends U> keyExtractor,
                                                          java.util.Comparator<? super U> keyComparator)

Returns a lexicographic-order comparator with a function that extracts a key to be compared with the given Comparator.

Implementation Requirements:
This default implementation behaves as if thenComparing(this_, comparing(keyExtractor, keyComparator)).

Type Parameters:

T - the type of objects that may be compared by the this_ comparator

U - the type of the sort key

Parameters:

this_ - the comparator to be used first

keyExtractor - the function used to extract the sort key

keyComparator - the Comparator used to compare the sort key

Returns:

a lexicographic-order comparator composed of the this_ comparator and then comparing on the key extracted by the keyExtractor function

Throws:

java.lang.NullPointerException - if either argument is null.

Since:

1.8

See Also:

comparing(Function, Comparator), thenComparing(Comparator, Comparator)

thenComparing

public static <T,U extends java.lang.Comparable<? super U>> java.util.Comparator<T> thenComparing(java.util.Comparator<? super T> this_,
                                                                                                  Function<? super T,? extends U> keyExtractor)

Returns a lexicographic-order comparator with a function that extracts a Comparable sort key.

Implementation Requirements:
This default implementation behaves as if thenComparing(this_, comparing(keyExtractor)).

Type Parameters:

T - the type of objects that may be compared by the this_ comparator

U - the type of the Comparable sort key

Parameters:

this_ - the comparator to be used first

keyExtractor - the function used to extract the Comparable sort key

Returns:

a lexicographic-order comparator composed of this_ and then the Comparable sort key.

Throws:

java.lang.NullPointerException - if either argument is null.

Since:

1.8

See Also:

comparing(Function), thenComparing(Comparator, Comparator)

thenComparingInt

public static <T> java.util.Comparator<T> thenComparingInt(java.util.Comparator<? super T> this_,
                                                           ToIntFunction<? super T> keyExtractor)

Returns a lexicographic-order comparator with a function that extracts a int sort key.

Implementation Requirements:
This default implementation behaves as if thenComparing(this_, comparingInt(keyExtractor)).

Type Parameters:

T - the type of objects that may be compared by the this_ comparator

Parameters:

this_ - the comparator to be used first

keyExtractor - the function used to extract the integer sort key

Returns:

a lexicographic-order comparator composed of this_ and then the int sort key

Throws:

java.lang.NullPointerException - if either argument is null.

Since:

1.8

See Also:

comparingInt(ToIntFunction), thenComparing(Comparator, Comparator)

thenComparingLong

public static <T> java.util.Comparator<T> thenComparingLong(java.util.Comparator<? super T> this_,
                                                            ToLongFunction<? super T> keyExtractor)

Returns a lexicographic-order comparator with a function that extracts a long sort key.

Implementation Requirements:
This default implementation behaves as if thenComparing(this_, comparingLong(keyExtractor)).

Type Parameters:

T - the type of objects that may be compared by the this_ comparator

Parameters:

this_ - the comparator to be used first

keyExtractor - the function used to extract the long sort key

Returns:

a lexicographic-order comparator composed of this_ and then the long sort key

Throws:

java.lang.NullPointerException - if either argument is null.

Since:

1.8

See Also:

comparingLong(ToLongFunction), thenComparing(Comparator, Comparator)

thenComparingDouble

public static <T> java.util.Comparator<T> thenComparingDouble(java.util.Comparator<? super T> this_,
                                                              ToDoubleFunction<? super T> keyExtractor)

Returns a lexicographic-order comparator with a function that extracts a double sort key.

Implementation Requirements:
This default implementation behaves as if thenComparing(this_, comparingDouble(keyExtractor)).

Type Parameters:

T - the type of objects that may be compared by the this_ comparator

Parameters:

this_ - the comparator to be used first

keyExtractor - the function used to extract the double sort key

Returns:

a lexicographic-order comparator composed of this_ and then the double sort key

Throws:

java.lang.NullPointerException - if either argument is null.

Since:

1.8

See Also:

comparingDouble(ToDoubleFunction), thenComparing(Comparator, Comparator)

reversed

public static <T> java.util.Comparator<T> reversed(java.util.Comparator<T> comparator)

Returns a comparator that imposes the reverse ordering of the passed comparator.

Type Parameters:

T - the type of objects that may be compared by the comparator argument

Parameters:

comparator - the comparator whose ordering needs to be reversed

Returns:

a comparator that imposes the reverse ordering of the passed comparator.

Since:

1.8

nullsFirst

public static <T> java.util.Comparator<T> nullsFirst(java.util.Comparator<? super T> comparator)

Returns a null-friendly comparator that considers null to be less than non-null. When both are null, they are considered equal. If both are non-null, the specified Comparator is used to determine the order. If the specified comparator is null, then the returned comparator considers all non-null values to be equal.

The returned comparator is serializable if the specified comparator is serializable.

Type Parameters:

T - the type of the elements to be compared

Parameters:

comparator - a Comparator for comparing non-null values

Returns:

a comparator that considers null to be less than non-null, and compares non-null objects with the supplied Comparator.

Since:

1.8

nullsLast

public static <T> java.util.Comparator<T> nullsLast(java.util.Comparator<? super T> comparator)

Returns a null-friendly comparator that considers null to be greater than non-null. When both are null, they are considered equal. If both are non-null, the specified Comparator is used to determine the order. If the specified comparator is null, then the returned comparator considers all non-null values to be equal.

The returned comparator is serializable if the specified comparator is serializable.

Type Parameters:

T - the type of the elements to be compared

Parameters:

comparator - a Comparator for comparing non-null values

Returns:

a comparator that considers null to be greater than non-null, and compares non-null objects with the supplied Comparator.

Since:

1.8