List (java-runtime 7.0.90 API)

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

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`boolean`	`add(E object)` Adds the specified object at the end of this `List`.
`void`	`add(int location, E object)` Inserts the specified object into this `List` at the specified location.
`boolean`	`addAll(Collection<? extends E> collection)` Adds the objects in the specified collection to 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`.
`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 Detail
  - 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 Lists, 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(java.lang.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.

Interface List<E>

Method Summary

Method Detail

add

add

addAll

addAll

clear

contains

containsAll

equals

get

hashCode

indexOf

isEmpty

iterator

lastIndexOf

listIterator

listIterator

remove

remove

removeAll

retainAll

set

size

subList

toArray

toArray