Module java.base

软件包 java.util

Interface Comparator<T>

参数类型

T - 可以由此比较器进行比较的对象的类型

所有已知实现类：

Collator ， RuleBasedCollator

Functional Interface:

这是一个功能界面，因此可以用作lambda表达式或方法引用的赋值对象。

@FunctionalInterface
public interface Comparator<T>

比较功能，对一些对象的集合施加了一个整体排序 。 比较器可以传递到排序方法（如Collections.sort或Arrays.sort ），以便对排序顺序进行精确控制。 比较器也可用于控制某些数据结构的顺序（如sorted sets或sorted maps ），或为不具有natural ordering2的对象集合提供排序。

当且仅当c.compare(e1, e2)==0具有与c.compare(e1, e2)==0相同的e1.equals(e2)值e1和e2中的S比较器c对一组元件S施加的排序被称为与等于一致 。

当使用能够强制排序不一致的比较器时，应注意使用排序集（或排序图）。 假设具有显式比较器c的排序集合（或排序映射）与从集合S绘制的元素（或键） S 。 如果c对S施加的排序与equals不一致，则排序集（或排序映射）将表现为“奇怪”。 特别是排序的集合（或排序的映射）将违反用于集合（或映射）的通用合同，其按照equals定义。

例如，假设一个将两个元件a和b使得(a.equals(b) && c.compare(a, b) != 0)到空TreeSet与比较c 。 因为a和b与树集的观点不相等，所以第二个add操作将返回true（并且树集的大小将增加），即使这与Set.add方法的规范相反。

注意：这通常是一个好主意比较，也能实现java.io.Serializable ，因为它们可能被用来作为排序的序列化数据结构的方法（比如TreeSet ， TreeMap ）。 为了使数据结构成功进行序列化，比较器（如果提供）必须实现Serializable 。

用于限定所施加的顺序 ，给定的比较器的数学倾斜，该关系 c强加一组给定对象的S是：

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

这个总订单的商是：

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

它从合同紧跟compare ，该商数是一个等价关系 S ，并且实行排序是一个总的顺序 S 。 当我们说c对S施加的排序与等于一致时 ，我们意味着排序的商是由对象' equals(Object)方法定义的等价关系：

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

与Comparable不同，比较器可以可选地允许比较空参数，同时保持对等价关系的要求。

此接口是Java Collections Framework的成员。

从以下版本开始：

1.2

另请参见：

Comparable ， Serializable

方法摘要

Modifier and Type	方法	描述
int	compare(T o1, T o2)	比较其两个参数的顺序。
static <T,U extends Comparable<? super U>> Comparator<T>	comparing(Function<? super T,? extends U> keyExtractor)	接受提取功能Comparable从类型排序键T ，并返回一个Comparator<T> ，通过那种关键的。
static <T,U> Comparator<T>	comparing(Function<? super T,? extends U> keyExtractor, Comparator<? super U> keyComparator)	接受从类型T提取排序键的功能，并返回一个Comparator<T> ，使用指定的Comparator比较该排序键。
static <T> Comparator<T>	comparingDouble(ToDoubleFunction<? super T> keyExtractor)	接受提取功能 double从类型排序键 T ，并返回一个 Comparator<T> ，通过那种关键的。
static <T> Comparator<T>	comparingInt(ToIntFunction<? super T> keyExtractor)	接受从类型 T中提取 int排序键的功能，并返回一个按该排序键进行比较的 Comparator<T> 。
static <T> Comparator<T>	comparingLong(ToLongFunction<? super T> keyExtractor)	接受提取功能 long从类型排序键 T ，并返回一个 Comparator<T> ，通过那种关键的。
boolean	equals(Object obj)	指示某个其他对象是否等于此比较器。
static <T extends Comparable<? super T>> Comparator<T>	naturalOrder()	返回一个以自然顺序比较Comparable对象的比较器。
static <T> Comparator<T>	nullsFirst(Comparator<? super T> comparator)	返回一个非常友好的比较器， null考虑为小于非空值。
static <T> Comparator<T>	nullsLast(Comparator<? super T> comparator)	返回一个比较友好的比较器， null设置为大于非空值。
default Comparator<T>	reversed()	返回一个比较器，强制该比较器的相反顺序。
static <T extends Comparable<? super T>> Comparator<T>	reverseOrder()	返回一个与 自然排序相反的比较器。
default Comparator<T>	thenComparing(Comparator<? super T> other)	用另一个比较器返回一个字典顺序比较器。
default <U extends Comparable<? super U>> Comparator<T>	thenComparing(Function<? super T,? extends U> keyExtractor)	返回具有提取 Comparable排序键的功能的字典顺序比较器。
default <U> Comparator<T>	thenComparing(Function<? super T,? extends U> keyExtractor, Comparator<? super U> keyComparator)	返回具有提取要与给定的 Comparator进行比较的键的函数的词典顺序比较器。
default Comparator<T>	thenComparingDouble(ToDoubleFunction<? super T> keyExtractor)	返回具有提取 double排序键的功能的字典顺序比较器。
default Comparator<T>	thenComparingInt(ToIntFunction<? super T> keyExtractor)	返回具有提取 int排序键的功能的字典顺序比较器。
default Comparator<T>	thenComparingLong(ToLongFunction<? super T> keyExtractor)	返回具有提取 long排序键的功能的字典顺序比较器。

方法详细信息

compare

int compare(T o1,
            T o2)

比较其两个参数的顺序。 返回负整数，零或正整数，因为第一个参数小于，等于或大于第二个参数。

实施者必须确保sgn(compare(x, y)) == -sgn(compare(y, x))全部为x和y 。 （这意味着当且仅当compare(y, x)引发异常时， compare(x, y)必须抛出异常。）

实施者还必须确保关系是可传递的： ((compare(x, y)>0) && (compare(y, z)>0))意味着compare(x, z)>0 。

最后，实施者必须确保compare(x, y)==0意味着sgn(compare(x, z))==sgn(compare(y, z))全部为z 。

一般情况，但不是严格要求(compare(x, y)==0) == (x.equals(y)) 。 一般而言，任何违反这种情况的比较方都应清楚地表明这一点。 推荐的语言是“注意：该比较器强制与等于”不一致的排序“。

在前面的描述中，符号sgn( 表达 )表示数学符号函数，其被定义为返回之一-1 ， 0 ，或1分别根据表达式的值是否为负，零或正。

参数

o1 - 要比较的第一个对象。

o2 - 要比较的第二个对象。

结果

第一个参数的负整数，零或正整数小于等于或大于第二个参数。

异常

NullPointerException - 如果参数为空，并且此比较器不允许空参数

ClassCastException - 如果参数的类型阻止它们被比较器进行比较。

equals

boolean equals(Object obj)

指示某个其他对象是否等于此比较器。 该方法必须符合Object.equals(Object)的一般合同。 另外， 只有指定的对象也是一个比较器，这个方法只能返回true ，它和这个比较器的顺序相同。 因此， comp1.equals(comp2)意味着sgn(comp1.compare(o1, o2))==sgn(comp2.compare(o1, o2))的每个对象的参考o1和o2 。

请注意， 始终安全不要覆盖Object.equals(Object) 。 然而，在某些情况下，覆盖此方法可以通过允许程序确定两个不同的比较器施加相同的顺序来提高性能。

重写：

equals在 Object

参数

obj - 与之比较的参考对象。

结果

true只有指定的对象也是一个比较器，并且它施加与这个比较器相同的顺序。

另请参见：

Object.equals(Object) ， Object.hashCode()

reversed

default Comparator<T> reversed()

返回一个比较器，强制该比较器的相反顺序。

结果

一个比较器，使比较器的顺序相反。

从以下版本开始：

1.8

thenComparing

default Comparator<T> thenComparing(Comparator<? super T> other)

用另一个比较器返回一个字典顺序比较器。 如果此Comparator认为两个元件相等，即compare(a, b) == 0 ， other被用来确定顺序。

如果指定的比较器也可串行化，则返回的比较器是可序列化的。

API Note:

例如，为了对基于长度进行排序String ，然后对不区分大小写的自然排序进行排序，比较器可以使用以下代码组成，

   Comparator<String> cmp = Comparator.comparingInt(String::length) .thenComparing(String.CASE_INSENSITIVE_ORDER);  

参数

other - 当比较器比较两个相等的对象时要使用的另一个比较器。

结果

一个由这个和另一个比较器组成的字典顺序比较器

异常

NullPointerException - 如果参数为空。

从以下版本开始：

1.8

thenComparing

default <U> Comparator<T> thenComparing(Function<? super T,? extends U> keyExtractor,
                                        Comparator<? super U> keyComparator)

返回具有提取要与给定的 Comparator比较的键的函数的词典顺序比较器。

实现要求：

此默认实现的行为就像 thenComparing(comparing(keyExtractor, cmp)) 。

参数类型

U - 排序键的类型

参数

keyExtractor - 用于提取排序键的函数

keyComparator - 用于比较排序键的 Comparator

结果

一个字典顺序比较器由该比较器组成，然后对由KeyExtractor函数提取的关键字进行比较

异常

NullPointerException - 如果任一参数为空。

从以下版本开始：

1.8

另请参见：

comparing(Function, Comparator) ， thenComparing(Comparator)

thenComparing

default <U extends Comparable<? super U>> Comparator<T> thenComparing(Function<? super T,? extends U> keyExtractor)

返回具有提取 Comparable排序键的功能的字典顺序比较器。

实现要求：

此默认实现的行为就像 thenComparing(comparing(keyExtractor)) 。

参数类型

U - Comparable排序键的类型

参数

keyExtractor - 用于提取Comparable排序键的功能

结果

一个字典顺序比较器由此组成，然后是Comparable排序键。

异常

NullPointerException - 如果参数为空。

从以下版本开始：

1.8

另请参见：

comparing(Function) ， thenComparing(Comparator)

thenComparingInt

default Comparator<T> thenComparingInt(ToIntFunction<? super T> keyExtractor)

返回具有提取 int排序键的功能的字典顺序比较器。

实现要求：

此默认实现的行为就像 thenComparing(comparingInt(keyExtractor)) 。

参数

keyExtractor - 用于提取整数排序键的函数

结果

一个字典顺序比较器由此组成，然后是 int排序键

异常

NullPointerException - 如果参数为空。

从以下版本开始：

1.8

另请参见：

comparingInt(ToIntFunction) ， thenComparing(Comparator)

thenComparingLong

default Comparator<T> thenComparingLong(ToLongFunction<? super T> keyExtractor)

返回具有提取 long排序键的功能的字典顺序比较器。

实现要求：

此默认实现的行为就像 thenComparing(comparingLong(keyExtractor)) 。

参数

keyExtractor - 用于提取长排序键的函数

结果

一个字典顺序比较器由此组成，然后是 long排序键

异常

NullPointerException - 如果参数为空。

从以下版本开始：

1.8

另请参见：

comparingLong(ToLongFunction) ， thenComparing(Comparator)

thenComparingDouble

default Comparator<T> thenComparingDouble(ToDoubleFunction<? super T> keyExtractor)

返回具有提取 double排序键的功能的字典顺序比较器。

实现要求：

此默认实现的行为就像 thenComparing(comparingDouble(keyExtractor)) 。

参数

keyExtractor - 用于提取双排序键的函数

结果

一个字典顺序比较器由此组成，然后是 double排序键

异常

NullPointerException - 如果参数为空。

从以下版本开始：

1.8

另请参见：

comparingDouble(ToDoubleFunction) ， thenComparing(Comparator)

reverseOrder

static <T extends Comparable<? super T>> Comparator<T> reverseOrder()

返回一个与自然排序相反的比较器。

返回的比较器是可序列化，并引发NullPointerException比较时null 。

参数类型

T - 要比较的Comparable类型的元素

结果

一个对 Comparable对象施加与 自然排序相反的比较器。

从以下版本开始：

1.8

另请参见：

Comparable

naturalOrder

static <T extends Comparable<? super T>> Comparator<T> naturalOrder()

返回一个以自然顺序比较Comparable对象的比较器。

返回的比较器是可序列化，并引发NullPointerException比较时null 。

参数类型

T - 要比较的Comparable类型的元素

结果

一个对 Comparable对象施加 自然排序的比较器。

从以下版本开始：

1.8

另请参见：

Comparable

nullsFirst

static <T> Comparator<T> nullsFirst(Comparator<? super T> comparator)

返回一个非常友好的比较器， null视为小于非空值。 当两者都是null ，它们被认为是相等的。 如果两者均为非空值，则使用指定的Comparator来确定顺序。 如果指定的比较器是null ，则返回的比较器将所有非空值视为相等。

如果指定的比较器可串行化，则返回的比较器是可序列化的。

参数类型

T - 要比较的元素的类型

参数

comparator - a Comparator用于比较非空值

结果

一个将 null考虑为小于非空的比较器，并将非空对象与所提供的 Comparator进行比较。

从以下版本开始：

1.8

nullsLast

static <T> Comparator<T> nullsLast(Comparator<? super T> comparator)

返回一个比较友好的比较器， null设置为大于非空值。 当两者都是null ，它们被认为是相等的。 如果两者均为非空值，则使用指定的Comparator来确定顺序。 如果指定的比较器是null ，则返回的比较器将所有非空值都认为是相等的。

如果指定的比较器可串行化，则返回的比较器是可序列化的。

参数类型

T - 要比较的元素的类型

参数

comparator - 用于比较非空值的 Comparator

结果

一个比较器，认为 null大于非空，并将非空对象与所提供的 Comparator进行比较。

从以下版本开始：

1.8

comparing

static <T,U> Comparator<T> comparing(Function<? super T,? extends U> keyExtractor,
                                     Comparator<? super U> keyComparator)

接受从类型T中提取排序键的T ，并返回一个Comparator<T> ，该数据使用指定的Comparator进行比较。

如果指定的功能和比较器都可串行化，则返回的比较器是可序列化的。

API Note:

例如，要获得Comparator比较Person对象的姓氏忽略大小写差异，

   Comparator<Person> cmp = Comparator.comparing( Person::getLastName, String.CASE_INSENSITIVE_ORDER);  

参数类型

T - 要比较的元素的类型

U - 排序键的类型

参数

keyExtractor - 用于提取排序键的函数

keyComparator - 用于比较排序键的 Comparator

结果

比较器使用指定的 Comparator与提取的密钥进行比较

异常

NullPointerException - 如果任一参数为空

从以下版本开始：

1.8

comparing

static <T,U extends Comparable<? super U>> Comparator<T> comparing(Function<? super T,? extends U> keyExtractor)

接受从T类型中提取Comparable排序键的T ，并返回一个按该排序键进行比较的Comparator<T> 。

如果指定的功能也可串行化，则返回的比较器是可序列化的。

API Note:

例如，要获得一个Comparator ，它比较了Person对象的姓氏，

   Comparator<Person> byLastName = Comparator.comparing(Person::getLastName);  

参数类型

T - 要比较的元素的类型

U - Comparable排序键的类型

参数

keyExtractor - 用于提取Comparable排序键的功能

结果

比较器，其被提取的密钥进行比较

异常

NullPointerException - 如果参数为空

从以下版本开始：

1.8

comparingInt

static <T> Comparator<T> comparingInt(ToIntFunction<? super T> keyExtractor)

接受提取的一个函数int从类型分类键T ，并返回一个Comparator<T> ，通过该排序关键字进行比较。

如果指定的功能也可串行化，则返回的比较器是可序列化的。

参数类型

T - 要比较的元素的类型

参数

keyExtractor - 用于提取整数排序键的函数

结果

比较器，其被提取的密钥进行比较

异常

NullPointerException - 如果参数为空

从以下版本开始：

1.8

另请参见：

comparing(Function)

comparingLong

static <T> Comparator<T> comparingLong(ToLongFunction<? super T> keyExtractor)

接受提取功能long从类型排序键T ，并返回一个Comparator<T> ，通过那种关键的。

如果指定的功能也可串行化，则返回的比较器是可序列化的。

参数类型

T - 要比较的元素的类型

参数

keyExtractor - 用于提取长排序键的函数

结果

比较器，其被提取的密钥进行比较

异常

NullPointerException - 如果参数为null

从以下版本开始：

1.8

另请参见：

comparing(Function)

comparingDouble

static <T> Comparator<T> comparingDouble(ToDoubleFunction<? super T> keyExtractor)

接受从类型T中提取double排序键的T ，并返回一个按该排序键进行比较的Comparator<T> 。

如果指定的功能也可串行化，则返回的比较器是可序列化的。

参数类型

T - 要比较的元素的类型

参数

keyExtractor - 用于提取双排序键的函数

结果

比较器，其被提取的密钥进行比较

异常

NullPointerException - 如果参数为空

从以下版本开始：

1.8

另请参见：

comparing(Function)