Collections – Collections: Part II
15.2 Collections
The Collection<E> interface specifies the contract that all collections should implement. Some of the operations in the interface are optional, meaning that a collection may choose to provide a stub implementation of such an operation that throws an UnsupportedOperationException when invoked—for example, when a collection is unmodifiable. The implementations of collections from the java.util package support all the optional operations in the Collection<E> interface (see Figure 15.2 and Table 15.2).
Many of the methods return a boolean value to indicate whether the collection was modified as a result of the operation.
Basic Operations
The basic operations are used to query a collection about its contents and allow elements to be added to and removed from a collection. Many examples in this chapter make use of these operations.
int size()
boolean isEmpty()
boolean contains(Object element)
boolean add(E element)
Optional
boolean remove(Object element)
Optional
The size() method returns the number of elements in the collection, and the isEmpty() method determines whether there are any elements in the collection.
The contains() method checks for membership of the argument object in the collection, using object value equality.
The add() and remove() methods return true if the collection was modified as a result of the operation.
By returning the value false, the add() method indicates that the collection excludes duplicates, and that the collection already contains an object equal to the argument object.
Note that we can only add an object of a specific type (E). However, a collection allows us to determine whether it has an element equal to an arbitrary object, or remove an element that is equal to an arbitrary object.
Bulk Operations
These operations are performed on a collection as a single entity. See §15.4, p. 804, for an example.
boolean containsAll(Collection<?> c)
boolean addAll(Collection<? extends E> c)
Optional
boolean removeAll(Collection<?> c)
Optional
boolean retainAll(Collection<?> c)
Optional
void clear()
Optional
These bulk operations can be used to perform the equivalent of set logic on arbitrary collections (i.e., also lists and not just sets). The containsAll() method returns true if all elements of the specified collection are also contained in the current collection.
The addAll(), removeAll(), and retainAll() methods are destructive in the sense that the collection on which they are invoked can be modified. The operations performed by these methods are visualized by Venn diagrams in Figure 15.4.
Figure 15.4 Bulk Operations on Collections
The addAll() method requires that the element type of the other collection is the same as, or a subtype of, the element type of the current collection. The removeAll() and retainAll() operations can be performed with collections of any type.
The clear() method removes all elements in the collection so that the collection is empty.