鸿蒙OS Comparator

Comparator

@FunctionalInterface
public interface Comparator<T>

一个比较函数，它对某些对象集合进行总排序。比较器可以传递给排序方法（例如 Collections#sort(List,Comparator) 或 [Arrays#sort(Object],Comparator)），以允许精确控制排序顺序。比较器还可用于控制某些数据结构（例如 SortedSet 或 SortedMap）的顺序，或者为没有 Comparable 的对象集合提供排序。

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

当使用能够施加与等于不一致的排序的比较器来对排序集（或排序映射）进行排序时，应谨慎行事。假设带有显式比较器 c 的有序集合（或有序映射）与从集合 S 中提取的元素（或键）一起使用。如果 c 对 S 施加的排序与 equals 不一致，则有序集合（或有序映射）将表现得“奇怪”。特别是有序集合（或有序映射）将违反集合（或映射）的一般合同，它是根据等式定义的。

例如，假设将两个元素 a 和 b 相加，使得 (a.equals(b) && c.compare(a, b) != 0) 到具有比较器 c 的空 TreeSet。第二个 add 操作将返回 true（并且树集的大小将增加），因为从树集的角度来看 a 和 b 不等价，即使这与 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}. 

立即从比较契约得出，商是 S 上的等价关系，并且强加的排序是 S 上的全排序。当我们说 c 对 S 强加的排序与 equals 一致时，我们的意思是 排序的商是对象的 Object#equals(Object) 方法定义的等价关系：

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

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

此接口是 Java 集合框架的成员。

方法总结

修饰符和类型	方法	描述
int	compare(T o1, T o2)	比较它的两个参数的顺序。
static <T,U extends Comparable<? super U>>Comparator<T>	comparing(Function<? super T,? extends U> keyExtractor)	接受从类型 T 中提取 Comparable 排序键的函数，并返回按该排序键进行比较的 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)	接受一个从类型 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)	接受从类型 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 友好的比较器，它认为 null 小于非 null。
static <T> Comparator<T>	nullsLast(Comparator<? super T> comparator)	返回一个 null 友好的比较器，它认为 null 大于非 null。
default ComparatorT	reversed()	返回一个强制此比较器反向排序的比较器。
static <T extends Comparable<? super T>>Comparator<T>	reverseOrder()	返回一个强制与自然顺序相反的比较器。
default ComparatorT	thenComparing(Comparator<? super T> other)	返回具有另一个比较器的字典顺序比较器。
default <U extends Comparable<? super U>>ComparatorT	thenComparing(Function<? super T,? extends U> keyExtractor)	返回具有提取 Comparable 排序键的函数的字典顺序比较器。
default <U> ComparatorT	thenComparing(Function<? super T,? extends U> keyExtractor, Comparator<? super U> keyComparator)	返回一个字典顺序比较器，其函数提取要与给定比较器比较的键。
default ComparatorT	thenComparingDouble(ToDoubleFunction<? super T> keyExtractor)	返回具有提取双排序键的函数的字典顺序比较器。
default ComparatorT	thenComparingInt(ToIntFunction<? super T> keyExtractor)	返回具有提取 int 排序键的函数的字典顺序比较器。
default ComparatorT	thenComparingLong(ToLongFunction<? super T> keyExtractor)	返回具有提取长排序键的函数的字典顺序比较器。

方法详情

compare

int compare(T o1, T o2)

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

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

实现者必须确保所有 x 和 y 的 sgn(compare(x, y)) == -sgn(compare(y, x))。 （这意味着当且仅当 compare(y, x) 抛出异常时 compare(x, y) 必须抛出异常。）

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

最后，实现者必须确保 compare(x, y)==0 意味着所有 z 的 sgn(compare(x, z))==sgn(compare(y, z))。

通常是这样，但并不严格要求 (compare(x, y)==0) == (x.equals(y))。一般来说，任何违反此条件的比较器都应清楚地表明这一事实。推荐的语言是“注意：这个比较器强加了与等于不一致的排序。”

参数：

参数名称	参数描述
o1	第一个要比较的对象。
o2	第二个要比较的对象。

返回:

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

Throws:

Throw名称	Throw描述
NullPointerException	如果参数为空且此比较器不允许空参数
ClassCastException	如果参数的类型阻止它们被此比较器进行比较。

equals

boolean equals(Object obj)

指示某个其他对象是否“等于”此比较器。 此方法必须遵守 Object#equals(Object) 的一般约定。 此外，只有当指定的对象也是一个比较器并且它强制执行与此比较器相同的排序时，此方法才能返回 true。 因此，对于每个对象引用 o1 和 o2，comp1.equals(comp2) 意味着 sgn(comp1.compare(o1, o2))==sgn(comp2.compare(o1, o2))。

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

覆盖：

类 Object 中的等于

参数：

参数名称	参数描述
obj	要与之比较的参考对象。

返回:

仅当指定对象也是一个比较器并且它施加与此比较器相同的顺序时才为true。

reversed

default ComparatorT reversed()

返回一个强制此比较器反向排序的比较器。

返回:

一个比较器，它强制此比较器的反向排序。

thenComparing

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

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

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

参数：

参数名称	参数描述
other	当此比较器比较两个相等的对象时要使用的另一个比较器。

返回:

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

Throws:

Throw名称	Throw描述
NullPointerException	如果参数为空。

thenComparing

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

返回一个字典顺序比较器，其函数提取要与给定比较器比较的键。

类型参数：

类型参数名称	类型参数描述
U	排序键的类型

参数:

参数名称	参数描述
keyExtractor	用于提取排序键的函数
keyComparator	用于比较排序键的 Comparator

返回:

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

Throws:

Throw名称	Throw描述
NullPointerException	如果任一参数为空。

thenComparing

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

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

类型参数：

类型参数名称	类型参数描述
U	Comparable 排序键的类型

参数:

参数名称	参数描述
keyExtractor	用于提取 Comparable 排序键的函数

返回:

由 this 和 Comparable 排序键组成的字典顺序比较器。

Throws:

Throw名称	Throw描述
NullPointerException	如果参数为空。

thenComparingInt

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

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

参数：

参数名称	参数描述
keyExtractor	用于提取整数排序键的函数

返回:

由 this 和 int 排序键组成的字典顺序比较器

Throws:

Throw名称	Throw描述
NullPointerException	如果参数为空。

thenComparingLong

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

返回具有提取长排序键的函数的字典顺序比较器。

参数：

参数名称	参数描述
keyExtractor	用于提取长排序键的函数

返回:

由 this 和长排序键组成的字典顺序比较器

Throws:

Throw名称	Throw描述
NullPointerException	如果参数为空。

thenComparingDouble

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

返回具有提取双排序键的函数的字典顺序比较器。

参数：

参数名称	参数描述
keyExtractor	用于提取双重排序键的函数

返回:

由 this 和双排序键组成的字典顺序比较器

Throws:

Throw名称	Throw描述
NullPointerException	如果参数为空。

reverseOrder

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

返回一个强制与自然顺序相反的比较器。

返回的比较器是可序列化的，并在比较 null 时抛出 NullPointerException。

类型参数：

类型参数名称	类型参数描述
T	要比较的元素的 Comparable 类型

返回:

一个比较器，它对 Comparable 对象施加相反的自然顺序。

naturalOrder

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

返回按自然顺序比较 Comparable 对象的比较器。

返回的比较器是可序列化的，并在比较 null 时抛出 NullPointerException。

类型参数：

类型参数名称	类型参数描述
T	要比较的元素的 Comparable 类型

返回:

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

nullsFirst

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

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

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

类型参数：

类型参数名称	类型参数描述
T	要比较的元素的类型

参数:

参数名称	参数描述
comparator	用于比较非空值的比较器

返回:

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

nullsLast

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

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

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

类型参数：

类型参数名称	类型参数描述
T	要比较的元素的类型

参数:

参数名称	参数描述
comparator	用于比较非空值的比较器

返回:

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

comparing

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

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

如果指定的函数和比较器都是可序列化的，则返回的比较器是可序列化的。

类型参数：

类型参数名称	类型参数描述
T	要比较的元素类型
U	排序键的类型

参数:

参数名称	参数描述
keyExtractor	用于提取排序键的函数
keyComparator	用于比较排序键的 Comparator

返回:

一个比较器，它使用指定的 Comparator 按提取的键进行比较

Throws:

Throw名称	Throw描述
NullPointerException	如果任一参数为空

comparing

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

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

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

类型参数：

类型参数名称	类型参数描述
T	要比较的元素类型
U	Comparable 排序键的类型

参数:

参数名称	参数描述
keyExtractor	用于提取 Comparable 排序键的函数

返回:

通过提取的键进行比较的比较器

Throws:

Throw名称	Throw描述
NullPointerException	如果参数为空

comparingInt

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

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

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

类型参数：

类型参数名称	类型参数描述
T	要比较的元素类型

参数:

参数名称	参数描述
keyExtractor	用于提取整数排序键的函数

返回:

通过提取的键进行比较的比较器

Throws:

Throw名称	Throw描述
NullPointerException	如果参数为空

comparingLong

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

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

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

类型参数：

类型参数名称	类型参数描述
T	要比较的元素类型

参数:

参数名称	参数描述
keyExtractor	用于提取长排序键的函数

返回:

通过提取的键进行比较的比较器

Throws:

Throw名称	Throw描述
NullPointerException	如果参数为空

comparingDouble

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

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

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

类型参数：

类型参数名称	类型参数描述
T	要比较的元素类型

参数:

参数名称	参数描述
keyExtractor	用于提取双重排序键的函数

返回:

通过提取的键进行比较的比较器

Throws:

Throw名称	Throw描述
NullPointerException	如果参数为空