鴻蒙OS Collection

Collection

public interface Collection<E>
extends Iterable<E>

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

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

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

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

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

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

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

一些執(zhí)行集合遞歸遍歷的集合操作可能會(huì)失敗，但對(duì)于集合直接或間接包含自身的自引用實(shí)例的異常。 這包括 clone()、equals()、hashCode() 和 toString() 方法。 實(shí)現(xiàn)可以選擇處理自引用場(chǎng)景，但是大多數(shù)當(dāng)前的實(shí)現(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)	比較指定對(duì)象與此集合是否相等。
int	hashCode()	返回此集合的哈希碼值。
boolean	isEmpty()	如果此集合不包含任何元素，則返回 true。
IteratorE	iterator()	返回此集合中元素的迭代器。
default StreamE	parallelStream()	返回以該集合為源的可能并行 Stream。
boolean	remove(Object o)	從此集合中移除指定元素的單個(gè)實(shí)例（如果存在）（可選操作）。
boolean	removeAll(Collection<?> c)	移除此集合的所有也包含在指定集合中的元素（可選操作）。
default boolean	removeIf(Predicate<? super E> filter)	刪除此集合中滿足給定謂詞的所有元素。
boolean	retainAll(Collection<?> c)	僅保留此集合中包含在指定集合中的元素（可選操作）。
int	size()	返回此集合中的元素?cái)?shù)。
default SpliteratorE	spliterator()	在此集合中的元素上創(chuàng)建一個(gè) Spliterator。
default StreamE	stream()	返回以此集合為源的順序流。
Object[]	toArray()	返回一個(gè)包含此集合中所有元素的數(shù)組。
<T> T[]	toArray(T[] a)	返回一個(gè)包含此集合中所有元素的數(shù)組； 返回?cái)?shù)組的運(yùn)行時(shí)類型是指定數(shù)組的運(yùn)行時(shí)類型。

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

方法詳情

size

int size()

返回此集合中的元素?cái)?shù)。 如果此集合包含多個(gè) Integer.MAX_VALUE 元素，則返回 Integer.MAX_VALUE。

返回:

此集合中的元素?cái)?shù)

isEmpty

boolean isEmpty()

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

返回:

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

contains

boolean contains(Object o)

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

參數(shù)：

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

返回：

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

Throws:

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

iterator

IteratorE iterator()

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

指定者：

接口 IterableE 中的迭代器

返回:

此集合中元素的迭代器

toArray

Object[] toArray()

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

返回的數(shù)組將是“安全的”，因?yàn)榇思喜痪S護(hù)對(duì)它的引用。 （換句話說，即使此集合由數(shù)組支持，此方法也必須分配一個(gè)新數(shù)組）。 因此，調(diào)用者可以自由修改返回的數(shù)組。

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

返回:

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

toArray

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

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

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

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

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

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

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

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

類型參數(shù)：

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

參數(shù):

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

返回:

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

Throws:

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

add

boolean add(E e)

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

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

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

參數(shù)：

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

返回:

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

Throws:

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

remove

boolean remove(Object o)

從此集合中移除指定元素的單個(gè)實(shí)例（如果存在）（可選操作）。 更正式地說，如果這個(gè)集合包含一個(gè)或多個(gè)這樣的元素，則刪除一個(gè)元素 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	如果指定集合中的一個(gè)或多個(gè)元素的類型與該集合不兼容（可選）
NullPointerException	如果指定的集合包含一個(gè)或多個(gè)空元素并且此集合不允許空元素（可選），或者指定的集合為空。

addAll

boolean addAll(Collection<? extends E> c)

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

參數(shù)：

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

返回:

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

Throws:

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

removeAll

boolean removeAll(Collection<?> c)

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

參數(shù)：

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

返回:

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

Throws:

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

removeIf

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

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

參數(shù)：

參數(shù)名稱	參數(shù)描述
filter	對(duì)于要?jiǎng)h除的元素返回 true 的謂詞

返回:

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

Throws:

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

retainAll

boolean retainAll(Collection<?> c)

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

參數(shù)：

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

返回:

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

Throws:

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

clear

void clear()

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

Throws:

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

equals

boolean equals(Object o)

比較指定對(duì)象與此集合是否相等。

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

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

覆蓋：

類 Object 中的等于

參數(shù)：

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

返回:

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

hashCode

int hashCode()

返回此集合的哈希碼值。 雖然 Collection 接口沒有對(duì) 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)建一個(gè) Spliterator。 實(shí)現(xiàn)應(yīng)該記錄分離器報(bào)告的特征值。 如果拆分器報(bào)告 Spliterator#SIZED 并且此集合不包含任何元素，則不需要報(bào)告此類特征值。

默認(rèn)實(shí)現(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() 方法生成的流將反映在終端流操作啟動(dòng)時(shí)集合的內(nèi)容。

指定者：

接口 IterableE 中的分離器

返回:

此集合中元素的拆分器

stream

default StreamE stream()

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

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

返回:

此集合中元素的順序流

parallelStream

default StreamE parallelStream()

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

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

返回:

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