鴻蒙OS Comparator

Comparator

@FunctionalInterface
public interface Comparator<T>

一個比較函數(shù)，它對某些對象集合進行總排序。比較器可以傳遞給排序方法（例如 Collections#sort(List,Comparator) 或 [Arrays#sort(Object],Comparator)），以允許精確控制排序順序。比較器還可用于控制某些數(shù)據(jù)結(jié)構(gòu)（例如 SortedSet 或 SortedMap）的順序，或者為沒有 Comparable 的對象集合提供排序。

當(dāng)且僅當(dāng) c.compare(e1, e2)==0 對于每個 e1 具有與 e1.equals(e2) 相同的布爾值時，比較器 c 對一組元素 S 施加的排序被稱為與 equals 一致和 S 中的 e2。

當(dāng)使用能夠施加與等于不一致的排序的比較器來對排序集（或排序映射）進行排序時，應(yīng)謹(jǐn)慎行事。假設(shè)帶有顯式比較器 c 的有序集合（或有序映射）與從集合 S 中提取的元素（或鍵）一起使用。如果 c 對 S 施加的排序與 equals 不一致，則有序集合（或有序映射）將表現(xiàn)得“奇怪”。特別是有序集合（或有序映射）將違反集合（或映射）的一般合同，它是根據(jù)等式定義的。

例如，假設(shè)將兩個元素 a 和 b 相加，使得 (a.equals(b) && c.compare(a, b) != 0) 到具有比較器 c 的空 TreeSet。第二個 add 操作將返回 true（并且樹集的大小將增加），因為從樹集的角度來看 a 和 b 不等價，即使這與 Set#add 方法的規(guī)范相反。

注意：比較器通常也實現(xiàn) java.io.Serializable 是一個好主意，因為它們可以用作可序列化數(shù)據(jù)結(jié)構(gòu)（如 TreeSet、TreeMap）中的排序方法。為了使數(shù)據(jù)結(jié)構(gòu)成功序列化，比較器（如果提供）必須實現(xiàn) Serializable。

對于數(shù)學(xué)傾向，定義給定比較器 c 對給定對象集 S 施加的強制排序的關(guān)系是：

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

這個總訂單的商是：

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

立即從比較契約得出，商是 S 上的等價關(guān)系，并且強加的排序是 S 上的全排序。當(dāng)我們說 c 對 S 強加的排序與 equals 一致時，我們的意思是 排序的商是對象的 Object#equals(Object) 方法定義的等價關(guān)系：

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

與 Comparable 不同的是，比較器可以選擇允許比較空參數(shù)，同時保持對等價關(guān)系的要求。

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

方法總結(jié)

修飾符和類型	方法	描述
int	compare(T o1, T o2)	比較它的兩個參數(shù)的順序。
static <T,U extends Comparable<? super U>>Comparator<T>	comparing(Function<? super T,? extends U> keyExtractor)	接受從類型 T 中提取 Comparable 排序鍵的函數(shù)，并返回按該排序鍵進行比較的 Comparator<T>。
static <T,U> Comparator<T>	comparing(Function<? super T,? extends U> keyExtractor, Comparator<? super U> keyComparator)	接受一個從類型 T 中提取排序鍵的函數(shù)，并返回一個 Comparator<T>，該函數(shù)使用指定的 Comparator 按該排序鍵進行比較。
static <T> Comparator<T>	comparingDouble(ToDoubleFunction<? super T> keyExtractor)	接受一個從類型 T 中提取雙重排序鍵的函數(shù)，并返回一個按該排序鍵進行比較的 Comparator<T>。
static <T> Comparator<T>	comparingInt(ToIntFunction<? super T> keyExtractor)	接受從類型 T 中提取 int 排序鍵的函數(shù)，并返回按該排序鍵進行比較的 Comparator<T>。
static <T> Comparator<T>	comparingLong(ToLongFunction<? super T> keyExtractor)	接受從類型 T 中提取長排序鍵的函數(shù)，并返回按該排序鍵進行比較的 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 友好的比較器，它認(rèn)為 null 小于非 null。
static <T> Comparator<T>	nullsLast(Comparator<? super T> comparator)	返回一個 null 友好的比較器，它認(rèn)為 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 排序鍵的函數(shù)的字典順序比較器。
default <U> ComparatorT	thenComparing(Function<? super T,? extends U> keyExtractor, Comparator<? super U> keyComparator)	返回一個字典順序比較器，其函數(shù)提取要與給定比較器比較的鍵。
default ComparatorT	thenComparingDouble(ToDoubleFunction<? super T> keyExtractor)	返回具有提取雙排序鍵的函數(shù)的字典順序比較器。
default ComparatorT	thenComparingInt(ToIntFunction<? super T> keyExtractor)	返回具有提取 int 排序鍵的函數(shù)的字典順序比較器。
default ComparatorT	thenComparingLong(ToLongFunction<? super T> keyExtractor)	返回具有提取長排序鍵的函數(shù)的字典順序比較器。

方法詳情

compare

int compare(T o1, T o2)

比較它的兩個參數(shù)的順序。返回負(fù)整數(shù)、零或正整數(shù)，因為第一個參數(shù)小于、等于或大于第二個。

在前面的描述中，符號sgn(expression)表示數(shù)學(xué)符號函數(shù)，它被定義為根據(jù)表達式的值是負(fù)數(shù)、零還是正數(shù)返回-1、0或1之一。

實現(xiàn)者必須確保所有 x 和 y 的 sgn(compare(x, y)) == -sgn(compare(y, x))。 （這意味著當(dāng)且僅當(dāng) compare(y, x) 拋出異常時 compare(x, y) 必須拋出異常。）

實現(xiàn)者還必須確保關(guān)系是可傳遞的： ((compare(x, y)>0) && (compare(y, z)>0)) 意味著 compare(x, z)>0。

最后，實現(xiàn)者必須確保 compare(x, y)==0 意味著所有 z 的 sgn(compare(x, z))==sgn(compare(y, z))。

通常是這樣，但并不嚴(yán)格要求 (compare(x, y)==0) == (x.equals(y))。一般來說，任何違反此條件的比較器都應(yīng)清楚地表明這一事實。推薦的語言是“注意：這個比較器強加了與等于不一致的排序?！?/p>

參數(shù)：

參數(shù)名稱	參數(shù)描述
o1	第一個要比較的對象。
o2	第二個要比較的對象。

返回:

作為第一個參數(shù)的負(fù)整數(shù)、零或正整數(shù)小于、等于或大于第二個參數(shù)。

Throws:

Throw名稱	Throw描述
NullPointerException	如果參數(shù)為空且此比較器不允許空參數(shù)
ClassCastException	如果參數(shù)的類型阻止它們被此比較器進行比較。

equals

boolean equals(Object obj)

指示某個其他對象是否“等于”此比較器。 此方法必須遵守 Object#equals(Object) 的一般約定。 此外，只有當(dāng)指定的對象也是一個比較器并且它強制執(zhí)行與此比較器相同的排序時，此方法才能返回 true。 因此，對于每個對象引用 o1 和 o2，comp1.equals(comp2) 意味著 sgn(comp1.compare(o1, o2))==sgn(comp2.compare(o1, o2))。

請注意，不要覆蓋 Object.equals(Object) 始終是安全的。 但是，在某些情況下，重寫此方法可能會通過允許程序確定兩個不同的比較器施加相同的順序來提高性能。

覆蓋：

類 Object 中的等于

參數(shù)：

參數(shù)名稱	參數(shù)描述
obj	要與之比較的參考對象。

返回:

僅當(dāng)指定對象也是一個比較器并且它施加與此比較器相同的順序時才為true。

reversed

default ComparatorT reversed()

返回一個強制此比較器反向排序的比較器。

返回:

一個比較器，它強制此比較器的反向排序。

thenComparing

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

返回具有另一個比較器的字典順序比較器。 如果此 Comparator 認(rèn)為兩個元素相等，即 compare(a, b) == 0，則使用 other 來確定順序。

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

參數(shù)：

參數(shù)名稱	參數(shù)描述
other	當(dāng)此比較器比較兩個相等的對象時要使用的另一個比較器。

返回:

由這個比較器和另一個比較器組成的字典順序比較器

Throws:

Throw名稱	Throw描述
NullPointerException	如果參數(shù)為空。

thenComparing

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

返回一個字典順序比較器，其函數(shù)提取要與給定比較器比較的鍵。

類型參數(shù)：

類型參數(shù)名稱	類型參數(shù)描述
U	排序鍵的類型

參數(shù):

參數(shù)名稱	參數(shù)描述
keyExtractor	用于提取排序鍵的函數(shù)
keyComparator	用于比較排序鍵的 Comparator

返回:

由該比較器組成的字典順序比較器，然后對 keyExtractor 函數(shù)提取的鍵進行比較

Throws:

Throw名稱	Throw描述
NullPointerException	如果任一參數(shù)為空。

thenComparing

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

返回具有提取 Comparable 排序鍵的函數(shù)的字典順序比較器。

類型參數(shù)：

類型參數(shù)名稱	類型參數(shù)描述
U	Comparable 排序鍵的類型

參數(shù):

參數(shù)名稱	參數(shù)描述
keyExtractor	用于提取 Comparable 排序鍵的函數(shù)

返回:

由 this 和 Comparable 排序鍵組成的字典順序比較器。

Throws:

Throw名稱	Throw描述
NullPointerException	如果參數(shù)為空。

thenComparingInt

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

返回具有提取 int 排序鍵的函數(shù)的字典順序比較器。

參數(shù)：

參數(shù)名稱	參數(shù)描述
keyExtractor	用于提取整數(shù)排序鍵的函數(shù)

返回:

由 this 和 int 排序鍵組成的字典順序比較器

Throws:

Throw名稱	Throw描述
NullPointerException	如果參數(shù)為空。

thenComparingLong

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

返回具有提取長排序鍵的函數(shù)的字典順序比較器。

參數(shù)：

參數(shù)名稱	參數(shù)描述
keyExtractor	用于提取長排序鍵的函數(shù)

返回:

由 this 和長排序鍵組成的字典順序比較器

Throws:

Throw名稱	Throw描述
NullPointerException	如果參數(shù)為空。

thenComparingDouble

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

返回具有提取雙排序鍵的函數(shù)的字典順序比較器。

參數(shù)：

參數(shù)名稱	參數(shù)描述
keyExtractor	用于提取雙重排序鍵的函數(shù)

返回:

由 this 和雙排序鍵組成的字典順序比較器

Throws:

Throw名稱	Throw描述
NullPointerException	如果參數(shù)為空。

reverseOrder

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

返回一個強制與自然順序相反的比較器。

返回的比較器是可序列化的，并在比較 null 時拋出 NullPointerException。

類型參數(shù)：

類型參數(shù)名稱	類型參數(shù)描述
T	要比較的元素的 Comparable 類型

返回:

一個比較器，它對 Comparable 對象施加相反的自然順序。

naturalOrder

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

返回按自然順序比較 Comparable 對象的比較器。

返回的比較器是可序列化的，并在比較 null 時拋出 NullPointerException。

類型參數(shù)：

類型參數(shù)名稱	類型參數(shù)描述
T	要比較的元素的 Comparable 類型

返回:

對 Comparable 對象施加自然排序的比較器。

nullsFirst

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

返回一個 null 友好的比較器，它認(rèn)為 null 小于非 null。 當(dāng)兩者都為空時，它們被認(rèn)為是相等的。 如果兩者都不為空，則使用指定的 Comparator 來確定順序。 如果指定的比較器為空，則返回的比較器將所有非空值視為相等。

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

類型參數(shù)：

類型參數(shù)名稱	類型參數(shù)描述
T	要比較的元素的類型

參數(shù):

參數(shù)名稱	參數(shù)描述
comparator	用于比較非空值的比較器

返回:

一個比較器，它認(rèn)為 null 小于非 null，并將非 null 對象與提供的 Comparator 進行比較。

nullsLast

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

返回一個 null 友好的比較器，它認(rèn)為 null 大于非 null。 當(dāng)兩者都為空時，它們被認(rèn)為是相等的。 如果兩者都不為空，則使用指定的 Comparator 來確定順序。 如果指定的比較器為空，則返回的比較器將所有非空值視為相等。

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

類型參數(shù)：

類型參數(shù)名稱	類型參數(shù)描述
T	要比較的元素的類型

參數(shù):

參數(shù)名稱	參數(shù)描述
comparator	用于比較非空值的比較器

返回:

一個比較器，它認(rèn)為 null 大于非 null，并將非 null 對象與提供的 Comparator 進行比較。

comparing

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

接受一個從類型 T 中提取排序鍵的函數(shù)，并返回一個 Comparator<T>，該函數(shù)使用指定的 Comparator 按該排序鍵進行比較。

如果指定的函數(shù)和比較器都是可序列化的，則返回的比較器是可序列化的。

類型參數(shù)：

類型參數(shù)名稱	類型參數(shù)描述
T	要比較的元素類型
U	排序鍵的類型

參數(shù):

參數(shù)名稱	參數(shù)描述
keyExtractor	用于提取排序鍵的函數(shù)
keyComparator	用于比較排序鍵的 Comparator

返回:

一個比較器，它使用指定的 Comparator 按提取的鍵進行比較

Throws:

Throw名稱	Throw描述
NullPointerException	如果任一參數(shù)為空

comparing

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

接受從類型 T 中提取 Comparable 排序鍵的函數(shù)，并返回按該排序鍵進行比較的 Comparator<T>。

如果指定的函數(shù)也是可序列化的，則返回的比較器是可序列化的。

類型參數(shù)：

類型參數(shù)名稱	類型參數(shù)描述
T	要比較的元素類型
U	Comparable 排序鍵的類型

參數(shù):

參數(shù)名稱	參數(shù)描述
keyExtractor	用于提取 Comparable 排序鍵的函數(shù)

返回:

通過提取的鍵進行比較的比較器

Throws:

Throw名稱	Throw描述
NullPointerException	如果參數(shù)為空

comparingInt

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

接受從類型 T 中提取 int 排序鍵的函數(shù)，并返回按該排序鍵進行比較的 Comparator<T>。

如果指定的函數(shù)也是可序列化的，則返回的比較器是可序列化的。

類型參數(shù)：

類型參數(shù)名稱	類型參數(shù)描述
T	要比較的元素類型

參數(shù):

參數(shù)名稱	參數(shù)描述
keyExtractor	用于提取整數(shù)排序鍵的函數(shù)

返回:

通過提取的鍵進行比較的比較器

Throws:

Throw名稱	Throw描述
NullPointerException	如果參數(shù)為空

comparingLong

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

接受從類型 T 中提取長排序鍵的函數(shù)，并返回按該排序鍵進行比較的 Comparator<T>。

如果指定的函數(shù)也是可序列化的，則返回的比較器是可序列化的。

類型參數(shù)：

類型參數(shù)名稱	類型參數(shù)描述
T	要比較的元素類型

參數(shù):

參數(shù)名稱	參數(shù)描述
keyExtractor	用于提取長排序鍵的函數(shù)

返回:

通過提取的鍵進行比較的比較器

Throws:

Throw名稱	Throw描述
NullPointerException	如果參數(shù)為空

comparingDouble

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

接受一個從類型 T 中提取雙重排序鍵的函數(shù)，并返回一個按該排序鍵進行比較的 Comparator<T>。

如果指定的函數(shù)也是可序列化的，則返回的比較器是可序列化的。

類型參數(shù)：

類型參數(shù)名稱	類型參數(shù)描述
T	要比較的元素類型

參數(shù):

參數(shù)名稱	參數(shù)描述
keyExtractor	用于提取雙重排序鍵的函數(shù)

返回:

通過提取的鍵進行比較的比較器

Throws:

Throw名稱	Throw描述
NullPointerException	如果參數(shù)為空