Overview Package Class Use Source Tree Index Deprecated About
Prev Class | Next ClassFrames | No Frames
Summary: Nested | Field | Method | ConstrDetail: Nested | Field | Method | Constr

java.util

Interface List<E>

All Superinterfaces:
Collection<E>, Iterable<E>
Known Implementing Classes:
AbstractList<E>, AbstractSequentialList<E>, ArrayList<E>, AttributeList, CopyOnWriteArrayList<E>, CorbaList, LinkedList<T>, Sequence, SimpleList, Stack<T>, Vector<T>
public interface List<E>
extends Collection<E>
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:
1.2
See Also:
Collection, Set, ArrayList, LinkedList, Vector, Arrays.asList(Object[]), Collections.nCopies(int, Object), Collections.EMPTY_LIST, AbstractList, AbstractSequentialList

Method Summary

T[] toArray(T[] a)
Copy the current contents of this list into an array.
boolean
add(E o)
Add an element to the end of the list (optional operation).
void
add(int index, E o)
Insert an element into the list at a given position (optional operation).
boolean
addAll(E> c)
Add the contents of a collection to the end of the list (optional operation).
boolean
addAll(int index, E> c)
Insert the contents of a collection into the list at a given position (optional operation).
void
clear()
Clear the list, such that a subsequent call to isEmpty() would return true (optional operation).
boolean
contains(Object o)
Test whether this list contains a given object as one of its elements.
boolean
containsAll(Collection c)
Test whether this list contains every element in a given collection.
boolean
equals(Object o)
Test whether this list is equal to another object.
E
get(int index)
Get the element at a given index in this list.
int
hashCode()
Obtains a hash code for this list.
int
indexOf(Object o)
Obtain the first index at which a given object is to be found in this list.
boolean
isEmpty()
Test whether this list is empty, that is, if size() == 0.
Iterator
iterator()
Obtain an Iterator over this list, whose sequence is the list order.
int
lastIndexOf(Object o)
Obtain the last index at which a given object is to be found in this list.
ListIterator
listIterator()
Obtain a ListIterator over this list, starting at the beginning.
ListIterator
listIterator(int index)
Obtain a ListIterator over this list, starting at a given position.
E
remove(int index)
Remove the element at a given position in this list (optional operation).
boolean
remove(Object o)
Remove the first occurence of an object from this list (optional operation).
boolean
removeAll(Collection c)
Remove all elements of a given collection from this list (optional operation).
boolean
retainAll(Collection c)
Remove all elements of this list that are not contained in a given collection (optional operation).
E
set(int index, E o)
Replace an element of this list with another object (optional operation).
int
size()
Get the number of elements in this list.
List
subList(int fromIndex, int toIndex)
Obtain a List view of a subsection of this list, from fromIndex (inclusive) to toIndex (exclusive).
Object[]
toArray()
Copy the current contents of this list into an array.

Methods inherited from interface java.util.Collection<E>

T[] toArray, add, addAll, clear, contains, containsAll, equals, hashCode, isEmpty, iterator, remove, removeAll, retainAll, size, toArray

Methods inherited from interface java.lang.Iterable<E>

iterator

Method Details

T[] toArray

public  T[] toArray(T[] 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.
Specified by:
T[] toArray in interface Collection<E>
Parameters:
a - the array to copy this list into
Returns:
an array containing the elements currently in this list, in order
Throws:
ArrayStoreException - if the type of any element of the collection is not a subtype of the element type of a
NullPointerException - if the specified array is null

add

public boolean add(E 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.
Specified by:
add in interface Collection<E>
Parameters:
o - the object to add
Returns:
true, as defined by Collection for a modified list
Throws:
UnsupportedOperationException - if this list does not support the add operation
ClassCastException - if o cannot be added to this list due to its type
IllegalArgumentException - if o cannot be added to this list for some other reason
NullPointerException - if o is null and this list doesn't support the addition of null values.

add

public void add(int index,
                E 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:
index - the location to insert the item
o - the object to insert
Throws:
UnsupportedOperationException - if this list does not support the add operation
IndexOutOfBoundsException - if index < 0 || index > size()
ClassCastException - if o cannot be added to this list due to its type
IllegalArgumentException - if o cannot be added to this list for some other reason
NullPointerException - if o is null and this list doesn't support the addition of null values.

addAll

public boolean addAll(E> 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).
Specified by:
addAll in interface Collection<E>
Parameters:
c - the collection to add
Returns:
true if the list was modified by this action, that is, if c is non-empty
Throws:
UnsupportedOperationException - if this list does not support the addAll operation
ClassCastException - if some element of c cannot be added to this list due to its type
IllegalArgumentException - if some element of c cannot be added to this list for some other reason
NullPointerException - if the specified collection is null
NullPointerException - if some element of c is null and this list doesn't support the addition of null values.
See Also:
add(Object)

addAll

public boolean addAll(int index,
                      E> 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:
index - the location to insert the collection
c - the collection to insert
Returns:
true if the list was modified by this action, that is, if c is non-empty
Throws:
UnsupportedOperationException - if this list does not support the addAll operation
IndexOutOfBoundsException - if index < 0 || index > size()
ClassCastException - if some element of c cannot be added to this list due to its type
IllegalArgumentException - if some element of c cannot be added to this list for some other reason
NullPointerException - if some element of c is null and this list doesn't support the addition of null values.
NullPointerException - if the specified collection is null
See Also:
add(int, Object)

clear

public void clear()
Clear the list, such that a subsequent call to isEmpty() would return true (optional operation).
Specified by:
clear in interface Collection<E>
Throws:
UnsupportedOperationException - if this list does not support the clear operation

contains

public boolean contains(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).
Specified by:
contains in interface Collection<E>
Parameters:
o - the element to look for
Returns:
true if this list contains the element
Throws:
ClassCastException - if the type of o is not a valid type for this list.
NullPointerException - if o is null and the list doesn't support null values.

containsAll

public boolean containsAll(Collection c)
Test whether this list contains every element in a given collection.
Specified by:
containsAll in interface Collection<E>
Parameters:
c - the collection to test for
Returns:
true if for every element o in c, contains(o) would return true
Throws:
NullPointerException - if the collection is null
ClassCastException - if the type of any element in c is not a valid type for this list.
NullPointerException - if some element of c is null and this list does not support null values.
See Also:
contains(Object)

equals

public boolean equals(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)).
Specified by:
equals in interface Collection<E>
Overrides:
equals in interface Object
Parameters:
o - the object to test for equality with this list
Returns:
true if o is equal to this list
See Also:
Object.equals(Object), hashCode()

get

public E get(int index)
Get the element at a given index in this list.
Parameters:
index - the index of the element to be returned
Returns:
the element at index index in this list
Throws:
IndexOutOfBoundsException - if index < 0 || index >= size()

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.

Specified by:
hashCode in interface Collection<E>
Overrides:
hashCode in interface Object
Returns:
the hash code of this list
See Also:
Object.hashCode(), equals(Object)

indexOf

public int indexOf(Object o)
Obtain the first index at which a given object is to be found in this list.
Parameters:
o - the object to search for
Returns:
the least integer n such that o == null ? get(n) == null : o.equals(get(n)), or -1 if there is no such index.
Throws:
ClassCastException - if the type of o is not a valid type for this list.
NullPointerException - if o is null and this list does not support null values.

isEmpty

public boolean isEmpty()
Test whether this list is empty, that is, if size() == 0.
Specified by:
isEmpty in interface Collection<E>
Returns:
true if this list contains no elements

iterator

public Iterator iterator()
Obtain an Iterator over this list, whose sequence is the list order.
Specified by:
iterator in interface Collection<E>
iterator in interface Iterable<E>
Returns:
an Iterator over the elements of this list, in order

lastIndexOf

public int lastIndexOf(Object o)
Obtain the last index at which a given object is to be found in this list.
Returns:
the greatest integer n such that o == null ? get(n) == null : o.equals(get(n)), or -1 if there is no such index.
Throws:
ClassCastException - if the type of o is not a valid type for this list.
NullPointerException - if o is null and this list does not support null values.

listIterator

public ListIterator listIterator()
Obtain a ListIterator over this list, starting at the beginning.
Returns:
a ListIterator over the elements of this list, in order, starting at the beginning

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:
index - the position, between 0 and size() inclusive, to begin the iteration from
Returns:
a ListIterator over the elements of this list, in order, starting at index
Throws:
IndexOutOfBoundsException - if index < 0 || index > size()

remove

public E 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:
index - the position within the list of the object to remove
Returns:
the object that was removed
Throws:
UnsupportedOperationException - if this list does not support the remove operation
IndexOutOfBoundsException - if index < 0 || index >= size()

remove

public boolean remove(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).
Specified by:
remove in interface Collection<E>
Parameters:
o - the object to remove
Returns:
true if the list changed as a result of this call, that is, if the list contained at least one occurrence of o
Throws:
UnsupportedOperationException - if this list does not support the remove operation
ClassCastException - if the type of o is not a valid type for this list.
NullPointerException - if o is null and this list does not support removing null values.

removeAll

public boolean removeAll(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).
Specified by:
removeAll in interface Collection<E>
Parameters:
c - the collection to filter out
Returns:
true if this list was modified as a result of this call
Throws:
UnsupportedOperationException - if this list does not support the removeAll operation
NullPointerException - if the collection is null
ClassCastException - if the type of any element in c is not a valid type for this list.
NullPointerException - if some element of c is null and this list does not support removing null values.
See Also:
remove(Object), contains(Object)

retainAll

public boolean retainAll(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).
Specified by:
retainAll in interface Collection<E>
Parameters:
c - the collection to retain
Returns:
true if this list was modified as a result of this call
Throws:
UnsupportedOperationException - if this list does not support the retainAll operation
NullPointerException - if the collection is null
ClassCastException - if the type of any element in c is not a valid type for this list.
NullPointerException - if some element of c is null and this list does not support retaining null values.
See Also:
remove(Object), contains(Object)

set

public E set(int index,
             E o)
Replace an element of this list with another object (optional operation).
Parameters:
index - the position within this list of the element to be replaced
o - the object to replace it with
Returns:
the object that was replaced
Throws:
UnsupportedOperationException - if this list does not support the set operation
IndexOutOfBoundsException - if index < 0 || index >= size()
ClassCastException - if o cannot be added to this list due to its type
IllegalArgumentException - if o cannot be added to this list for some other reason
NullPointerException - if o is null and this list does not support null values.

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.
Specified by:
size in interface Collection<E>
Returns:
the number of elements in the list

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:
fromIndex - the index that the returned list should start from (inclusive)
toIndex - the index that the returned list should go to (exclusive)
Returns:
a List backed by a subsection of this list
Throws:
IndexOutOfBoundsException - if fromIndex < 0 || toIndex > size() || fromIndex > toIndex

toArray

public Object[] toArray()
Copy the current contents of this list into an array.
Specified by:
toArray in interface Collection<E>
Returns:
an array of type Object[] and length equal to the length of this list, containing the elements currently in this list, in order
List.java -- An ordered collection which allows indexed access Copyright (C) 1998, 2001, 2004, 2005 Free Software Foundation, Inc. This file is part of GNU Classpath. GNU Classpath is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version. GNU Classpath is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with GNU Classpath; see the file COPYING. If not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. Linking this library statically or dynamically with other modules is making a combined work based on this library. Thus, the terms and conditions of the GNU General Public License cover the whole combination. As a special exception, the copyright holders of this library give you permission to link this library with independent modules to produce an executable, regardless of the license terms of these independent modules, and to copy and distribute the resulting executable under terms of your choice, provided that you also meet, for each linked independent module, the terms and conditions of the license of that module. An independent module is a module which is not derived from or based on this library. If you modify this library, you may extend this exception to your version of the library, but you are not obligated to do so. If you do not wish to do so, delete this exception statement from your version.

Overview Package Class Use Source Tree Index Deprecated About