Package org.apache.commons.collections4.comparators

# Class ComparableComparator<E extends Comparable<? super E>>

java.lang.Object
org.apache.commons.collections4.comparators.ComparableComparator<E>

Type Parameters:
  `E` - The type of objects compared by this comparator

All Implemented Interfaces:
  `Serializable`, `Comparator<E>`

public class ComparableComparator<E extends Comparable<? super E>> extends Object implements Comparator<E>, Serializable
A `Comparator` that compares `Comparable` objects.

This Comparator is useful, for example, for enforcing the natural order in custom implementations of `SortedSet` and `SortedMap`.

Note: In the 2.0 and 2.1 releases of Commons Collections, this class would throw a `ClassCastException` if either of the arguments to `compare(Comparable, Comparable)` compare} were `null`, not `Comparable`, or for which `compareTo` gave inconsistent results. This is no longer the case. See `compare(Comparable, Comparable)` compare} for details.

Since:
  2.0
See Also:
  - `Collections.reverseOrder()`
  - Serialized Form

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final ComparableComparator`
  `INSTANCE`
  The singleton instance.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `ComparableComparator()`
  Constructor whose use should be avoided.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static <E extends Comparable<? super E>>
  ComparableComparator<E>`
  `comparableComparator()`
  Gets the singleton instance of a ComparableComparator.
  `int`
  `compare(E obj1, E obj2)`
  Compare the two `Comparable` arguments.
  `boolean`
  `equals(Object object)`
  Returns `true` iff that Object is a `Comparator` whose ordering is known to be equivalent to mine.
  `int`
  `hashCode()`
  Implement a hash code for this comparator that is consistent with `equals`.

  ### Methods inherited from class java.lang.Object

  `clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait`

  ### Methods inherited from interface java.util.Comparator

  `reversed, thenComparing, thenComparing, thenComparing, thenComparingDouble, thenComparingInt, thenComparingLong`

- ## Field Details

  - ### INSTANCE

    public static final ComparableComparator INSTANCE
    The singleton instance.

- ## Constructor Details

  - ### ComparableComparator

    public ComparableComparator()
    Constructor whose use should be avoided.

    Please use the `comparableComparator()` method whenever possible.

- ## Method Details

  - ### comparableComparator

    public static <E extends Comparable<? super E>> ComparableComparator<E> comparableComparator()
    Gets the singleton instance of a ComparableComparator.

    Developers are encouraged to use the comparator returned from this method instead of constructing a new instance to reduce allocation and GC overhead when multiple comparable comparators may be used in the same VM.

    Type Parameters:
      `E` - the element type
    Returns:
      The singleton ComparableComparator
    Since:
      4.0

  - ### compare

    public int compare(E obj1, E obj2)
    Compare the two `Comparable` arguments. This method is equivalent to:

        ((Comparable)obj1).compareTo(obj2)

    Specified by:
      `compare` in interface `Comparator<E extends Comparable<? super E>>`
    Parameters:
      `obj1` - The first object to compare
      `obj2` - The second object to compare
    Returns:
      negative if obj1 is less, positive if greater, zero if equal
    Throws:
      `NullPointerException` - if obj1 is `null`, or when `((Comparable)obj1).compareTo(obj2)` does
      `ClassCastException` - if obj1 is not a `Comparable`, or when `((Comparable)obj1).compareTo(obj2)` does

  - ### equals

    public boolean equals(Object object)
    Returns `true` iff that Object is a `Comparator` whose ordering is known to be equivalent to mine.

    This implementation returns `true` iff `<em>object</em>.{@link Object#getClass() getClass()}` equals `this.getClass()`. Subclasses may want to override this behavior to remain consistent with the `Comparator.equals(Object)` contract.

    Specified by:
      `equals` in interface `Comparator<E extends Comparable<? super E>>`
    Overrides:
      `equals` in class `Object`
    Parameters:
      `object` - The object to compare with
    Returns:
      `true` if equal
    Since:
      3.0

  - ### hashCode

    public int hashCode()
    Implement a hash code for this comparator that is consistent with `equals`.
    Overrides:
      `hashCode` in class `Object`
    Returns:
      A hash code for this comparator.
    Since:
      3.0