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, Lists 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 Lists, 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>