Module org.tquadrat.foundation.util

Package org.tquadrat.foundation.util

Class Comparators

java.lang.Object

org.tquadrat.foundation.util.Comparators

@UtilityClass
@ClassVersion(sourceVersion="$Id: Comparators.java 1084 2024-01-03 15:31:20Z tquadrat $")
@API(status=STABLE,
     since="0.0.5")
public final class Comparators
extends Object

This class provides factory methods for a bunch of different implementations of Comparator.

Author:

Thomas Thrien (thomas.thrien@tquadrat.org)

Version:

$Id: Comparators.java 1084 2024-01-03 15:31:20Z tquadrat $

Since:

0.0.5

UML Diagram

⁠

UML Diagram for "org.tquadrat.foundation.util.Comparators"

⁠

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static interface	Comparators.KeyProvider<T,K>	Implementations of this interface provides the sort order key from the given instance of the type.

Constructor Summary

Constructors

Modifier	Constructor	Description
private	Comparators()	No instance allowed for this class.

Method Summary

Modifier and Type	Method	Description
static final Comparator<String>	caseInsensitiveComparator()	Returns a comparator that compares Strings ignoring the case. Internally this is String.CASE_INSENSITIVE_ORDER, with the limitations described there.
static final <T, K extends Comparable<K>> Comparator<T>	keyBasedComparator(Comparators.KeyProvider<? super T,K> keyProvider)	Returns a comparator that generates a sort key from the elements before sorting them. The implementation of this comparator generates the sort keys for each and every comparison.
static final <T, K> Comparator<T>	keyBasedComparator(Comparators.KeyProvider<T,K> keyProvider, Comparator<K> keyComparator, boolean cacheKeys)	A comparator that generates a sort key from the elements before sorting them. As it is not very efficient to generate the sort keys for each and every comparison, it is possible to cache them.
static final <T, K> Comparator<T>	listBasedComparator(Comparators.KeyProvider<T,K> keyProvider, Comparator<? super K> comparator, K... keys)	A comparator that works on a list of sort keys.
static final <T, K extends Comparable<K>> Comparator<T>	listBasedComparator(Comparators.KeyProvider<T,K> keyProvider, K... keys)	A comparator that works on a list of sort keys.
static final <T extends Comparable<T>> Comparator<T>	listBasedComparator(T... values)	Returns a comparator that works on a list of sort keys.
static final <T extends Number> Comparator<T>	numberComparator()	A comparator for numeric values.
static final <T> Comparator<T>	stringBasedComparator(StringConverter<T> stringConverter)	A comparator that compares arbitrary object types based on their String representations.

Methods inherited from class java.lang.Object

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

Constructor Details

Comparators

private Comparators()

No instance allowed for this class.

Method Details

caseInsensitiveComparator

@API(status=STABLE,
     since="0.0.5")
public static final Comparator<String> caseInsensitiveComparator()

Returns a comparator that compares Strings ignoring the case.

Internally this is String.CASE_INSENSITIVE_ORDER, with the limitations described there.

Returns:

The comparator.

keyBasedComparator

@API(status=STABLE,
     since="0.0.5")
public static final <T,
K extends Comparable<K>>
Comparator<T> keyBasedComparator(Comparators.KeyProvider<? super T,K> keyProvider)

Returns a comparator that generates a sort key from the elements before sorting them.

The implementation of this comparator generates the sort keys for each and every comparison. This is obviously not very efficient. A more efficient implementation is provided by keyBasedComparator(KeyProvider, Comparator, boolean)

Note:

• The key provider must return null for a null value, as described for .

Type Parameters:

T - The type to compare.

K - The key type that is used to determine the order; this may be the same as the type itself.

Parameters:

keyProvider - The method that generates the sort key.

Returns:

The comparator.

See Also:

• Comparators.KeyProvider

keyBasedComparator

@API(status=STABLE,
     since="0.0.5")
public static final <T,
K> Comparator<T> keyBasedComparator(Comparators.KeyProvider<T,K> keyProvider,
 Comparator<K> keyComparator,
 boolean cacheKeys)

A comparator that generates a sort key from the elements before sorting them.

As it is not very efficient to generate the sort keys for each and every comparison, it is possible to cache them.

Notes:

• The key provider must return null for a null value, as described for .
• The internally used cache will be kept for later uses of the comparator; this means that the key provider may not change its behaviour meanwhile.
• The internal cache is based on an with instances of the argument type <T> as the key. If the key generation through the key provider will provide equal keys for non-identical, but otherwise equal arguments, the cache may not be efficient.

Type Parameters:

T - The type to compare.

K - The key type that is used to determine the order; this may be the same as the type itself.

Parameters:

keyProvider - The method that generates the sort key.

keyComparator - The comparator that determines the order for the keys.

cacheKeys - A flag that determines whether the keys are to be cached internally; true means they are kept, false means that the keys are generated newly for each comparison.

Returns:

The comparator.

See Also:

• Comparators.KeyProvider

listBasedComparator

@SafeVarargs
@API(status=STABLE,
     since="0.0.5")
public static final <T extends Comparable<T>>
Comparator<T> listBasedComparator(T... values)

Returns a comparator that works on a list of sort keys.

Sometimes, a special sort order is required that cannot be defined as a rule based on the values themselves. Instead an ordered list of values defines their sequence.

This method creates a new Comparator instance that works on the given list of values. Values that are not on that list will be placed to the end, ordered according to their natural order.

Type Parameters:

T - The type to compare.

Parameters:

values - The values in their order.

Returns:

The comparator.

listBasedComparator

@API(status=STABLE,
     since="0.0.5")
@SafeVarargs
public static final <T,
K extends Comparable<K>>
Comparator<T> listBasedComparator(Comparators.KeyProvider<T,K> keyProvider,
 K... keys)

A comparator that works on a list of sort keys.

Sometimes, a special sort order is required that cannot be defined as a rule based on the values themselves. Instead an ordered list of keys defines their sequence.

The implementation first determines the key for a given value, then it looks up that key in the key list to determine the sort order. Values whose keys are not in the key list are ordered based on the natural sort order of the keys.

Type Parameters:

T - The type to compare.

K - The key type that is used to determine the order; this may be the same as the type itself.

Parameters:

keyProvider - The implementation of Comparators.KeyProvider that returns the sort keys for the instances to compare.

keys - The sort order keys.

Returns:

The comparator.

listBasedComparator

@SafeVarargs
@API(status=STABLE,
     since="0.0.5")
public static final <T,
K> Comparator<T> listBasedComparator(Comparators.KeyProvider<T,K> keyProvider,
 Comparator<? super K> comparator,
 K... keys)

A comparator that works on a list of sort keys.

Sometimes, a special sort order is required that cannot be defined as a rule based on the values themselves. Instead an ordered list of keys defines their sequence.

The implementation first determines the key for a given value, then it looks up that key in the key list to determine the sort order. Values whose keys are not in the key list are ordered based on the order of their keys that is implied by the given comparator.

Type Parameters:

T - The type to compare.

K - The key type that is used to determine the order; this may be the same as the type itself.

Parameters:

keyProvider - The implementation of Comparators.KeyProvider that returns the sort keys for the instances to compare.

comparator - The comparator that is used to order the instances that are not listed.

keys - The sort order keys.

Returns:

The comparator.

numberComparator

@API(status=STABLE,
     since="0.1.0")
public static final <T extends Number>
Comparator<T> numberComparator()

A comparator for numeric values.

Type Parameters:

T - The type to compare.

Returns:

The comparator.

Since:

0.1.0

stringBasedComparator

@API(status=STABLE,
     since="0.1.0")
public static final <T> Comparator<T> stringBasedComparator(StringConverter<T> stringConverter)

A comparator that compares arbitrary object types based on their String representations.

Type Parameters:

T - The type to compare.

Parameters:

stringConverter - The instance of StringConverter that is used to get the String representation of the instances to compare.

Returns:

The comparator.

Since:

0.1.0