25 |
|
* operations cannot fail. |
26 |
|
* |
27 |
|
* <p>The twelve methods described above are summarized in the |
28 |
< |
* following table:<p> |
28 |
> |
* following table: |
29 |
|
* |
30 |
< |
* <table BORDER CELLPADDING=3 CELLSPACING=1> |
30 |
> |
* <p><table BORDER CELLPADDING=3 CELLSPACING=1> |
31 |
|
* <tr> |
32 |
|
* <td></td> |
33 |
|
* <td ALIGN=CENTER COLSPAN = 2> <b>First Element (Head)</b></td> |
65 |
|
* |
66 |
|
* <p>This interface extends the {@link Queue} interface. When a deque is |
67 |
|
* used as a queue, FIFO (First-In-First-Out) behavior results. Elements are |
68 |
< |
* added to the end of the deque and removed from the beginning. The methods |
68 |
> |
* added at the end of the deque and removed from the beginning. The methods |
69 |
|
* inherited from the <tt>Queue</tt> interface are precisely equivalent to |
70 |
< |
* <tt>Deque</tt> methods as indicated in the following table:<p> |
70 |
> |
* <tt>Deque</tt> methods as indicated in the following table: |
71 |
|
* |
72 |
< |
* <table BORDER CELLPADDING=3 CELLSPACING=1> |
72 |
> |
* <p><table BORDER CELLPADDING=3 CELLSPACING=1> |
73 |
|
* <tr> |
74 |
|
* <td ALIGN=CENTER> <b><tt>Queue</tt> Method</b></td> |
75 |
|
* <td ALIGN=CENTER> <b>Equivalent <tt>Deque</tt> Method</b></td> |
76 |
|
* </tr> |
77 |
|
* <tr> |
78 |
– |
* <tr> |
78 |
|
* <td>{@link java.util.Queue#offer offer(e)}</td> |
79 |
|
* <td>{@link #offerLast offerLast(e)}</td> |
80 |
< |
* </tr> |
81 |
< |
* <tr> |
80 |
> |
* </tr> |
81 |
> |
* <tr> |
82 |
|
* <td>{@link java.util.Queue#add add(e)}</td> |
83 |
|
* <td>{@link #addLast addLast(e)}</td> |
84 |
< |
* </tr> |
85 |
< |
* <tr> |
84 |
> |
* </tr> |
85 |
> |
* <tr> |
86 |
|
* <td>{@link java.util.Queue#poll poll()}</td> |
87 |
|
* <td>{@link #pollFirst pollFirst()}</td> |
88 |
< |
* </tr> |
89 |
< |
* <tr> |
88 |
> |
* </tr> |
89 |
> |
* <tr> |
90 |
|
* <td>{@link java.util.Queue#remove remove()}</td> |
91 |
|
* <td>{@link #removeFirst removeFirst()}</td> |
92 |
< |
* </tr> |
93 |
< |
* <tr> |
92 |
> |
* </tr> |
93 |
> |
* <tr> |
94 |
|
* <td>{@link java.util.Queue#peek peek()}</td> |
95 |
|
* <td>{@link #peek peekFirst()}</td> |
96 |
< |
* </tr> |
97 |
< |
* <tr> |
96 |
> |
* </tr> |
97 |
> |
* <tr> |
98 |
|
* <td>{@link java.util.Queue#element element()}</td> |
99 |
|
* <td>{@link #getFirst getFirst()}</td> |
100 |
< |
* </tr> |
100 |
> |
* </tr> |
101 |
|
* </table> |
102 |
|
* |
103 |
|
* <p>Deques can also be used as LIFO (Last-In-First-Out) stacks. This |
104 |
|
* interface should be used in preference to the legacy {@link Stack} class. |
105 |
|
* When a deque is used as a stack, elements are pushed and popped from the |
106 |
|
* beginning of the deque. Stack methods are precisely equivalent to |
107 |
< |
* <tt>Deque</tt> methods as indicated in the table below:<p> |
107 |
> |
* <tt>Deque</tt> methods as indicated in the table below: |
108 |
|
* |
109 |
< |
* <table BORDER CELLPADDING=3 CELLSPACING=1> |
109 |
> |
* <p><table BORDER CELLPADDING=3 CELLSPACING=1> |
110 |
|
* <tr> |
111 |
|
* <td ALIGN=CENTER> <b>Stack Method</b></td> |
112 |
|
* <td ALIGN=CENTER> <b>Equivalent <tt>Deque</tt> Method</b></td> |
113 |
|
* </tr> |
114 |
|
* <tr> |
116 |
– |
* <tr> |
115 |
|
* <td>{@link #push push(e)}</td> |
116 |
|
* <td>{@link #addFirst addFirst(e)}</td> |
117 |
< |
* </tr> |
118 |
< |
* <tr> |
117 |
> |
* </tr> |
118 |
> |
* <tr> |
119 |
|
* <td>{@link #pop pop()}</td> |
120 |
|
* <td>{@link #removeFirst removeFirst()}</td> |
121 |
< |
* </tr> |
122 |
< |
* <tr> |
121 |
> |
* </tr> |
122 |
> |
* <tr> |
123 |
|
* <td>{@link #peek peek()}</td> |
124 |
|
* <td>{@link #peekFirst peekFirst()}</td> |
125 |
< |
* </tr> |
125 |
> |
* </tr> |
126 |
|
* </table> |
127 |
|
* |
128 |
|
* <p>Note that the {@link #peek peek} method works equally well when |
174 |
|
boolean offerFirst(E e); |
175 |
|
|
176 |
|
/** |
177 |
< |
* Inserts the specified element to the end of this deque unless it would |
177 |
> |
* Inserts the specified element at the end of this deque unless it would |
178 |
|
* violate capacity restrictions. When using a capacity-restricted deque, |
179 |
|
* this method is generally preferable to method <tt>addLast</tt> which |
180 |
|
* can fail to insert an element only by throwing an exception. |
200 |
|
void addFirst(E e); |
201 |
|
|
202 |
|
/** |
203 |
< |
* Inserts the specified element to the end of this deque unless it would |
203 |
> |
* Inserts the specified element at the end of this deque unless it would |
204 |
|
* violate capacity restrictions. |
205 |
|
* |
206 |
|
* @param e the element to insert |
230 |
|
E pollLast(); |
231 |
|
|
232 |
|
/** |
233 |
< |
* Removes and returns the first element of this deque. This method |
234 |
< |
* differs from the <tt>pollFirst</tt> method only in that it throws an |
233 |
> |
* Retrieves and removes the first element of this deque. This method |
234 |
> |
* differs from the {@link #pollFirst} method only in that it throws an |
235 |
|
* exception if this deque is empty. |
236 |
|
* |
237 |
|
* @return the first element of this deque |
241 |
|
|
242 |
|
/** |
243 |
|
* Retrieves and removes the last element of this deque. This method |
244 |
< |
* differs from the <tt>pollLast</tt> method only in that it throws an |
244 |
> |
* differs from the {@link #pollLast} method only in that it throws an |
245 |
|
* exception if this deque is empty. |
246 |
|
* |
247 |
|
* @return the last element of this deque |
269 |
|
|
270 |
|
/** |
271 |
|
* Retrieves, but does not remove, the first element of this |
272 |
< |
* deque. This method differs from the <tt>peekFirst</tt> method only |
272 |
> |
* deque. This method differs from the {@link #peekFirst} method only |
273 |
|
* in that it throws an exception if this deque is empty. |
274 |
|
* |
275 |
|
* @return the first element of this deque |
279 |
|
|
280 |
|
/** |
281 |
|
* Retrieves, but does not remove, the last element of this |
282 |
< |
* deque. This method differs from the <tt>peekLast</tt> method only |
282 |
> |
* deque. This method differs from the {@link #peekLast} method only |
283 |
|
* in that it throws an exception if this deque is empty. |
284 |
|
* |
285 |
|
* @return the last element of this deque |
296 |
|
* |
297 |
|
* @param o element to be removed from this deque, if present |
298 |
|
* @return <tt>true</tt> if the deque contained the specified element |
299 |
< |
* @throws NullPointerException if the specified element is <tt>null</tt> |
299 |
> |
* @throws NullPointerException if the specified element is null and this |
300 |
> |
* deque does not permit null elements |
301 |
|
*/ |
302 |
|
boolean removeFirstOccurrence(Object o); |
303 |
|
|
310 |
|
* |
311 |
|
* @param o element to be removed from this deque, if present |
312 |
|
* @return <tt>true</tt> if the deque contained the specified element |
313 |
< |
* @throws NullPointerException if the specified element is <tt>null</tt> |
313 |
> |
* @throws NullPointerException if the specified element is null and this |
314 |
> |
* deque does not permit null elements |
315 |
|
*/ |
316 |
|
boolean removeLastOccurrence(Object o); |
317 |
|
|
321 |
|
/** |
322 |
|
* Inserts the specified element into the queue represented by this deque |
323 |
|
* unless it would violate capacity restrictions. In other words, inserts |
324 |
< |
* the specified element to the end of this deque. When using a |
324 |
> |
* the specified element at the end of this deque. When using a |
325 |
|
* capacity-restricted deque, this method is generally preferable to the |
326 |
|
* {@link #add} method, which can fail to insert an element only by |
327 |
|
* throwing an exception. |
367 |
|
|
368 |
|
/** |
369 |
|
* Retrieves and removes the head of the queue represented by this deque. |
370 |
< |
* This method differs from the <tt>poll</tt> method only in that it |
370 |
> |
* This method differs from the {@link #poll} method only in that it |
371 |
|
* throws an exception if this deque is empty. |
372 |
|
* |
373 |
|
* <p>This method is equivalent to {@link #removeFirst()}. |
390 |
|
|
391 |
|
/** |
392 |
|
* Retrieves, but does not remove, the head of the queue represented by |
393 |
< |
* this deque. This method differs from the <tt>peek</tt> method only in |
393 |
> |
* this deque. This method differs from the {@link #peek} method only in |
394 |
|
* that it throws an exception if this deque is empty. |
395 |
|
* |
396 |
|
* <p>This method is equivalent to {@link #getFirst()}. |