public interface List extends Collection
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.
Collection
,
Set
,
ArrayList
,
LinkedList
,
Vector
Modifier and Type | Method and Description |
---|---|
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(Collection c)
Add the contents of a collection 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).
|
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.
|
Object |
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.
|
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.
|
void add(int index, Object o)
index
- the location to insert the itemo
- the object to insertUnsupportedOperationException
- if this list does not support the
add operationIndexOutOfBoundsException
- if index < 0 || index > size()ClassCastException
- if o cannot be added to this list due to its
typeIllegalArgumentException
- if o cannot be added to this list for
some other reasonboolean add(Object o)
add
in interface Collection
o
- the object to addUnsupportedOperationException
- if this list does not support the
add operationClassCastException
- if o cannot be added to this list due to its
typeIllegalArgumentException
- if o cannot be added to this list for
some other reasonboolean addAll(int index, Collection c)
index
- the location to insert the collectionc
- the collection to insertUnsupportedOperationException
- if this list does not support the
addAll operationIndexOutOfBoundsException
- if index < 0 || index > size()ClassCastException
- if some element of c cannot be added to this
list due to its typeIllegalArgumentException
- if some element of c cannot be added
to this list for some other reasonNullPointerException
- if the specified collection is nulladd(int, Object)
boolean addAll(Collection c)
addAll
in interface Collection
c
- the collection to addUnsupportedOperationException
- if this list does not support the
addAll operationClassCastException
- if some element of c cannot be added to this
list due to its typeIllegalArgumentException
- if some element of c cannot be added
to this list for some other reasonNullPointerException
- if the specified collection is nulladd(Object)
void clear()
clear
in interface Collection
UnsupportedOperationException
- if this list does not support the
clear operationboolean contains(Object o)
o == null ? e == null : o.equals(e)
.contains
in interface Collection
o
- the element to look forboolean containsAll(Collection c)
containsAll
in interface Collection
c
- the collection to test forNullPointerException
- if the collection is nullcontains(Object)
boolean equals(Object o)
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))
.equals
in interface Collection
equals
in class Object
o
- the object to test for equality with this listObject.equals(Object)
,
hashCode()
Object get(int index)
index
- the index of the element to be returnedIndexOutOfBoundsException
- if index < 0 || index >= size()int hashCode()
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.
hashCode
in interface Collection
hashCode
in class Object
Object.hashCode()
,
equals(Object)
int indexOf(Object o)
o
- the object to search foro == null ? get(n) == null :
o.equals(get(n))
, or -1 if there is no such indexboolean isEmpty()
isEmpty
in interface Collection
Iterator iterator()
iterator
in interface Collection
int lastIndexOf(Object o)
o == null ? get(n) == null
: o.equals(get(n))
, or -1 if there is no such indexListIterator listIterator()
ListIterator listIterator(int index)
index
- the position, between 0 and size() inclusive, to begin the
iteration fromIndexOutOfBoundsException
- if index < 0 || index > size()Object remove(int index)
index
- the position within the list of the object to removeUnsupportedOperationException
- if this list does not support the
remove operationIndexOutOfBoundsException
- if index < 0 || index >= size()boolean remove(Object o)
o == null ? e == null : o.equals(e)
.remove
in interface Collection
o
- the object to removeUnsupportedOperationException
- if this list does not support the
remove operationboolean removeAll(Collection c)
removeAll
in interface Collection
c
- the collection to filter outUnsupportedOperationException
- if this list does not support the
removeAll operationNullPointerException
- if the collection is nullremove(Object)
,
contains(Object)
boolean retainAll(Collection c)
retainAll
in interface Collection
c
- the collection to retainUnsupportedOperationException
- if this list does not support the
retainAll operationNullPointerException
- if the collection is nullremove(Object)
,
contains(Object)
Object set(int index, Object o)
index
- the position within this list of the element to be replacedo
- the object to replace it withUnsupportedOperationException
- if this list does not support the
set operationIndexOutOfBoundsException
- if index < 0 || index >= size()ClassCastException
- if o cannot be added to this list due to its
typeIllegalArgumentException
- if o cannot be added to this list for
some other reasonint size()
size
in interface Collection
List subList(int fromIndex, int toIndex)
fromIndex
- the index that the returned list should start from
(inclusive)toIndex
- the index that the returned list should go to (exclusive)IndexOutOfBoundsException
- if fromIndex < 0
|| toIndex > size() || fromIndex > toIndexIllegalArgumentException
- if fromIndex > toIndex (according to
AbstractList). Don't you love Sun's inconsistent specifications?Object[] toArray()
toArray
in interface Collection
Object[] toArray(Object[] a)
toArray
in interface Collection
a
- the array to copy this list intoArrayStoreException
- if the type of any element of the
collection is not a subtype of the element type of aNullPointerException
- if the specified array is null