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 |
28 |
> |
* <p>The twelve methods described above are are summarized in the |
29 |
|
* follwoing table:<p> |
30 |
< |
* |
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 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> |
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 |
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(); |