# Class ArrayList<E>

java.lang.Object
java.util.AbstractCollection<E>
java.util.AbstractList<E>
java.util.ArrayList<E>

All Implemented Interfaces:
  `Iterable<E>, Collection<E>, List<E>, RandomAccess`

public class ArrayList<E> extends AbstractList<E> implements List<E>, RandomAccess

ArrayList is an implementation of `List`, backed by an array. All optional operations adding, removing, and replacing are supported. The elements can be any objects.

##### Since

1.2

- ## Field Summary

  ### Fields inherited from class AbstractList

  `modCount`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `ArrayList()`
  Constructs a new instance of `ArrayList` with ten capacity.
  `ArrayList(int capacity)`
  Constructs a new instance of `ArrayList` with the specified capacity.
  `ArrayList(Collection<? extends E> collection)`
  Constructs a new instance of `ArrayList` containing the elements of the specified collection.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `add(int location, E object)`
  Inserts the specified object into this `ArrayList` at the specified location.
  `boolean`
  `add(E object)`
  Adds the specified object at the end of this `ArrayList`.
  `boolean`
  `addAll(int location, Collection<? extends E> collection)`
  Inserts the objects in the specified collection at the specified location in this List.
  `boolean`
  `addAll(Collection<? extends E> collection)`
  Adds the objects in the specified collection to this `ArrayList`.
  `void`
  `clear()`
  Removes all elements from this `ArrayList`, leaving it empty.
  `boolean`
  `contains(java.lang.Object object)`
  Searches this `ArrayList` for the specified object.
  `void`
  `ensureCapacity(int minimumCapacity)`
  Ensures that after this operation the `ArrayList` can hold the specified number of elements without further growing.
  `E`
  `get(int location)`
  Returns the element at the specified location in this list.
  `int`
  `indexOf(java.lang.Object object)`
  Searches this list for the specified object and returns the index of the first occurrence.
  `boolean`
  `isEmpty()`
  Returns if this `Collection` contains no elements.
  `int`
  `lastIndexOf(java.lang.Object object)`
  Searches this list for the specified object and returns the index of the last occurrence.
  `E`
  `remove(int location)`
  Removes the object at the specified location from this list.
  `boolean`
  `remove(java.lang.Object object)`
  Removes one instance of the specified object from this `Collection` if one is contained (optional).
  `protected void`
  `removeRange(int start, int end)`
  Removes the objects in the specified range from the start to the end, but not including the end index.
  `E`
  `set(int location, E object)`
  Replaces the element at the specified location in this `ArrayList` with the specified object.
  `int`
  `size()`
  Returns the number of elements in this `ArrayList`.
  `java.lang.Object[]`
  `toArray()`
  Returns a new array containing all elements contained in this `ArrayList`.
  `<T> T[]`
  `toArray(T[] contents)`
  Returns an array containing all elements contained in this `ArrayList`.
  `void`
  `trimToSize()`
  Sets the capacity of this `ArrayList` to be the same as the current size.

  ### Methods inherited from class AbstractList

  `equals, hashCode, iterator, listIterator, listIterator, subList`

  ### Methods inherited from class AbstractCollection

  `containsAll, removeAll, retainAll, toString`

  ### Methods inherited from class java.lang.Object

  `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

  ### Methods inherited from interface Collection

  `removeIf`

  ### Methods inherited from interface Iterable

  `forEach`

  ### Methods inherited from interface List

  `containsAll, equals, hashCode, iterator, listIterator, listIterator, removeAll, replaceAll, retainAll, sort, subList`

- ## Constructor Details

  - ### ArrayList

    public ArrayList()
    Constructs a new instance of `ArrayList` with ten capacity.

  - ### ArrayList

    public ArrayList(int capacity)

    Constructs a new instance of `ArrayList` with the specified capacity.

    ###### Parameters

    - `capacity`: the initial capacity of this `ArrayList`.

  - ### ArrayList

    public ArrayList(Collection<? extends E> collection)

    Constructs a new instance of `ArrayList` containing the elements of the specified collection. The initial size of the `ArrayList` will be 10% larger than the size of the specified collection.

    ###### Parameters

    - `collection`: the collection of elements to add.

- ## Method Details

  - ### add

    public void add(int location, E object)

    Inserts the specified object into this `ArrayList` 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 `ArrayList`, the object is added at the end.

    ###### Parameters

    - `location`: the index at which to insert the object.

    - `object`: the object to add.

    ###### Throws

    - `IndexOutOfBoundsException`: when `location size()`
    Specified by:
      `add` in interface `List<E>`
    Overrides:
      `add` in class `AbstractList<E>`

  - ### add

    public boolean add(E object)

    Adds the specified object at the end of this `ArrayList`.

    ###### Parameters

    - `object`: the object to add.

    ###### Returns

    always true

    Specified by:
      `add` in interface `Collection<E>`
    Specified by:
      `add` in interface `List<E>`
    Overrides:
      `add` in class `AbstractList<E>`
    Returns:

      `true` if this `Collection` is modified, `false` otherwise.

      ###### Throws

      - `UnsupportedOperationException`: if adding to this `Collection` is not supported.

      - `ClassCastException`: @throws ClassCastException if the class of the object is inappropriate for this collection.

      - `IllegalArgumentException`: if the object cannot be added to this `Collection`.

      - `NullPointerException`: if null elements cannot be added to the `Collection`.

  - ### addAll

    public boolean addAll(int location, Collection<? extends E> 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's iterator.

    ###### Parameters

    - `location`: the index at which to insert.

    - `collection`: the collection of objects.

    ###### Returns

    Specified by:
      `addAll` in interface `List<E>`
    Overrides:
      `addAll` in class `AbstractList<E>`
    Returns:

      `true` if this `ArrayList` is modified, `false` otherwise.

      ###### Throws

      - `IndexOutOfBoundsException`: when `location size()`

  - ### addAll

    public boolean addAll(Collection<? extends E> collection)

    Adds the objects in the specified collection to this `ArrayList`.

    ###### Parameters

    - `collection`: the collection of objects.

    ###### Returns

    Specified by:
      `addAll` in interface `Collection<E>`
    Specified by:
      `addAll` in interface `List<E>`
    Overrides:
      `addAll` in class `AbstractCollection<E>`
    Returns:
      `true` if this `ArrayList` is modified, `false` otherwise.

  - ### clear

    public void clear()

    Removes all elements from this `ArrayList`, leaving it empty.

    ###### See also

    - #isEmpty

    - #size

    Specified by:
      `clear` in interface `Collection<E>`
    Specified by:
      `clear` in interface `List<E>`
    Overrides:
      `clear` in class `AbstractList<E>`

  - ### contains

    public boolean contains(java.lang.Object object)

    Searches this `ArrayList` for the specified object.

    ###### Parameters

    - `object`: the object to search for.

    ###### Returns

    Specified by:
      `contains` in interface `Collection<E>`
    Specified by:
      `contains` in interface `List<E>`
    Overrides:
      `contains` in class `AbstractCollection<E>`
    Returns:
      `true` if `object` is an element of this `ArrayList`, `false` otherwise

  - ### ensureCapacity

    public void ensureCapacity(int minimumCapacity)

    Ensures that after this operation the `ArrayList` can hold the specified number of elements without further growing.

    ###### Parameters

    - `minimumCapacity`: the minimum capacity asked for.

  - ### get

    public E get(int location)
    Description copied from class: `AbstractList`

    Returns the element at the specified location in this list.

    ###### Parameters

    - `location`: the index of the element to return.

    ###### Returns

    the element at the specified index.

    ###### Throws

    - `IndexOutOfBoundsException`: if `location = size()`
    Specified by:
      `get` in interface `List<E>`
    Specified by:
      `get` in class `AbstractList<E>`

  - ### indexOf

    public int indexOf(java.lang.Object object)
    Description copied from class: `AbstractList`

    Searches this list for the specified object and returns the index of the first occurrence.

    ###### Parameters

    - `object`: the object to search for.

    ###### Returns

    Specified by:
      `indexOf` in interface `List<E>`
    Overrides:
      `indexOf` in class `AbstractList<E>`
    Returns:
      the index of the first occurrence of the object, or -1 if it was not found.

  - ### isEmpty

    public boolean isEmpty()
    Description copied from class: `AbstractCollection`

    Returns if this `Collection` contains no elements. This implementation tests, whether `size` returns 0.

    ###### Returns

    Specified by:
      `isEmpty` in interface `Collection<E>`
    Specified by:
      `isEmpty` in interface `List<E>`
    Overrides:
      `isEmpty` in class `AbstractCollection<E>`
    Returns:

      `true` if this `Collection` has no elements, `false` otherwise.

      ###### See also

      - #size

  - ### lastIndexOf

    public int lastIndexOf(java.lang.Object object)
    Description copied from class: `AbstractList`

    Searches this list for the specified object and returns the index of the last occurrence.

    ###### Parameters

    - `object`: the object to search for.

    ###### Returns

    Specified by:
      `lastIndexOf` in interface `List<E>`
    Overrides:
      `lastIndexOf` in class `AbstractList<E>`
    Returns:
      the index of the last occurrence of the object, or -1 if the object was not found.

  - ### remove

    public E 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

    - `IndexOutOfBoundsException`: when `location = size()`
    Specified by:
      `remove` in interface `List<E>`
    Overrides:
      `remove` in class `AbstractList<E>`

  - ### remove

    public boolean remove(java.lang.Object object)
    Description copied from class: `AbstractCollection`

    Removes one instance of the specified object from this `Collection` if one is contained (optional). This implementation iterates over this `Collection` and tests for each element `e` returned by the iterator, whether `e` is equal to the given object. If `object != null` then this test is performed using `object.equals(e)`, otherwise using `object == null`. If an element equal to the given object is found, then the `remove` method is called on the iterator and `true` is returned, `false` otherwise. If the iterator does not support removing elements, an `UnsupportedOperationException` is thrown.

    ###### Parameters

    - `object`: the object to remove.

    ###### Returns

    Specified by:
      `remove` in interface `Collection<E>`
    Specified by:
      `remove` in interface `List<E>`
    Overrides:
      `remove` in class `AbstractCollection<E>`
    Returns:

      `true` if this `Collection` is modified, `false` otherwise.

      ###### Throws

      - `UnsupportedOperationException`: if removing from this `Collection` is not supported.

      - `ClassCastException`: if the object passed is not of the correct type.

      - `NullPointerException`: @throws NullPointerException if `object` is `null` and this `Collection` doesn't support `null` elements.

  - ### removeRange

    protected void removeRange(int start, int end)

    Removes the objects in the specified range from the start to the end, but not including the end index.

    ###### Parameters

    - `start`: the index at which to start removing.

    - `end`: the index one after the end of the range to remove.

    ###### Throws

    - `IndexOutOfBoundsException`: when `start end` or `end > size()`
    Overrides:
      `removeRange` in class `AbstractList<E>`

  - ### set

    public E set(int location, E object)

    Replaces the element at the specified location in this `ArrayList` 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

    - `IndexOutOfBoundsException`: when `location = size()`
    Specified by:
      `set` in interface `List<E>`
    Overrides:
      `set` in class `AbstractList<E>`

  - ### size

    public int size()

    Returns the number of elements in this `ArrayList`.

    ###### Returns

    the number of elements in this `ArrayList`.

    Specified by:
      `size` in interface `Collection<E>`
    Specified by:
      `size` in interface `List<E>`
    Specified by:
      `size` in class `AbstractCollection<E>`
    Returns:
      how many objects this `Collection` contains, or `Integer.MAX_VALUE` if there are more than `Integer.MAX_VALUE` elements in this `Collection`.

  - ### toArray

    public java.lang.Object[] toArray()

    Returns a new array containing all elements contained in this `ArrayList`.

    ###### Returns

    an array of the elements from this `ArrayList`

    Specified by:
      `toArray` in interface `Collection<E>`
    Specified by:
      `toArray` in interface `List<E>`
    Overrides:
      `toArray` in class `AbstractList<E>`

  - ### toArray

    public <T> T[] toArray(T[] contents)

    Returns an array containing all elements contained in this `ArrayList`. 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 `ArrayList`, the array element following the collection elements is set to null.

    ###### Parameters

    - `contents`: the array.

    ###### Returns

    an array of the elements from this `ArrayList`.

    ###### Throws

    - `ArrayStoreException`: @throws ArrayStoreException when the type of an element in this `ArrayList` cannot be stored in the type of the specified array.
    Specified by:
      `toArray` in interface `Collection<E>`
    Specified by:
      `toArray` in interface `List<E>`
    Overrides:
      `toArray` in class `AbstractList<E>`

  - ### trimToSize

    public void trimToSize()

    Sets the capacity of this `ArrayList` to be the same as the current size.

    ###### See also

    - #size