net.sf.collections15.comparators
Class ComparatorUtils

java.lang.Object
  net.sf.collections15.comparators.ComparatorUtils

public class ComparatorUtils
extends java.lang.Object

Provides convenient static utility methods for Comparator objects.

Most of the functionality in this class can also be found in the comparators package. This class merely provides a convenient central place if you have use for more than one class in the comparators subpackage.

Since:

Collections15 1.0

Author:

Paul Jack, Stephen Colebourne, Chris Lambrou (port to Java 5.0)

Constructor Summary

protected

ComparatorUtils() Protected constructor prevents direct instantiation, but allows users to extend this library to provide their own augmented static library class.

Method Summary

static java.util.Comparator<java.lang.Boolean>	booleanComparator(boolean trueFirst) Gets a Comparator that can sort Boolean objects.
static <T> java.util.Comparator<T>	chainedComparator(java.util.Collection<java.util.Comparator<T>> comparators) Gets a comparator that compares using a collection of Comparators, applied in (default iterator) sequence until one returns not equal or the collection is exhausted.
static <T extends java.lang.Comparable> T	max(T o1, T o2) Returns the larger of the given objects according to the given comparator, returning the second object if the comparator returns equal.
static <T> T	max(T o1, T o2, java.util.Comparator<T> comparator) Returns the larger of the given objects according to the given comparator, returning the second object if the comparator returns equal.
static <T extends java.lang.Comparable> T	min(T o1, T o2) Returns the smaller of the given objects according to the natural sort order of the objects, returning the second object if the comparator returns equal.
static <T> T	min(T o1, T o2, java.util.Comparator<T> comparator) Returns the smaller of the given objects according to the given comparator, returning the second object if the comparator returns equal.
static <T extends java.lang.Comparable> java.util.Comparator<T>	naturalComparator() Gets a comparator that uses the natural order of the objects.
static <T extends java.lang.Comparable> java.util.Comparator<T>	nullHighComparator() Gets a Comparator that controls the comparison of null values.
static <T> java.util.Comparator<T>	nullHighComparator(java.util.Comparator<T> comparator) Gets a Comparator that controls the comparison of null values.
static <T extends java.lang.Comparable> java.util.Comparator<T>	nullLowComparator() Gets a Comparator that controls the comparison of null values.
static <T> java.util.Comparator<T>	nullLowComparator(java.util.Comparator<T> comparator) Gets a Comparator that controls the comparison of null values.
static <T extends java.lang.Comparable> java.util.Comparator<T>	reversedComparator() Gets a Comparator whose ordering is based on the reverse of the natural ordering of the compared objects.
static <T> java.util.Comparator<T>	reversedComparator(java.util.Comparator<T> comparator) Gets a Comparator that reverses the order of a specified comparator.
static <I,O> java.util.Comparator<I>	transformedComparator(java.util.Comparator<O> comparator, Transformer<I,O> transformer) Gets a Comparator that passes transformed objects to the given comparator.
static <I,O extends java.lang.Comparable> java.util.Comparator<I>	transformedComparator(Transformer<I,O> transformer) Gets a Comparator that passes transformed objects to the given comparator.

Methods inherited from class java.lang.Object

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

Constructor Detail

ComparatorUtils

protected ComparatorUtils()

Protected constructor prevents direct instantiation, but allows users to extend this library to provide their own augmented static library class.

Method Detail

naturalComparator

public static <T extends java.lang.Comparable> java.util.Comparator<T> naturalComparator()

Gets a comparator that uses the natural order of the objects.

Returns:

A comparator which uses the natural ordering of the compared objects.

chainedComparator

public static <T> java.util.Comparator<T> chainedComparator(java.util.Collection<java.util.Comparator<T>> comparators)

Gets a comparator that compares using a collection of Comparators, applied in (default iterator) sequence until one returns not equal or the collection is exhausted.

Parameters:

comparators - The Comparators to use. Cannot be null or contains any null elements. May be empty.

Returns:

A Comparator that chains together the input Comparators. When comparing two object, it will iterate through the chain, comparing the objects using each comparator in turn, and returning the first non-zero result. If the chain is exhausted and none of the Comparators returns a non-zero value, zero is returned.

Throws:

java.lang.IllegalArgumentException - If comparators is null or contains a null. It may be empty, however.

reversedComparator

public static <T extends java.lang.Comparable> java.util.Comparator<T> reversedComparator()

Gets a Comparator whose ordering is based on the reverse of the natural ordering of the compared objects.

Returns:

A Comparator whose ordering is based on the reverse of the natural ordering of the compared objects.

See Also:

ReverseComparator

reversedComparator

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

Gets a Comparator that reverses the order of a specified comparator.

Parameters:

comparator - The Comparator for which a reversed ordering is required.

Returns:

A Comparator whose ordering is the reverse of the specified input Comparator.

Throws:

java.lang.IllegalArgumentException - Thrown if the specified Comparator is null.

See Also:

ReverseComparator

booleanComparator

public static java.util.Comparator<java.lang.Boolean> booleanComparator(boolean trueFirst)

Gets a Comparator that can sort Boolean objects.

The parameter specifies whether true or false is sorted first.

The comparator throws NullPointerException if a null value is compared.

Parameters:

trueFirst - when true, sort true Boolean values before false ones.when false, sort true Boolean values after false ones.

Returns:

A Comparator that sorts Booleans.

nullLowComparator

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

Gets a Comparator that controls the comparison of null values.

The returned comparator will consider a null value to be less than any nonnull value, and equal to any other null value. Two nonnull values will be evaluated with the given comparator.

Parameters:

comparator - the comparator that wants to allow nulls

Returns:

a version of that comparator that allows nulls

See Also:

NullComparator

nullLowComparator

public static <T extends java.lang.Comparable> java.util.Comparator<T> nullLowComparator()

Gets a Comparator that controls the comparison of null values.

The returned comparator will consider a null value to be less than any nonnull value, and equal to any other null value. Two nonnull values will be evaluated according to their natural ordering.

Returns:

a version of that comparator that allows nulls

See Also:

NullComparator

nullHighComparator

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

Gets a Comparator that controls the comparison of null values.

The returned comparator will consider a null value to be greater than any nonnull value, and equal to any other null value. Two nonnull values will be evaluated with the given comparator.

Parameters:

comparator - the comparator that wants to allow nulls

Returns:

a version of that comparator that allows nulls

See Also:

NullComparator

nullHighComparator

public static <T extends java.lang.Comparable> java.util.Comparator<T> nullHighComparator()

Gets a Comparator that controls the comparison of null values.

The returned comparator will consider a null value to be greater than any nonnull value, and equal to any other null value. Two nonnull values will be evaluated according to their natural ordering.

Returns:

a version of that comparator that allows nulls

See Also:

NullComparator

transformedComparator

public static <I,O extends java.lang.Comparable> java.util.Comparator<I> transformedComparator(Transformer<I,O> transformer)

Gets a Comparator that passes transformed objects to the given comparator.

Objects passed to the returned comparator will first be transformed by the given transformer before they are compared by the given comparator.

Parameters:

transformer - the transformer to use

Returns:

a comparator that transforms its input objects before comparing them

See Also:

TransformingComparator

transformedComparator

public static <I,O> java.util.Comparator<I> transformedComparator(java.util.Comparator<O> comparator,
                                                                  Transformer<I,O> transformer)

Gets a Comparator that passes transformed objects to the given comparator.

Objects passed to the returned comparator will first be transformed by the given transformer before they are compared by the given comparator.

Parameters:

comparator - the sort order to use

transformer - the transformer to use

Returns:

a comparator that transforms its input objects before comparing them

See Also:

TransformingComparator

min

public static <T> T min(T o1,
                        T o2,
                        java.util.Comparator<T> comparator)

Returns the smaller of the given objects according to the given comparator, returning the second object if the comparator returns equal.

Parameters:

o1 - the first object to compare

o2 - the second object to compare

comparator - the sort order to use

Returns:

the smaller of the two objects

min

public static <T extends java.lang.Comparable> T min(T o1,
                                                     T o2)

Returns the smaller of the given objects according to the natural sort order of the objects, returning the second object if the comparator returns equal.

Parameters:

o1 - the first object to compare

o2 - the second object to compare

Returns:

the smaller of the two objects

max

public static <T> T max(T o1,
                        T o2,
                        java.util.Comparator<T> comparator)

Returns the larger of the given objects according to the given comparator, returning the second object if the comparator returns equal.

Parameters:

o1 - the first object to compare

o2 - the second object to compare

comparator - the sort order to use

Returns:

the larger of the two objects

max

public static <T extends java.lang.Comparable> T max(T o1,
                                                     T o2)

Returns the larger of the given objects according to the given comparator, returning the second object if the comparator returns equal.

Parameters:

o1 - the first object to compare

o2 - the second object to compare

Returns:

the larger of the two objects