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

Print this page
rev 6190 : imported patch 8001667

@@ -1,7 +1,7 @@
 /*
- * Copyright (c) 1997, 2007, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1997, 2012, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
  * under the terms of the GNU General Public License version 2 only, as
  * published by the Free Software Foundation.  Oracle designates this

@@ -23,10 +23,15 @@
  * questions.
  */
 
 package java.util;
 
+import java.util.function.Function;
+import java.util.function.IntFunction;
+import java.util.function.LongFunction;
+import java.util.function.DoubleFunction;
+
 /**
  * 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,6 +168,94 @@
      *          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);
+    }
+
+    /**
+     * Construct 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.compose(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);
+    }
+
+    /**
+     * Construct a lexicographic order comparator with a function that extracts
+     * a {@code Comparable} key.  This is essentially calling {@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 Comparators.compose(this, Comparators.comparing(keyExtractor));
+    }
+
+    /**
+     * Construct a lexicographic order comparator with a function that extracts
+     * a {@code int} value.  This is essentially calling {@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(IntFunction)
+     * @see #thenComparing(Comparator)
+     * @since 1.8
+     */
+    default Comparator<T> thenComparing(IntFunction<? super T> keyExtractor) {
+        return Comparators.compose(this, Comparators.comparing(keyExtractor));
+    }
+
+    /**
+     * Construct a lexicographic order comparator with a function that extracts
+     * a {@code long} value.  This is essentially calling {@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(LongFunction)
+     * @see #thenComparing(Comparator)
+     * @since 1.8
+     */
+    default Comparator<T> thenComparing(LongFunction<? super T> keyExtractor) {
+        return Comparators.compose(this, Comparators.comparing(keyExtractor));
+    }
+
+    /**
+     * Construct a lexicographic order comparator with a function that extracts
+     * a {@code double} value.  This is essentially calling {@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(DoubleFunction)
+     * @see #thenComparing(Comparator)
+     * @since 1.8
+     */
+    default Comparator<T> thenComparing(DoubleFunction<? super T> keyExtractor) {
+        return Comparators.compose(this, Comparators.comparing(keyExtractor));
+    }
 }