77  * given set of objects {@code S} is:<pre>
  78  *       {(x, y) such that c.compare(x, y) &lt;= 0}.
  79  * </pre> The <i>quotient</i> for this total order is:<pre>
  80  *       {(x, y) such that c.compare(x, y) == 0}.
  81  * </pre>
  82  *
  83  * It follows immediately from the contract for {@code compare} that the
  84  * quotient is an <i>equivalence relation</i> on {@code S}, and that the
  85  * imposed ordering is a <i>total order</i> on {@code S}.  When we say that
  86  * the ordering imposed by {@code c} on {@code S} is <i>consistent with
  87  * equals</i>, we mean that the quotient for the ordering is the equivalence
  88  * relation defined by the objects' {@link Object#equals(Object)
  89  * equals(Object)} method(s):<pre>
  90  *     {(x, y) such that x.equals(y)}. </pre>
  91  *
  92  * <p>Unlike {@code Comparable}, a comparator may optionally permit
  93  * comparison of null arguments, while maintaining the requirements for
  94  * an equivalence relation.
  95  *
  96  * <p>This interface is a member of the
  97  * <a href="{@docRoot}/java/util/package-summary.html#CollectionsFramework">
  98  * Java Collections Framework</a>.
  99  *
 100  * @param <T> the type of objects that may be compared by this comparator
 101  *
 102  * @author  Josh Bloch
 103  * @author  Neal Gafter
 104  * @see Comparable
 105  * @see java.io.Serializable
 106  * @since 1.2
 107  */
 108 @FunctionalInterface
 109 public interface Comparator<T> {
 110     /**
 111      * Compares its two arguments for order.  Returns a negative integer,
 112      * zero, or a positive integer as the first argument is less than, equal
 113      * to, or greater than the second.<p>
 114      *
 115      * The implementor must ensure that {@code sgn(compare(x, y)) ==
 116      * -sgn(compare(y, x))} for all {@code x} and {@code y}.  (This
 117      * implies that {@code compare(x, y)} must throw an exception if and only

  77  * given set of objects {@code S} is:<pre>
  78  *       {(x, y) such that c.compare(x, y) &lt;= 0}.
  79  * </pre> The <i>quotient</i> for this total order is:<pre>
  80  *       {(x, y) such that c.compare(x, y) == 0}.
  81  * </pre>
  82  *
  83  * It follows immediately from the contract for {@code compare} that the
  84  * quotient is an <i>equivalence relation</i> on {@code S}, and that the
  85  * imposed ordering is a <i>total order</i> on {@code S}.  When we say that
  86  * the ordering imposed by {@code c} on {@code S} is <i>consistent with
  87  * equals</i>, we mean that the quotient for the ordering is the equivalence
  88  * relation defined by the objects' {@link Object#equals(Object)
  89  * equals(Object)} method(s):<pre>
  90  *     {(x, y) such that x.equals(y)}. </pre>
  91  *
  92  * <p>Unlike {@code Comparable}, a comparator may optionally permit
  93  * comparison of null arguments, while maintaining the requirements for
  94  * an equivalence relation.
  95  *
  96  * <p>This interface is a member of the
  97  * <a href="{@docRoot}/java.base/java/util/package-summary.html#CollectionsFramework">
  98  * Java Collections Framework</a>.
  99  *
 100  * @param <T> the type of objects that may be compared by this comparator
 101  *
 102  * @author  Josh Bloch
 103  * @author  Neal Gafter
 104  * @see Comparable
 105  * @see java.io.Serializable
 106  * @since 1.2
 107  */
 108 @FunctionalInterface
 109 public interface Comparator<T> {
 110     /**
 111      * Compares its two arguments for order.  Returns a negative integer,
 112      * zero, or a positive integer as the first argument is less than, equal
 113      * to, or greater than the second.<p>
 114      *
 115      * The implementor must ensure that {@code sgn(compare(x, y)) ==
 116      * -sgn(compare(y, x))} for all {@code x} and {@code y}.  (This
 117      * implies that {@code compare(x, y)} must throw an exception if and only