deque.java

来自「SRI international 发布的OAA框架软件」· Java 代码 · 共 444 行 · 第 1/2 页

     */
    Object pollFirst();

    /**
     * Retrieves and removes the last element of this deque, or
     * <tt>null</tt> if this deque is empty.
     *
     * @return the last element of this deque, or <tt>null</tt> if
     *     this deque is empty
     */
    Object pollLast();

    /**
     * Removes and returns the first element of this deque.  This method
     * differs from the <tt>pollFirst</tt> method only in that it throws an
     * exception if this deque is empty.
     *
     * @return the first element of this deque
     * @throws NoSuchElementException if this deque is empty
     */
    Object removeFirst();

    /**
     * Retrieves and removes the last element of this deque.  This method
     * differs from the <tt>pollLast</tt> method only in that it throws an
     * exception if this deque is empty.
     *
     * @return the last element of this deque
     * @throws NoSuchElementException if this deque is empty
     */
    Object removeLast();

    /**
     * Retrieves, but does not remove, the first element of this deque,
     * returning <tt>null</tt> if this deque is empty.
     *
     * @return the first element of this deque, or <tt>null</tt> if
     *     this deque is empty
     */
    Object peekFirst();

    /**
     * Retrieves, but does not remove, the last element of this deque,
     * returning <tt>null</tt> if this deque is empty.
     *
     * @return the last element of this deque, or <tt>null</tt> if this deque
     *     is empty
     */
    Object peekLast();

    /**
     * Retrieves, but does not remove, the first element of this
     * deque.  This method differs from the <tt>peek</tt> method only
     * in that it throws an exception if this deque is empty.
     *
     * @return the first element of this deque
     * @throws NoSuchElementException if this deque is empty
     */
    Object getFirst();

    /**
     * Retrieves, but does not remove, the last element of this
     * deque.  This method differs from the <tt>peek</tt> method only
     * in that it throws an exception if this deque is empty.
     *
     * @return the last element of this deque
     * @throws NoSuchElementException if this deque is empty
     */
    Object getLast();

    /**
     * Removes the first occurrence of the specified element in this
     * deque.  If the deque does not contain the element, it is
     * unchanged.  More formally, removes the first element <tt>e</tt>
     * such that <tt>(o==null ? e==null : o.equals(e))</tt> (if
     * such an element exists).
     *
     * @param e element to be removed from this deque, if present
     * @return <tt>true</tt> if the deque contained the specified element
     * @throws NullPointerException if the specified element is <tt>null</tt>
     */
    boolean removeFirstOccurrence(Object e);

    /**
     * Removes the last occurrence of the specified element in this
     * deque.  If the deque does not contain the element, it is
     * unchanged.  More formally, removes the last element <tt>e</tt>
     * such that <tt>(o==null ? e==null : o.equals(e))</tt> (if
     * such an element exists).
     *
     * @param e element to be removed from this deque, if present
     * @return <tt>true</tt> if the deque contained the specified element
     * @throws NullPointerException if the specified element is <tt>null</tt>
     */
    boolean removeLastOccurrence(Object e);


    // *** Queue methods ***

    /**
     * Inserts the specified element into the queue represented by this deque
     * unless it would violate capacity restrictions.  In other words, inserts
     * the specified element to the end of this deque.  When using a
     * capacity-restricted deque, this method is generally preferable to the
     * {@link #add} method, which can fail to insert an element only by
     * throwing an exception.
     *
     * <p>This method is equivalent to {@link #offerLast}.
     *
     * @param e the element to insert
     * @return <tt>true</tt> if it was possible to insert the element,
     *     else <tt>false</tt>
     * @throws NullPointerException if <tt>e</tt> is null and this
     *     deque does not permit null elements
     */
    boolean offer(Object e);

    /**
     * Inserts the specified element into the queue represented by this
     * deque unless it would violate capacity restrictions.  In other words,
     * inserts the specified element as the last element of this deque.
     *
     * <p>This method is equivalent to {@link #addLast}.
     *
     * @param e the element to insert
     * @return <tt>true</tt> (as per the spec for {@link Collection#add})
     * @throws IllegalStateException if it was not possible to insert
     *    the element due to capacity restrictions
     * @throws NullPointerException if <tt>e</tt> is null and this
     *     deque does not permit null elements
     */
    boolean add(Object e);

    /**
     * Retrieves and removes the head of the queue represented by
     * this deque, or <tt>null</tt> if this deque is empty.  In other words,
     * retrieves and removes the first element of this deque, or <tt>null</tt>
     * if this deque is empty.
     *
     * <p>This method is equivalent to {@link #pollFirst()}.
     *
     * @return the first element of this deque, or <tt>null</tt> if
     *     this deque is empty
     */
    Object poll();

    /**
     * Retrieves and removes the head of the queue represented by this deque.
     * This method differs from the <tt>poll</tt> method only in that it
     * throws an exception if this deque is empty.
     *
     * <p>This method is equivalent to {@link #removeFirst()}.
     *
     * @return the head of the queue represented by this deque
     * @throws NoSuchElementException if this deque is empty
     */
    Object remove();

    /**
     * Retrieves, but does not remove, the head of the queue represented by
     * this deque, returning <tt>null</tt> if this deque is empty.
     *
     * <p>This method is equivalent to {@link #peekFirst()}
     *
     * @return the head of the queue represented by this deque, or
     *     <tt>null</tt> if this deque is empty
     */
    Object peek();

    /**
     * Retrieves, but does not remove, the head of the queue represented by
     * this deque.  This method differs from the <tt>peek</tt> method only in
     * that it throws an exception if this deque is empty.
     *
     * <p>This method is equivalent to {@link #getFirst()}
     *
     * @return the head of the queue represented by this deque
     * @throws NoSuchElementException if this deque is empty
     */
    Object element();


    // *** Stack methods ***

    /**
     * Pushes an element onto the stack represented by this deque.  In other
     * words, inserts the element to the front this deque unless it would
     * violate capacity restrictions.
     *
     * <p>This method is equivalent to {@link #addFirst}.
     *
     * @throws IllegalStateException if it was not possible to insert
     *    the element due to capacity restrictions
     * @throws NullPointerException if <tt>e</tt> is null and this
     *     deque does not permit null elements
     */
    void push(Object e);

    /**
     * Pops an element from the stack represented by this deque.  In other
     * words, removes and returns the the first element of this deque.
     *
     * <p>This method is equivalent to {@link #removeFirst()}.
     *
     * @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
     */
    Object pop();


    // *** Collection Method ***

    /**
     * Returns an iterator over the elements in this deque.  The elements
     * will be ordered from first (head) to last (tail).
     *
     * @return an <tt>Iterator</tt> over the elements in this deque
     */
    Iterator iterator();
}