| 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. |
| 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 are summarized in the |
| 29 |
|
* follwoing table:<p> |
| 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. |
| 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 inteface provides two methods to 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> |
