Back to index

plt-scheme  4.2.1
Public Member Functions
java.util.List Interface Reference

An ordered collection (also known as a list). More...

Inheritance diagram for java.util.List:
Inheritance graph
[legend]
Collaboration diagram for java.util.List:
Collaboration graph
[legend]

List of all members.

Public Member Functions

void add (int index, Object o)
 Insert an element into the list at a given position (optional operation).
boolean add (Object o)
 Add an element to the end of the list (optional operation).
boolean addAll (int index, Collection c)
 Insert the contents of a collection into the list at a given position (optional operation).
boolean addAll (Collection 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.
Object get (int index)
 Test whether this list is equal to another object.
int indexOf (Object o)
 Obtains a hash code for 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.
Object 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).
Object set (int index, Object 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.
Object[] toArray (Object[] a)
 Copy the current contents of this list into an array.

Detailed Description

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.

Author:
Original author unknown
Eric Blake ebb9@.nosp@m.emai.nosp@m.l.byu.nosp@m..edu
See also:
Collection
Set
ArrayList
LinkedList
Vector
Arrays::asList(Object[])
Collections::nCopies(int, Object)
Collections::EMPTY_LIST
AbstractList
AbstractSequentialList
Since:
1.2 updated to 1.4

Definition at line 83 of file List.java.


Member Function Documentation

void java.util.List.add ( int  index,
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:
indexthe location to insert the item
othe object to insert
Exceptions:
UnsupportedOperationExceptionif this list does not support the add operation
IndexOutOfBoundsExceptionif index < 0 || index > size()
ClassCastExceptionif o cannot be added to this list due to its type
IllegalArgumentExceptionif o cannot be added to this list for some other reason

Implemented in java.util.SubList, java.util.AbstractList, and java.util.AbstractSequentialList.

boolean java.util.List.add ( 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:
othe object to add
Returns:
true, as defined by Collection for a modified list
Exceptions:
UnsupportedOperationExceptionif this list does not support the add operation
ClassCastExceptionif o cannot be added to this list due to its type
IllegalArgumentExceptionif o cannot be added to this list for some other reason

Implements java.util.Collection.

Implemented in java.util.AbstractList.

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:
indexthe location to insert the collection
cthe collection to insert
Returns:
true if the list was modified by this action, that is, if c is non-empty
Exceptions:
UnsupportedOperationExceptionif this list does not support the addAll operation
IndexOutOfBoundsExceptionif index < 0 || index > size()
ClassCastExceptionif some element of c cannot be added to this list due to its type
IllegalArgumentExceptionif some element of c cannot be added to this list for some other reason
NullPointerExceptionif the specified collection is null
See also:
add(int, Object)

Implemented in java.util.SubList, java.util.AbstractList, and java.util.AbstractSequentialList.

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:
cthe collection to add
Returns:
true if the list was modified by this action, that is, if c is non-empty
Exceptions:
UnsupportedOperationExceptionif this list does not support the addAll operation
ClassCastExceptionif some element of c cannot be added to this list due to its type
IllegalArgumentExceptionif some element of c cannot be added to this list for some other reason
NullPointerExceptionif the specified collection is null
See also:
add(Object)

Implements java.util.Collection.

Implemented in java.util.SubList, and java.util.AbstractList.

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

Exceptions:
UnsupportedOperationExceptionif this list does not support the clear operation

Implements java.util.Collection.

Implemented in java.util.AbstractList.

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:
othe element to look for
Returns:
true if this list contains the element

Implements java.util.Collection.

Implemented in java.util.SubList, and java.util.AbstractList.

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

Parameters:
cthe collection to test for
Returns:
true if for every element o in c, contains(o) would return true
Exceptions:
NullPointerExceptionif the collection is null
See also:
contains(Object)

Implements java.util.Collection.

Implemented in java.util.SubList, and java.util.AbstractList.

Object java.util.List.get ( int  index)

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:
othe object to test for equality with this list
Returns:
true if o is equal to this list
See also:
Object::equals(Object)
#hashCode() Get the element at a given index in this list.
Parameters:
indexthe index of the element to be returned
Returns:
the element at index index in this list
Exceptions:
IndexOutOfBoundsExceptionif index < 0 || index >= size()

Implemented in java.util.SubList, java.util.AbstractSequentialList, and java.util.AbstractList.

int java.util.List.indexOf ( Object  o)

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:
the hash code of this list
See also:
Object::hashCode()
#equals(Object) Obtain the first index at which a given object is to be found in this list.
Parameters:
othe 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

Implemented in java.util.AbstractList.

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

Returns:
true if this list contains no elements

Implements java.util.Collection.

Implemented in java.util.SubList, and java.util.AbstractList.

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

Returns:
an Iterator over the elements of this list, in order

Implements java.util.Collection.

Implemented in java.util.SubList, java.util.AbstractList, and java.util.AbstractSequentialList.

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

Implemented in java.util.AbstractList.

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

Implemented in java.util.AbstractList.

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:
indexthe 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
Exceptions:
IndexOutOfBoundsExceptionif index < 0 || index > size()

Implemented in java.util.AbstractSequentialList.

Object java.util.List.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:
indexthe position within the list of the object to remove
Returns:
the object that was removed
Exceptions:
UnsupportedOperationExceptionif this list does not support the remove operation
IndexOutOfBoundsExceptionif index < 0 || index >= size()

Implemented in java.util.SubList, java.util.AbstractList, and java.util.AbstractSequentialList.

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:
othe 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
Exceptions:
UnsupportedOperationExceptionif this list does not support the remove operation

Implements java.util.Collection.

Implemented in java.util.SubList, and java.util.AbstractList.

Remove all elements of a given collection from this list (optional operation).

That is, remove every element e such that c.contains(e).

Parameters:
cthe collection to filter out
Returns:
true if this list was modified as a result of this call
Exceptions:
UnsupportedOperationExceptionif this list does not support the removeAll operation
NullPointerExceptionif the collection is null
See also:
remove(Object)
contains(Object)

Implements java.util.Collection.

Implemented in java.util.SubList, and java.util.AbstractList.

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:
cthe collection to retain
Returns:
true if this list was modified as a result of this call
Exceptions:
UnsupportedOperationExceptionif this list does not support the retainAll operation
NullPointerExceptionif the collection is null
See also:
remove(Object)
contains(Object)

Implements java.util.Collection.

Implemented in java.util.SubList, and java.util.AbstractList.

Object java.util.List.set ( int  index,
Object  o 
)

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

Parameters:
indexthe position within this list of the element to be replaced
othe object to replace it with
Returns:
the object that was replaced
Exceptions:
UnsupportedOperationExceptionif this list does not support the set operation
IndexOutOfBoundsExceptionif index < 0 || index >= size()
ClassCastExceptionif o cannot be added to this list due to its type
IllegalArgumentExceptionif o cannot be added to this list for some other reason

Implemented in java.util.SubList, java.util.AbstractList, and java.util.AbstractSequentialList.

Get the number of elements in this list.

If the list contains more than Integer.MAX_VALUE elements, return Integer.MAX_VALUE.

Returns:
the number of elements in the list

Implements java.util.Collection.

Implemented in java.util.SubList, and java.util.AbstractList.

List java.util.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:
fromIndexthe index that the returned list should start from (inclusive)
toIndexthe index that the returned list should go to (exclusive)
Returns:
a List backed by a subsection of this list
Exceptions:
IndexOutOfBoundsExceptionif fromIndex < 0 || toIndex > size() || fromIndex > toIndex
IllegalArgumentExceptionif fromIndex > toIndex (according to AbstractList). Don't you love Sun's inconsistent specifications?

Implemented in java.util.AbstractList.

Object [] java.util.List.toArray ( )

Copy the current contents of this list into an array.

Returns:
an array of type Object[] and length equal to the length of this list, containing the elements currently in this list, in order

Implements java.util.Collection.

Implemented in java.util.SubList, and java.util.AbstractList.

Object [] java.util.List.toArray ( 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:
athe array to copy this list into
Returns:
an array containing the elements currently in this list, in order
Exceptions:
ArrayStoreExceptionif the type of any element of the collection is not a subtype of the element type of a
NullPointerExceptionif the specified array is null

Implements java.util.Collection.

Implemented in java.util.SubList, and java.util.AbstractList.


The documentation for this interface was generated from the following file: