# Interface Collection<E>

All Superinterfaces:
  `Iterable<E>`

All Known Subinterfaces:
  `Deque<E>, List<E>, NavigableSet<E>, Queue<E>, Set<E>, SortedSet<E>`

All Known Implementing Classes:
  `AbstractCollection, AbstractList, AbstractQueue, AbstractSequentialList, AbstractSet, ArrayDeque, ArrayList, ComponentSelector, HashSet, LinkedHashSet, LinkedList, PriorityQueue, Stack, TreeSet, Vector`

public interface Collection<E> extends Iterable<E>

`Collection` is the root of the collection hierarchy. It defines operations on data collections and the behavior that they will have in all implementations of `Collection`s.

All direct or indirect implementations of `Collection` should implement at least two constructors. One with no parameters which creates an empty collection and one with a parameter of type `Collection`. This second constructor can be used to create a collection of different type as the initial collection but with the same elements. Implementations of `Collection` cannot be forced to implement these two constructors but at least all implementations under `java.util` do.

Methods that change the content of a collection throw an `UnsupportedOperationException` if the underlying collection does not support that operation, though it's not mandatory to throw such an `Exception` in cases where the requested operation would not change the collection. In these cases it's up to the implementation whether it throws an `UnsupportedOperationException` or not.

Methods marked with (optional) can throw an `UnsupportedOperationException` if the underlying collection doesn't support that method.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `boolean`
  `add(E object)`
  Attempts to add `object` to the contents of this `Collection` (optional).
  `boolean`
  `addAll(Collection<? extends E> collection)`
  Attempts to add all of the objects contained in `Collection` to the contents of this `Collection` (optional).
  `void`
  `clear()`
  Removes all elements from this `Collection`, leaving it empty (optional).
  `boolean`
  `contains(Object object)`
  Tests whether this `Collection` contains the specified object.
  `boolean`
  `containsAll(Collection<?> collection)`
  Tests whether this `Collection` contains all objects contained in the specified `Collection`.
  `boolean`
  `equals(Object object)`
  Compares the argument to the receiver, and returns true if they represent the same object using a class specific comparison.
  `int`
  `hashCode()`
  Returns an integer hash code for the receiver.
  `boolean`
  `isEmpty()`
  Returns if this `Collection` contains no elements.
  `Iterator<E>`
  `iterator()`
  Returns an instance of `Iterator` that may be used to access the objects contained by this `Collection`.
  `boolean`
  `remove(Object object)`
  Removes one instance of the specified object from this `Collection` if one is contained (optional).
  `boolean`
  `removeAll(Collection<?> collection)`
  Removes all occurrences in this `Collection` of each object in the specified `Collection` (optional).
  `boolean`
  `retainAll(Collection<?> collection)`
  Removes all objects from this `Collection` that are not also found in the `Collection` passed (optional).
  `int`
  `size()`
  Returns a count of how many objects this `Collection` contains.
  `Object[]`
  `toArray()`
  Returns a new array containing all elements contained in this `Collection`.
  `<T> T[]`
  `toArray(T[] array)`
  Returns an array containing all elements contained in this `Collection`.

- ## Method Details

  - ### add

    boolean add(E object)

    Attempts to add `object` to the contents of this `Collection` (optional).

    After this method finishes successfully it is guaranteed that the object is contained in the collection.

    If the collection was modified it returns `true`, `false` if no changes were made.

    An implementation of `Collection` may narrow the set of accepted objects, but it has to specify this in the documentation. If the object to be added does not meet this restriction, then an `IllegalArgumentException` is thrown.

    If a collection does not yet contain an object that is to be added and adding the object fails, this method must throw an appropriate unchecked Exception. Returning false is not permitted in this case because it would violate the postcondition that the element will be part of the collection after this method finishes.

    ###### Parameters

    - `object`: the object to add.

    ###### Returns

    Returns:

      `true` if this `Collection` is modified, `false` otherwise.

      ###### Throws

      - `UnsupportedOperationException`: if adding to this `Collection` is not supported.

      - `ClassCastException`: @throws ClassCastException if the class of the object is inappropriate for this collection.

      - `IllegalArgumentException`: if the object cannot be added to this `Collection`.

      - `NullPointerException`: if null elements cannot be added to the `Collection`.

  - ### addAll

    boolean addAll(Collection<? extends E> collection)

    Attempts to add all of the objects contained in `Collection` to the contents of this `Collection` (optional). If the passed `Collection` is changed during the process of adding elements to this `Collection`, the behavior is not defined.

    ###### Parameters

    - `collection`: the `Collection` of objects.

    ###### Returns

    Returns:

      `true` if this `Collection` is modified, `false` otherwise.

      ###### Throws

      - `UnsupportedOperationException`: if adding to this `Collection` is not supported.

      - `ClassCastException`: @throws ClassCastException if the class of an object is inappropriate for this `Collection`.

      - `IllegalArgumentException`: if an object cannot be added to this `Collection`.

      - `NullPointerException`: @throws NullPointerException if `collection` is `null`, or if it contains `null` elements and this `Collection` does not support such elements.

  - ### clear

    void clear()

    Removes all elements from this `Collection`, leaving it empty (optional).

    ###### Throws

    - `UnsupportedOperationException`: if removing from this `Collection` is not supported.

    ###### See also

    - #isEmpty

    - #size

  - ### contains

    boolean contains(Object object)

    Tests whether this `Collection` contains the specified object. Returns `true` if and only if at least one element `elem` in this `Collection` meets following requirement: `(object==null ? elem==null : object.equals(elem))`.

    ###### Parameters

    - `object`: the object to search for.

    ###### Returns

    Returns:

      `true` if object is an element of this `Collection`, `false` otherwise.

      ###### Throws

      - `ClassCastException`: @throws ClassCastException if the object to look for isn't of the correct type.

      - `NullPointerException`: @throws NullPointerException if the object to look for is `null` and this `Collection` doesn't support `null` elements.

  - ### containsAll

    boolean containsAll(Collection<?> collection)

    Tests whether this `Collection` contains all objects contained in the specified `Collection`. If an element `elem` is contained several times in the specified `Collection`, the method returns `true` even if `elem` is contained only once in this `Collection`.

    ###### Parameters

    - `collection`: the collection of objects.

    ###### Returns

    Returns:

      `true` if all objects in the specified `Collection` are elements of this `Collection`, `false` otherwise.

      ###### Throws

      - `ClassCastException`: @throws ClassCastException if one or more elements of `collection` isn't of the correct type.

      - `NullPointerException`: @throws NullPointerException if `collection` contains at least one `null` element and this `Collection` doesn't support `null` elements.

      - `NullPointerException`: if `collection` is `null`.

  - ### equals

    boolean equals(Object object)

    Compares the argument to the receiver, and returns true if they represent the same object using a class specific comparison.

    ###### Parameters

    - `object`: the object to compare with this object.

    ###### Returns

    Overrides:
      `equals` in class `Object`
    Returns:

      `true` if the object is the same as this object and `false` if it is different from this object.

      ###### See also

      - #hashCode

  - int hashCode()

    Returns an integer hash code for the receiver. Objects which are equal return the same value for this method.

    ###### Returns

    the receiver's hash.

    ###### See also

    - #equals
    Overrides:
      `hashCode` in class `Object`

  - ### isEmpty

    boolean isEmpty()

    Returns if this `Collection` contains no elements.

    ###### Returns

    Returns:

      `true` if this `Collection` has no elements, `false` otherwise.

      ###### See also

      - #size

  - ### iterator

    Iterator<E> iterator()

    Returns an instance of `Iterator` that may be used to access the objects contained by this `Collection`. The order in which the elements are returned by the iterator is not defined. Only if the instance of the `Collection` has a defined order the elements are returned in that order.

    ###### Returns

    an iterator for accessing the `Collection` contents.

    Specified by:
      `iterator` in interface `Iterable<E>`

  - ### remove

    boolean remove(Object object)

    Removes one instance of the specified object from this `Collection` if one is contained (optional). The element `elem` that is removed complies with `(object==null ? elem==null : object.equals(elem)`.

    ###### Parameters

    - `object`: the object to remove.

    ###### Returns

    Returns:

      `true` if this `Collection` is modified, `false` otherwise.

      ###### Throws

      - `UnsupportedOperationException`: if removing from this `Collection` is not supported.

      - `ClassCastException`: if the object passed is not of the correct type.

      - `NullPointerException`: @throws NullPointerException if `object` is `null` and this `Collection` doesn't support `null` elements.

  - ### removeAll

    boolean removeAll(Collection<?> collection)

    Removes all occurrences in this `Collection` of each object in the specified `Collection` (optional). After this method returns none of the elements in the passed `Collection` can be found in this `Collection` anymore.

    ###### Parameters

    - `collection`: the collection of objects to remove.

    ###### Returns

    Returns:

      `true` if this `Collection` is modified, `false` otherwise.

      ###### Throws

      - `UnsupportedOperationException`: if removing from this `Collection` is not supported.

      - `ClassCastException`: @throws ClassCastException if one or more elements of `collection` isn't of the correct type.

      - `NullPointerException`: @throws NullPointerException if `collection` contains at least one `null` element and this `Collection` doesn't support `null` elements.

      - `NullPointerException`: if `collection` is `null`.

  - ### retainAll

    boolean retainAll(Collection<?> collection)

    Removes all objects from this `Collection` that are not also found in the `Collection` passed (optional). After this method returns this `Collection` will only contain elements that also can be found in the `Collection` passed to this method.

    ###### Parameters

    - `collection`: the collection of objects to retain.

    ###### Returns

    Returns:

      `true` if this `Collection` is modified, `false` otherwise.

      ###### Throws

      - `UnsupportedOperationException`: if removing from this `Collection` is not supported.

      - `ClassCastException`: @throws ClassCastException if one or more elements of `collection` isn't of the correct type.

      - `NullPointerException`: @throws NullPointerException if `collection` contains at least one `null` element and this `Collection` doesn't support `null` elements.

      - `NullPointerException`: if `collection` is `null`.

  - ### size

    int size()

    Returns a count of how many objects this `Collection` contains.

    ###### Returns

    Returns:
      how many objects this `Collection` contains, or Integer.MAX_VALUE if there are more than Integer.MAX_VALUE elements in this `Collection`.

  - ### toArray

    Object[] toArray()

    Returns a new array containing all elements contained in this `Collection`.

    If the implementation has ordered elements it will return the element array in the same order as an iterator would return them.

    The array returned does not reflect any changes of the `Collection`. A new array is created even if the underlying data structure is already an array.

    ###### Returns

    an array of the elements from this `Collection`.

  - ### toArray

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

    Returns an array containing all elements contained in this `Collection`. If the specified array is large enough to hold the elements, the specified array is used, otherwise an array of the same type is created. If the specified array is used and is larger than this `Collection`, the array element following the `Collection` elements is set to null.

    If the implementation has ordered elements it will return the element array in the same order as an iterator would return them.

    `toArray(new Object[0])` behaves exactly the same way as `toArray()` does.

    ###### Parameters

    - `array`: the array.

    ###### Returns

    an array of the elements from this `Collection`.

    ###### Throws

    - `ArrayStoreException`: @throws ArrayStoreException if the type of an element in this `Collection` cannot be stored in the type of the specified array.