| 1 |
|
/* |
| 2 |
|
* Written by Doug Lea and Josh Bloch with assistance from members of |
| 3 |
|
* JCP JSR-166 Expert Group and released to the public domain, as explained |
| 4 |
< |
* at http://creativecommons.org/licenses/publicdomain |
| 4 |
> |
* at http://creativecommons.org/publicdomain/zero/1.0/ |
| 5 |
|
*/ |
| 6 |
|
|
| 7 |
|
package jsr166x; // XXX This belongs in java.util!!! XXX |
| 8 |
|
import java.util.*; // XXX This import goes away XXX |
| 9 |
|
|
| 10 |
|
/** |
| 11 |
< |
* A linear collection that supports element insertion and removal |
| 12 |
< |
* at both ends. The name <i>deque</i> is short for "double ended |
| 13 |
< |
* queue" and is usually pronounced "deck". Most <tt>Deque</tt> |
| 11 |
> |
* A linear collection that supports element insertion and removal at |
| 12 |
> |
* both ends. The name <i>deque</i> is short for "double ended queue" |
| 13 |
> |
* and is usually pronounced "deck". Most <tt>Deque</tt> |
| 14 |
|
* implementations place no fixed limits on the number of elements |
| 15 |
|
* they may contain, but this interface supports capacity-restricted |
| 16 |
|
* deques as well as those with no fixed size limit. |
| 17 |
|
* |
| 18 |
< |
* <p>This interface defines methods to access the elements at both ends of |
| 19 |
< |
* the deque. Methods are provided to insert, remove, and examine the |
| 20 |
< |
* element. Each of these methods exists in two forms: one throws an |
| 21 |
< |
* exception if the operation fails, the other returns a special value (either |
| 22 |
< |
* <tt>null</tt> or <tt>false</tt>, depending on the operation). The latter |
| 23 |
< |
* form of the insert operation is designed specifically for use with |
| 24 |
< |
* capacity-restricted <tt>Deque</tt> implementations; in most implementations, |
| 25 |
< |
* insert operations cannot fail. |
| 26 |
< |
* |
| 27 |
< |
* <p>The twelve methods described above are are summarized in the |
| 28 |
< |
* follwoing table:<p> |
| 29 |
< |
* |
| 18 |
> |
* <p>This interface defines methods to access the elements at both |
| 19 |
> |
* ends of the deque. Methods are provided to insert, remove, and |
| 20 |
> |
* examine the element. Each of these methods exists in two forms: |
| 21 |
> |
* one throws an exception if the operation fails, the other returns a |
| 22 |
> |
* special value (either <tt>null</tt> or <tt>false</tt>, depending on |
| 23 |
> |
* the operation). The latter form of the insert operation is |
| 24 |
> |
* designed specifically for use with capacity-restricted |
| 25 |
> |
* <tt>Deque</tt> implementations; in most implementations, insert |
| 26 |
> |
* operations cannot fail. |
| 27 |
> |
* |
| 28 |
> |
* <p>The twelve methods described above are summarized in the |
| 29 |
> |
* following table:<p> |
| 30 |
> |
* |
| 31 |
|
* <table BORDER CELLPADDING=3 CELLSPACING=1> |
| 32 |
|
* <tr> |
| 33 |
|
* <td></td> |
| 57 |
|
* </tr> |
| 58 |
|
* <tr> |
| 59 |
|
* <td><b>Examine</b></td> |
| 60 |
< |
* <td>{@link #firstElement firstElement()}</td> |
| 60 |
> |
* <td>{@link #getFirst getFirst()}</td> |
| 61 |
|
* <td>{@link #peekFirst peekFirst()}</td> |
| 62 |
< |
* <td>{@link #lastElement lastElement()}</td> |
| 62 |
> |
* <td>{@link #getLast getLast()}</td> |
| 63 |
|
* <td>{@link #peekLast peekLast()}</td> |
| 64 |
|
* </tr> |
| 65 |
|
* </table> |
| 98 |
|
* </tr> |
| 99 |
|
* <tr> |
| 100 |
|
* <td>{@link java.util.Queue#element element()}</td> |
| 101 |
< |
* <td>{@link #firstElement firstElement()}</td> |
| 101 |
> |
* <td>{@link #getFirst getFirst()}</td> |
| 102 |
|
* </tr> |
| 103 |
|
* </table> |
| 104 |
|
* |
| 127 |
|
* <td>{@link #peekFirst peekFirst()}</td> |
| 128 |
|
* </tr> |
| 129 |
|
* </table> |
| 130 |
< |
* <p>Note that the {@link #peek peek} method works equally well when a deque |
| 131 |
< |
* is used as a queue or a stack; in either case, elements are drawn from the |
| 132 |
< |
* beginning of the deque. |
| 133 |
< |
* |
| 134 |
< |
* <p>This inteface provides two methods to to remove interior elements, |
| 135 |
< |
* {@link #removeFirstOccurrence removeFirstOccurrence} and {@link |
| 136 |
< |
* #removeLastOccurrence removeLastOccurrence}. Unlike the {@link List} |
| 137 |
< |
* interface, this interface does not provide support for indexed access to |
| 138 |
< |
* elements. |
| 139 |
< |
* |
| 140 |
< |
* <p>While <tt>Deque</tt> implementations are not strictly required to |
| 141 |
< |
* prohibit the insertion of null elements, they are strongly encouraged to do |
| 142 |
< |
* so. Users of any <tt>Deque</tt> implementations that do allow null |
| 143 |
< |
* elements are strongly encouraged <i>not</i> to take advantage of the |
| 144 |
< |
* ability to insert nulls. This is so because <tt>null</tt> is used as a |
| 145 |
< |
* special return value by various methods to indicated that the deque is |
| 146 |
< |
* empty. |
| 147 |
< |
* |
| 130 |
> |
* |
| 131 |
> |
* <p>Note that the {@link #peek peek} method works equally well when |
| 132 |
> |
* a deque is used as a queue or a stack; in either case, elements are |
| 133 |
> |
* drawn from the beginning of the deque. |
| 134 |
> |
* |
| 135 |
> |
* <p>This interface provides two methods to remove interior |
| 136 |
> |
* elements, {@link #removeFirstOccurrence removeFirstOccurrence} and |
| 137 |
> |
* {@link #removeLastOccurrence removeLastOccurrence}. Unlike the |
| 138 |
> |
* {@link List} interface, this interface does not provide support for |
| 139 |
> |
* indexed access to elements. |
| 140 |
> |
* |
| 141 |
> |
* <p>While <tt>Deque</tt> implementations are not strictly required |
| 142 |
> |
* to prohibit the insertion of null elements, they are strongly |
| 143 |
> |
* encouraged to do so. Users of any <tt>Deque</tt> implementations |
| 144 |
> |
* that do allow null elements are strongly encouraged <i>not</i> to |
| 145 |
> |
* take advantage of the ability to insert nulls. This is so because |
| 146 |
> |
* <tt>null</tt> is used as a special return value by various methods |
| 147 |
> |
* to indicated that the deque is empty. |
| 148 |
> |
* |
| 149 |
|
* <p><tt>Deque</tt> implementations generally do not define |
| 150 |
|
* element-based versions of the <tt>equals</tt> and <tt>hashCode</tt> |
| 151 |
|
* methods, but instead inherit the identity-based versions from class |
| 277 |
|
* @return the first element of this deque |
| 278 |
|
* @throws NoSuchElementException if this deque is empty |
| 279 |
|
*/ |
| 280 |
< |
E firstElement(); |
| 280 |
> |
E getFirst(); |
| 281 |
|
|
| 282 |
|
/** |
| 283 |
|
* Retrieves, but does not remove, the last element of this |
| 287 |
|
* @return the last element of this deque |
| 288 |
|
* @throws NoSuchElementException if this deque is empty |
| 289 |
|
*/ |
| 290 |
< |
E lastElement(); |
| 290 |
> |
E getLast(); |
| 291 |
|
|
| 292 |
|
/** |
| 293 |
|
* Removes the first occurrence of the specified element in this |
| 339 |
|
/** |
| 340 |
|
* Inserts the specified element into the queue represented by this |
| 341 |
|
* deque unless it would violate capacity restrictions. In other words, |
| 342 |
< |
* inserts the specified element as the last element of this deque. |
| 342 |
> |
* inserts the specified element as the last element of this deque. |
| 343 |
|
* |
| 344 |
|
* <p>This method is equivalent to {@link #addLast}. |
| 345 |
|
* |
| 393 |
|
* this deque. This method differs from the <tt>peek</tt> method only in |
| 394 |
|
* that it throws an exception if this deque is empty. |
| 395 |
|
* |
| 396 |
< |
* <p>This method is equivalent to {@link #firstElement()} |
| 396 |
> |
* <p>This method is equivalent to {@link #getFirst()} |
| 397 |
|
* |
| 398 |
|
* @return the head of the queue represented by this deque |
| 399 |
|
* @throws NoSuchElementException if this deque is empty |
| 419 |
|
|
| 420 |
|
/** |
| 421 |
|
* Pops an element from the stack represented by this deque. In other |
| 422 |
< |
* words, removes and returns the the first element of this deque. |
| 422 |
> |
* words, removes and returns the first element of this deque. |
| 423 |
|
* |
| 424 |
|
* <p>This method is equivalent to {@link #removeFirst()}. |
| 425 |
|
* |
| 435 |
|
/** |
| 436 |
|
* Returns an iterator over the elements in this deque. The elements |
| 437 |
|
* will be ordered from first (head) to last (tail). |
| 438 |
< |
* |
| 438 |
> |
* |
| 439 |
|
* @return an <tt>Iterator</tt> over the elements in this deque |
| 440 |
|
*/ |
| 441 |
|
Iterator<E> iterator(); |
