src/share/classes/java/util/Comparator.java

rev 6620 : 8001667: Comparator combinators and extension methods
Reviewed-by: mduigou, briangoetz
Contributed-by: henry.jen@oracle.com

*** 23,32 ****
--- 23,37 ----
   * questions.
   */
  
  package java.util;
  
+ import java.util.function.Function;
+ import java.util.function.ToIntFunction;
+ import java.util.function.ToLongFunction;
+ import java.util.function.ToDoubleFunction;
+ 
  /**
   * A comparison function, which imposes a <i>total ordering</i> on some
   * collection of objects.  Comparators can be passed to a sort method (such
   * as {@link Collections#sort(List,Comparator) Collections.sort} or {@link
   * Arrays#sort(Object[],Comparator) Arrays.sort}) to allow precise control
*** 163,168 ****
--- 168,262 ----
       *          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<T> reverseOrder() {
+         return Collections.reverseOrder(this);
+     }
+ 
+     /**
+      * Constructs a lexicographic order comparator with another comparator.
+      * For example, a {@code Comparator<Person> byLastName} can be composed
+      * with another {@code Comparator<Person> byFirstName}, then {@code
+      * byLastName.thenComparing(byFirstName)} creates a {@code
+      * Comparator<Person>} which sorts by last name, and for equal last names
+      * sorts by first name.
+      *
+      * @param other the other comparator used when equals on this.
+      * @throws NullPointerException if the argument is null.
+      * @since 1.8
+      */
+     default Comparator<T> thenComparing(Comparator<? super T> other) {
+         return Comparators.compose(this, other);
+     }
+ 
+     /**
+      * Constructs a lexicographic order comparator with a function that
+      * extracts a {@code Comparable} key.  This default implementation calls
+      * {@code thenComparing(this, Comparators.comparing(keyExtractor))}.
+      *
+      * @param <U> the {@link Comparable} type for comparison
+      * @param keyExtractor the function used to extract the {@link Comparable} sort key
+      * @throws NullPointerException if the argument is null.
+      * @see Comparators#comparing(Function)
+      * @see #thenComparing(Comparator)
+      * @since 1.8
+      */
+     default <U extends Comparable<? super U>> Comparator<T> thenComparing(Function<? super T, ? extends U> keyExtractor) {
+         return thenComparing(Comparators.comparing(keyExtractor));
+     }
+ 
+     /**
+      * Constructs a lexicographic order comparator with a function that
+      * extracts a {@code int} value.  This default implementation calls {@code
+      * thenComparing(this, Comparators.comparing(keyExtractor))}.
+      *
+      * @param keyExtractor the function used to extract the integer value
+      * @throws NullPointerException if the argument is null.
+      * @see Comparators#comparing(ToIntFunction)
+      * @see #thenComparing(Comparator)
+      * @since 1.8
+      */
+     default Comparator<T> thenComparing(ToIntFunction<? super T> keyExtractor) {
+         return thenComparing(Comparators.comparing(keyExtractor));
+     }
+ 
+     /**
+      * Constructs a lexicographic order comparator with a function that
+      * extracts a {@code long} value.  This default implementation calls
+      * {@code thenComparing(this, Comparators.comparing(keyExtractor))}.
+      *
+      * @param keyExtractor the function used to extract the long value
+      * @throws NullPointerException if the argument is null.
+      * @see Comparators#comparing(ToLongFunction)
+      * @see #thenComparing(Comparator)
+      * @since 1.8
+      */
+     default Comparator<T> thenComparing(ToLongFunction<? super T> keyExtractor) {
+         return thenComparing(Comparators.comparing(keyExtractor));
+     }
+ 
+     /**
+      * Constructs a lexicographic order comparator with a function that
+      * extracts a {@code double} value.  This default implementation calls
+      * {@code thenComparing(this, Comparators.comparing(keyExtractor))}.
+      *
+      * @param keyExtractor the function used to extract the double value
+      * @throws NullPointerException if the argument is null.
+      * @see Comparators#comparing(ToDoubleFunction)
+      * @see #thenComparing(Comparator)
+      * @since 1.8
+      */
+     default Comparator<T> thenComparing(ToDoubleFunction<? super T> keyExtractor) {
+         return thenComparing(Comparators.comparing(keyExtractor));
+     }
  }