Index (Frames) | Index (No Frames) | Package | Package Tree | Tree
java.util

Interface List

java.lang.Object
|
+--java.util.Collection
   |
   +--java.util.List

All Implemented Interfaces:

Collection


public interface List

implements Collection

An ordered collection (also known as a list). This collection allows access to elements by position, as well as control on where elements are inserted. Unlike sets, duplicate elements are permitted by this general contract (if a subclass forbids duplicates, this should be documented).

List places additional requirements on iterator, add, remove, equals, and hashCode, in addition to requiring more methods. List indexing is 0-based (like arrays), although some implementations may require time proportional to the index to obtain an arbitrary element. The List interface is incompatible with Set; you cannot implement both simultaneously.

Lists also provide a ListIterator which allows bidirectional traversal and other features atop regular iterators. Lists can be searched for arbitrary elements, and allow easy insertion and removal of multiple elements in one method call.

Note: While lists may contain themselves as elements, this leads to undefined (usually infinite recursive) behavior for some methods like hashCode or equals.

Since:Authors:See Also:

Method Summary

voidadd(int index, java.lang.Object o)

Insert an element into the list at a given position (optional operation).
booleanadd(java.lang.Object o)

Add an element to the end of the list (optional operation).
booleanaddAll(int index, java.util.Collection c)

Insert the contents of a collection into the list at a given position (optional operation).
booleanaddAll(java.util.Collection c)

Add the contents of a collection to the end of the list (optional operation).
voidclear()

Clear the list, such that a subsequent call to isEmpty() would return true (optional operation).
booleancontains(java.lang.Object o)

Test whether this list contains a given object as one of its elements.
booleancontainsAll(java.util.Collection c)

Test whether this list contains every element in a given collection.
booleanequals(java.lang.Object o)

Test whether this list is equal to another object.
java.lang.Objectget(int index)

Get the element at a given index in this list.
inthashCode()

Obtains a hash code for this list.
intindexOf(java.lang.Object o)

Obtain the first index at which a given object is to be found in this list.
booleanisEmpty()

Test whether this list is empty, that is, if size() == 0.
java.util.Iteratoriterator()

Obtain an Iterator over this list, whose sequence is the list order.
intlastIndexOf(java.lang.Object o)

Obtain the last index at which a given object is to be found in this list.
java.util.ListIteratorlistIterator()

Obtain a ListIterator over this list, starting at the beginning.
java.util.ListIteratorlistIterator(int index)

Obtain a ListIterator over this list, starting at a given position.
java.lang.Objectremove(int index)

Remove the element at a given position in this list (optional operation).
booleanremove(java.lang.Object o)

Remove the first occurence of an object from this list (optional operation).
booleanremoveAll(java.util.Collection c)

Remove all elements of a given collection from this list (optional operation).
booleanretainAll(java.util.Collection c)

Remove all elements of this list that are not contained in a given collection (optional operation).
java.lang.Objectset(int index, java.lang.Object o)

Replace an element of this list with another object (optional operation).
intsize()

Get the number of elements in this list.
java.util.ListsubList(int fromIndex, int toIndex)

Obtain a List view of a subsection of this list, from fromIndex (inclusive) to toIndex (exclusive).
java.lang.Object[]toArray()

Copy the current contents of this list into an array.
java.lang.Object[]toArray(java.lang.Object[] a)

Copy the current contents of this list into an array.

Method Details

add

public void add(int index, java.lang.Object o)

Insert an element into the list at a given position (optional operation). This shifts all existing elements from that position to the end one index to the right. This version of add has no return, since it is assumed to always succeed if there is no exception.

Parameters:

Throws:


add

public boolean add(java.lang.Object o)

Add an element to the end of the list (optional operation). If the list imposes restraints on what can be inserted, such as no null elements, this should be documented.

Parameters:

Returns:

Throws:


addAll

public boolean addAll(int index, java.util.Collection c)

Insert the contents of a collection into the list at a given position (optional operation). Shift all elements at that position to the right by the number of elements inserted. This operation is undefined if this list is modified during the operation (for example, if you try to insert a list into itself).

Parameters:

Returns:

Throws:

See Also:


addAll

public boolean addAll(java.util.Collection c)

Add the contents of a collection to the end of the list (optional operation). This operation is undefined if this list is modified during the operation (for example, if you try to insert a list into itself).

Parameters:

Returns:

Throws:

See Also:


clear

public void clear()

Clear the list, such that a subsequent call to isEmpty() would return true (optional operation).

Throws:


contains

public boolean contains(java.lang.Object o)

Test whether this list contains a given object as one of its elements. This is defined as the existence of an element e such that o == null ? e == null : o.equals(e).

Parameters:

Returns:


containsAll

public boolean containsAll(java.util.Collection c)

Test whether this list contains every element in a given collection.

Parameters:

Returns:

Throws:

See Also:


equals

public boolean equals(java.lang.Object o)

Test whether this list is equal to another object. A List is defined to be equal to an object if and only if that object is also a List, and the two lists have the same sequence. Two lists l1 and l2 are equal if and only if l1.size() == l2.size(), and for every integer n between 0 and l1.size() - 1 inclusive, l1.get(n) == null ? l2.get(n) == null : l1.get(n).equals(l2.get(n)).

Parameters:

Returns:

See Also:


get

public Object get(int index)

Get the element at a given index in this list.

Parameters:

Returns:

Throws:


hashCode

public int hashCode()

Obtains a hash code for this list. In order to obey the general contract of the hashCode method of class Object, this value is calculated as follows:

hashCode = 1;
Iterator i = list.iterator();
while (i.hasNext())
{
Object obj = i.next();
hashCode = 31 * hashCode + (obj == null ? 0 : obj.hashCode());
}

This ensures that the general contract of Object.hashCode() is adhered to.

Returns:

See Also:


indexOf

public int indexOf(java.lang.Object o)

Obtain the first index at which a given object is to be found in this list.

Parameters:

Returns:


isEmpty

public boolean isEmpty()

Test whether this list is empty, that is, if size() == 0.

Returns:


iterator

public Iterator iterator()

Obtain an Iterator over this list, whose sequence is the list order.

Returns:


lastIndexOf

public int lastIndexOf(java.lang.Object o)

Obtain the last index at which a given object is to be found in this list.

Parameters:

Returns:


listIterator

public ListIterator listIterator()

Obtain a ListIterator over this list, starting at the beginning.

Returns:


listIterator

public ListIterator listIterator(int index)

Obtain a ListIterator over this list, starting at a given position. A first call to next() would return the same as get(index), and a first call to previous() would return the same as get(index - 1).

Parameters:

Returns:

Throws:


remove

public Object remove(int index)

Remove the element at a given position in this list (optional operation). Shifts all remaining elements to the left to fill the gap.

Parameters:

Returns:

Throws:


remove

public boolean remove(java.lang.Object o)

Remove the first occurence of an object from this list (optional operation). That is, remove the first element e such that o == null ? e == null : o.equals(e).

Parameters:

Returns:

Throws:


removeAll

public boolean removeAll(java.util.Collection c)

Remove all elements of a given collection from this list (optional operation). That is, remove every element e such that c.contains(e).

Parameters:

Returns:

Throws:

See Also:


retainAll

public boolean retainAll(java.util.Collection c)

Remove all elements of this list that are not contained in a given collection (optional operation). That is, remove every element e such that !c.contains(e).

Parameters:

Returns:

Throws:

See Also:


set

public Object set(int index, java.lang.Object o)

Replace an element of this list with another object (optional operation).

Parameters:

Returns:

Throws:


size

public int size()

Get the number of elements in this list. If the list contains more than Integer.MAX_VALUE elements, return Integer.MAX_VALUE.

Returns:


subList

public List subList(int fromIndex, int toIndex)

Obtain a List view of a subsection of this list, from fromIndex (inclusive) to toIndex (exclusive). If the two indices are equal, the sublist is empty. The returned list should be modifiable if and only if this list is modifiable. Changes to the returned list should be reflected in this list. If this list is structurally modified in any way other than through the returned list, the result of any subsequent operations on the returned list is undefined.

Parameters:

Returns:

Throws:


toArray

public Object[] toArray()

Copy the current contents of this list into an array.

Returns:


toArray

public Object[] toArray(java.lang.Object[] a)

Copy the current contents of this list into an array. If the array passed as an argument has length less than that of this list, an array of the same run-time type as a, and length equal to the length of this list, is allocated using Reflection. Otherwise, a itself is used. The elements of this list are copied into it, and if there is space in the array, the following element is set to null. The resultant array is returned. Note: The fact that the following element is set to null is only useful if it is known that this list does not contain any null elements.

Parameters:

Returns:

Throws: