Bags or multisets (unordered collections that may contain * duplicate elements) should implement this interface directly. * *
All general-purpose Collection implementation classes (which * typically implement Collection indirectly through one of its * subinterfaces) should provide two "standard" constructors: a void (no * arguments) constructor, which creates an empty collection, and a * constructor with a single argument of type Collection, which * creates a new collection with the same elements as its argument. In * effect, the latter constructor allows the user to copy any collection, * producing an equivalent collection of the desired implementation type. * There is no way to enforce this convention (as interfaces cannot contain * constructors) but all of the general-purpose Collection * implementations in the Java platform libraries comply. * *
The "destructive" methods contained in this interface, that is, the * methods that modify the collection on which they operate, are specified to * throw UnsupportedOperationException if this collection does not * support the operation. If this is the case, these methods may, but are not * required to, throw an UnsupportedOperationException if the * invocation would have no effect on the collection. For example, invoking * the {@link #addAll(Collection)} method on an unmodifiable collection may, * but is not required to, throw the exception if the collection to be added * is empty. * *
* Some collection implementations have restrictions on the elements that * they may contain. For example, some implementations prohibit null elements, * and some have restrictions on the types of their elements. Attempting to * add an ineligible element throws an unchecked exception, typically * NullPointerException or ClassCastException. Attempting * to query the presence of an ineligible element may throw an exception, * or it may simply return false; some implementations will exhibit the former * behavior and some will exhibit the latter. More generally, attempting an * operation on an ineligible element whose completion would not result in * the insertion of an ineligible element into the collection may throw an * exception or it may succeed, at the option of the implementation. * Such exceptions are marked as "optional" in the specification for this * interface. * *
It is up to each collection to determine its own synchronization * policy. In the absence of a stronger guarantee by the * implementation, undefined behavior may result from the invocation * of any method on a collection that is being mutated by another * thread; this includes direct invocations, passing the collection to * a method that might perform invocations, and using an existing * iterator to examine the collection. * *
Many methods in Collections Framework interfaces are defined in * terms of the {@link Object#equals(Object) equals} method. For example, * the specification for the {@link #contains(Object) contains(Object o)} * method says: "returns true if and only if this collection * contains at least one element e such that * (o==null ? e==null : o.equals(e))." This specification should * not be construed to imply that invoking Collection.contains * with a non-null argument o will cause o.equals(e) to be * invoked for any element e. Implementations are free to implement * optimizations whereby the equals invocation is avoided, for * example, by first comparing the hash codes of the two elements. (The * {@link Object#hashCode()} specification guarantees that two objects with * unequal hash codes cannot be equal.) More generally, implementations of * the various Collections Framework interfaces are free to take advantage of * the specified behavior of underlying {@link Object} methods wherever the * implementor deems it appropriate. * *
This interface is a member of the
*
* Java Collections Framework.
*
* @implSpec
* The default method implementations (inherited or otherwise) do not apply any
* synchronization protocol. If a {@code Collection} implementation has a
* specific synchronization protocol, then it must override default
* implementations to apply that protocol.
*
* @param The returned array will be "safe" in that no references to it are
* maintained by this collection. (In other words, this method must
* allocate a new array even if this collection is backed by an array).
* The caller is thus free to modify the returned array.
*
* This method acts as bridge between array-based and collection-based
* APIs.
*
* @return an array containing all of the elements in this collection
*/
Object[] toArray();
/**
* Returns an array containing all of the elements in this collection;
* the runtime type of the returned array is that of the specified array.
* If the collection fits in the specified array, it is returned therein.
* Otherwise, a new array is allocated with the runtime type of the
* specified array and the size of this collection.
*
* If this collection fits in the specified array with room to spare
* (i.e., the array has more elements than this collection), the element
* in the array immediately following the end of the collection is set to
* null. (This is useful in determining the length of this
* collection only if the caller knows that this collection does
* not contain any null elements.)
*
* If this collection makes any guarantees as to what order its elements
* are returned by its iterator, this method must return the elements in
* the same order.
*
* Like the {@link #toArray()} method, this method acts as bridge between
* array-based and collection-based APIs. Further, this method allows
* precise control over the runtime type of the output array, and may,
* under certain circumstances, be used to save allocation costs.
*
* Suppose x is a collection known to contain only strings.
* The following code can be used to dump the collection into a newly
* allocated array of String:
*
*
*
* Collections that support this operation may place limitations on what
* elements may be added to this collection. In particular, some
* collections will refuse to add null elements, and others will
* impose restrictions on the type of elements that may be added.
* Collection classes should clearly specify in their documentation any
* restrictions on what elements may be added.
*
* If a collection refuses to add a particular element for any reason
* other than that it already contains the element, it must throw
* an exception (rather than returning false). This preserves
* the invariant that a collection always contains the specified element
* after this call returns.
*
* @param e element whose presence in this collection is to be ensured
* @return true if this collection changed as a result of the
* call
* @throws UnsupportedOperationException if the add operation
* is not supported by this collection
* @throws ClassCastException if the class of the specified element
* prevents it from being added to this collection
* @throws NullPointerException if the specified element is null and this
* collection does not permit null elements
* @throws IllegalArgumentException if some property of the element
* prevents it from being added to this collection
* @throws IllegalStateException if the element cannot be added at this
* time due to insertion restrictions
*/
boolean add(E e);
/**
* Removes a single instance of the specified element from this
* collection, if it is present (optional operation). More formally,
* removes an element e such that
* (o==null ? e==null : o.equals(e)), if
* this collection contains one or more such elements. Returns
* true if this collection contained the specified element (or
* equivalently, if this collection changed as a result of the call).
*
* @param o element to be removed from this collection, if present
* @return 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)
* @throws NullPointerException if the specified element is null and this
* collection does not permit null elements
* (optional)
* @throws UnsupportedOperationException if the remove operation
* is not supported by this collection
*/
boolean remove(Object o);
// Bulk Operations
/**
* Returns true if this collection contains all of the elements
* in the specified collection.
*
* @param c collection to be checked for containment in this collection
* @return 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)
* @throws 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.
* @see #contains(Object)
*/
boolean containsAll(Collection c);
/**
* Adds all of the elements in the specified collection to this collection
* (optional operation). The behavior of this operation is undefined if
* the specified collection is modified while the operation is in progress.
* (This implies that the behavior of this call is undefined if the
* specified collection is this collection, and this collection is
* nonempty.)
*
* @param c collection containing elements to be added to this collection
* @return true if this collection changed as a result of the call
* @throws UnsupportedOperationException if the addAll operation
* is not supported by this collection
* @throws ClassCastException if the class of an element of the specified
* collection prevents it from being added to this collection
* @throws NullPointerException if the specified collection contains a
* null element and this collection does not permit null elements,
* or if the specified collection is null
* @throws IllegalArgumentException if some property of an element of the
* specified collection prevents it from being added to this
* collection
* @throws IllegalStateException if not all the elements can be added at
* this time due to insertion restrictions
* @see #add(Object)
*/
boolean addAll(Collection c);
/**
* Removes all of this collection's elements that are also contained in the
* specified collection (optional operation). After this call returns,
* this collection will contain no elements in common with the specified
* collection.
*
* @param c collection containing elements to be removed from this collection
* @return true if this collection changed as a result of the
* call
* @throws UnsupportedOperationException if the removeAll method
* is not supported by this collection
* @throws ClassCastException if the types of one or more elements
* in this collection are incompatible with the specified
* collection
* (optional)
* @throws 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
* @see #remove(Object)
* @see #contains(Object)
*/
boolean removeAll(Collection c);
/**
* Removes all of the elements of this collection that satisfy the given
* predicate. Errors or runtime exceptions thrown during iteration or by
* the predicate are relayed to the caller.
*
* @implSpec
* The default implementation traverses all elements of the collection using
* its {@link #iterator}. Each matching element is removed using
* {@link Iterator#remove()}. If the collection's iterator does not
* support removal then an {@code UnsupportedOperationException} will be
* thrown on the first matching element.
*
* @param filter a predicate which returns {@code true} for elements to be
* removed
* @return {@code true} if any elements were removed
* @throws NullPointerException if the specified filter is null
* @throws UnsupportedOperationException if a matching element cannot be
* removed from this collection
* @since 1.8
*/
default boolean removeAll(Predicate filter) {
Objects.requireNonNull(filter);
boolean removed = false;
final Iterator
*
* While the Collection interface adds no stipulations to the
* general contract for the Object.equals, programmers who
* implement the Collection interface "directly" (in other words,
* create a class that is a Collection but is not a Set
* or a List) must exercise care if they choose to override the
* Object.equals. It is not necessary to do so, and the simplest
* course of action is to rely on Object's implementation, but
* the implementor may wish to implement a "value comparison" in place of
* the default "reference comparison." (The List and
* Set interfaces mandate such value comparisons.)
*
* The general contract for the Object.equals method states that
* equals must be symmetric (in other words, a.equals(b) if and
* only if b.equals(a)). The contracts for List.equals
* and Set.equals state that lists are only equal to other lists,
* and sets to other sets. Thus, a custom equals method for a
* collection class that implements neither the List nor
* Set interface must return false when this collection
* is compared to any list or set. (By the same logic, it is not possible
* to write a class that correctly implements both the Set and
* List interfaces.)
*
* @param o object to be compared for equality with this collection
* @return true if the specified object is equal to this
* collection
*
* @see Object#equals(Object)
* @see Set#equals(Object)
* @see List#equals(Object)
*/
boolean equals(Object o);
/**
* Returns the hash code value for this collection. While the
* Collection interface adds no stipulations to the general
* contract for the Object.hashCode method, programmers should
* take note that any class that overrides the Object.equals
* method must also override the Object.hashCode method in order
* to satisfy the general contract for the Object.hashCode method.
* In particular, c1.equals(c2) implies that
* c1.hashCode()==c2.hashCode().
*
* @return the hash code value for this collection
*
* @see Object#hashCode()
* @see Object#equals(Object)
*/
int hashCode();
/**
* Creates a {@link Spliterator} over the elements in this collection.
*
* The returned {@code Spliterator} must report the characteristic
* {@link Spliterator#SIZED}; implementations should document any additional
* characteristic values reported by the returned spliterator. If
* this collection contains no elements then the returned spliterator is
* only required to report {@link Spliterator#SIZED} and is not required to
* report additional characteristic values (if any).
*
* The default implementation should be overridden by subclasses that
* can return a more efficient spliterator. In order to
* preserve expected laziness behavior for the {@link #stream()} and
* {@link #parallelStream()}} methods, spliterators should either have the
* characteristic of {@code IMMUTABLE} or {@code CONCURRENT}, or be
* late-binding.
* If none of these is practical, the overriding class should describe the
* spliterator's documented policy of binding and structural interference,
* and should override the {@link #stream()} and {@link #parallelStream()}
* methods to create streams using a {@code Supplier} of the spliterator,
* as in:
* These requirements ensure that streams produced by the
* {@link #stream()} and {@link #parallelStream()} methods will reflect the
* contents of the collection as of initiation of the terminal stream
* operation.
*
* @implSpec
* The default implementation creates a
* late-binding spliterator
* from the collections's {@code Iterator}. The spliterator inherits the
* fail-fast properties of the collection's iterator.
*
* @implNote
* The returned {@code Spliterator} additionally reports
* {@link Spliterator#SUBSIZED}.
*
* If a spliterator covers no elements then the reporting of additional
* characteristic values, beyond that of {@code SIZED} and {@code SUBSIZED},
* does not aid clients to control, specialize or simplify computation.
* However, this does enable shared use of an immutable and empty
* spliterator instance (see {@link Spliterators#emptySpliterator()}) for
* empty collections, and enables clients to determine if such a spliterator
* covers no elements.
*
* @return a {@code Spliterator} over the elements in this collection
* @since 1.8
*/
default Spliterator This method should be overridden when the {@link #spliterator()}
* method cannot return a spliterator that is {@code IMMUTABLE},
* {@code CONCURRENT}, or late-binding. (See {@link #spliterator()}
* for details.)
*
* @implSpec
* The default implementation creates a sequential {@code Stream} from the
* collection's {@code Spliterator}.
*
* @return a sequential {@code Stream} over the elements in this collection
* @since 1.8
*/
default Stream This method should be overridden when the {@link #spliterator()}
* method cannot return a spliterator that is {@code IMMUTABLE},
* {@code CONCURRENT}, or late-binding. (See {@link #spliterator()}
* for details.)
*
* @implSpec
* The default implementation creates a parallel {@code Stream} from the
* collection's {@code Spliterator}.
*
* @return a possibly parallel {@code Stream} over the elements in this
* collection
* @since 1.8
*/
default Stream
* String[] y = x.toArray(new String[0]);
*
* Note that toArray(new Object[0]) is identical in function to
* toArray().
*
* @param {@code
* Stream
*