*
* The ordering imposed by a comparator `c` on a set of elements
* `S` is said to be *consistent with equals* if and only if
* `c.compare(e1, e2)==0` has the same boolean value as
* `e1.equals(e2)` for every `e1` and `e2` in
* `S`.

*
* Caution should be exercised when using a comparator capable of imposing an
* ordering inconsistent with equals to order a sorted set (or sorted map).
* Suppose a sorted set (or sorted map) with an explicit comparator `c`
* is used with elements (or keys) drawn from a set `S`. If the
* ordering imposed by `c` on `S` is inconsistent with equals,
* the sorted set (or sorted map) will behave "strangely." In particular the
* sorted set (or sorted map) will violate the general contract for set (or
* map), which is defined in terms of `equals`.

* * For example, suppose one adds two elements {@code a} and {@code b} such that * {@code (a.equals(b) && c.compare(a, b) != 0)} * to an empty {@code TreeSet} with comparator {@code c}. * The second {@code add} operation will return * true (and the size of the tree set will increase) because {@code a} and * {@code b} are not equivalent from the tree set's perspective, even though * this is contrary to the specification of the * {@link Set#add Set.add} method.

*
* Note: It is generally a good idea for comparators to also implement
* `java.io.Serializable`, as they may be used as ordering methods in
* serializable data structures (like {@link TreeSet}, {@link TreeMap}). In
* order for the data structure to serialize successfully, the comparator (if
* provided) must implement `Serializable`.

*
* For the mathematically inclined, the *relation* that defines the
* *imposed ordering* that a given comparator `c` imposes on a
* given set of objects `S` is:

* {(x, y) such that c.compare(x, y) <= 0}. *The

* {(x, y) such that c.compare(x, y) == 0}. ** * It follows immediately from the contract for

* {(x, y) such that x.equals(y)}.* *

Unlike {@code Comparable}, a comparator may optionally permit * comparison of null arguments, while maintaining the requirements for * an equivalence relation. * *

This interface is a member of the
*
* Java Collections Framework.
*
* @param

*
* In the foregoing description, the notation
* `sgn(`*expression*`)` designates the mathematical
* *signum* function, which is defined to return one of `-1`,
* `0`, or `1` according to whether the value of
* *expression* is negative, zero or positive.

*
* The implementor must ensure that `sgn(compare(x, y)) ==
* -sgn(compare(y, x))` for all `x` and `y`. (This
* implies that `compare(x, y)` must throw an exception if and only
* if `compare(y, x)` throws an exception.)

*
* The implementor must also ensure that the relation is transitive:
* `((compare(x, y)>0) && (compare(y, z)>0))` implies
* `compare(x, z)>0`.

*
* Finally, the implementor must ensure that `compare(x, y)==0`
* implies that `sgn(compare(x, z))==sgn(compare(y, z))` for all
* `z`.

*
* It is generally the case, but *not* strictly required that
* `(compare(x, y)==0) == (x.equals(y))`. Generally speaking,
* any comparator that violates this condition should clearly indicate
* this fact. The recommended language is "Note: this comparator
* imposes orderings that are inconsistent with equals."
*
* @param o1 the first object to be compared.
* @param o2 the second object to be compared.
* @return a negative integer, zero, or a positive integer as the
* first argument is less than, equal to, or greater than the
* second.
* @throws NullPointerException if an argument is null and this
* comparator does not permit null arguments
* @throws ClassCastException if the arguments' types prevent them from
* being compared by this comparator.
*/
int compare(T o1, T o2);
/**
* Indicates whether some other object is "equal to" this
* comparator. This method must obey the general contract of
* {@link Object#equals(Object)}. Additionally, this method can return
* `true` *only* if the specified object is also a comparator
* and it imposes the same ordering as this comparator. Thus,
* `comp1.equals(comp2)`

implies that `sgn(comp1.compare(o1,
* o2))==sgn(comp2.compare(o1, o2))` for every object reference
* `o1` and `o2`.

*
* Note that it is *always* safe *not* to override
* `Object.equals(Object)`. However, overriding this method may,
* in some cases, improve performance by allowing programs to determine
* that two distinct comparators impose the same order.
*
* @param obj the reference object with which to compare.
* @return `true`

only if the specified object is also
* a comparator and it imposes the same ordering as this
* comparator.
* @see Object#equals(Object)
* @see Object#hashCode()
*/
boolean equals(Object obj);
/**
* Returns a comparator that imposes the reverse ordering of this
* comparator.
*
* @return a comparator that imposes the reverse ordering of this
* comparator.
* @since 1.8
*/
default Comparator

The returned comparator is serializable if the specified comparator * is also serializable. * * @apiNote * For example, to sort a collection of {@code String} based on the length * and then case-insensitive natural ordering, the comparator can be * composed using following code, * *

{@code * Comparator* * @param other the other comparator to be used when this comparator * compares two objects that are equal. * @return a lexicographic-order comparator composed of this and then the * other comparator * @throws NullPointerException if the argument is null. * @since 1.8 */ default Comparatorcmp = Comparator.comparingInt(String::length) * .thenComparing(String.CASE_INSENSITIVE_ORDER); * }

The returned comparator is serializable and throws {@link
* NullPointerException} when comparing {@code null}.
*
* @param *natural
* ordering* on {@code Comparable} objects.
* @see Comparable
* @since 1.8
*/
public static

The returned comparator is serializable and throws {@link
* NullPointerException} when comparing {@code null}.
*
* @param *natural ordering* on {@code
* Comparable} objects.
* @see Comparable
* @since 1.8
*/
@SuppressWarnings("unchecked")
public static

The returned comparator is serializable if the specified comparator
* is serializable.
*
* @param

The returned comparator is serializable if the specified comparator
* is serializable.
*
* @param

The returned comparator is serializable if the specified function * and comparator are both serializable. * * @apiNote * For example, to obtain a {@code Comparator} that compares {@code * Person} objects by their last name ignoring case differences, * *

{@code * Comparator* * @paramcmp = Comparator.comparing( * Person::getLastName, * String.CASE_INSENSITIVE_ORDER); * }

The returned comparator is serializable if the specified function * is also serializable. * * @apiNote * For example, to obtain a {@code Comparator} that compares {@code * Person} objects by their last name, * *

{@code * Comparator* * @parambyLastName = Comparator.comparing(Person::getLastName); * }

The returned comparator is serializable if the specified function
* is also serializable.
*
* @param

The returned comparator is serializable if the specified function is
* also serializable.
*
* @param

The returned comparator is serializable if the specified function
* is also serializable.
*
* @param