java.util
Interface List

All Superinterfaces:

Collection, Iterable

All Known Implementing Classes:

AbstractList, ArrayList, Vector

public interface List

extends Collection

List is a collection which maintains an ordering for its elements. Every element in the list has an index.

Method Summary

void	add(int location, java.lang.Object object) Inserts the specified object into this Vector at the specified location.
boolean	add(java.lang.Object object) Adds the specified object at the end of this List.
boolean	addAll(Collection collection) Adds the objects in the specified Collection to the end of this List.
boolean	addAll(int location, Collection 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(java.lang.Object object) Searches this List for the specified object.
boolean	containsAll(Collection collection) Searches this List for all objects in the specified Collection.
boolean	equals(java.lang.Object object) Compares the argument to the receiver, and answers true if they represent the same object using a class specific comparison.
java.lang.Object	get(int location) Answers the element at the specified location in this List.
int	hashCode() Answers an integer hash code for the receiver.
int	indexOf(java.lang.Object object) Searches this List for the specified object and returns the index of the first occurrence.
boolean	isEmpty() Answers if this List has no elements, a size of zero.
Iterator	iterator() Answers an Iterator on the elements of this List.
int	lastIndexOf(java.lang.Object object) Searches this List for the specified object and returns the index of the last occurrence.
ListIterator	listIterator() Answers a ListIterator on the elements of this List.
ListIterator	listIterator(int location) Answers a ListIterator on the elements of this List.
java.lang.Object	remove(int location) Removes the object at the specified location from this List.
boolean	remove(java.lang.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.
java.lang.Object	set(int location, java.lang.Object object) Replaces the element at the specified location in this List with the specified object.
int	size() Answers the number of elements in this List.
List	subList(int start, int end) Answers a List of the specified portion of this List from the start index to one less than the end index.
java.lang.Object[]	toArray() Answers an array containing all elements contained in this List.
java.lang.Object[]	toArray(java.lang.Object[] array) Answers an array containing all elements contained in this List.

Method Detail

add

public void add(int location,
                java.lang.Object object)

Inserts the specified object into this Vector at the specified location. The object is inserted before any previous element at the specified location. If the location is equal to the size of this List, the object is added at the end.

Parameters:

location - the index at which to insert

object - the object to add

Throws:

UnsupportedOperationException - when adding to this List is not supported

ClassCastException - when the class of the object is inappropriate for this List

IllegalArgumentException - when the object cannot be added to this List

IndexOutOfBoundsException - when location < 0 || >= size()

add

public boolean add(java.lang.Object object)

Adds the specified object at the end of this List.

Specified by:

add in interface Collection

Parameters:

object - the object to add

Returns:

true

Throws:

UnsupportedOperationException - when adding to this List is not supported

ClassCastException - when the class of the object is inappropriate for this List

IllegalArgumentException - when the object cannot be added to this List

addAll

public boolean addAll(int location,
                      Collection 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 iterator.

Parameters:

location - the index at which to insert

collection - the Collection of objects

Returns:

true if this List is modified, false otherwise

Throws:

UnsupportedOperationException - when adding to this List is not supported

ClassCastException - when the class of an object is inappropriate for this List

IllegalArgumentException - when an object cannot be added to this List

IndexOutOfBoundsException - when location < 0 || >= size()

addAll

public boolean addAll(Collection collection)

Adds the objects in the specified Collection to the end of this List. The objects are added in the order they are returned from the Collection iterator.

Specified by:

addAll in interface Collection

Parameters:

collection - the Collection of objects

Returns:

true if this List is modified, false otherwise

Throws:

UnsupportedOperationException - when adding to this List is not supported

ClassCastException - when the class of an object is inappropriate for this List

IllegalArgumentException - when an object cannot be added to this List

clear

public void clear()

Removes all elements from this List, leaving it empty.

Specified by:

clear in interface Collection

Throws:

UnsupportedOperationException - when removing from this List is not supported

See Also:

isEmpty(), size()

contains

public boolean contains(java.lang.Object object)

Searches this List for the specified object.

Specified by:

contains in interface Collection

Parameters:

object - the object to search for

Returns:

true if object is an element of this List, false otherwise

containsAll

public boolean containsAll(Collection collection)

Searches this List for all objects in the specified Collection.

Specified by:

containsAll in interface Collection

Parameters:

collection - the Collection of objects

Returns:

true if all objects in the specified Collection are elements of this List, false otherwise

equals

public boolean equals(java.lang.Object object)

Compares the argument to the receiver, and answers true if they represent the same object using a class specific comparison.

Specified by:

equals in interface Collection

Parameters:

object - Object the object to compare with this object.

Returns:

boolean true if the object is the same as this object false if it is different from this object.

See Also:

hashCode()

get

public java.lang.Object get(int location)

Answers 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 - when location < 0 || >= size()

hashCode

public int hashCode()

Answers an integer hash code for the receiver. Objects which are equal answer the same value for this method.

Specified by:

hashCode in interface Collection

Returns:

the receiver's hash

See Also:

equals(java.lang.Object)

indexOf

public int indexOf(java.lang.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

isEmpty

public boolean isEmpty()

Answers if this List has no elements, a size of zero.

Specified by:

isEmpty in interface Collection

Returns:

true if this List has no elements, false otherwise

See Also:

size()

iterator

public Iterator iterator()

Answers an Iterator on the elements of this List. The elements are iterated in the same order that they occur in the List.

Specified by:

iterator in interface Collection

Returns:

an Iterator on the elements of this List

See Also:

Iterator

lastIndexOf

public int lastIndexOf(java.lang.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

listIterator

public ListIterator listIterator()

Answers a ListIterator on the elements of this List. The elements are iterated in the same order that they occur in the List.

Returns:

a ListIterator on the elements of this List

See Also:

ListIterator

listIterator

public ListIterator listIterator(int location)

Answers a ListIterator on the elements of this List. The elements are iterated in the same order that they occur in the List. The iteration starts at the specified location.

Parameters:

location - the index at which to start the iteration

Returns:

a ListIterator on the elements of this List

Throws:

IndexOutOfBoundsException - when location < 0 || >= size()

See Also:

ListIterator

remove

public java.lang.Object 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 - when removing from this List is not supported

IndexOutOfBoundsException - when location < 0 || >= size()

remove

public boolean remove(java.lang.Object object)

Removes the first occurrence of the specified object from this List.

Specified by:

remove in interface Collection

Parameters:

object - the object to remove

Returns:

true if this List is modified, false otherwise

Throws:

UnsupportedOperationException - when removing from this List is not supported

removeAll

public boolean removeAll(Collection collection)

Removes all occurrences in this List of each object in the specified Collection.

Specified by:

removeAll in interface Collection

Parameters:

collection - the Collection of objects to remove

Returns:

true if this List is modified, false otherwise

Throws:

UnsupportedOperationException - when removing from this List is not supported

retainAll

public boolean retainAll(Collection collection)

Removes all objects from this List that are not contained in the specified Collection.

Specified by:

retainAll in interface Collection

Parameters:

collection - the Collection of objects to retain

Returns:

true if this List is modified, false otherwise

Throws:

UnsupportedOperationException - when removing from this List is not supported

set

public java.lang.Object set(int location,
                            java.lang.Object object)

Replaces the element at the specified location in this List with the specified object.

Parameters:

location - the index at which to put the specified object

object - the object to add

Returns:

the previous element at the index

Throws:

UnsupportedOperationException - when replacing elements in this List is not supported

ClassCastException - when the class of an object is inappropriate for this List

IllegalArgumentException - when an object cannot be added to this List

IndexOutOfBoundsException - when location < 0 || >= size()

size

public int size()

Answers the number of elements in this List.

Specified by:

size in interface Collection

Returns:

the number of elements in this List

subList

public List subList(int start,
                    int end)

Answers a List of the specified portion of this List from the start index to one less than the end index. The returned List is backed by this list so changes to one 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 - when start < 0, start > end or end > size()

toArray

public java.lang.Object[] toArray()

Answers an array containing all elements contained in this List.

Specified by:

toArray in interface Collection

Returns:

an array of the elements from this List

toArray

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

Answers 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

Parameters:

array - the array

Returns:

an array of the elements from this List

Throws:

ArrayStoreException - when the type of an element in this List cannot be stored in the type of the specified array