List<E> (GNU Classpath 0.94-pre Documentation)

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

UNKNOWN: updated to 1.4

Method Summary
void	add(int index, E o) Insert an element into the list at a given position (optional operation).
boolean	add(E o) Add an element to the end of the list (optional operation).
boolean	addAll(int index, Collection<? extends E> c) Insert the contents of a collection into the list at a given position (optional operation).
boolean	addAll(Collection<? extends E> c) Add the contents of a collection to the end of the list (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<E>	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<E>	listIterator() Obtain a ListIterator over this list, starting at the beginning.
ListIterator<E>	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<E>	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.
<T> T[]	toArray(T[] a) Copy the current contents of this list into an array.

Method Detail

add

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.

add

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: 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.

addAll

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

Interface List<E>