java.util
Interface List<E>
- Collection<E>, Iterable<E>
- AbstractList<E>, AbstractSequentialList<E>, ArrayList<E>, AttributeList, CopyOnWriteArrayList<E>, LinkedList<T>, Stack<T>, Vector<T>
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.
Collection, Set, ArrayList, LinkedList, Vector, Arrays.asList(Object[]), Collections.nCopies(int, Object), Collections.EMPTY_LIST, AbstractList, AbstractSequentialList
| 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.
|
T[] toArray, add, addAll, clear, contains, containsAll, equals, hashCode, isEmpty, iterator, remove, removeAll, retainAll, size, toArray |
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.
- T[] toArray in interface Collection<E>
a - the array to copy this list into
- an array containing the elements currently in this list, in
order
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.
- add in interface Collection<E>
- true, as defined by Collection for a modified list
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.
index - the location to insert the itemo - the object to insert
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).
- addAll in interface Collection<E>
c - the collection to add
- true if the list was modified by this action, that is, if c is
non-empty
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).
index - the location to insert the collectionc - the collection to insert
- true if the list was modified by this action, that is, if c is
non-empty
clear
public void clear()
Clear the list, such that a subsequent call to isEmpty() would return
true (optional operation).
- clear in interface Collection<E>
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).
- contains in interface Collection<E>
o - the element to look for
- true if this list contains the element
containsAll
public boolean containsAll(Collection c)
Test whether this list contains every element in a given collection.
- containsAll in interface Collection<E>
c - the collection to test for
- true if for every element o in c, contains(o) would return true
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)).
- equals in interface Collection<E>
- equals in interface Object
o - the object to test for equality with this list
- true if o is equal to this list
get
public E get(int index)
Get the element at a given index in this list.
index - the index of the element to be returned
- the element at index index in this list
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.
- hashCode in interface Collection<E>
- hashCode in interface Object
- the hash code of this list
indexOf
public int indexOf(Object o)
Obtain the first index at which a given object is to be found in this
list.
o - the object to search for
- the least integer n such that
o == null ? get(n) == null :
o.equals(get(n)), or -1 if there is no such index.
isEmpty
public boolean isEmpty()
Test whether this list is empty, that is, if size() == 0.
- isEmpty in interface Collection<E>
- true if this list contains no elements
lastIndexOf
public int lastIndexOf(Object o)
Obtain the last index at which a given object is to be found in this
list.
- the greatest integer n such that
o == null ? get(n) == null
: o.equals(get(n)), or -1 if there is no such index.
listIterator
public ListIterator listIterator()
Obtain a ListIterator over this list, starting at the beginning.
- 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).
index - the position, between 0 and size() inclusive, to begin the
iteration from
- a ListIterator over the elements of this list, in order, starting
at index
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.
index - the position within the list of the object to remove
- the object that was removed
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).
- remove in interface Collection<E>
- true if the list changed as a result of this call, that is, if
the list contained at least one occurrence of o
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).
- removeAll in interface Collection<E>
c - the collection to filter out
- true if this list was modified as a result of this call
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).
- retainAll in interface Collection<E>
c - the collection to retain
- true if this list was modified as a result of this call
set
public E set(int index,
E o) Replace an element of this list with another object (optional operation).
index - the position within this list of the element to be replacedo - the object to replace it with
- the object that was replaced
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.
- size in interface Collection<E>
- 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.
fromIndex - the index that the returned list should start from
(inclusive)toIndex - the index that the returned list should go to (exclusive)
- a List backed by a subsection of this list
toArray
public Object[] toArray()
Copy the current contents of this list into an array.
- toArray in interface Collection<E>
- 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.