# Class ArrayDeque<E>

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

Type Parameters:
  `E` - the type of elements in this collection

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.

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`
  Modifier and Type
  Method
  Description
  `boolean`
  `addAll(Collection<? extends E> collection)`
  Attempts to add all of the objects contained in `collection` to the contents of this `Collection` (optional).
  `boolean`
  `containsAll(Collection<?> collection)`
  Tests whether this `Collection` contains all objects contained in the specified `Collection`.
  `boolean`
  `removeAll(Collection<?> collection)`
  Removes all occurrences in this `Collection` of each object in the specified `Collection` (optional).
  `boolean`
  `retainAll(Collection<?> collection)`
  Removes all objects from this `Collection` that are not also found in the `Collection` passed (optional).
  `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`.
  `String`
  `toString()`
  Returns the string representation of this `Collection`.

  ### Methods inherited from class Object

  `clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait`
  Modifier and Type
  Method
  Description
  `protected Object`
  `clone()`
  `boolean`
  `equals(Object obj)`
  Indicates whether some other object is "equal to" this one.
  `final Class`
  `getClass()`
  Returns the runtime class of an object.
  `int`
  `hashCode()`
  Returns a hash code value for the object.
  `final void`
  `notify()`
  Wakes up a single thread that is waiting on this object's monitor.
  `final void`
  `notifyAll()`
  Wakes up all threads that are waiting on this object's monitor.
  `final void`
  `wait()`
  Causes current thread to wait until another thread invokes the method or the method for this object.
  `final void`
  `wait(long timeout)`
  Causes current thread to wait until either another thread invokes the method or the method for this object, or a specified amount of time has elapsed.
  `final void`
  `wait(long timeout, int nanos)`
  Causes current thread to wait until another thread invokes the method or the method for this object, or some other thread interrupts the current thread, or a certain amount of real time has elapsed.

  ### Methods inherited from interface Collection

  `equals, hashCode`
  Modifier and Type
  Method
  Description
  `boolean`
  `equals(Object object)`
  Compares the argument to the receiver, and returns true if they represent the same object using a class specific comparison.
  `int`
  `hashCode()`
  Returns an integer hash code for the receiver.

- ## 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.
    Specified by:
      `addFirst` in interface `Deque<E>`
    Parameters:
      `e` - the element
    Throws:
      `NullPointerException` - if the element is null
    See Also:
      - `Deque.addFirst(java.lang.Object)`

  - ### 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.
    Specified by:
      `addLast` in interface `Deque<E>`
    Parameters:
      `e` - the element
    Throws:
      `NullPointerException` - if the element is null
    See Also:
      - `Deque.addLast(java.lang.Object)`

  - ### 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.
    Specified by:
      `offerFirst` in interface `Deque<E>`
    Parameters:
      `e` - the element
    Returns:
      true
    Throws:
      `NullPointerException` - if the element is null
    See Also:
      - `Deque.offerFirst(java.lang.Object)`

  - ### 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.
    Specified by:
      `offerLast` in interface `Deque<E>`
    Parameters:
      `e` - the element
    Returns:
      true if the operation succeeds or false if it fails
    Throws:
      `NullPointerException` - if the element is null
    See Also:
      - `Deque.offerLast(java.lang.Object)`

  - ### offer

    public boolean offer(E e)
    Inserts the element at the tail of the deque.
    Specified by:
      `offer` in interface `Queue<E>`
    Parameters:
      `e` - the element
    Returns:
      true if the operation succeeds or false if it fails.
    Throws:
      `NullPointerException` - if the element is null
    See Also:
      - `Queue.offer(java.lang.Object)`

  - ### add

    public boolean add(E e)
    Inserts the element to the tail of the deque.
    Specified by:
      `add` in interface `Collection<E>`
    Overrides:
      `add` in class `AbstractCollection<E>`
    Parameters:
      `e` - the element
    Returns:
      true
    See Also:
      - `AbstractCollection.add(java.lang.Object)`

  - ### push

    public void push(E e)
    Pushes the element to the deque(at the head of the deque), just same as addFirst(E).
    Specified by:
      `push` in interface `Deque<E>`
    Parameters:
      `e` - the element to push
    Throws:
      `NullPointerException` - if the element is null
    See Also:
      - `Deque.push(java.lang.Object)`

  - ### removeFirst

    public E removeFirst()
    Gets and removes the head element of this deque. This method throws an exception if the deque is empty.
    Specified by:
      `removeFirst` in interface `Deque<E>`
    Returns:
      the head element
    Throws:
      `NoSuchElementException` - if the deque is empty
    See Also:
      - `Deque.removeFirst()`

  - ### remove

    public E remove()
    Gets and removes the head element of this deque. This method throws an exception if the deque is empty.
    Specified by:
      `remove` in interface `Queue<E>`
    Returns:
      the head element
    Throws:
      `NoSuchElementException` - if the deque is empty
    See Also:
      - `Queue.remove()`

  - ### pop

    public E pop()
    Pops the head element of the deque, just same as removeFirst().
    Specified by:
      `pop` in interface `Deque<E>`
    Returns:
      the head element
    Throws:
      `NoSuchElementException` - if the deque is empty
    See Also:
      - `Deque.pop()`

  - ### removeLast

    public E removeLast()
    Gets and removes the tail element of this deque. This method throws an exception if the deque is empty.
    Specified by:
      `removeLast` in interface `Deque<E>`
    Returns:
      the tail element
    Throws:
      `NoSuchElementException` - if the deque is empty
    See Also:
      - `Deque.removeLast()`

  - ### pollFirst

    public E pollFirst()
    Gets and removes the head element of this deque. This method returns null if the deque is empty.
    Specified by:
      `pollFirst` in interface `Deque<E>`
    Returns:
      the head element or null if the deque is empty
    See Also:
      - `Deque.pollFirst()`

  - ### poll

    public E poll()
    Gets and removes the head element of this deque. This method returns null if the deque is empty.
    Specified by:
      `poll` in interface `Queue<E>`
    Returns:
      the head element or null if the deque is empty
    See Also:
      - `Queue.poll()`

  - ### pollLast

    public E pollLast()
    Gets and removes the tail element of this deque. This method returns null if the deque is empty.
    Specified by:
      `pollLast` in interface `Deque<E>`
    Returns:
      the tail element or null if the deque is empty
    See Also:
      - `Deque.pollLast()`

  - ### getFirst

    public E getFirst()
    Gets but not removes the head element of this deque. This method throws an exception if the deque is empty.
    Specified by:
      `getFirst` in interface `Deque<E>`
    Returns:
      the head element
    Throws:
      `NoSuchElementException` - if the deque is empty
    See Also:
      - `Deque.getFirst()`

  - ### element

    public E element()
    Gets but does not remove the head element of this deque. It throws an exception if the deque is empty.
    Specified by:
      `element` in interface `Queue<E>`
    Returns:
      the head element
    Throws:
      `NoSuchElementException` - if the deque is empty
    See Also:
      - `Queue.element()`

  - ### getLast

    public E getLast()
    Gets but not removes the tail element of this deque. This method throws an exception if the deque is empty.
    Specified by:
      `getLast` in interface `Deque<E>`
    Returns:
      the tail element
    Throws:
      `NoSuchElementException` - if the deque is empty
    See Also:
      - `Deque.getLast()`

  - ### peekFirst

    public E peekFirst()
    Gets but not removes the head element of this deque. This method returns null if the deque is empty.
    Specified by:
      `peekFirst` in interface `Deque<E>`
    Returns:
      the head element or null if the deque is empty
    See Also:
      - `Deque.peekFirst()`

  - ### peek

    public E peek()
    Gets but not removes the head element of this deque. This method returns null if the deque is empty.
    Specified by:
      `peek` in interface `Queue<E>`
    Returns:
      the head element or null if the deque is empty
    See Also:
      - `Queue.peek()`

  - ### peekLast

    public E peekLast()
    Gets but not removes the tail element of this deque. This method returns null if the deque is empty.
    Specified by:
      `peekLast` in interface `Deque<E>`
    Returns:
      the tail element or null if the deque is empty
    See Also:
      - `Deque.peekLast()`

  - ### 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.
    Specified by:
      `removeFirstOccurrence` in interface `Deque<E>`
    Parameters:
      `obj` - the element to be removed
    Returns:
      true if the operation succeeds or false if the deque does not contain the element
    See Also:
      - `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.
    Specified by:
      `remove` in interface `Collection<E>`
    Overrides:
      `remove` in class `AbstractCollection<E>`
    Parameters:
      `obj` - the element to be removed
    Returns:
      true if the operation succeeds or false if the deque does not contain the element
    See Also:
      - `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.
    Specified by:
      `removeLastOccurrence` in interface `Deque<E>`
    Parameters:
      `obj` - the element to be removed
    Returns:
      true if the operation succeeds or false if the deque does not contain the element.
    See Also:
      - `Deque.removeLastOccurrence(java.lang.Object)`

  - ### size

    public int size()
    Returns the size of the deque.
    Specified by:
      `size` in interface `Collection<E>`
    Specified by:
      `size` in class `AbstractCollection<E>`
    Returns:
      the size of the deque
    See Also:
      - `AbstractCollection.size()`

  - ### isEmpty

    public boolean isEmpty()
    Returns true if the deque has no elements.
    Specified by:
      `isEmpty` in interface `Collection<E>`
    Overrides:
      `isEmpty` in class `AbstractCollection<E>`
    Returns:
      true if the deque has no elements, false otherwise
    See Also:
      - `AbstractCollection.isEmpty()`

  - ### contains

    public boolean contains(Object obj)
    Returns true if the specified element is in the deque.
    Specified by:
      `contains` in interface `Collection<E>`
    Overrides:
      `contains` in class `AbstractCollection<E>`
    Parameters:
      `obj` - the element
    Returns:
      true if the element is in the deque, false otherwise
    See Also:
      - `AbstractCollection.contains(java.lang.Object)`

  - ### clear

    public void clear()
    Empty the deque.
    Specified by:
      `clear` in interface `Collection<E>`
    Overrides:
      `clear` in class `AbstractCollection<E>`
    See Also:
      - `AbstractCollection.clear()`

  - ### iterator

    public Iterator<E> iterator()
    Returns the iterator of the deque. The elements will be ordered from head to tail.
    Specified by:
      `iterator` in interface `Collection<E>`
    Specified by:
      `iterator` in interface `Iterable<E>`
    Specified by:
      `iterator` in class `AbstractCollection<E>`
    Returns:
      the iterator
    See Also:
      - `AbstractCollection.iterator()`

  - ### descendingIterator

    public Iterator<E> descendingIterator()
    Returns the iterator in reverse order, from tail to head.
    Specified by:
      `descendingIterator` in interface `Deque<E>`
    Returns:
      the reverse order Iterator
    See Also:
      - `Deque.descendingIterator()`