jdk/src/java.base/share/classes/java/util/Comparator.java
author mchung
Fri, 22 May 2015 16:43:39 -0700
changeset 30789 9eca83469588
parent 25859 3317bb8137f4
child 32108 aa5490a167ee
permissions -rw-r--r--
8074431: Remove native2ascii tool Reviewed-by: erikj, alanb, okutsu, mfang, naoto
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
     1
/*
22944
a9e7afb60f4f 8033590: java.util.Comparator::thenComparing has unnecessary type restriction
henryjen
parents: 19867
diff changeset
     2
 * Copyright (c) 1997, 2014, Oracle and/or its affiliates. All rights reserved.
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
     3
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
90ce3da70b43 Initial load
duke
parents:
diff changeset
     4
 *
90ce3da70b43 Initial load
duke
parents:
diff changeset
     5
 * This code is free software; you can redistribute it and/or modify it
90ce3da70b43 Initial load
duke
parents:
diff changeset
     6
 * under the terms of the GNU General Public License version 2 only, as
5506
202f599c92aa 6943119: Rebrand source copyright notices
ohair
parents: 2
diff changeset
     7
 * published by the Free Software Foundation.  Oracle designates this
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
     8
 * particular file as subject to the "Classpath" exception as provided
5506
202f599c92aa 6943119: Rebrand source copyright notices
ohair
parents: 2
diff changeset
     9
 * by Oracle in the LICENSE file that accompanied this code.
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
    10
 *
90ce3da70b43 Initial load
duke
parents:
diff changeset
    11
 * This code is distributed in the hope that it will be useful, but WITHOUT
90ce3da70b43 Initial load
duke
parents:
diff changeset
    12
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
90ce3da70b43 Initial load
duke
parents:
diff changeset
    13
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
90ce3da70b43 Initial load
duke
parents:
diff changeset
    14
 * version 2 for more details (a copy is included in the LICENSE file that
90ce3da70b43 Initial load
duke
parents:
diff changeset
    15
 * accompanied this code).
90ce3da70b43 Initial load
duke
parents:
diff changeset
    16
 *
90ce3da70b43 Initial load
duke
parents:
diff changeset
    17
 * You should have received a copy of the GNU General Public License version
90ce3da70b43 Initial load
duke
parents:
diff changeset
    18
 * 2 along with this work; if not, write to the Free Software Foundation,
90ce3da70b43 Initial load
duke
parents:
diff changeset
    19
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    20
 *
5506
202f599c92aa 6943119: Rebrand source copyright notices
ohair
parents: 2
diff changeset
    21
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
202f599c92aa 6943119: Rebrand source copyright notices
ohair
parents: 2
diff changeset
    22
 * or visit www.oracle.com if you need additional information or have any
202f599c92aa 6943119: Rebrand source copyright notices
ohair
parents: 2
diff changeset
    23
 * questions.
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
    24
 */
90ce3da70b43 Initial load
duke
parents:
diff changeset
    25
90ce3da70b43 Initial load
duke
parents:
diff changeset
    26
package java.util;
90ce3da70b43 Initial load
duke
parents:
diff changeset
    27
18571
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
    28
import java.io.Serializable;
16064
ef93558b0d63 8001667: Comparator combinators and extension methods
mduigou
parents: 15647
diff changeset
    29
import java.util.function.Function;
ef93558b0d63 8001667: Comparator combinators and extension methods
mduigou
parents: 15647
diff changeset
    30
import java.util.function.ToIntFunction;
ef93558b0d63 8001667: Comparator combinators and extension methods
mduigou
parents: 15647
diff changeset
    31
import java.util.function.ToLongFunction;
ef93558b0d63 8001667: Comparator combinators and extension methods
mduigou
parents: 15647
diff changeset
    32
import java.util.function.ToDoubleFunction;
18571
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
    33
import java.util.Comparators;
16064
ef93558b0d63 8001667: Comparator combinators and extension methods
mduigou
parents: 15647
diff changeset
    34
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
    35
/**
90ce3da70b43 Initial load
duke
parents:
diff changeset
    36
 * A comparison function, which imposes a <i>total ordering</i> on some
90ce3da70b43 Initial load
duke
parents:
diff changeset
    37
 * collection of objects.  Comparators can be passed to a sort method (such
90ce3da70b43 Initial load
duke
parents:
diff changeset
    38
 * as {@link Collections#sort(List,Comparator) Collections.sort} or {@link
90ce3da70b43 Initial load
duke
parents:
diff changeset
    39
 * Arrays#sort(Object[],Comparator) Arrays.sort}) to allow precise control
90ce3da70b43 Initial load
duke
parents:
diff changeset
    40
 * over the sort order.  Comparators can also be used to control the order of
90ce3da70b43 Initial load
duke
parents:
diff changeset
    41
 * certain data structures (such as {@link SortedSet sorted sets} or {@link
90ce3da70b43 Initial load
duke
parents:
diff changeset
    42
 * SortedMap sorted maps}), or to provide an ordering for collections of
90ce3da70b43 Initial load
duke
parents:
diff changeset
    43
 * objects that don't have a {@link Comparable natural ordering}.<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    44
 *
90ce3da70b43 Initial load
duke
parents:
diff changeset
    45
 * The ordering imposed by a comparator <tt>c</tt> on a set of elements
90ce3da70b43 Initial load
duke
parents:
diff changeset
    46
 * <tt>S</tt> is said to be <i>consistent with equals</i> if and only if
90ce3da70b43 Initial load
duke
parents:
diff changeset
    47
 * <tt>c.compare(e1, e2)==0</tt> has the same boolean value as
90ce3da70b43 Initial load
duke
parents:
diff changeset
    48
 * <tt>e1.equals(e2)</tt> for every <tt>e1</tt> and <tt>e2</tt> in
90ce3da70b43 Initial load
duke
parents:
diff changeset
    49
 * <tt>S</tt>.<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    50
 *
90ce3da70b43 Initial load
duke
parents:
diff changeset
    51
 * Caution should be exercised when using a comparator capable of imposing an
90ce3da70b43 Initial load
duke
parents:
diff changeset
    52
 * ordering inconsistent with equals to order a sorted set (or sorted map).
90ce3da70b43 Initial load
duke
parents:
diff changeset
    53
 * Suppose a sorted set (or sorted map) with an explicit comparator <tt>c</tt>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    54
 * is used with elements (or keys) drawn from a set <tt>S</tt>.  If the
90ce3da70b43 Initial load
duke
parents:
diff changeset
    55
 * ordering imposed by <tt>c</tt> on <tt>S</tt> is inconsistent with equals,
90ce3da70b43 Initial load
duke
parents:
diff changeset
    56
 * the sorted set (or sorted map) will behave "strangely."  In particular the
90ce3da70b43 Initial load
duke
parents:
diff changeset
    57
 * sorted set (or sorted map) will violate the general contract for set (or
90ce3da70b43 Initial load
duke
parents:
diff changeset
    58
 * map), which is defined in terms of <tt>equals</tt>.<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    59
 *
90ce3da70b43 Initial load
duke
parents:
diff changeset
    60
 * For example, suppose one adds two elements {@code a} and {@code b} such that
90ce3da70b43 Initial load
duke
parents:
diff changeset
    61
 * {@code (a.equals(b) && c.compare(a, b) != 0)}
90ce3da70b43 Initial load
duke
parents:
diff changeset
    62
 * to an empty {@code TreeSet} with comparator {@code c}.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    63
 * The second {@code add} operation will return
90ce3da70b43 Initial load
duke
parents:
diff changeset
    64
 * true (and the size of the tree set will increase) because {@code a} and
90ce3da70b43 Initial load
duke
parents:
diff changeset
    65
 * {@code b} are not equivalent from the tree set's perspective, even though
90ce3da70b43 Initial load
duke
parents:
diff changeset
    66
 * this is contrary to the specification of the
90ce3da70b43 Initial load
duke
parents:
diff changeset
    67
 * {@link Set#add Set.add} method.<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    68
 *
90ce3da70b43 Initial load
duke
parents:
diff changeset
    69
 * Note: It is generally a good idea for comparators to also implement
90ce3da70b43 Initial load
duke
parents:
diff changeset
    70
 * <tt>java.io.Serializable</tt>, as they may be used as ordering methods in
90ce3da70b43 Initial load
duke
parents:
diff changeset
    71
 * serializable data structures (like {@link TreeSet}, {@link TreeMap}).  In
90ce3da70b43 Initial load
duke
parents:
diff changeset
    72
 * order for the data structure to serialize successfully, the comparator (if
90ce3da70b43 Initial load
duke
parents:
diff changeset
    73
 * provided) must implement <tt>Serializable</tt>.<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    74
 *
90ce3da70b43 Initial load
duke
parents:
diff changeset
    75
 * For the mathematically inclined, the <i>relation</i> that defines the
90ce3da70b43 Initial load
duke
parents:
diff changeset
    76
 * <i>imposed ordering</i> that a given comparator <tt>c</tt> imposes on a
90ce3da70b43 Initial load
duke
parents:
diff changeset
    77
 * given set of objects <tt>S</tt> is:<pre>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    78
 *       {(x, y) such that c.compare(x, y) &lt;= 0}.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    79
 * </pre> The <i>quotient</i> for this total order is:<pre>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    80
 *       {(x, y) such that c.compare(x, y) == 0}.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    81
 * </pre>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    82
 *
90ce3da70b43 Initial load
duke
parents:
diff changeset
    83
 * It follows immediately from the contract for <tt>compare</tt> that the
90ce3da70b43 Initial load
duke
parents:
diff changeset
    84
 * quotient is an <i>equivalence relation</i> on <tt>S</tt>, and that the
90ce3da70b43 Initial load
duke
parents:
diff changeset
    85
 * imposed ordering is a <i>total order</i> on <tt>S</tt>.  When we say that
90ce3da70b43 Initial load
duke
parents:
diff changeset
    86
 * the ordering imposed by <tt>c</tt> on <tt>S</tt> is <i>consistent with
90ce3da70b43 Initial load
duke
parents:
diff changeset
    87
 * equals</i>, we mean that the quotient for the ordering is the equivalence
90ce3da70b43 Initial load
duke
parents:
diff changeset
    88
 * relation defined by the objects' {@link Object#equals(Object)
90ce3da70b43 Initial load
duke
parents:
diff changeset
    89
 * equals(Object)} method(s):<pre>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    90
 *     {(x, y) such that x.equals(y)}. </pre>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    91
 *
90ce3da70b43 Initial load
duke
parents:
diff changeset
    92
 * <p>Unlike {@code Comparable}, a comparator may optionally permit
90ce3da70b43 Initial load
duke
parents:
diff changeset
    93
 * comparison of null arguments, while maintaining the requirements for
90ce3da70b43 Initial load
duke
parents:
diff changeset
    94
 * an equivalence relation.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    95
 *
90ce3da70b43 Initial load
duke
parents:
diff changeset
    96
 * <p>This interface is a member of the
90ce3da70b43 Initial load
duke
parents:
diff changeset
    97
 * <a href="{@docRoot}/../technotes/guides/collections/index.html">
90ce3da70b43 Initial load
duke
parents:
diff changeset
    98
 * Java Collections Framework</a>.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    99
 *
90ce3da70b43 Initial load
duke
parents:
diff changeset
   100
 * @param <T> the type of objects that may be compared by this comparator
90ce3da70b43 Initial load
duke
parents:
diff changeset
   101
 *
90ce3da70b43 Initial load
duke
parents:
diff changeset
   102
 * @author  Josh Bloch
90ce3da70b43 Initial load
duke
parents:
diff changeset
   103
 * @author  Neal Gafter
90ce3da70b43 Initial load
duke
parents:
diff changeset
   104
 * @see Comparable
90ce3da70b43 Initial load
duke
parents:
diff changeset
   105
 * @see java.io.Serializable
90ce3da70b43 Initial load
duke
parents:
diff changeset
   106
 * @since 1.2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   107
 */
15647
314007859004 8005623: Retrofit FunctionalInterface annotations to core platform interfaces
darcy
parents: 5506
diff changeset
   108
@FunctionalInterface
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   109
public interface Comparator<T> {
90ce3da70b43 Initial load
duke
parents:
diff changeset
   110
    /**
90ce3da70b43 Initial load
duke
parents:
diff changeset
   111
     * Compares its two arguments for order.  Returns a negative integer,
90ce3da70b43 Initial load
duke
parents:
diff changeset
   112
     * zero, or a positive integer as the first argument is less than, equal
90ce3da70b43 Initial load
duke
parents:
diff changeset
   113
     * to, or greater than the second.<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   114
     *
90ce3da70b43 Initial load
duke
parents:
diff changeset
   115
     * In the foregoing description, the notation
90ce3da70b43 Initial load
duke
parents:
diff changeset
   116
     * <tt>sgn(</tt><i>expression</i><tt>)</tt> designates the mathematical
90ce3da70b43 Initial load
duke
parents:
diff changeset
   117
     * <i>signum</i> function, which is defined to return one of <tt>-1</tt>,
90ce3da70b43 Initial load
duke
parents:
diff changeset
   118
     * <tt>0</tt>, or <tt>1</tt> according to whether the value of
90ce3da70b43 Initial load
duke
parents:
diff changeset
   119
     * <i>expression</i> is negative, zero or positive.<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   120
     *
90ce3da70b43 Initial load
duke
parents:
diff changeset
   121
     * The implementor must ensure that <tt>sgn(compare(x, y)) ==
90ce3da70b43 Initial load
duke
parents:
diff changeset
   122
     * -sgn(compare(y, x))</tt> for all <tt>x</tt> and <tt>y</tt>.  (This
90ce3da70b43 Initial load
duke
parents:
diff changeset
   123
     * implies that <tt>compare(x, y)</tt> must throw an exception if and only
90ce3da70b43 Initial load
duke
parents:
diff changeset
   124
     * if <tt>compare(y, x)</tt> throws an exception.)<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   125
     *
90ce3da70b43 Initial load
duke
parents:
diff changeset
   126
     * The implementor must also ensure that the relation is transitive:
90ce3da70b43 Initial load
duke
parents:
diff changeset
   127
     * <tt>((compare(x, y)&gt;0) &amp;&amp; (compare(y, z)&gt;0))</tt> implies
90ce3da70b43 Initial load
duke
parents:
diff changeset
   128
     * <tt>compare(x, z)&gt;0</tt>.<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   129
     *
90ce3da70b43 Initial load
duke
parents:
diff changeset
   130
     * Finally, the implementor must ensure that <tt>compare(x, y)==0</tt>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   131
     * implies that <tt>sgn(compare(x, z))==sgn(compare(y, z))</tt> for all
90ce3da70b43 Initial load
duke
parents:
diff changeset
   132
     * <tt>z</tt>.<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   133
     *
90ce3da70b43 Initial load
duke
parents:
diff changeset
   134
     * It is generally the case, but <i>not</i> strictly required that
90ce3da70b43 Initial load
duke
parents:
diff changeset
   135
     * <tt>(compare(x, y)==0) == (x.equals(y))</tt>.  Generally speaking,
90ce3da70b43 Initial load
duke
parents:
diff changeset
   136
     * any comparator that violates this condition should clearly indicate
90ce3da70b43 Initial load
duke
parents:
diff changeset
   137
     * this fact.  The recommended language is "Note: this comparator
90ce3da70b43 Initial load
duke
parents:
diff changeset
   138
     * imposes orderings that are inconsistent with equals."
90ce3da70b43 Initial load
duke
parents:
diff changeset
   139
     *
90ce3da70b43 Initial load
duke
parents:
diff changeset
   140
     * @param o1 the first object to be compared.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   141
     * @param o2 the second object to be compared.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   142
     * @return a negative integer, zero, or a positive integer as the
90ce3da70b43 Initial load
duke
parents:
diff changeset
   143
     *         first argument is less than, equal to, or greater than the
90ce3da70b43 Initial load
duke
parents:
diff changeset
   144
     *         second.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   145
     * @throws NullPointerException if an argument is null and this
90ce3da70b43 Initial load
duke
parents:
diff changeset
   146
     *         comparator does not permit null arguments
90ce3da70b43 Initial load
duke
parents:
diff changeset
   147
     * @throws ClassCastException if the arguments' types prevent them from
90ce3da70b43 Initial load
duke
parents:
diff changeset
   148
     *         being compared by this comparator.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   149
     */
90ce3da70b43 Initial load
duke
parents:
diff changeset
   150
    int compare(T o1, T o2);
90ce3da70b43 Initial load
duke
parents:
diff changeset
   151
90ce3da70b43 Initial load
duke
parents:
diff changeset
   152
    /**
90ce3da70b43 Initial load
duke
parents:
diff changeset
   153
     * Indicates whether some other object is &quot;equal to&quot; this
90ce3da70b43 Initial load
duke
parents:
diff changeset
   154
     * comparator.  This method must obey the general contract of
90ce3da70b43 Initial load
duke
parents:
diff changeset
   155
     * {@link Object#equals(Object)}.  Additionally, this method can return
90ce3da70b43 Initial load
duke
parents:
diff changeset
   156
     * <tt>true</tt> <i>only</i> if the specified object is also a comparator
90ce3da70b43 Initial load
duke
parents:
diff changeset
   157
     * and it imposes the same ordering as this comparator.  Thus,
90ce3da70b43 Initial load
duke
parents:
diff changeset
   158
     * <code>comp1.equals(comp2)</code> implies that <tt>sgn(comp1.compare(o1,
90ce3da70b43 Initial load
duke
parents:
diff changeset
   159
     * o2))==sgn(comp2.compare(o1, o2))</tt> for every object reference
90ce3da70b43 Initial load
duke
parents:
diff changeset
   160
     * <tt>o1</tt> and <tt>o2</tt>.<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   161
     *
90ce3da70b43 Initial load
duke
parents:
diff changeset
   162
     * Note that it is <i>always</i> safe <i>not</i> to override
90ce3da70b43 Initial load
duke
parents:
diff changeset
   163
     * <tt>Object.equals(Object)</tt>.  However, overriding this method may,
90ce3da70b43 Initial load
duke
parents:
diff changeset
   164
     * in some cases, improve performance by allowing programs to determine
90ce3da70b43 Initial load
duke
parents:
diff changeset
   165
     * that two distinct comparators impose the same order.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   166
     *
90ce3da70b43 Initial load
duke
parents:
diff changeset
   167
     * @param   obj   the reference object with which to compare.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   168
     * @return  <code>true</code> only if the specified object is also
90ce3da70b43 Initial load
duke
parents:
diff changeset
   169
     *          a comparator and it imposes the same ordering as this
90ce3da70b43 Initial load
duke
parents:
diff changeset
   170
     *          comparator.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   171
     * @see Object#equals(Object)
90ce3da70b43 Initial load
duke
parents:
diff changeset
   172
     * @see Object#hashCode()
90ce3da70b43 Initial load
duke
parents:
diff changeset
   173
     */
90ce3da70b43 Initial load
duke
parents:
diff changeset
   174
    boolean equals(Object obj);
16064
ef93558b0d63 8001667: Comparator combinators and extension methods
mduigou
parents: 15647
diff changeset
   175
ef93558b0d63 8001667: Comparator combinators and extension methods
mduigou
parents: 15647
diff changeset
   176
    /**
ef93558b0d63 8001667: Comparator combinators and extension methods
mduigou
parents: 15647
diff changeset
   177
     * Returns a comparator that imposes the reverse ordering of this
ef93558b0d63 8001667: Comparator combinators and extension methods
mduigou
parents: 15647
diff changeset
   178
     * comparator.
ef93558b0d63 8001667: Comparator combinators and extension methods
mduigou
parents: 15647
diff changeset
   179
     *
18571
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   180
     * @return a comparator that imposes the reverse ordering of this
16064
ef93558b0d63 8001667: Comparator combinators and extension methods
mduigou
parents: 15647
diff changeset
   181
     *         comparator.
ef93558b0d63 8001667: Comparator combinators and extension methods
mduigou
parents: 15647
diff changeset
   182
     * @since 1.8
ef93558b0d63 8001667: Comparator combinators and extension methods
mduigou
parents: 15647
diff changeset
   183
     */
18571
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   184
    default Comparator<T> reversed() {
16064
ef93558b0d63 8001667: Comparator combinators and extension methods
mduigou
parents: 15647
diff changeset
   185
        return Collections.reverseOrder(this);
ef93558b0d63 8001667: Comparator combinators and extension methods
mduigou
parents: 15647
diff changeset
   186
    }
ef93558b0d63 8001667: Comparator combinators and extension methods
mduigou
parents: 15647
diff changeset
   187
ef93558b0d63 8001667: Comparator combinators and extension methods
mduigou
parents: 15647
diff changeset
   188
    /**
18571
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   189
     * Returns a lexicographic-order comparator with another comparator.
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   190
     * If this {@code Comparator} considers two elements equal, i.e.
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   191
     * {@code compare(a, b) == 0}, {@code other} is used to determine the order.
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   192
     *
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   193
     * <p>The returned comparator is serializable if the specified comparator
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   194
     * is also serializable.
16064
ef93558b0d63 8001667: Comparator combinators and extension methods
mduigou
parents: 15647
diff changeset
   195
     *
18571
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   196
     * @apiNote
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   197
     * For example, to sort a collection of {@code String} based on the length
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   198
     * and then case-insensitive natural ordering, the comparator can be
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   199
     * composed using following code,
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   200
     *
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   201
     * <pre>{@code
19605
0f98f8e3bdcb 8023528: Rename Comparator combinators to disambiguate overloading methods
henryjen
parents: 19208
diff changeset
   202
     *     Comparator<String> cmp = Comparator.comparingInt(String::length)
18571
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   203
     *             .thenComparing(String.CASE_INSENSITIVE_ORDER);
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   204
     * }</pre>
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   205
     *
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   206
     * @param  other the other comparator to be used when this comparator
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   207
     *         compares two objects that are equal.
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   208
     * @return a lexicographic-order comparator composed of this and then the
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   209
     *         other comparator
16064
ef93558b0d63 8001667: Comparator combinators and extension methods
mduigou
parents: 15647
diff changeset
   210
     * @throws NullPointerException if the argument is null.
ef93558b0d63 8001667: Comparator combinators and extension methods
mduigou
parents: 15647
diff changeset
   211
     * @since 1.8
ef93558b0d63 8001667: Comparator combinators and extension methods
mduigou
parents: 15647
diff changeset
   212
     */
ef93558b0d63 8001667: Comparator combinators and extension methods
mduigou
parents: 15647
diff changeset
   213
    default Comparator<T> thenComparing(Comparator<? super T> other) {
18571
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   214
        Objects.requireNonNull(other);
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   215
        return (Comparator<T> & Serializable) (c1, c2) -> {
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   216
            int res = compare(c1, c2);
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   217
            return (res != 0) ? res : other.compare(c1, c2);
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   218
        };
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   219
    }
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   220
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   221
    /**
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   222
     * Returns a lexicographic-order comparator with a function that
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   223
     * extracts a key to be compared with the given {@code Comparator}.
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   224
     *
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   225
     * @implSpec This default implementation behaves as if {@code
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   226
     *           thenComparing(comparing(keyExtractor, cmp))}.
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   227
     *
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   228
     * @param  <U>  the type of the sort key
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   229
     * @param  keyExtractor the function used to extract the sort key
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   230
     * @param  keyComparator the {@code Comparator} used to compare the sort key
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   231
     * @return a lexicographic-order comparator composed of this comparator
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   232
     *         and then comparing on the key extracted by the keyExtractor function
19867
9918d2d14f78 8024874: Copy-paste typo in the spec for j.u.Comparator.thenComparing(Function, Comparator)
henryjen
parents: 19605
diff changeset
   233
     * @throws NullPointerException if either argument is null.
18571
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   234
     * @see #comparing(Function, Comparator)
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   235
     * @see #thenComparing(Comparator)
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   236
     * @since 1.8
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   237
     */
22944
a9e7afb60f4f 8033590: java.util.Comparator::thenComparing has unnecessary type restriction
henryjen
parents: 19867
diff changeset
   238
    default <U> Comparator<T> thenComparing(
18571
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   239
            Function<? super T, ? extends U> keyExtractor,
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   240
            Comparator<? super U> keyComparator)
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   241
    {
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   242
        return thenComparing(comparing(keyExtractor, keyComparator));
16064
ef93558b0d63 8001667: Comparator combinators and extension methods
mduigou
parents: 15647
diff changeset
   243
    }
ef93558b0d63 8001667: Comparator combinators and extension methods
mduigou
parents: 15647
diff changeset
   244
ef93558b0d63 8001667: Comparator combinators and extension methods
mduigou
parents: 15647
diff changeset
   245
    /**
18571
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   246
     * Returns a lexicographic-order comparator with a function that
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   247
     * extracts a {@code Comparable} sort key.
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   248
     *
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   249
     * @implSpec This default implementation behaves as if {@code
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   250
     *           thenComparing(comparing(keyExtractor))}.
16064
ef93558b0d63 8001667: Comparator combinators and extension methods
mduigou
parents: 15647
diff changeset
   251
     *
18571
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   252
     * @param  <U>  the type of the {@link Comparable} sort key
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   253
     * @param  keyExtractor the function used to extract the {@link
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   254
     *         Comparable} sort key
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   255
     * @return a lexicographic-order comparator composed of this and then the
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   256
     *         {@link Comparable} sort key.
16064
ef93558b0d63 8001667: Comparator combinators and extension methods
mduigou
parents: 15647
diff changeset
   257
     * @throws NullPointerException if the argument is null.
18571
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   258
     * @see #comparing(Function)
16064
ef93558b0d63 8001667: Comparator combinators and extension methods
mduigou
parents: 15647
diff changeset
   259
     * @see #thenComparing(Comparator)
ef93558b0d63 8001667: Comparator combinators and extension methods
mduigou
parents: 15647
diff changeset
   260
     * @since 1.8
ef93558b0d63 8001667: Comparator combinators and extension methods
mduigou
parents: 15647
diff changeset
   261
     */
18571
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   262
    default <U extends Comparable<? super U>> Comparator<T> thenComparing(
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   263
            Function<? super T, ? extends U> keyExtractor)
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   264
    {
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   265
        return thenComparing(comparing(keyExtractor));
16064
ef93558b0d63 8001667: Comparator combinators and extension methods
mduigou
parents: 15647
diff changeset
   266
    }
ef93558b0d63 8001667: Comparator combinators and extension methods
mduigou
parents: 15647
diff changeset
   267
ef93558b0d63 8001667: Comparator combinators and extension methods
mduigou
parents: 15647
diff changeset
   268
    /**
18571
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   269
     * Returns a lexicographic-order comparator with a function that
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   270
     * extracts a {@code int} sort key.
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   271
     *
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   272
     * @implSpec This default implementation behaves as if {@code
19605
0f98f8e3bdcb 8023528: Rename Comparator combinators to disambiguate overloading methods
henryjen
parents: 19208
diff changeset
   273
     *           thenComparing(comparingInt(keyExtractor))}.
16064
ef93558b0d63 8001667: Comparator combinators and extension methods
mduigou
parents: 15647
diff changeset
   274
     *
18571
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   275
     * @param  keyExtractor the function used to extract the integer sort key
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   276
     * @return a lexicographic-order comparator composed of this and then the
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   277
     *         {@code int} sort key
16064
ef93558b0d63 8001667: Comparator combinators and extension methods
mduigou
parents: 15647
diff changeset
   278
     * @throws NullPointerException if the argument is null.
19605
0f98f8e3bdcb 8023528: Rename Comparator combinators to disambiguate overloading methods
henryjen
parents: 19208
diff changeset
   279
     * @see #comparingInt(ToIntFunction)
16064
ef93558b0d63 8001667: Comparator combinators and extension methods
mduigou
parents: 15647
diff changeset
   280
     * @see #thenComparing(Comparator)
ef93558b0d63 8001667: Comparator combinators and extension methods
mduigou
parents: 15647
diff changeset
   281
     * @since 1.8
ef93558b0d63 8001667: Comparator combinators and extension methods
mduigou
parents: 15647
diff changeset
   282
     */
19605
0f98f8e3bdcb 8023528: Rename Comparator combinators to disambiguate overloading methods
henryjen
parents: 19208
diff changeset
   283
    default Comparator<T> thenComparingInt(ToIntFunction<? super T> keyExtractor) {
0f98f8e3bdcb 8023528: Rename Comparator combinators to disambiguate overloading methods
henryjen
parents: 19208
diff changeset
   284
        return thenComparing(comparingInt(keyExtractor));
16064
ef93558b0d63 8001667: Comparator combinators and extension methods
mduigou
parents: 15647
diff changeset
   285
    }
ef93558b0d63 8001667: Comparator combinators and extension methods
mduigou
parents: 15647
diff changeset
   286
ef93558b0d63 8001667: Comparator combinators and extension methods
mduigou
parents: 15647
diff changeset
   287
    /**
18571
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   288
     * Returns a lexicographic-order comparator with a function that
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   289
     * extracts a {@code long} sort key.
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   290
     *
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   291
     * @implSpec This default implementation behaves as if {@code
19605
0f98f8e3bdcb 8023528: Rename Comparator combinators to disambiguate overloading methods
henryjen
parents: 19208
diff changeset
   292
     *           thenComparing(comparingLong(keyExtractor))}.
16064
ef93558b0d63 8001667: Comparator combinators and extension methods
mduigou
parents: 15647
diff changeset
   293
     *
18571
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   294
     * @param  keyExtractor the function used to extract the long sort key
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   295
     * @return a lexicographic-order comparator composed of this and then the
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   296
     *         {@code long} sort key
16064
ef93558b0d63 8001667: Comparator combinators and extension methods
mduigou
parents: 15647
diff changeset
   297
     * @throws NullPointerException if the argument is null.
19605
0f98f8e3bdcb 8023528: Rename Comparator combinators to disambiguate overloading methods
henryjen
parents: 19208
diff changeset
   298
     * @see #comparingLong(ToLongFunction)
16064
ef93558b0d63 8001667: Comparator combinators and extension methods
mduigou
parents: 15647
diff changeset
   299
     * @see #thenComparing(Comparator)
ef93558b0d63 8001667: Comparator combinators and extension methods
mduigou
parents: 15647
diff changeset
   300
     * @since 1.8
ef93558b0d63 8001667: Comparator combinators and extension methods
mduigou
parents: 15647
diff changeset
   301
     */
19605
0f98f8e3bdcb 8023528: Rename Comparator combinators to disambiguate overloading methods
henryjen
parents: 19208
diff changeset
   302
    default Comparator<T> thenComparingLong(ToLongFunction<? super T> keyExtractor) {
0f98f8e3bdcb 8023528: Rename Comparator combinators to disambiguate overloading methods
henryjen
parents: 19208
diff changeset
   303
        return thenComparing(comparingLong(keyExtractor));
16064
ef93558b0d63 8001667: Comparator combinators and extension methods
mduigou
parents: 15647
diff changeset
   304
    }
ef93558b0d63 8001667: Comparator combinators and extension methods
mduigou
parents: 15647
diff changeset
   305
ef93558b0d63 8001667: Comparator combinators and extension methods
mduigou
parents: 15647
diff changeset
   306
    /**
18571
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   307
     * Returns a lexicographic-order comparator with a function that
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   308
     * extracts a {@code double} sort key.
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   309
     *
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   310
     * @implSpec This default implementation behaves as if {@code
19605
0f98f8e3bdcb 8023528: Rename Comparator combinators to disambiguate overloading methods
henryjen
parents: 19208
diff changeset
   311
     *           thenComparing(comparingDouble(keyExtractor))}.
16064
ef93558b0d63 8001667: Comparator combinators and extension methods
mduigou
parents: 15647
diff changeset
   312
     *
18571
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   313
     * @param  keyExtractor the function used to extract the double sort key
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   314
     * @return a lexicographic-order comparator composed of this and then the
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   315
     *         {@code double} sort key
16064
ef93558b0d63 8001667: Comparator combinators and extension methods
mduigou
parents: 15647
diff changeset
   316
     * @throws NullPointerException if the argument is null.
19605
0f98f8e3bdcb 8023528: Rename Comparator combinators to disambiguate overloading methods
henryjen
parents: 19208
diff changeset
   317
     * @see #comparingDouble(ToDoubleFunction)
16064
ef93558b0d63 8001667: Comparator combinators and extension methods
mduigou
parents: 15647
diff changeset
   318
     * @see #thenComparing(Comparator)
ef93558b0d63 8001667: Comparator combinators and extension methods
mduigou
parents: 15647
diff changeset
   319
     * @since 1.8
ef93558b0d63 8001667: Comparator combinators and extension methods
mduigou
parents: 15647
diff changeset
   320
     */
19605
0f98f8e3bdcb 8023528: Rename Comparator combinators to disambiguate overloading methods
henryjen
parents: 19208
diff changeset
   321
    default Comparator<T> thenComparingDouble(ToDoubleFunction<? super T> keyExtractor) {
0f98f8e3bdcb 8023528: Rename Comparator combinators to disambiguate overloading methods
henryjen
parents: 19208
diff changeset
   322
        return thenComparing(comparingDouble(keyExtractor));
18571
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   323
    }
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   324
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   325
    /**
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   326
     * Returns a comparator that imposes the reverse of the <em>natural
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   327
     * ordering</em>.
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   328
     *
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   329
     * <p>The returned comparator is serializable and throws {@link
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   330
     * NullPointerException} when comparing {@code null}.
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   331
     *
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   332
     * @param  <T> the {@link Comparable} type of element to be compared
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   333
     * @return a comparator that imposes the reverse of the <i>natural
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   334
     *         ordering</i> on {@code Comparable} objects.
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   335
     * @see Comparable
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   336
     * @since 1.8
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   337
     */
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   338
    public static <T extends Comparable<? super T>> Comparator<T> reverseOrder() {
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   339
        return Collections.reverseOrder();
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   340
    }
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   341
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   342
    /**
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   343
     * Returns a comparator that compares {@link Comparable} objects in natural
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   344
     * order.
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   345
     *
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   346
     * <p>The returned comparator is serializable and throws {@link
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   347
     * NullPointerException} when comparing {@code null}.
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   348
     *
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   349
     * @param  <T> the {@link Comparable} type of element to be compared
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   350
     * @return a comparator that imposes the <i>natural ordering</i> on {@code
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   351
     *         Comparable} objects.
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   352
     * @see Comparable
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   353
     * @since 1.8
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   354
     */
19208
1e3d351eba80 8022412: Fixed warnings in java.util root, except for HashMap
lagergren
parents: 18571
diff changeset
   355
    @SuppressWarnings("unchecked")
18571
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   356
    public static <T extends Comparable<? super T>> Comparator<T> naturalOrder() {
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   357
        return (Comparator<T>) Comparators.NaturalOrderComparator.INSTANCE;
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   358
    }
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   359
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   360
    /**
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   361
     * Returns a null-friendly comparator that considers {@code null} to be
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   362
     * less than non-null. When both are {@code null}, they are considered
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   363
     * equal. If both are non-null, the specified {@code Comparator} is used
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   364
     * to determine the order. If the specified comparator is {@code null},
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   365
     * then the returned comparator considers all non-null values to be equal.
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   366
     *
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   367
     * <p>The returned comparator is serializable if the specified comparator
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   368
     * is serializable.
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   369
     *
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   370
     * @param  <T> the type of the elements to be compared
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   371
     * @param  comparator a {@code Comparator} for comparing non-null values
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   372
     * @return a comparator that considers {@code null} to be less than
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   373
     *         non-null, and compares non-null objects with the supplied
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   374
     *         {@code Comparator}.
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   375
     * @since 1.8
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   376
     */
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   377
    public static <T> Comparator<T> nullsFirst(Comparator<? super T> comparator) {
19208
1e3d351eba80 8022412: Fixed warnings in java.util root, except for HashMap
lagergren
parents: 18571
diff changeset
   378
        return new Comparators.NullComparator<>(true, comparator);
18571
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   379
    }
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   380
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   381
    /**
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   382
     * Returns a null-friendly comparator that considers {@code null} to be
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   383
     * greater than non-null. When both are {@code null}, they are considered
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   384
     * equal. If both are non-null, the specified {@code Comparator} is used
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   385
     * to determine the order. If the specified comparator is {@code null},
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   386
     * then the returned comparator considers all non-null values to be equal.
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   387
     *
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   388
     * <p>The returned comparator is serializable if the specified comparator
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   389
     * is serializable.
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   390
     *
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   391
     * @param  <T> the type of the elements to be compared
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   392
     * @param  comparator a {@code Comparator} for comparing non-null values
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   393
     * @return a comparator that considers {@code null} to be greater than
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   394
     *         non-null, and compares non-null objects with the supplied
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   395
     *         {@code Comparator}.
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   396
     * @since 1.8
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   397
     */
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   398
    public static <T> Comparator<T> nullsLast(Comparator<? super T> comparator) {
19208
1e3d351eba80 8022412: Fixed warnings in java.util root, except for HashMap
lagergren
parents: 18571
diff changeset
   399
        return new Comparators.NullComparator<>(false, comparator);
18571
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   400
    }
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   401
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   402
    /**
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   403
     * Accepts a function that extracts a sort key from a type {@code T}, and
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   404
     * returns a {@code Comparator<T>} that compares by that sort key using
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   405
     * the specified {@link Comparator}.
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   406
      *
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   407
     * <p>The returned comparator is serializable if the specified function
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   408
     * and comparator are both serializable.
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   409
     *
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   410
     * @apiNote
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   411
     * For example, to obtain a {@code Comparator} that compares {@code
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   412
     * Person} objects by their last name ignoring case differences,
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   413
     *
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   414
     * <pre>{@code
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   415
     *     Comparator<Person> cmp = Comparator.comparing(
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   416
     *             Person::getLastName,
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   417
     *             String.CASE_INSENSITIVE_ORDER);
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   418
     * }</pre>
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   419
     *
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   420
     * @param  <T> the type of element to be compared
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   421
     * @param  <U> the type of the sort key
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   422
     * @param  keyExtractor the function used to extract the sort key
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   423
     * @param  keyComparator the {@code Comparator} used to compare the sort key
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   424
     * @return a comparator that compares by an extracted key using the
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   425
     *         specified {@code Comparator}
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   426
     * @throws NullPointerException if either argument is null
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   427
     * @since 1.8
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   428
     */
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   429
    public static <T, U> Comparator<T> comparing(
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   430
            Function<? super T, ? extends U> keyExtractor,
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   431
            Comparator<? super U> keyComparator)
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   432
    {
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   433
        Objects.requireNonNull(keyExtractor);
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   434
        Objects.requireNonNull(keyComparator);
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   435
        return (Comparator<T> & Serializable)
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   436
            (c1, c2) -> keyComparator.compare(keyExtractor.apply(c1),
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   437
                                              keyExtractor.apply(c2));
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   438
    }
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   439
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   440
    /**
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   441
     * Accepts a function that extracts a {@link java.lang.Comparable
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   442
     * Comparable} sort key from a type {@code T}, and returns a {@code
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   443
     * Comparator<T>} that compares by that sort key.
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   444
     *
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   445
     * <p>The returned comparator is serializable if the specified function
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   446
     * is also serializable.
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   447
     *
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   448
     * @apiNote
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   449
     * For example, to obtain a {@code Comparator} that compares {@code
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   450
     * Person} objects by their last name,
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   451
     *
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   452
     * <pre>{@code
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   453
     *     Comparator<Person> byLastName = Comparator.comparing(Person::getLastName);
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   454
     * }</pre>
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   455
     *
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   456
     * @param  <T> the type of element to be compared
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   457
     * @param  <U> the type of the {@code Comparable} sort key
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   458
     * @param  keyExtractor the function used to extract the {@link
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   459
     *         Comparable} sort key
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   460
     * @return a comparator that compares by an extracted key
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   461
     * @throws NullPointerException if the argument is null
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   462
     * @since 1.8
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   463
     */
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   464
    public static <T, U extends Comparable<? super U>> Comparator<T> comparing(
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   465
            Function<? super T, ? extends U> keyExtractor)
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   466
    {
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   467
        Objects.requireNonNull(keyExtractor);
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   468
        return (Comparator<T> & Serializable)
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   469
            (c1, c2) -> keyExtractor.apply(c1).compareTo(keyExtractor.apply(c2));
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   470
    }
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   471
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   472
    /**
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   473
     * Accepts a function that extracts an {@code int} sort key from a type
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   474
     * {@code T}, and returns a {@code Comparator<T>} that compares by that
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   475
     * sort key.
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   476
     *
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   477
     * <p>The returned comparator is serializable if the specified function
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   478
     * is also serializable.
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   479
     *
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   480
     * @param  <T> the type of element to be compared
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   481
     * @param  keyExtractor the function used to extract the integer sort key
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   482
     * @return a comparator that compares by an extracted key
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   483
     * @see #comparing(Function)
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   484
     * @throws NullPointerException if the argument is null
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   485
     * @since 1.8
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   486
     */
19605
0f98f8e3bdcb 8023528: Rename Comparator combinators to disambiguate overloading methods
henryjen
parents: 19208
diff changeset
   487
    public static <T> Comparator<T> comparingInt(ToIntFunction<? super T> keyExtractor) {
18571
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   488
        Objects.requireNonNull(keyExtractor);
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   489
        return (Comparator<T> & Serializable)
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   490
            (c1, c2) -> Integer.compare(keyExtractor.applyAsInt(c1), keyExtractor.applyAsInt(c2));
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   491
    }
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   492
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   493
    /**
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   494
     * Accepts a function that extracts a {@code long} sort key from a type
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   495
     * {@code T}, and returns a {@code Comparator<T>} that compares by that
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   496
     * sort key.
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   497
     *
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   498
     * <p>The returned comparator is serializable if the specified function is
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   499
     * also serializable.
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   500
     *
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   501
     * @param  <T> the type of element to be compared
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   502
     * @param  keyExtractor the function used to extract the long sort key
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   503
     * @return a comparator that compares by an extracted key
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   504
     * @see #comparing(Function)
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   505
     * @throws NullPointerException if the argument is null
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   506
     * @since 1.8
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   507
     */
19605
0f98f8e3bdcb 8023528: Rename Comparator combinators to disambiguate overloading methods
henryjen
parents: 19208
diff changeset
   508
    public static <T> Comparator<T> comparingLong(ToLongFunction<? super T> keyExtractor) {
18571
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   509
        Objects.requireNonNull(keyExtractor);
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   510
        return (Comparator<T> & Serializable)
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   511
            (c1, c2) -> Long.compare(keyExtractor.applyAsLong(c1), keyExtractor.applyAsLong(c2));
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   512
    }
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   513
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   514
    /**
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   515
     * Accepts a function that extracts a {@code double} sort key from a type
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   516
     * {@code T}, and returns a {@code Comparator<T>} that compares by that
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   517
     * sort key.
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   518
     *
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   519
     * <p>The returned comparator is serializable if the specified function
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   520
     * is also serializable.
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   521
     *
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   522
     * @param  <T> the type of element to be compared
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   523
     * @param  keyExtractor the function used to extract the double sort key
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   524
     * @return a comparator that compares by an extracted key
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   525
     * @see #comparing(Function)
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   526
     * @throws NullPointerException if the argument is null
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   527
     * @since 1.8
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   528
     */
19605
0f98f8e3bdcb 8023528: Rename Comparator combinators to disambiguate overloading methods
henryjen
parents: 19208
diff changeset
   529
    public static<T> Comparator<T> comparingDouble(ToDoubleFunction<? super T> keyExtractor) {
18571
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   530
        Objects.requireNonNull(keyExtractor);
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   531
        return (Comparator<T> & Serializable)
8e3cb3c46ae8 8009736: Comparator API cleanup
henryjen
parents: 16064
diff changeset
   532
            (c1, c2) -> Double.compare(keyExtractor.applyAsDouble(c1), keyExtractor.applyAsDouble(c2));
16064
ef93558b0d63 8001667: Comparator combinators and extension methods
mduigou
parents: 15647
diff changeset
   533
    }
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   534
}