# Class ArrayDeque<E>

java.lang.Object
java.util.AbstractCollection<E>
java.util.ArrayDeque<E>

All Implemented Interfaces:
  `Iterable<E>, Collection<E>, Deque<E>, Queue<E>`

public class ArrayDeque<E> extends AbstractCollection<E> implements Deque<E>

An implementation of Deque, backed by an array.

ArrayDeques have no size limit, can not contain null element, and they are not thread-safe.

All optional operations are supported, and the elements can be any objects.

Type parameter `E`: the type of elements in this collection

##### Since

1.6

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `ArrayDeque()`
  Constructs a new empty instance of ArrayDeque big enough for 16 elements.
  `ArrayDeque(int minSize)`
  Constructs a new empty instance of ArrayDeque big enough for specified number of elements.
  `ArrayDeque(Collection<? extends E> c)`
  Constructs a new instance of ArrayDeque containing the elements of the specified collection, with the order returned by the collection's iterator.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `boolean`
  `add(E e)`
  Inserts the element to the tail of the deque.
  `void`
  `addFirst(E e)`
  Inserts an element at the head of this deque if it dose not violate size limit immediately.
  `void`
  `addLast(E e)`
  Inserts an element at the tail of this deque if it dose not violate size limit immediately.
  `void`
  `clear()`
  Empty the deque.
  `boolean`
  `contains(Object obj)`
  Returns true if the specified element is in the deque.
  `Iterator<E>`
  `descendingIterator()`
  Returns the iterator in reverse order, from tail to head.
  `E`
  `element()`
  Gets but does not remove the head element of this deque.
  `E`
  `getFirst()`
  Gets but not removes the head element of this deque.
  `E`
  `getLast()`
  Gets but not removes the tail element of this deque.
  `boolean`
  `isEmpty()`
  Returns true if the deque has no elements.
  `Iterator<E>`
  `iterator()`
  Returns the iterator of the deque.
  `boolean`
  `offer(E e)`
  Inserts the element at the tail of the deque.
  `boolean`
  `offerFirst(E e)`
  Inserts an element at the head of this deque unless it would violate size limit.
  `boolean`
  `offerLast(E e)`
  Inserts an element at the tail of this deque unless it would violate size limit.
  `E`
  `peek()`
  Gets but not removes the head element of this deque.
  `E`
  `peekFirst()`
  Gets but not removes the head element of this deque.
  `E`
  `peekLast()`
  Gets but not removes the tail element of this deque.
  `E`
  `poll()`
  Gets and removes the head element of this deque.
  `E`
  `pollFirst()`
  Gets and removes the head element of this deque.
  `E`
  `pollLast()`
  Gets and removes the tail element of this deque.
  `E`
  `pop()`
  Pops the head element of the deque, just same as removeFirst().
  `void`
  `push(E e)`
  Pushes the element to the deque(at the head of the deque), just same as addFirst(E).
  `E`
  `remove()`
  Gets and removes the head element of this deque.
  `boolean`
  `remove(Object obj)`
  Removes the first equivalent element of the specified object.
  `E`
  `removeFirst()`
  Gets and removes the head element of this deque.
  `boolean`
  `removeFirstOccurrence(Object obj)`
  Removes the first equivalent element of the specified object.
  `E`
  `removeLast()`
  Gets and removes the tail element of this deque.
  `boolean`
  `removeLastOccurrence(Object obj)`
  Removes the last equivalent element of the specified object.
  `int`
  `size()`
  Returns the size of the deque.

  ### Methods inherited from class AbstractCollection

  `addAll, containsAll, removeAll, retainAll, toArray, toArray, toString`

  ### Methods inherited from class Object

  `clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait`

  ### Methods inherited from interface Collection

  `addAll, containsAll, equals, hashCode, removeAll, retainAll, toArray, toArray`

- ## Constructor Details

  - ### ArrayDeque

    public ArrayDeque()
    Constructs a new empty instance of ArrayDeque big enough for 16 elements.

  - ### ArrayDeque

    public ArrayDeque(int minSize)

    Constructs a new empty instance of ArrayDeque big enough for specified number of elements.

    ###### Parameters

    - `minSize`: the smallest size of the ArrayDeque

  - ### ArrayDeque

    public ArrayDeque(Collection<? extends E> c)

    Constructs a new instance of ArrayDeque containing the elements of the specified collection, with the order returned by the collection's iterator.

    ###### Parameters

    - `c`: the source of the elements

    ###### Throws

    - `NullPointerException`: if the collection is null

- ## Method Details

  - ### addFirst

    public void addFirst(E e)

    Inserts an element at the head of this deque if it dose not violate size limit immediately. It is better to use offerFirst(E) if a deque is size-limited.

    ###### Parameters

    - `e`: the element

    ###### Throws

    - `IllegalStateException`: if it can not add now due to size limit

    - `ClassCastException`: if the class of element can not be added into this deque

    - `NullPointerException`: @throws NullPointerException if the element is null and the deque can not contain null element

    - `IllegalArgumentException`: if the element can not be added due to some property.

    ###### Parameters

    - `e`: the element

    ###### Throws

    - `NullPointerException`: if the element is null

    ###### See also

    - java.util.Deque#addFirst(java.lang.Object)
    Specified by:
      `addFirst` in interface `Deque<E>`

  - ### addLast

    public void addLast(E e)

    Inserts an element at the tail of this deque if it dose not violate size limit immediately. It is better to use offerLast(E) if a deque is size-limited.

    ###### Parameters

    - `e`: the element

    ###### Throws

    - `IllegalStateException`: if it can not add now due to size limit

    - `ClassCastException`: if the class of element can not be added into this deque

    - `NullPointerException`: @throws NullPointerException if the element is null and the deque can not contain null element

    - `IllegalArgumentException`: if the element can not be added due to some property.

    ###### Parameters

    - `e`: the element

    ###### Throws

    - `NullPointerException`: if the element is null

    ###### See also

    - java.util.Deque#addLast(java.lang.Object)
    Specified by:
      `addLast` in interface `Deque<E>`

  - ### offerFirst

    public boolean offerFirst(E e)

    Inserts an element at the head of this deque unless it would violate size limit. It is better than the addFirst(E) method in a size-limited deque, because the latter one may fail to add the element only by throwing an exception.

    ###### Parameters

    - `e`: the element

    ###### Returns

    true if the operation succeeds or false if it fails.

    ###### Throws

    - `ClassCastException`: if the class of element can not be added into this deque

    - `NullPointerException`: @throws NullPointerException if the element is null and the deque can not contain null element

    - `IllegalArgumentException`: if the element can not be added due to some property.

    ###### Parameters

    - `e`: the element

    ###### Returns

    true

    ###### Throws

    - `NullPointerException`: if the element is null

    ###### See also

    - java.util.Deque#offerFirst(java.lang.Object)
    Specified by:
      `offerFirst` in interface `Deque<E>`

  - ### offerLast

    public boolean offerLast(E e)

    Inserts an element at the tail of this deque unless it would violate size limit. It is better than the addLast(E) method in a size-limited deque, because the latter one may fail to add the element only by throwing an exception.

    ###### Parameters

    - `e`: the element

    ###### Returns

    true if the operation succeeds or false if it fails

    ###### Throws

    - `ClassCastException`: if the class of element can not be added into this deque

    - `NullPointerException`: @throws NullPointerException if the element is null and the deque can not contain null element

    - `IllegalArgumentException`: if the element can not be added due to some property

    ###### Parameters

    - `e`: the element

    ###### Returns

    true if the operation succeeds or false if it fails

    ###### Throws

    - `NullPointerException`: if the element is null

    ###### See also

    - java.util.Deque#offerLast(java.lang.Object)
    Specified by:
      `offerLast` in interface `Deque<E>`

  - ### offer

    public boolean offer(E e)

    Inserts the element at the tail of the deque.

    ###### Parameters

    - `e`: the element

    ###### Returns

    true if the operation succeeds or false if it fails.

    ###### Throws

    - `NullPointerException`: if the element is null

    ###### See also

    - java.util.Queue#offer(java.lang.Object)
    Specified by:
      `offer` in interface `Queue<E>`
    Returns:
      `true` if the operation succeeds and `false` if it fails.

  - ### add

    public boolean add(E e)

    Inserts the element to the tail of the deque.

    ###### Parameters

    - `e`: the element

    ###### Returns

    true

    ###### See also

    - java.util.AbstractCollection#add(java.lang.Object)
    Specified by:
      `add` in interface `Collection<E>`
    Overrides:
      `add` in class `AbstractCollection<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`.

  - ### push

    public void push(E e)

    Pushes the element to the deque(at the head of the deque), just same as addFirst(E).

    ###### Parameters

    - `e`: the element

    ###### Throws

    - `IllegalStateException`: if it can not add now due to size limit

    - `ClassCastException`: if the class of element can not be added into this deque

    - `NullPointerException`: @throws NullPointerException if the element is null and the deque can not contain null element

    - `IllegalArgumentException`: if the element can not be added due to some property.

    ###### Parameters

    - `e`: the element to push

    ###### Throws

    - `NullPointerException`: if the element is null

    ###### See also

    - java.util.Deque#push(java.lang.Object)
    Specified by:
      `push` in interface `Deque<E>`

  - ### removeFirst

    public E removeFirst()

    Gets and removes the head element of this deque. This method throws an exception if the deque is empty.

    ###### Returns

    the head element

    ###### Throws

    - `NoSuchElementException`: if the deque is empty

    ###### Returns

    the head element

    ###### Throws

    - `NoSuchElementException`: if the deque is empty

    ###### See also

    - java.util.Deque#removeFirst()
    Specified by:
      `removeFirst` in interface `Deque<E>`

  - ### remove

    public E remove()

    Gets and removes the head element of this deque. This method throws an exception if the deque is empty.

    ###### Returns

    the head element

    ###### Throws

    - `NoSuchElementException`: if the deque is empty

    ###### See also

    - java.util.Queue#remove()
    Specified by:
      `remove` in interface `Queue<E>`

  - ### pop

    public E pop()

    Pops the head element of the deque, just same as removeFirst().

    ###### Returns

    the head element

    ###### Throws

    - `NoSuchElementException`: if the deque is empty

    ###### Returns

    the head element

    ###### Throws

    - `NoSuchElementException`: if the deque is empty

    ###### See also

    - java.util.Deque#pop()
    Specified by:
      `pop` in interface `Deque<E>`

  - ### removeLast

    public E removeLast()

    Gets and removes the tail element of this deque. This method throws an exception if the deque is empty.

    ###### Returns

    the tail element

    ###### Throws

    - `NoSuchElementException`: if the deque is empty

    ###### Returns

    the tail element

    ###### Throws

    - `NoSuchElementException`: if the deque is empty

    ###### See also

    - java.util.Deque#removeLast()
    Specified by:
      `removeLast` in interface `Deque<E>`

  - ### pollFirst

    public E pollFirst()

    Gets and removes the head element of this deque. This method returns null if the deque is empty.

    ###### Returns

    the head element or null if the deque is empty

    ###### Returns

    the head element or null if the deque is empty

    ###### See also

    - java.util.Deque#pollFirst()
    Specified by:
      `pollFirst` in interface `Deque<E>`

  - ### poll

    public E poll()

    Gets and removes the head element of this deque. This method returns null if the deque is empty.

    ###### Returns

    the head element or null if the deque is empty

    ###### See also

    - java.util.Queue#poll()
    Specified by:
      `poll` in interface `Queue<E>`
    Returns:
      the element at the head of the queue or `null` if there is no element in the queue.

  - ### pollLast

    public E pollLast()

    Gets and removes the tail element of this deque. This method returns null if the deque is empty.

    ###### Returns

    the tail element or null if the deque is empty

    ###### Returns

    the tail element or null if the deque is empty

    ###### See also

    - java.util.Deque#pollLast()
    Specified by:
      `pollLast` in interface `Deque<E>`

  - ### getFirst

    public E getFirst()

    Gets but not removes the head element of this deque. This method throws an exception if the deque is empty.

    ###### Returns

    the head element

    ###### Throws

    - `NoSuchElementException`: if the deque is empty

    ###### Returns

    the head element

    ###### Throws

    - `NoSuchElementException`: if the deque is empty

    ###### See also

    - java.util.Deque#getFirst()
    Specified by:
      `getFirst` in interface `Deque<E>`

  - ### element

    public E element()

    Gets but does not remove the head element of this deque. It throws an exception if the deque is empty.

    ###### Returns

    the head element

    ###### Throws

    - `NoSuchElementException`: if the deque is empty

    ###### See also

    - java.util.Queue#element()
    Specified by:
      `element` in interface `Queue<E>`

  - ### getLast

    public E getLast()

    Gets but not removes the tail element of this deque. This method throws an exception if the deque is empty.

    ###### Returns

    the tail element

    ###### Throws

    - `NoSuchElementException`: if the deque is empty

    ###### Returns

    the tail element

    ###### Throws

    - `NoSuchElementException`: if the deque is empty

    ###### See also

    - java.util.Deque#getLast()
    Specified by:
      `getLast` in interface `Deque<E>`

  - ### peekFirst

    public E peekFirst()

    Gets but not removes the head element of this deque. This method returns null if the deque is empty.

    ###### Returns

    the head element or null if the deque is empty

    ###### Returns

    the head element or null if the deque is empty

    ###### See also

    - java.util.Deque#peekFirst()
    Specified by:
      `peekFirst` in interface `Deque<E>`

  - ### peek

    public E peek()

    Gets but not removes the head element of this deque. This method returns null if the deque is empty.

    ###### Returns

    the head element or null if the deque is empty

    ###### See also

    - java.util.Queue#peek()
    Specified by:
      `peek` in interface `Queue<E>`
    Returns:
      the element at the head of the queue or `null` if there is no element in the queue.

  - ### peekLast

    public E peekLast()

    Gets but not removes the tail element of this deque. This method returns null if the deque is empty.

    ###### Returns

    the tail element or null if the deque is empty

    ###### Returns

    the tail element or null if the deque is empty

    ###### See also

    - java.util.Deque#peekLast()
    Specified by:
      `peekLast` in interface `Deque<E>`

  - ### removeFirstOccurrence

    public boolean removeFirstOccurrence(Object obj)

    Removes the first equivalent element of the specified object. If the deque does not contain the element, it is unchanged and returns false.

    ###### Parameters

    - `o`: the element to be removed

    ###### Returns

    ###### Parameters

    - `obj`: the element to be removed

    ###### Returns

    Specified by:
      `removeFirstOccurrence` in interface `Deque<E>`
    Returns:

      true if the operation succeeds or false if the deque does not contain the element

      ###### See also

      - java.util.Deque#removeFirstOccurrence(java.lang.Object)

  - ### remove

    public boolean remove(Object obj)

    Removes the first equivalent element of the specified object. If the deque does not contain the element, it is unchanged and returns false.

    ###### Parameters

    - `obj`: the element to be removed

    ###### Returns

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

      true if the operation succeeds or false if the deque does not contain the element

      ###### See also

      - java.util.AbstractCollection#remove(java.lang.Object)

  - ### removeLastOccurrence

    public boolean removeLastOccurrence(Object obj)

    Removes the last equivalent element of the specified object. If the deque does not contain the element, it is unchanged and returns false.

    ###### Parameters

    - `o`: the element to be removed

    ###### Returns

    ###### Parameters

    - `obj`: the element to be removed

    ###### Returns

    Specified by:
      `removeLastOccurrence` in interface `Deque<E>`
    Returns:

      true if the operation succeeds or false if the deque does not contain the element.

      ###### See also

      - java.util.Deque#removeLastOccurrence(java.lang.Object)

  - ### size

    public int size()

    Returns the size of the deque.

    ###### Returns

    the size of the deque

    ###### See also

    - java.util.AbstractCollection#size()
    Specified by:
      `size` in interface `Collection<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`.

  - ### isEmpty

    public boolean isEmpty()

    Returns true if the deque has no elements.

    ###### Returns

    true if the deque has no elements, false otherwise

    ###### See also

    - java.util.AbstractCollection#isEmpty()
    Specified by:
      `isEmpty` in interface `Collection<E>`
    Overrides:
      `isEmpty` in class `AbstractCollection<E>`
    Returns:

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

      ###### See also

      - #size

  - ### contains

    public boolean contains(Object obj)

    Returns true if the specified element is in the deque.

    ###### Parameters

    - `obj`: the element

    ###### Returns

    true if the element is in the deque, false otherwise

    ###### See also

    - java.util.AbstractCollection#contains(java.lang.Object)
    Specified by:
      `contains` in interface `Collection<E>`
    Overrides:
      `contains` in class `AbstractCollection<E>`
    Returns:

      `true` if object is an element of this `Collection`, `false` otherwise.

      ###### Throws

      - `ClassCastException`: @throws ClassCastException if the object to look for isn't of the correct type.

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

  - ### clear

    public void clear()

    Empty the deque.

    ###### See also

    - java.util.AbstractCollection#clear()
    Specified by:
      `clear` in interface `Collection<E>`
    Overrides:
      `clear` in class `AbstractCollection<E>`

  - ### iterator

    public Iterator<E> iterator()

    Returns the iterator of the deque. The elements will be ordered from head to tail.

    ###### Returns

    the iterator

    ###### See also

    - java.util.AbstractCollection#iterator()
    Specified by:
      `iterator` in interface `Collection<E>`
    Specified by:
      `iterator` in interface `Iterable<E>`
    Specified by:
      `iterator` in class `AbstractCollection<E>`

  - ### descendingIterator

    public Iterator<E> descendingIterator()

    Returns the iterator in reverse order, from tail to head.

    ###### Returns

    the iterator in reverse order

    ###### Returns

    the reverse order Iterator

    ###### See also

    - java.util.Deque#descendingIterator()
    Specified by:
      `descendingIterator` in interface `Deque<E>`