# 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` - if the class of the object is inappropriate for this `List`.
      `IllegalArgumentException` - if the object cannot be added to this `List`.
      `IndexOutOfBoundsException` - if `location < 0 || location > size()`

  - ### add

    boolean add(E object)
    Adds the specified object at the end of this `List`.
    Specified by:
      `add` in interface `Collection<E>`
    Parameters:
      `object` - the object to add.
    Returns:
      always true.
    Throws:
      `UnsupportedOperationException` - if adding to this `List` is not supported.
      `ClassCastException` - if the class of the object is inappropriate for this `List`.
      `IllegalArgumentException` - if the object cannot be added to this `List`.

  - ### 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:
      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` - if the class of an object is inappropriate for this `List`.
      `IllegalArgumentException` - if an object cannot be added to this `List`.
      `IndexOutOfBoundsException` - if `location < 0 || > 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.
    Specified by:
      `addAll` in interface `Collection<E>`
    Parameters:
      `collection` - the collection of objects.
    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` - 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.
    Specified by:
      `clear` in interface `Collection<E>`
    Throws:
      `UnsupportedOperationException` - if removing from this `List` is not supported.
    See Also:
      - `isEmpty()`
      - `size()`

  - ### contains

    boolean contains(Object object)
    Tests whether this `List` contains the specified object.
    Specified by:
      `contains` in interface `Collection<E>`
    Parameters:
      `object` - the object to search for.
    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.
    Specified by:
      `containsAll` in interface `Collection<E>`
    Parameters:
      `collection` - the collection of objects
    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.
    Specified by:
      `equals` in interface `Collection<E>`
    Overrides:
      `equals` in class `Object`
    Parameters:
      `object` - the object to compare with this 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 < 0 || >= 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.
    Specified by:
      `hashCode` in interface `Collection<E>`
    Overrides:
      `hashCode` in class `Object`
    Returns:
      the hash code of the `List`.
    See Also:
      - `Collection.equals(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:
      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.
    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`.
    Specified by:
      `iterator` in interface `Collection<E>`
    Specified by:
      `iterator` in interface `Iterable<E>`
    Returns:
      an iterator on the elements of this `List`.
    See Also:
      - `Iterator`

  - ### 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:
      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 < 0 || 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 < 0 || >= size()`

  - ### remove

    boolean remove(Object object)
    Removes the first occurrence of the specified object from this `List`.
    Specified by:
      `remove` in interface `Collection<E>`
    Parameters:
      `object` - the object to remove.
    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.
    Specified by:
      `removeAll` in interface `Collection<E>`
    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.

  - ### retainAll

    boolean retainAll(Collection<?> collection)
    Removes all objects from this `List` that are not contained in the specified collection.
    Specified by:
      `retainAll` in interface `Collection<E>`
    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.

  - ### 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` - if the class of an object is inappropriate for this `List`.
      `IllegalArgumentException` - if an object cannot be added to this `List`.
      `IndexOutOfBoundsException` - if `location < 0 || >= size()`

  - ### size

    int size()
    Returns the number of elements in this `List`.
    Specified by:
      `size` in interface `Collection<E>`
    Returns:
      the number of elements in this `List`.

  - ### 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` - if `start < 0, start > end` or `end > size()`

  - ### toArray

    Object[] toArray()
    Returns an array containing all elements contained in this `List`.
    Specified by:
      `toArray` in interface `Collection<E>`
    Returns:
      an array of the elements from this `List`.

  - ### 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.
    Specified by:
      `toArray` in interface `Collection<E>`
    Parameters:
      `array` - the array.
    Returns:
      an array of the elements from this `List`.
    Throws:
      `ArrayStoreException` - if the type of an element in this `List` cannot be stored in the type of the specified array.