鴻蒙OS Collection

Collection

public interface Collection<E>
extends Iterable<E>

集合層次結(jié)構(gòu)中的根接口。 集合表示一組對象，稱為其元素。 一些集合允許重復(fù)元素，而另一些則不允許。 有些是有序的，有些是無序的。 JDK 不提供此接口的任何直接實現(xiàn)：它提供更具體的子接口（如 Set 和 List）的實現(xiàn)。 此接口通常用于傳遞集合并在需要最大通用性的地方操作它們。

Bags 或 multisets（可能包含重復(fù)元素的無序集合）應(yīng)該直接實現(xiàn)這個接口。

所有通用 Collection 實現(xiàn)類（通常通過其子接口之一間接實現(xiàn) Collection）應(yīng)提供兩個“標(biāo)準(zhǔn)”構(gòu)造函數(shù)：一個 void（無參數(shù)）構(gòu)造函數(shù)，它創(chuàng)建一個空集合，以及一個具有單個參數(shù)類型的構(gòu)造函數(shù)集合，它創(chuàng)建一個具有與其參數(shù)相同的元素的新集合。實際上，后一個構(gòu)造函數(shù)允許用戶復(fù)制任何集合，生成所需實現(xiàn)類型的等效集合。沒有辦法強(qiáng)制執(zhí)行此約定（因為接口不能包含構(gòu)造函數(shù)），但 Java 平臺庫中的所有通用 Collection 實現(xiàn)都遵守。

此接口中包含的“破壞性”方法，即修改其操作的集合的方法，指定在此集合不支持操作時拋出 UnsupportedOperationException。如果是這種情況，如果調(diào)用對集合沒有影響，這些方法可能會（但不是必須）拋出 UnsupportedOperationException。例如，如果要添加的集合為空，則對不可修改的集合調(diào)用 addAll(java.util.Collection) 方法可能但不是必須拋出異常。

一些集合實現(xiàn)對它們可能包含的元素有限制。 例如，一些實現(xiàn)禁止空元素，而一些實現(xiàn)對其元素的類型有限制。 嘗試添加不合格的元素會引發(fā)未經(jīng)檢查的異常，通常是 NullPointerException 或 ClassCastException。 嘗試查詢不合格元素的存在可能會引發(fā)異常，或者它可能只是返回 false； 一些實現(xiàn)會表現(xiàn)出前一種行為，而另一些會表現(xiàn)出后者。 更一般地，嘗試對不合格元素執(zhí)行操作，該不合格元素的完成不會導(dǎo)致將不合格元素插入集合中，這可能會引發(fā)異常，也可能會成功，這取決于實現(xiàn)的選擇。 此類異常在此接口的規(guī)范中被標(biāo)記為“可選”。

由每個集合決定自己的同步策略。在實現(xiàn)沒有更強(qiáng)有力的保證的情況下，未定義的行為可能是由于對正在被另一個線程改變的集合上的任何方法的調(diào)用引起的；這包括直接調(diào)用，將集合傳遞給可能執(zhí)行調(diào)用的方法，以及使用現(xiàn)有迭代器檢查集合。

Collections Framework 接口中的許多方法都是根據(jù) Object#equals(Object) 方法定義的。例如，contains(Object o) 方法的規(guī)范說：“當(dāng)且僅當(dāng)此集合包含至少一個元素 e 使得 (o==null ? e==null : o.equals(e)) ?！北疽?guī)范不應(yīng)被解釋為暗示使用非空參數(shù) o 調(diào)用 Collection.contains 將導(dǎo)致對任何元素 e 調(diào)用 o.equals(e)。實現(xiàn)可以自由地實現(xiàn)優(yōu)化，從而避免調(diào)用 equals，例如，首先比較兩個元素的哈希碼。 （Object#hashCode() 規(guī)范保證具有不相等哈希碼的兩個對象不能相等。）更一般地說，各種集合框架接口的實現(xiàn)可以自由地利用底層 Object 方法的指定行為，只要實現(xiàn)者認(rèn)為它合適.

一些執(zhí)行集合遞歸遍歷的集合操作可能會失敗，但對于集合直接或間接包含自身的自引用實例的異常。 這包括 clone()、equals()、hashCode() 和 toString() 方法。 實現(xiàn)可以選擇處理自引用場景，但是大多數(shù)當(dāng)前的實現(xiàn)不這樣做。

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

方法總結(jié)

修飾符和類型	方法	描述
boolean	add(E e)	確保此集合包含指定的元素（可選操作）。
boolean	addAll(Collection<? extends E> c)	將指定集合中的所有元素添加到此集合（可選操作）。
void	clear()	從此集合中移除所有元素（可選操作）。
boolean	contains(Object o)	如果此集合包含指定元素，則返回 true。
boolean	containsAll(Collection<?> c)	如果此集合包含指定集合中的所有元素，則返回 true。
boolean	equals(Object o)	比較指定對象與此集合是否相等。
int	hashCode()	返回此集合的哈希碼值。
boolean	isEmpty()	如果此集合不包含任何元素，則返回 true。
IteratorE	iterator()	返回此集合中元素的迭代器。
default StreamE	parallelStream()	返回以該集合為源的可能并行 Stream。
boolean	remove(Object o)	從此集合中移除指定元素的單個實例（如果存在）（可選操作）。
boolean	removeAll(Collection<?> c)	移除此集合的所有也包含在指定集合中的元素（可選操作）。
default boolean	removeIf(Predicate<? super E> filter)	刪除此集合中滿足給定謂詞的所有元素。
boolean	retainAll(Collection<?> c)	僅保留此集合中包含在指定集合中的元素（可選操作）。
int	size()	返回此集合中的元素數(shù)。
default SpliteratorE	spliterator()	在此集合中的元素上創(chuàng)建一個 Spliterator。
default StreamE	stream()	返回以此集合為源的順序流。
Object[]	toArray()	返回一個包含此集合中所有元素的數(shù)組。
<T> T[]	toArray(T[] a)	返回一個包含此集合中所有元素的數(shù)組； 返回數(shù)組的運(yùn)行時類型是指定數(shù)組的運(yùn)行時類型。

從接口 java.lang.Iterable 繼承的方法
forEach

方法詳情

size

int size()

返回此集合中的元素數(shù)。 如果此集合包含多個 Integer.MAX_VALUE 元素，則返回 Integer.MAX_VALUE。

返回:

此集合中的元素數(shù)

isEmpty

boolean isEmpty()

如果此集合不包含任何元素，則返回 true。

返回:

如果此集合不包含任何元素，則為 true

contains

boolean contains(Object o)

如果此集合包含指定元素，則返回 true。 更正式地說，當(dāng)且僅當(dāng)此集合包含至少一個元素 e 滿足 (o==null ? e==null : o.equals(e)) 時才返回 true。

參數(shù)：

參數(shù)名稱	參數(shù)描述
o	要測試其在此集合中的存在的元素

返回：

如果此集合包含指定元素，則為 true

Throws:

Throw名稱	Throw描述
ClassCastException	如果指定元素的類型與此集合不兼容（可選）
NullPointerException	如果指定元素為空且此集合不允許空元素（可選）

iterator

IteratorE iterator()

返回此集合中元素的迭代器。 不保證返回元素的順序（除非此集合是提供保證的某個類的實例）。

指定者：

接口 IterableE 中的迭代器

返回:

此集合中元素的迭代器

toArray

Object[] toArray()

返回一個包含此集合中所有元素的數(shù)組。 如果此集合對其迭代器返回其元素的順序做出任何保證，則此方法必須以相同的順序返回元素。

返回的數(shù)組將是“安全的”，因為此集合不維護(hù)對它的引用。 （換句話說，即使此集合由數(shù)組支持，此方法也必須分配一個新數(shù)組）。 因此，調(diào)用者可以自由修改返回的數(shù)組。

此方法充當(dāng)基于數(shù)組和基于集合的 API 之間的橋梁。

返回:

包含此集合中所有元素的數(shù)組

toArray

<T> T[] toArray(T[] a)

返回一個包含此集合中所有元素的數(shù)組；返回數(shù)組的運(yùn)行時類型是指定數(shù)組的運(yùn)行時類型。如果集合適合指定的數(shù)組，則在其中返回。否則，將使用指定數(shù)組的運(yùn)行時類型和此集合的大小分配一個新數(shù)組。

如果此集合適合指定的數(shù)組并有剩余空間（即，數(shù)組的元素比此集合多），則數(shù)組中緊跟集合末尾的元素設(shè)置為 null。 （僅當(dāng)調(diào)用者知道此集合不包含任何空元素時，這在確定此集合的長度時才有用。）

如果此集合對其迭代器返回其元素的順序做出任何保證，則此方法必須以相同的順序返回元素。

與 toArray() 方法一樣，此方法充當(dāng)基于數(shù)組的 API 和基于集合的 API 之間的橋梁。此外，此方法允許對輸出數(shù)組的運(yùn)行時類型進(jìn)行精確控制，并且在某些情況下可用于節(jié)省分配成本。

假設(shè) x 是一個已知只包含字符串的集合。以下代碼可用于將集合轉(zhuǎn)儲到新分配的 String 數(shù)組中：

     String[] y = x.toArray(new String[0]);

請注意，toArray(new Object[0]) 在功能上與 toArray() 相同。

類型參數(shù)：

類型參數(shù)名稱	類型參數(shù)描述
T	包含集合的數(shù)組的運(yùn)行時類型

參數(shù):

參數(shù)名稱	參數(shù)描述
a	這個集合的元素要存儲到的數(shù)組，如果它足夠大的話； 否則，將為此目的分配相同運(yùn)行時類型的新數(shù)組。

返回:

包含此集合中所有元素的數(shù)組

Throws:

Throw名稱	Throw描述
ArrayStoreException	如果指定數(shù)組的運(yùn)行時類型不是此集合中每個元素的運(yùn)行時類型的超類型
NullPointerException	如果指定的數(shù)組為空

add

boolean add(E e)

確保此集合包含指定的元素（可選操作）。 如果此集合因調(diào)用而更改，則返回 true。 （如果此集合不允許重復(fù)且已包含指定元素，則返回 false。）

支持此操作的集合可能會限制可以添加到此集合的元素。 特別是，一些集合會拒絕添加空元素，而另一些則會對可能添加的元素類型施加限制。 集合類應(yīng)在其文檔中明確指定對可以添加哪些元素的任何限制。

如果一個集合拒絕添加一個特定元素，除了它已經(jīng)包含該元素之外，它必須拋出一個異常（而不是返回 false）。 這保留了在此調(diào)用返回后集合始終包含指定元素的不變量。

參數(shù)：

參數(shù)名稱	參數(shù)描述
e	要確保在此集合中存在的元素

返回:

如果此集合因調(diào)用而更改，則為 true

Throws:

Throw名稱	Throw描述
UnsupportedOperationException	如果此集合不支持添加操作
ClassCastException	如果指定元素的類阻止它被添加到此集合中
NullPointerException	如果指定元素為 null 并且此集合不允許 null 元素
IllegalArgumentException	如果元素的某些屬性阻止它被添加到此集合中
IllegalStateException	如果此時由于插入限制無法添加元素

remove

boolean remove(Object o)

從此集合中移除指定元素的單個實例（如果存在）（可選操作）。 更正式地說，如果這個集合包含一個或多個這樣的元素，則刪除一個元素 e 使得 (o==null ? e==null : o.equals(e))。 如果此集合包含指定元素（或等效地，如果此集合因調(diào)用而更改），則返回 true。

參數(shù)：

參數(shù)名稱	參數(shù)描述
o	要從此集合中刪除的元素（如果存在）

返回:

如果由于此調(diào)用而刪除了元素，則為 true

Throws:

Throw名稱	Throw描述
ClassCastException	如果指定元素的類型與此集合不兼容（可選）
NullPointerException	如果指定元素為空且此集合不允許空元素（可選）
UnsupportedOperationException	如果此集合不支持刪除操作

containsAll

boolean containsAll(Collection<?> c)

如果此集合包含指定集合中的所有元素，則返回 true。

參數(shù)：

參數(shù)名稱	參數(shù)描述
c	要檢查此集合中包含的集合

返回:

如果此集合包含指定集合中的所有元素，則為 true

Throws:

Throw名稱	Throw描述
ClassCastException	如果指定集合中的一個或多個元素的類型與該集合不兼容（可選）
NullPointerException	如果指定的集合包含一個或多個空元素并且此集合不允許空元素（可選），或者指定的集合為空。

addAll

boolean addAll(Collection<? extends E> c)

將指定集合中的所有元素添加到此集合（可選操作）。 如果在操作正在進(jìn)行時修改了指定的集合，則此操作的行為是未定義的。 （這意味著如果指定的集合是這個集合，并且這個集合是非空的，那么這個調(diào)用的行為是未定義的。）

參數(shù)：

參數(shù)名稱	參數(shù)描述
c	包含要添加到此集合的元素的集合

返回:

如果此集合因調(diào)用而更改，則為 true

Throws:

Throw名稱	Throw描述
UnsupportedOperationException	如果此集合不支持 addAll 操作
ClassCastException	如果指定集合的元素的類阻止將其添加到此集合中
NullPointerException	如果指定的集合包含空元素并且此集合不允許空元素，或者指定的集合為空
IllegalArgumentException	如果指定集合的某個元素的某些屬性阻止它被添加到此集合中
IllegalStateException	如果由于插入限制，此時不能添加所有元素

removeAll

boolean removeAll(Collection<?> c)

移除此集合的所有也包含在指定集合中的元素（可選操作）。 在此調(diào)用返回后，此集合將不包含與指定集合共有的元素。

參數(shù)：

參數(shù)名稱	參數(shù)描述
c	包含要從此集合中刪除的元素的集合

返回:

如果此集合因調(diào)用而更改，則為 true

Throws:

Throw名稱	Throw描述
UnsupportedOperationException	如果此集合不支持 removeAll 方法
ClassCastException	如果此集合中的一個或多個元素的類型與指定的集合不兼容（可選）
NullPointerException	如果此集合包含一個或多個空元素并且指定的集合不支持空元素（可選），或者指定的集合為空

removeIf

default boolean removeIf(Predicate<? super E> filter)

刪除此集合中滿足給定謂詞的所有元素。 在迭代期間或由謂詞引發(fā)的錯誤或運(yùn)行時異常將轉(zhuǎn)發(fā)給調(diào)用者。

參數(shù)：

參數(shù)名稱	參數(shù)描述
filter	對于要刪除的元素返回 true 的謂詞

返回:

如果刪除了任何元素，則為 true

Throws:

Throw名稱	Throw描述
NullPointerException	如果指定的過濾器為空
UnsupportedOperationException	如果無法從此集合中刪除元素。 如果無法刪除匹配的元素，或者通常不支持刪除，則實現(xiàn)可能會拋出此異常。

retainAll

boolean retainAll(Collection<?> c)

僅保留此集合中包含在指定集合中的元素（可選操作）。 換句話說，從這個集合中移除所有不包含在指定集合中的元素。

參數(shù)：

參數(shù)名稱	參數(shù)描述
c	包含要保留在此集合中的元素的集合

返回:

如果此集合因調(diào)用而更改，則為 true

Throws:

Throw名稱	Throw描述
UnsupportedOperationException	如果此集合不支持 retainAll 操作
ClassCastException	如果此集合中的一個或多個元素的類型與指定的集合不兼容（可選）
NullPointerException	如果此集合包含一個或多個空元素并且指定的集合不允許空元素（可選），或者指定的集合為空

clear

void clear()

從此集合中移除所有元素（可選操作）。 此方法返回后，集合將為空。

Throws:

Throw名稱	Throw描述
UnsupportedOperationException	如果此集合不支持清除操作

equals

boolean equals(Object o)

比較指定對象與此集合是否相等。

雖然 Collection 接口沒有為 Object.equals 的一般約定添加任何規(guī)定，但“直接”實現(xiàn) Collection 接口的程序員（換句話說，創(chuàng)建一個是 Collection 但不是 Set 或 List 的類）必須小心如果他們選擇覆蓋 Object.equals。沒有必要這樣做，最簡單的做法是依賴 Object 的實現(xiàn)，但實現(xiàn)者可能希望實現(xiàn)“值比較”來代替默認(rèn)的“引用比較”。 （List 和 Set 接口要求進(jìn)行此類值比較。）

Object.equals 方法的一般約定規(guī)定 equals 必須是對稱的（換句話說，a.equals(b) 當(dāng)且僅當(dāng) b.equals(a) 時）。 List.equals 和 Set.equals 的協(xié)定規(guī)定列表僅等于其他列表，并且集合與其他集合相同。因此，當(dāng)將此集合與任何列表或集合進(jìn)行比較時，既不實現(xiàn) List 也不實現(xiàn) Set 接口的集合類的自定義 equals 方法必須返回 false。 （按照同樣的邏輯，不可能編寫一個同時正確實現(xiàn) Set 和 List 接口的類。）

覆蓋：

類 Object 中的等于

參數(shù)：

參數(shù)名稱	參數(shù)描述
o	要與此集合比較是否相等的對象

返回:

如果指定的對象等于此集合，則為 true

hashCode

int hashCode()

返回此集合的哈希碼值。 雖然 Collection 接口沒有對 Object.hashCode 方法的通用約定添加任何規(guī)定，但程序員應(yīng)注意，任何重寫 Object.equals 方法的類也必須重寫 Object.hashCode 方法以滿足 Object 的通用約定 .hashCode 方法。 特別是，c1.equals(c2) 意味著 c1.hashCode()==c2.hashCode()。

覆蓋：

類 Object 中的 hashCode

返回:

此集合的哈希碼值

spliterator

default SpliteratorE spliterator()

在此集合中的元素上創(chuàng)建一個 Spliterator。 實現(xiàn)應(yīng)該記錄分離器報告的特征值。 如果拆分器報告 Spliterator#SIZED 并且此集合不包含任何元素，則不需要報告此類特征值。

默認(rèn)實現(xiàn)應(yīng)該被可以返回更有效拆分器的子類覆蓋。 為了保留 stream() 和 parallelStream()} 方法的預(yù)期惰性行為，拆分器應(yīng)該具有 IMMUTABLE 或 CONCURRENT 的特性，或者是后期綁定的。 如果這些都不可行，則覆蓋類應(yīng)描述拆分器的綁定和結(jié)構(gòu)干擾的文檔化策略，并應(yīng)覆蓋 stream() 和 parallelStream() 方法以使用拆分器的供應(yīng)商創(chuàng)建流，如下所示：

     Stream<E> s = StreamSupport.stream(() -> spliterator(), spliteratorCharacteristics) 

這些要求確保由 stream() 和 parallelStream() 方法生成的流將反映在終端流操作啟動時集合的內(nèi)容。

指定者：

接口 IterableE 中的分離器

返回:

此集合中元素的拆分器

stream

default StreamE stream()

返回以此集合為源的順序流。

當(dāng) spliterator() 方法無法返回 IMMUTABLE、CONCURRENT 或后期綁定的拆分器時，應(yīng)覆蓋此方法。 （有關(guān)詳細(xì)信息，請參閱 spliterator()。）

返回:

此集合中元素的順序流

parallelStream

default StreamE parallelStream()

返回以該集合為源的可能并行 Stream。 此方法允許返回順序流。

當(dāng) spliterator() 方法無法返回 IMMUTABLE、CONCURRENT 或后期綁定的拆分器時，應(yīng)覆蓋此方法。

返回:

此集合中元素的可能并行 Stream