Most visited

Recently visited

Added in API level 1

Collection

public interface Collection
implements Iterable<E>

java.util.Collection<E>
Known Indirect Subclasses


集合层次结构中的根接口。 一个集合表示一组对象,称为其元素 有些集合允许重复元素,而其他集合不允许。 一些是有序的,另一些是无序的。 JDK不提供此接口的任何直接实现:它提供了更具体的子接口的实现,如SetList 这个接口通常用于传递集合并在需要最大普遍性的情况下处理它们。

多重 (可能包含重复元素的无序集合)应直接实现此接口。

所有通用的Collection实现类(通常通过其子接口之一间接实现Collection )应提供两个“标准”构造函数:一个void(无参数)构造函数,它创建一个空集合,以及一个具有单类型参数的构造函数Collection ,它创建一个与它的参数具有相同元素的新集合。 实际上,后者的构造函数允许用户复制任何集合,生成所需实现类型的等效集合。 没有办法强制执行这个约定(因为接口不能包含构造函数),但是Java平台库中的所有通用Collection实现都符合。

如果此集合不支持该操作,则指定此接口中包含的“破坏性”方法,即修改其操作所在集合的方法,以引发UnsupportedOperationException 如果是这种情况,如果调用对集合没有影响,这些方法可能(但不是必需)抛出UnsupportedOperationException 例如,如果要添加的集合为空,则在不可修改集合上调用addAll(Collection)方法可能(但不是必需)抛出异常。

Some collection implementations have restrictions on the elements that they may contain.例如,某些实现禁止空元素,并且一些实现对元素类型有限制。 尝试添加不合格的元素会引发未检查的异常,通常为NullPointerExceptionClassCastException 尝试查询不合格元素的存在可能会引发异常,或者它可能仅返回false; 一些实现将展现前一种行为,一些将展现后者。 更一般地说,尝试对不合格元素进行操作,其完成不会导致将不合格元素插入到集合中可能会引发异常,或者可能会成功执行。 这种例外在该接口的规范中被标记为“可选”。

由每个集合决定其自己的同步策略。 在没有实现的更强保证的情况下,未定义的行为可能是由另一个线程正在改变的集合上的任何方法的调用引起的; 这包括直接调用,将集合传递给可能执行调用的方法,并使用现有的迭代器来检查集合。

根据equals方法定义集合框架接口中的equals方法。 例如, contains(Object o)方法的规范说:“返回true当且仅当此集合包含至少一个元素e,例如(o==null ? e==null : o.equals(e))” 该规范应该被解释为意味着具有非空参数调用o Collection.contains会导致o.equals(e)被调用任何元素e。 实现可以自由地实现优化,从而避免equals调用,例如,首先比较两个元素的哈希代码。 hashCode()规范保证了两个哈希代码不相等的对象不能相等)。更一般地说,不同的集合框架接口的实现可以自由地利用底层Object方法的特定行为,只要实现者认为它适合。

该界面是 Java Collections Framework的成员。

也可以看看:

Summary

Public methods

abstract boolean add(E e)

确保此集合包含指定的元素(可选操作)。

abstract boolean addAll(Collection<? extends E> c)

将指定集合中的所有元素添加到此集合(可选操作)。

abstract void clear()

从该集合中删除所有元素(可选操作)。

abstract boolean contains(Object o)

如果此集合包含指定的元素,则返回 true

abstract boolean containsAll(Collection<?> c)

如果此集合包含指定集合中的所有元素,则返回 true

abstract boolean equals(Object o)

将指定的对象与此集合进行比较以获得相等性。

abstract int hashCode()

返回此集合的哈希码值。

abstract boolean isEmpty()

如果此集合不包含元素,则返回 true

abstract Iterator<E> iterator()

返回此集合中元素的迭代器。

default Stream<E> parallelStream()

返回一个可能与此集合并行的 Stream作为源。

abstract boolean remove(Object o)

从该集合中移除指定元素的单个实例(如果存在)(可选操作)。

abstract boolean removeAll(Collection<?> c)

删除指定集合中包含的所有此集合的元素(可选操作)。

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

删除此集合中满足给定谓词的所有元素。

abstract boolean retainAll(Collection<?> c)

仅保留包含在指定集合中的此集合中的元素(可选操作)。

abstract int size()

返回此集合中的元素数量。

default Spliterator<E> spliterator()

在此集合中的元素上创建一个 Spliterator

default Stream<E> stream()

以此集合作为源返回连续的 Stream

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

返回包含此集合中所有元素的数组; 返回数组的运行时类型是指定数组的运行时类型。

abstract Object[] toArray()

返回包含此集合中所有元素的数组。

Inherited methods

From interface java.lang.Iterable

Public methods

add

Added in API level 1
boolean add (E e)

确保此集合包含指定的元素(可选操作)。 如果此集合因呼叫而改变,则返回true (如果此集合不允许重复且已包含指定元素,则返回false。

支持此操作的集合可能会限制可将哪些元素添加到此集合中。 具体而言,某些集合将拒绝添加null元素,而其他集合将对可能添加的元素的类型施加限制。 集合类应在其文档中明确指定可添加哪些元素的任何限制。

如果一个集合因为除了它已经包含该元素之外的任何其他原因而拒绝添加一个特定的元素,它必须抛出一个异常(而不是返回false )。 这保留了该调用返回后集合始终包含指定元素的不变量。

Parameters
e E: element whose presence in this collection is to be ensured
Returns
boolean true if this collection changed as a result of the call
Throws
UnsupportedOperationException if the add operation is not supported by this collection
ClassCastException if the class of the specified element prevents it from being added to this collection
NullPointerException if the specified element is null and this collection does not permit null elements
IllegalArgumentException if some property of the element prevents it from being added to this collection
IllegalStateException if the element cannot be added at this time due to insertion restrictions

addAll

Added in API level 1
boolean addAll (Collection<? extends E> c)

将指定集合中的所有元素添加到此集合(可选操作)。 如果在操作过程中修改了指定的集合,则此操作的行为未定义。 (这意味着如果指定的集合是此集合,并且此集合不是空的,则此调用的行为是未定义的。)

Parameters
c Collection: collection containing elements to be added to this collection
Returns
boolean true if this collection changed as a result of the call
Throws
UnsupportedOperationException if the addAll operation is not supported by this collection
ClassCastException if the class of an element of the specified collection prevents it from being added to this collection
NullPointerException if the specified collection contains a null element and this collection does not permit null elements, or if the specified collection is null
IllegalArgumentException if some property of an element of the specified collection prevents it from being added to this collection
IllegalStateException if not all the elements can be added at this time due to insertion restrictions

也可以看看:

clear

Added in API level 1
void clear ()

从该集合中删除所有元素(可选操作)。 此方法返回后,集合将为空。

Throws
UnsupportedOperationException if the clear operation is not supported by this collection

contains

Added in API level 1
boolean contains (Object o)

如果此集合包含指定的元素,则返回true 更正式地说,返回true当且仅当该集合包含至少一个元素e,例如(o==null ? e==null : o.equals(e))

Parameters
o Object: element whose presence in this collection is to be tested
Returns
boolean true if this collection contains the specified element
Throws
ClassCastException if the type of the specified element is incompatible with this collection (optional)
NullPointerException if the specified element is null and this collection does not permit null elements (optional)

containsAll

Added in API level 1
boolean containsAll (Collection<?> c)

如果此集合包含指定集合中的所有元素,则返回 true

Parameters
c Collection: collection to be checked for containment in this collection
Returns
boolean true if this collection contains all of the elements in the specified collection
Throws
ClassCastException if the types of one or more elements in the specified collection are incompatible with this collection (optional)
NullPointerException if the specified collection contains one or more null elements and this collection does not permit null elements (optional), or if the specified collection is null.

也可以看看:

equals

Added in API level 1
boolean equals (Object o)

将指定的对象与此集合进行比较以获得相等性。

虽然Collection接口不会增加规定向工程总承包为Object.equals,谁落实Collection接口程序员“直接”(换句话说,创建一个类,是Collection,但不是Set或者List),如果必须小心谨慎,他们选择覆盖Object.equals 没有必要这样做,最简单的方法是依靠Object的实现,但实现者可能希望实施“值比较”来代替默认的“参考比较”。 ListSet接口要求进行这种值比较。)

Object.equals方法的一般合同规定等于必须是对称的(换句话说, a.equals(b)当且仅当b.equals(a) )。 List.equalsSet.equals的合同规定列表仅与其他列表相同,并设置为其他集合。 因此,对于既不实现List也不实现Set接口的集合类的自定义equals方法必须在将此集合与任何列表或集进行比较时返回false (通过相同的逻辑,不可能编写正确实现SetList接口的类。)

Parameters
o Object: object to be compared for equality with this collection
Returns
boolean true if the specified object is equal to this collection

也可以看看:

hashCode

Added in API level 1
int hashCode ()

返回此集合的哈希码值。 虽然Collection接口不会增加规定为Object.hashCode方法的常规协定,程序员应该注意的是,它覆盖Object.equals方法的类也必须重写Object.hashCode方法,以满足为Object.hashCode方法一般合同。 特别是, c1.equals(c2)意味着c1.hashCode()==c2.hashCode()

Returns
int the hash code value for this collection

也可以看看:

isEmpty

Added in API level 1
boolean isEmpty ()

如果此集合不包含元素,则返回 true

Returns
boolean true if this collection contains no elements

iterator

Added in API level 1
Iterator<E> iterator ()

返回此集合中元素的迭代器。 没有关于元素返回顺序的保证(除非这个集合是某个提供担保的类的实例)。

Returns
Iterator<E> an Iterator over the elements in this collection

parallelStream

Added in API level 24
Stream<E> parallelStream ()

返回一个可能与此集合并行的Stream作为其源。 该方法允许返回顺序流。

当此方法应该重写spliterator()方法不能返回spliterator是IMMUTABLECONCURRENT ,或后期绑定 (详情请参阅spliterator()

实现要求:
  • The default implementation creates a parallel Stream from the collection's Spliterator.
Returns
Stream<E> a possibly parallel Stream over the elements in this collection

remove

Added in API level 1
boolean remove (Object o)

从该集合中移除指定元素的单个实例(如果存在)(可选操作)。 更正式地说,删除一个元素e,例如(o==null ? e==null : o.equals(e)) ,如果这个集合包含一个或多个这样的元素。 如果此集合包含指定的元素(或等同于此集合因该调用而更改),则返回true

Parameters
o Object: element to be removed from this collection, if present
Returns
boolean true if an element was removed as a result of this call
Throws
ClassCastException if the type of the specified element is incompatible with this collection (optional)
NullPointerException if the specified element is null and this collection does not permit null elements (optional)
UnsupportedOperationException if the remove operation is not supported by this collection

removeAll

Added in API level 1
boolean removeAll (Collection<?> c)

删除指定集合中包含的所有此集合的元素(可选操作)。 此调用返回后,此集合将不包含与指定集合相同的元素。

Parameters
c Collection: collection containing elements to be removed from this collection
Returns
boolean true if this collection changed as a result of the call
Throws
UnsupportedOperationException if the removeAll method is not supported by this collection
ClassCastException if the types of one or more elements in this collection are incompatible with the specified collection (optional)
NullPointerException if this collection contains one or more null elements and the specified collection does not support null elements (optional), or if the specified collection is null

也可以看看:

removeIf

Added in API level 24
boolean removeIf (Predicate<? super E> filter)

删除此集合中满足给定谓词的所有元素。 在迭代过程中或由谓词抛出的错误或运行时异常会传递给调用者。

实现要求:
  • The default implementation traverses all elements of the collection using its iterator(). Each matching element is removed using remove(). If the collection's iterator does not support removal then an UnsupportedOperationException will be thrown on the first matching element.
Parameters
filter Predicate: a predicate which returns true for elements to be removed
Returns
boolean true if any elements were removed
Throws
NullPointerException if the specified filter is null
UnsupportedOperationException if elements cannot be removed from this collection. Implementations may throw this exception if a matching element cannot be removed or if, in general, removal is not supported.

retainAll

Added in API level 1
boolean retainAll (Collection<?> c)

仅保留包含在指定集合中的此集合中的元素(可选操作)。 换句话说,从该集合中删除所有未包含在指定集合中的元素。

Parameters
c Collection: collection containing elements to be retained in this collection
Returns
boolean true if this collection changed as a result of the call
Throws
UnsupportedOperationException if the retainAll operation is not supported by this collection
ClassCastException if the types of one or more elements in this collection are incompatible with the specified collection (optional)
NullPointerException if this collection contains one or more null elements and the specified collection does not permit null elements (optional), or if the specified collection is null

也可以看看:

size

Added in API level 1
int size ()

返回此集合中的元素数量。 如果此集合包含多个Integer.MAX_VALUE元素,则返回Integer.MAX_VALUE

Returns
int the number of elements in this collection

spliterator

Spliterator<E> spliterator ()

在此集合中的元素上创建一个Spliterator 实现应记录由分割器报告的特征值。 如果分隔符报告SIZED并且此集合不包含任何元素,则不需要报告此类特征值。

默认实现应该被可以返回更高效的分割器的子类覆盖。 为了保持stream()parallelStream() }方法的预期懒惰行为,分割器应该具有IMMUTABLECONCURRENT的特征,或者late-binding 如果这些都不切实际,则重写类应描述分割器记录的绑定和结构干扰策略,并应覆盖stream()parallelStream()方法以使用Supplier的Supplier创建流,如下所示:

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

这些要求确保 stream()parallelStream()方法生成的流将反映终端流操作启动时的集合内容。

实现要求:
  • The default implementation creates a late-binding spliterator from the collections's Iterator. The spliterator inherits the fail-fast properties of the collection's iterator.

    创建的 Spliterator报告 SIZED

Implementation Note:
  • The created Spliterator additionally reports SUBSIZED.

    如果分割器不包含任何元素,则额外特征值的报告超出SIZEDSUBSIZED ,这不会帮助客户端控制,专门化或简化计算。 但是,这确实允许空集合共享使用不可变的空分割器实例(请参阅emptySpliterator() ),并使客户端能够确定这样的分割器是否不包含任何元素。

Returns
Spliterator<E> a Spliterator over the elements in this collection

stream

Added in API level 24
Stream<E> stream ()

以此集合作为源返回顺序 Stream

当此方法应该重写spliterator()方法不能返回spliterator是IMMUTABLECONCURRENT ,或后期绑定 (详情请参阅spliterator()

实现要求:
  • The default implementation creates a sequential Stream from the collection's Spliterator.
Returns
Stream<E> a sequential Stream over the elements in this collection

toArray

Added in API level 1
T[] toArray (T[] a)

返回包含此集合中所有元素的数组; 返回数组的运行时类型是指定数组的运行时类型。 如果集合适合指定的数组,则将其返回。 否则,将使用指定数组的运行时类型和此集合的大小分配一个新数组。

如果这个集合适合指定的数组,并且有空余的空间(即数组的元素多于这个集合),紧接在集合结尾的数组元素被设置为null 只有在调用者知道该集合不包含任何null元素时, 有助于确定此集合的长度。)

如果此集合对其迭代器返回的元素的顺序做出任何保证,则此方法必须以相同顺序返回元素。

toArray()方法一样,此方法充当基于数组和基于集合的API之间的桥梁。 此外,该方法允许精确控制输出数组的运行时类型,并且在某些情况下可以用于节省分配成本。

假设x是已知只包含字符串的集合。 以下代码可用于将集合转储到新分配的String数组中:

     String[] y = x.toArray(new String[0]);
Note that toArray(new Object[0]) is identical in function to toArray().

Parameters
a T: the array into which the elements of this collection are to be stored, if it is big enough; otherwise, a new array of the same runtime type is allocated for this purpose.
Returns
T[] an array containing all of the elements in this collection
Throws
ArrayStoreException if the runtime type of the specified array is not a supertype of the runtime type of every element in this collection
NullPointerException if the specified array is null

toArray

Added in API level 1
Object[] toArray ()

返回包含此集合中所有元素的数组。 如果此集合对其迭代器返回的元素的顺序做出任何保证,则此方法必须以相同顺序返回元素。

返回的数组将是“安全的”,因为这个集合没有维护它的引用。 (换句话说,即使该集合由数组支持,该方法也必须分配一个新数组)。 调用者可以自由修改返回的数组。

此方法充当基于数组和基于集合的API之间的桥梁。

Returns
Object[] an array containing all of the elements in this collection

Hooray!