Java Reference ยท Collections
The Collection interface
Reference for java.util.Collection: the methods shared by lists, sets and queues, bulk operations, toArray(), removeIf() and the optional-operation rules.
java.util.Collection<E> is the root interface of lists, sets and queues. It describes a group of elements and the operations every such group supports: adding, removing, testing membership, asking for the size, iterating and converting to an array. Map is not a Collection.
Writing a method that takes a Collection<E> (or Iterable<E> when you only need to loop) lets callers pass any list, set or queue. Because Collection does not say anything about ordering or duplicates, the exact behavior of some methods depends on the implementation.
static double average(Collection<Integer> numbers) { ... }
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.
Syntax
public interface Collection<E> extends Iterable<E>
| Method | Description |
|---|---|
boolean add(E e) |
Adds an element; returns true if the collection changed (a set returns false for a duplicate). |
boolean addAll(Collection<? extends E> c) |
Adds every element of c. |
boolean remove(Object o) |
Removes one occurrence of o, if present. |
boolean removeAll(Collection<?> c) |
Removes all elements that are also in c. |
boolean retainAll(Collection<?> c) |
Keeps only elements that are also in c. |
boolean removeIf(Predicate<? super E> filter) |
Removes elements matching the predicate (Java 8). |
boolean contains(Object o) / containsAll(Collection<?> c) |
Membership tests, using equals(). |
int size() / boolean isEmpty() |
Number of elements; emptiness test. |
void clear() |
Removes everything. |
Object[] toArray() / <T> T[] toArray(T[] a) / toArray(IntFunction<T[]>) |
Copies the elements into a new array (the generator form is Java 11). |
Stream<E> stream() / parallelStream() |
Stream over the elements. |
Iterator<E> iterator() |
Inherited from Iterable. |
Throws: mutators throw UnsupportedOperationException on unmodifiable collections; NullPointerException where an implementation forbids null; ClassCastException or IllegalArgumentException for elements the collection refuses.
Usage notes
- Optional operations:
add,remove,clearand friends are "optional".List.of(),Collections.unmodifiableCollection()andArrays.asList()(for add/remove) reject them. - Return value: mutators report whether the collection changed, which is useful for sets:
if (seen.add(x)) { ... }. remove(Object)removes one element in a list with duplicates. UseremoveIforremoveAllto remove every match.equals()drivescontains()andremove(). Elements without a properequals()are never found.- Bulk operations take collections, not arrays. Wrap an array with
Arrays.asList(). toArray(new T[0])is the recommended array form; passing a pre-sized array brings no speed benefit on modern JVMs.- Concurrent modification: changing a collection while iterating over it (except through the iterator) throws
ConcurrentModificationExceptionin most implementations. - Sequenced collections: since Java 21,
List,Dequeand some sets extendSequencedCollectionwithgetFirst(),getLast()andreversed().