# Interface List<E>

All Superinterfaces:
  `Collection<E>, Iterable<E>`

All Known Implementing Classes:
  `AbstractList, AbstractSequentialList, ArrayList, LinkedList, Stack, Vector`

public interface List<E> extends Collection<E>
A `List` is a collection which maintains an ordering for its elements. Every element in the `List` has an index. Each element can thus be accessed by its index, with the first index being zero. Normally, `List`s allow duplicate elements, as compared to Sets, where elements have to be unique.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `add(int location, E object)`
  Inserts the specified object into this `List` at the specified location.
  `boolean`
  `add(E object)`
  Adds the specified object at the end of this `List`.
  `boolean`
  `addAll(int location, Collection<? extends E> collection)`
  Inserts the objects in the specified collection at the specified location in this `List`.
  `boolean`
  `addAll(Collection<? extends E> collection)`
  Adds the objects in the specified collection to the end of this `List`.
  `void`
  `clear()`
  Removes all elements from this `List`, leaving it empty.
  `boolean`
  `contains(Object object)`
  Tests whether this `List` contains the specified object.
  `boolean`
  `containsAll(Collection<?> collection)`
  Tests whether this `List` contains all objects contained in the specified collection.
  `boolean`
  `equals(Object object)`
  Compares the given object with the `List`, and returns true if they represent the same object using a class specific comparison.
  `E`
  `get(int location)`
  Returns the element at the specified location in this `List`.
  `int`
  `hashCode()`
  Returns the hash code for this `List`.
  `int`
  `indexOf(Object object)`
  Searches this `List` for the specified object and returns the index of the first occurrence.
  `boolean`
  `isEmpty()`
  Returns whether this `List` contains no elements.
  `Iterator<E>`
  `iterator()`
  Returns an iterator on the elements of this `List`.
  `int`
  `lastIndexOf(Object object)`
  Searches this `List` for the specified object and returns the index of the last occurrence.
  `ListIterator<E>`
  `listIterator()`
  Returns a `List` iterator on the elements of this `List`.
  `ListIterator<E>`
  `listIterator(int location)`
  Returns a list iterator on the elements of this `List`.
  `E`
  `remove(int location)`
  Removes the object at the specified location from this `List`.
  `boolean`
  `remove(Object object)`
  Removes the first occurrence of the specified object from this `List`.
  `boolean`
  `removeAll(Collection<?> collection)`
  Removes all occurrences in this `List` of each object in the specified collection.
  `boolean`
  `retainAll(Collection<?> collection)`
  Removes all objects from this `List` that are not contained in the specified collection.
  `E`
  `set(int location, E object)`
  Replaces the element at the specified location in this `List` with the specified object.
  `int`
  `size()`
  Returns the number of elements in this `List`.
  `List<E>`
  `subList(int start, int end)`
  Returns a `List` of the specified portion of this `List` from the given start index to the end index minus one.
  `Object[]`
  `toArray()`
  Returns an array containing all elements contained in this `List`.
  `<T> T[]`
  `toArray(T[] array)`
  Returns an array containing all elements contained in this `List`.

- ## Method Details

  - ### add

    void add(int location, E object)

    Inserts the specified object into this `List` at the specified location. The object is inserted before the current element at the specified location. If the location is equal to the size of this `List`, the object is added at the end. If the location is smaller than the size of this `List`, then all elements beyond the specified location are moved by one position towards the end of the `List`.

    ###### Parameters

    - `location`: the index at which to insert.

    - `object`: the object to add.

    ###### Throws

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

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

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

    - `IndexOutOfBoundsException`: if `location size()`

  - ### add

    boolean add(E object)

    Adds the specified object at the end of this `List`.

    ###### Parameters

    - `object`: the object to add.

    ###### Returns

    always true.

    ###### Throws

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

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

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

    Specified by:
      `add` in interface `Collection<E>`
    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(int location, Collection<? extends E> collection)

    Inserts the objects in the specified collection at the specified location in this `List`. The objects are added in the order they are returned from the collection's iterator.

    ###### Parameters

    - `location`: the index at which to insert.

    - `collection`: the collection of objects to be inserted.

    ###### Returns

    Returns:

      true if this `List` has been modified through the insertion, false otherwise (i.e. if the passed collection was empty).

      ###### Throws

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

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

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

      - `IndexOutOfBoundsException`: if `location size()`

  - ### addAll

    boolean addAll(Collection<? extends E> collection)

    Adds the objects in the specified collection to the end of this `List`. The objects are added in the order in which they are returned from the collection's iterator.

    ###### Parameters

    - `collection`: the collection of objects.

    ###### Returns

    Specified by:
      `addAll` in interface `Collection<E>`
    Returns:

      `true` if this `List` is modified, `false` otherwise (i.e. if the passed collection was empty).

      ###### Throws

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

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

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

  - ### clear

    void clear()

    Removes all elements from this `List`, leaving it empty.

    ###### Throws

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

    ###### See also

    - #isEmpty

    - #size

    Specified by:
      `clear` in interface `Collection<E>`

  - ### contains

    boolean contains(Object object)

    Tests whether this `List` contains the specified object.

    ###### Parameters

    - `object`: the object to search for.

    ###### Returns

    Specified by:
      `contains` in interface `Collection<E>`
    Returns:
      `true` if object is an element of this `List`, `false` otherwise

  - ### containsAll

    boolean containsAll(Collection<?> collection)

    Tests whether this `List` contains all objects contained in the specified collection.

    ###### Parameters

    - `collection`: the collection of objects

    ###### Returns

    Specified by:
      `containsAll` in interface `Collection<E>`
    Returns:
      `true` if all objects in the specified collection are elements of this `List`, `false` otherwise.

  - ### equals

    boolean equals(Object object)

    Compares the given object with the `List`, and returns true if they represent the same object using a class specific comparison. For `List`s, this means that they contain the same elements in exactly the same order.

    ###### Parameters

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

    ###### Returns

    Specified by:
      `equals` in interface `Collection<E>`
    Overrides:
      `equals` in class `Object`
    Returns:

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

      ###### See also

      - #hashCode

  - ### get

    E get(int location)

    Returns the element at the specified location in this `List`.

    ###### Parameters

    - `location`: the index of the element to return.

    ###### Returns

    the element at the specified location.

    ###### Throws

    - `IndexOutOfBoundsException`: if `location = size()`

  - ### hashCode

    int hashCode()

    Returns the hash code for this `List`. It is calculated by taking each element' hashcode and its position in the `List` into account.

    ###### Returns

    the hash code of the `List`.

    Specified by:
      `hashCode` in interface `Collection<E>`
    Overrides:
      `hashCode` in class `Object`

  - ### indexOf

    int indexOf(Object object)

    Searches this `List` for the specified object and returns the index of the first occurrence.

    ###### Parameters

    - `object`: the object to search for.

    ###### Returns

    Returns:
      the index of the first occurrence of the object or -1 if the object was not found.

  - ### isEmpty

    boolean isEmpty()

    Returns whether this `List` contains no elements.

    ###### Returns

    Specified by:
      `isEmpty` in interface `Collection<E>`
    Returns:

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

      ###### See also

      - #size

  - ### iterator

    Iterator<E> iterator()

    Returns an iterator on the elements of this `List`. The elements are iterated in the same order as they occur in the `List`.

    ###### Returns

    an iterator on the elements of this `List`.

    ###### See also

    - Iterator
    Specified by:
      `iterator` in interface `Collection<E>`
    Specified by:
      `iterator` in interface `Iterable<E>`

  - ### lastIndexOf

    int lastIndexOf(Object object)

    Searches this `List` for the specified object and returns the index of the last occurrence.

    ###### Parameters

    - `object`: the object to search for.

    ###### Returns

    Returns:
      the index of the last occurrence of the object, or -1 if the object was not found.

  - ### listIterator

    ListIterator<E> listIterator()

    Returns a `List` iterator on the elements of this `List`. The elements are iterated in the same order that they occur in the `List`.

    ###### Returns

    a `List` iterator on the elements of this `List`

    ###### See also

    - ListIterator

  - ### listIterator

    ListIterator<E> listIterator(int location)

    Returns a list iterator on the elements of this `List`. The elements are iterated in the same order as they occur in the `List`. The iteration starts at the specified location.

    ###### Parameters

    - `location`: the index at which to start the iteration.

    ###### Returns

    a list iterator on the elements of this `List`.

    ###### Throws

    - `IndexOutOfBoundsException`: if `location size()`

    ###### See also

    - ListIterator

  - ### remove

    E remove(int location)

    Removes the object at the specified location from this `List`.

    ###### Parameters

    - `location`: the index of the object to remove.

    ###### Returns

    the removed object.

    ###### Throws

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

    - `IndexOutOfBoundsException`: if `location = size()`

  - ### remove

    boolean remove(Object object)

    Removes the first occurrence of the specified object from this `List`.

    ###### Parameters

    - `object`: the object to remove.

    ###### Returns

    Specified by:
      `remove` in interface `Collection<E>`
    Returns:

      true if this `List` was modified by this operation, false otherwise.

      ###### Throws

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

  - ### removeAll

    boolean removeAll(Collection<?> collection)

    Removes all occurrences in this `List` of each object in the specified collection.

    ###### Parameters

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

    ###### Returns

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

    ###### Throws

    - `UnsupportedOperationException`: if removing from this `List` is not supported.
    Specified by:
      `removeAll` in interface `Collection<E>`
    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 `List` that are not contained in the specified collection.

    ###### Parameters

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

    ###### Returns

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

    ###### Throws

    - `UnsupportedOperationException`: if removing from this `List` is not supported.
    Specified by:
      `retainAll` in interface `Collection<E>`
    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`.

  - ### set

    E set(int location, E object)

    Replaces the element at the specified location in this `List` with the specified object. This operation does not change the size of the `List`.

    ###### Parameters

    - `location`: the index at which to put the specified object.

    - `object`: the object to insert.

    ###### Returns

    the previous element at the index.

    ###### Throws

    - `UnsupportedOperationException`: if replacing elements in this `List` is not supported.

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

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

    - `IndexOutOfBoundsException`: if `location = size()`

  - ### size

    int size()

    Returns the number of elements in this `List`.

    ###### Returns

    the number of elements in this `List`.

    Specified by:
      `size` in interface `Collection<E>`
    Returns:
      how many objects this `Collection` contains, or Integer.MAX_VALUE if there are more than Integer.MAX_VALUE elements in this `Collection`.

  - ### subList

    List<E> subList(int start, int end)

    Returns a `List` of the specified portion of this `List` from the given start index to the end index minus one. The returned `List` is backed by this `List` so changes to it are reflected by the other.

    ###### Parameters

    - `start`: the index at which to start the sublist.

    - `end`: the index one past the end of the sublist.

    ###### Returns

    a list of a portion of this `List`.

    ###### Throws

    - `IndexOutOfBoundsException`: @throws IndexOutOfBoundsException if `start end` or `end > size()`

  - ### toArray

    Object[] toArray()

    Returns an array containing all elements contained in this `List`.

    ###### Returns

    an array of the elements from this `List`.

    Specified by:
      `toArray` in interface `Collection<E>`

  - ### toArray

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

    Returns an array containing all elements contained in this `List`. 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 `List`, the array element following the collection elements is set to null.

    ###### Parameters

    - `array`: the array.

    ###### Returns

    an array of the elements from this `List`.

    ###### Throws

    - `ArrayStoreException`: @throws ArrayStoreException if the type of an element in this `List` cannot be stored in the type of the specified array.
    Specified by:
      `toArray` in interface `Collection<E>`