java.util
Class ArrayList
java.lang.Object
|
+--java.util.AbstractCollection
|
+--java.util.AbstractList
|
+--java.util.ArrayList
All Implemented Interfaces:
List, RandomAccess, Cloneable, Serializable, List, Collection
An array-backed implementation of the List interface. This implements
all optional list operations, and permits null elements, so that it is
better than Vector, which it replaces. Random access is roughly constant
time, and iteration is roughly linear time, so it is nice and fast, with
less overhead than a LinkedList.
Each list has a capacity, and as the array reaches that capacity it
is automatically transferred to a larger array. You also have access to
ensureCapacity and trimToSize to control the backing array's size, avoiding
reallocation or wasted memory.
ArrayList is not synchronized, so if you need multi-threaded access,
consider using:
List l = Collections.synchronizedList(new ArrayList(...));
The iterators are fail-fast, meaning that any structural
modification, except for remove()
called on the iterator
itself, cause the iterator to throw a
ConcurrentModificationException rather than exhibit
non-deterministic behavior.
Authors:- Jon A. Zeppieri
- Bryce McKinlay
- Eric Blake <ebb9@email.byu.edu>
See Also:
ArrayList
public ArrayList()
Construct a new ArrayList with the default capcity (16).
ArrayList
public ArrayList(int capacity)
Construct a new ArrayList with the supplied initial capacity.
Parameters:
Throws:
ArrayList
public ArrayList(java.util.Collection c)
Construct a new ArrayList, and initialize it with the elements
in the supplied Collection. The initial capacity is 110% of the
Collection's size.
Parameters:
Throws:
add
public void add(int index, java.lang.Object e)
Adds the supplied element at the specified index, shifting all
elements currently at that index or higher one to the right.
Parameters:
Throws:
add
public boolean add(java.lang.Object e)
Appends the supplied element to the end of this list.
Parameters:
Returns:
- true, the add will always succeed
addAll
public boolean addAll(int index, java.util.Collection c)
Add all elements in the supplied collection, inserting them beginning
at the specified index.
Parameters:
Throws:
addAll
public boolean addAll(java.util.Collection c)
Add each element in the supplied Collection to this List. It is undefined
what happens if you modify the list while this is taking place; for
example, if the collection contains this list.
Parameters:
Returns:
- true if the list was modified, in other words c is not empty
Throws:
clear
public void clear()
Removes all elements from this List
clone
public Object clone()
Creates a shallow copy of this ArrayList (elements are not cloned).
Returns:
contains
public boolean contains(java.lang.Object e)
Returns true iff element is in this ArrayList.
Parameters:
Returns:
- true if the list contains e
ensureCapacity
public void ensureCapacity(int minCapacity)
Guarantees that this list will have at least enough capacity to
hold minCapacity elements. This implementation will grow the list to
max(current * 2, minCapacity) if (minCapacity > current). The JCL says
explictly that "this method increases its capacity to minCap", while
the JDK 1.3 online docs specify that the list will grow to at least the
size specified.
Parameters:
get
public Object get(int index)
Retrieves the element at the user-supplied index.
Parameters:
Throws:
indexOf
public int indexOf(java.lang.Object e)
Returns the lowest index at which element appears in this List, or
-1 if it does not appear.
Parameters:
Returns:
- the index where e was found
isEmpty
public boolean isEmpty()
Checks if the list is empty.
Returns:
- true if there are no elements
lastIndexOf
public int lastIndexOf(java.lang.Object e)
Returns the highest index at which element appears in this List, or
-1 if it does not appear.
Parameters:
Returns:
- the index where e was found
remove
public Object remove(int index)
Removes the element at the user-supplied index.
Parameters:
Returns:
Throws:
removeRange
protected void removeRange(int fromIndex, int toIndex)
Removes all elements in the half-open interval [fromIndex, toIndex).
Does nothing when toIndex is equal to fromIndex.
Parameters:
Throws:
set
public Object set(int index, java.lang.Object e)
Sets the element at the specified index.
Parameters:
Returns:
- the element previously at the specified index
Throws:
size
public int size()
Returns the number of elements in this list.
Returns:
toArray
public Object[] toArray()
Returns an Object array containing all of the elements in this ArrayList.
The array is independent of this list.
Returns:
- an array representation of this list
toArray
public Object[] toArray(java.lang.Object[] a)
Returns an Array whose component type is the runtime component type of
the passed-in Array. The returned Array is populated with all of the
elements in this ArrayList. If the passed-in Array is not large enough
to store all of the elements in this List, a new Array will be created
and returned; if the passed-in Array is larger than the size
of this List, then size() index will be set to null.
Parameters:
Returns:
- an array representation of this list
Throws:
trimToSize
public void trimToSize()
Trims the capacity of this List to be equal to its size;
a memory saver.
Each list has a capacity, and as the array reaches that capacity it is automatically transferred to a larger array. You also have access to ensureCapacity and trimToSize to control the backing array's size, avoiding reallocation or wasted memory.
ArrayList is not synchronized, so if you need multi-threaded access, consider using:
List l = Collections.synchronizedList(new ArrayList(...));
The iterators are fail-fast, meaning that any structural modification, except for
remove()
called on the iterator itself, cause the iterator to throw a ConcurrentModificationException rather than exhibit non-deterministic behavior.