java.util.Deque接口

 支持在两端插入和删除元素的线性集合。大多数Deque实现对它们可能包含的元素数量没有固定的限制，
 但是此接口支持容量受限的双端队列以及没有固定大小限制的双端队列。
 * A linear collection that supports element insertion and removal at
 * both ends.  The name <i>deque</i> is short for "double ended queue"
 * and is usually pronounced "deck".  Most {@code Deque}
 * implementations place no fixed limits on the number of elements
 * they may contain, but this interface supports capacity-restricted
 * deques as well as those with no fixed size limit.
 
 此接口定义访问双端队列两端的元素的方法。 提供了用于插入，删除和检查元素的方法。 
 这些方法中的每一种都以两种形式存在：一种在操作失败时引发异常，另一种返回一个特殊值null或false，具体取决于操作）。 
 插入操作的后一种形式专门设计用于容量受限的Deque实现； 在大多数实现中，插入操作不会失败。
 * <p>This interface defines methods to access the elements at both
 * ends of the deque.  Methods are provided to insert, remove, and
 * examine the element.  Each of these methods exists in two forms:
 * one throws an exception if the operation fails, the other returns a
 * special value (either {@code null} or {@code false}, depending on
 * the operation).  The latter form of the insert operation is
 * designed specifically for use with capacity-restricted
 * {@code Deque} implementations; in most implementations, insert
 * operations cannot fail.
 
 此接口扩展了{@link Queue}接口。 当双端队列用作队列时，将导致FIFO（先进先出）行为。 
 元素在双端队列的末尾添加，并从开头删除。
 * <p>This interface extends the {@link Queue} interface.  When a deque is
 * used as a queue, FIFO (First-In-First-Out) behavior results.  Elements are
 * added at the end of the deque and removed from the beginning. 
 
 双端队列也可以用作LIFO（后进先出）堆栈。 此接口应优先于旧式Stack类使用。 
 当双端队列用作堆栈时，元素从双端队列的开头被压入并弹出。
 * <p>Deques can also be used as LIFO (Last-In-First-Out) stacks.  This
 * interface should be used in preference to the legacy {@link Stack} class.
 * When a deque is used as a stack, elements are pushed and popped from the
 * beginning of the deque.
 
 当将双端队列用作队列或堆栈时，peek方法同样有效。 无论哪种情况，元素都是从双端队列的开始处绘制的。
 * <p>Note that the {@link #peek peek} method works equally well when
 * a deque is used as a queue or a stack; in either case, elements are
 * drawn from the beginning of the deque.
 
 该接口提供了两种删除内部元素的方法：removeFirstOccurrence和removeLastOccurrence。
 * <p>This interface provides two methods to remove interior
 * elements, {@link #removeFirstOccurrence removeFirstOccurrence} and
 * {@link #removeLastOccurrence removeLastOccurrence}.
 
 与List接口不同，此接口不支持对元素的索引访问。
 * <p>Unlike the {@link List} interface, this interface does not
 * provide support for indexed access to elements.
 
 虽然并非严格要求Deque实现禁止插入空元素，但强烈建议这样做。 
 强烈建议任何允许使用null元素的Deque实现的用户不要利用插入null的功能。 
 之所以这样，是因为null被各种方法用作特殊的返回值，以指示双端队列为空。
 * <p>While {@code Deque} implementations are not strictly required
 * to prohibit the insertion of null elements, they are strongly
 * encouraged to do so.  Users of any {@code Deque} implementations
 * that do allow null elements are strongly encouraged <i>not</i> to
 * take advantage of the ability to insert nulls.  This is so because
 * {@code null} is used as a special return value by various methods
 * to indicated that the deque is empty.
 
 Deque实现通常不定义equals和hashCode方法的基于元素的版本，而是从类Object继承。
 * <p>{@code Deque} implementations generally do not define
 * element-based versions of the {@code equals} and {@code hashCode}
 * methods, but instead inherit the identity-based versions from class
 * {@code Object}.

public interface Deque<E> extends Queue<E> {
    /**
     * @param e the element to add
     * @throws IllegalStateException if the element cannot be added at this
     *         time due to capacity restrictions
     * @throws ClassCastException if the class of the specified element
     *         prevents it from being added to this deque
     * @throws NullPointerException if the specified element is null and this
     *         deque does not permit null elements
     * @throws IllegalArgumentException if some property of the specified
     *         element prevents it from being added to this deque
     */
     如果可以在不违反容量限制的情况下立即执行此操作，则将指定的元素插入此双端队列的前面，如果当前没有可用空间，则抛出IllegalStateException。 
     使用容量受限的双端队列时，通常最好使用方法offerFirst()。
    void addFirst(E e);

    /**
     * @param e the element to add
     * @throws IllegalStateException if the element cannot be added at this
     *         time due to capacity restrictions
     * @throws ClassCastException if the class of the specified element
     *         prevents it from being added to this deque
     * @throws NullPointerException if the specified element is null and this
     *         deque does not permit null elements
     * @throws IllegalArgumentException if some property of the specified
     *         element prevents it from being added to this deque
     */
     如果可以立即执行此操作，而不会违反容量限制，则在此双端队列的末尾插入指定的元素；
     如果当前没有可用空间，则抛出 IllegalStateException。 
     使用容量受限的双端队列时，通常最好使用方法offerLast()。此方法等效于add()。
    void addLast(E e);

    /**
     * @param e the element to add
     * @return {@code true} if the element was added to this deque, else
     *         {@code false}
     * @throws ClassCastException if the class of the specified element
     *         prevents it from being added to this deque
     * @throws NullPointerException if the specified element is null and this
     *         deque does not permit null elements
     * @throws IllegalArgumentException if some property of the specified
     *         element prevents it from being added to this deque
     */
     将指定的元素插入此双端队列的前面，除非会违反容量限制。 
     使用容量受限的双端队列时，此方法通常比addFirst()方法更可取，后者只能通过引发异常来插入元素。
    boolean offerFirst(E e);

    /**
     * @param e the element to add
     * @return {@code true} if the element was added to this deque, else
     *         {@code false}
     * @throws ClassCastException if the class of the specified element
     *         prevents it from being added to this deque
     * @throws NullPointerException if the specified element is null and this
     *         deque does not permit null elements
     * @throws IllegalArgumentException if some property of the specified
     *         element prevents it from being added to this deque
     */
     在此双端队列的末尾插入指定的元素，除非会违反容量限制。 
     当使用容量受限的双端队列时，此方法通常比addLast()方法更可取，后者只能通过引发异常才能插入元素。
    boolean offerLast(E e);

    /**
     * @return the head of this deque
     * @throws NoSuchElementException if this deque is empty
     */
     检索并删除此双端队列的第一个元素。 此方法与pollFirst()的不同之处仅在于，如果此双端队列为空，则它将引发异常。
    E removeFirst();

    /**
     * @return the tail of this deque
     * @throws NoSuchElementException if this deque is empty
     */
     检索并删除此双端队列的最后一个元素。 此方法与pollLast()的不同之处仅在于，如果此双端队列为空，它将引发异常。
    E removeLast();

    /**
     * @return the head of this deque, or {@code null} if this deque is empty
     */
     检索并删除此双端队列的第一个元素，如果此双端队列为空，则返回null。
    E pollFirst();

    /**
     * @return the tail of this deque, or {@code null} if this deque is empty
     */
     检索并删除此双端队列的最后一个元素，如果此双端队列为空，则返回null。
    E pollLast();

    /**
     * @return the head of this deque
     * @throws NoSuchElementException if this deque is empty
     */
     检索但不删除此双端队列的第一个元素。
     此方法与peekFirst()的不同之处仅在于，如果此双端队列为空，它将引发异常。
    E getFirst();

    /**
     * @return the tail of this deque
     * @throws NoSuchElementException if this deque is empty
     */
     检索但不删除此双端队列的最后一个元素。
     此方法与peekLast()的不同之处仅在于，如果此双端队列为空，它将引发异常。
    E getLast();

    /**
     * @return the head of this deque, or {@code null} if this deque is empty
     */
     检索但不删除此双端队列的第一个元素，如果此双端队列为空，则返回null。
    E peekFirst();

    /**
     * @return the tail of this deque, or {@code null} if this deque is empty
     */
     检索但不删除此双端队列的最后一个元素，如果此双端队列为空，则返回null。
    E peekLast();

    /**
     * @param o element to be removed from this deque, if present
     * @return {@code true} if an element was removed as a result of this call
     * @throws ClassCastException if the class of the specified element
     *         is incompatible with this deque
     * @throws NullPointerException if the specified element is null and this
     *         deque does not permit null elements
     */
    从此双端队列删除指定元素的第一次出现。
    如果双端队列不包含元素，则它保持不变。更正式地说，删除第一个元素e，使（o == null && e == null && o.equals（e））（如果存在这样的元素）。
    如果此双端队列包含指定的元素（或如果此双端队列由于调用而发生更改），则返回true。
    boolean removeFirstOccurrence(Object o);

    /**
     * @param o element to be removed from this deque, if present
     * @return {@code true} if an element was removed as a result of this call
     * @throws ClassCastException if the class of the specified element
     *         is incompatible with this deque
     * @throws NullPointerException if the specified element is null and this deque does not permit null elements
     */
     从此双端队列删除指定元素的最后一次出现。
    如果双端队列不包含元素，则它保持不变。更正式地说，删除最后一个元素e，使（o == null && e == null && o.equals（e））（如果存在这样的元素）。
    如果此双端队列包含指定的元素（或如果此双端队列由于调用而发生更改），则返回true。
    boolean removeLastOccurrence(Object o);

    // *** Queue methods ***

    /**
     * @param e the element to add
     * @return {@code true} (as specified by {@link Collection#add})
     * @throws IllegalStateException if the element cannot be added at this
     *         time due to capacity restrictions
     * @throws ClassCastException if the class of the specified element
     *         prevents it from being added to this deque
     * @throws NullPointerException if the specified element is null and this
     *         deque does not permit null elements
     * @throws IllegalArgumentException if some property of the specified
     *         element prevents it from being added to this deque
     */
     如果可能的话立即将指定的元素插入此双端队列表示的队列中（换句话说，在此双端队列的末尾），而不会违反容量限制，成功则返回true或者抛出一个IllegalStateException，如果当前没有可用空间。
    使用容量受限的双端队列时，通常最好使用offer()。此方法等效于addLast()。
    boolean add(E e);

    /**
     * @param e the element to add
     * @return {@code true} if the element was added to this deque, else
     *         {@code false}
     * @throws ClassCastException if the class of the specified element
     *         prevents it from being added to this deque
     * @throws NullPointerException if the specified element is null and this
     *         deque does not permit null elements
     * @throws IllegalArgumentException if some property of the specified
     *         element prevents it from being added to this deque
     */
     如果可以在不违反容量限制的情况下立即执行操作，则将指定的元素插入此双端队列表示的队列中（换句话说，在此双端队列的末尾），并在成功后返回true或者如果当前没有可用空间时返回false。 使用容量受限的双端队列时，此方法通常比add()方法更可取，后者只能通过引发异常才能插入元素。
     此方法等效于offerLast()。
    boolean offer(E e);

    /**
     * @return the head of the queue represented by this deque
     * @throws NoSuchElementException if this deque is empty
     */
     检索并删除此双端队列代表的队列的头部（换句话说，此双端队列的第一个元素）。
     此方法与{@link #poll poll}的不同之处仅在于，如果此双端队列为空，它将引发异常。
     此方法等效于removeFirst()。
    E remove();

    /**
     * @return the first element of this deque, or {@code null} if
     *         this deque is empty
     */
     检索并删除此双端队列表示的队列的头部（换句话说，此双端队列的第一个元素），如果此双端队列为空，则返回null。
     此方法等效于pollFirst()。
    E poll();

    /**
     * @return the head of the queue represented by this deque
     * @throws NoSuchElementException if this deque is empty
     */
     检索但不删除此双端队列代表的队列的头（换句话说，此双端队列的第一个元素）。
     此方法与peek()的不同之处仅在于，如果此双端队列为空，它将引发异常。
     此方法等效于getFirst()。
    E element();

    /**
     * @return the head of the queue represented by this deque, or
     *         {@code null} if this deque is empty
     */
     检索但不删除此双端队列表示的队列的头（换句话说，此双端队列的第一个元素），如果此双端队列为空，则返回null。
      此方法等效于peekFirst()。
    E peek();


    // *** Stack methods ***

    /**
     * @param e the element to push
     * @throws IllegalStateException if the element cannot be added at this
     *         time due to capacity restrictions
     * @throws ClassCastException if the class of the specified element
     *         prevents it from being added to this deque
     * @throws NullPointerException if the specified element is null and this
     *         deque does not permit null elements
     * @throws IllegalArgumentException if some property of the specified
     *         element prevents it from being added to this deque
     */
     如果有可能在不违反容量限制的情况下立即将元素压入此双端队列表示的堆栈（换句话说，此双端队列的开头），如果当前没有可用空间，则抛出IllegalStateException。
     此方法等效于addFirst()。
    void push(E e);

    /**
     * @return the element at the front of this deque (which is the top
     *         of the stack represented by this deque)
     * @throws NoSuchElementException if this deque is empty
     */
     从此双端队列表示的堆栈中弹出一个元素。 换句话说，删除并返回此双端队列的第一个元素。
     此方法等效于removeFirst()。
    E pop();


    // *** Collection methods ***

    /**
     * @param o element to be removed from this deque, if present
     * @return {@code true} if an element was removed as a result of this call
     * @throws ClassCastException if the class of the specified element
     *         is incompatible with this deque
     * @throws NullPointerException if the specified element is null and this
     *         deque does not permit null elements
     */
     从此双端队列删除指定元素的第一次出现。如果双端队列不包含元素，则它保持不变。
     更正式地，删除第一个元素e，使得（o == null && e == null && o.equals（e））（如果存在这样的元素）。
     如果此双端队列包含指定的元素（或者等效地，如果此双端队列是由于调用而更改的），则返回true。
     此方法等效于removeFirstOccurrence(Object)。
    boolean remove(Object o);

    /**
     * @param o element whose presence in this deque is to be tested
     * @return {@code true} if this deque contains the specified element
     * @throws ClassCastException if the type of the specified element
     *         is incompatible with this deque
     * @throws NullPointerException if the specified element is null and this
     *         deque does not permit null elements
     */
     如果此双端队列包含指定的元素，则返回true。
     更正式地说，当且仅当此双端队列包含至少一个元素e时，才返回{@code true}，以使（o == null && e == null && o.equals(e)）。
    boolean contains(Object o);

    /**
     * @return the number of elements in this deque
     */
     返回此双端队列的元素数量。
    public int size();

    /**
     * @return an iterator over the elements in this deque in proper sequence
     */
     以适当的顺序返回此双端队列中的元素的迭代器。
     元素将从头（头）到尾（头）的顺序返回。
    Iterator<E> iterator();

    /**
     * @return an iterator over the elements in this deque in reverse
     * sequence
     */
     以相反的顺序返回此双端队列中的元素的迭代器。 元素将按从最后（尾）到第一个（头）的顺序返回。
    Iterator<E> descendingIterator();

}