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 |
+ |
* <p> |
31 |
|
* <table BORDER CELLPADDING=3 CELLSPACING=1> |
32 |
|
* <tr> |
33 |
|
* <td></td> |
66 |
|
* |
67 |
|
* <p>This interface extends the {@link Queue} interface. When a deque is |
68 |
|
* used as a queue, FIFO (First-In-First-Out) behavior results. Elements are |
69 |
< |
* added to the end of the deque and removed from the beginning. The methods |
69 |
> |
* added at the end of the deque and removed from the beginning. The methods |
70 |
|
* inherited from the <tt>Queue</tt> interface are precisely equivalent to |
71 |
< |
* <tt>Deque</tt> methods as indicated in the following table:<p> |
71 |
> |
* <tt>Deque</tt> methods as indicated in the following table: |
72 |
|
* |
73 |
+ |
* <p> |
74 |
|
* <table BORDER CELLPADDING=3 CELLSPACING=1> |
75 |
|
* <tr> |
76 |
|
* <td ALIGN=CENTER> <b><tt>Queue</tt> Method</b></td> |
77 |
|
* <td ALIGN=CENTER> <b>Equivalent <tt>Deque</tt> Method</b></td> |
78 |
|
* </tr> |
79 |
|
* <tr> |
78 |
– |
* <tr> |
80 |
|
* <td>{@link java.util.Queue#offer offer(e)}</td> |
81 |
|
* <td>{@link #offerLast offerLast(e)}</td> |
82 |
< |
* </tr> |
83 |
< |
* <tr> |
82 |
> |
* </tr> |
83 |
> |
* <tr> |
84 |
|
* <td>{@link java.util.Queue#add add(e)}</td> |
85 |
|
* <td>{@link #addLast addLast(e)}</td> |
86 |
< |
* </tr> |
87 |
< |
* <tr> |
86 |
> |
* </tr> |
87 |
> |
* <tr> |
88 |
|
* <td>{@link java.util.Queue#poll poll()}</td> |
89 |
|
* <td>{@link #pollFirst pollFirst()}</td> |
90 |
< |
* </tr> |
91 |
< |
* <tr> |
90 |
> |
* </tr> |
91 |
> |
* <tr> |
92 |
|
* <td>{@link java.util.Queue#remove remove()}</td> |
93 |
|
* <td>{@link #removeFirst removeFirst()}</td> |
94 |
< |
* </tr> |
95 |
< |
* <tr> |
94 |
> |
* </tr> |
95 |
> |
* <tr> |
96 |
|
* <td>{@link java.util.Queue#peek peek()}</td> |
97 |
|
* <td>{@link #peek peekFirst()}</td> |
98 |
< |
* </tr> |
99 |
< |
* <tr> |
98 |
> |
* </tr> |
99 |
> |
* <tr> |
100 |
|
* <td>{@link java.util.Queue#element element()}</td> |
101 |
|
* <td>{@link #getFirst getFirst()}</td> |
102 |
< |
* </tr> |
102 |
> |
* </tr> |
103 |
|
* </table> |
104 |
|
* |
105 |
|
* <p>Deques can also be used as LIFO (Last-In-First-Out) stacks. This |
106 |
|
* interface should be used in preference to the legacy {@link Stack} class. |
107 |
|
* When a deque is used as a stack, elements are pushed and popped from the |
108 |
|
* beginning of the deque. Stack methods are precisely equivalent to |
109 |
< |
* <tt>Deque</tt> methods as indicated in the table below:<p> |
109 |
> |
* <tt>Deque</tt> methods as indicated in the table below: |
110 |
|
* |
111 |
+ |
* <p> |
112 |
|
* <table BORDER CELLPADDING=3 CELLSPACING=1> |
113 |
|
* <tr> |
114 |
|
* <td ALIGN=CENTER> <b>Stack Method</b></td> |
115 |
|
* <td ALIGN=CENTER> <b>Equivalent <tt>Deque</tt> Method</b></td> |
116 |
|
* </tr> |
117 |
|
* <tr> |
116 |
– |
* <tr> |
118 |
|
* <td>{@link #push push(e)}</td> |
119 |
|
* <td>{@link #addFirst addFirst(e)}</td> |
120 |
< |
* </tr> |
121 |
< |
* <tr> |
120 |
> |
* </tr> |
121 |
> |
* <tr> |
122 |
|
* <td>{@link #pop pop()}</td> |
123 |
|
* <td>{@link #removeFirst removeFirst()}</td> |
124 |
< |
* </tr> |
125 |
< |
* <tr> |
124 |
> |
* </tr> |
125 |
> |
* <tr> |
126 |
|
* <td>{@link #peek peek()}</td> |
127 |
|
* <td>{@link #peekFirst peekFirst()}</td> |
128 |
< |
* </tr> |
128 |
> |
* </tr> |
129 |
|
* </table> |
130 |
|
* |
131 |
|
* <p>Note that the {@link #peek peek} method works equally well when |
177 |
|
boolean offerFirst(E e); |
178 |
|
|
179 |
|
/** |
180 |
< |
* Inserts the specified element to the end of this deque unless it would |
180 |
> |
* Inserts the specified element at the end of this deque unless it would |
181 |
|
* violate capacity restrictions. When using a capacity-restricted deque, |
182 |
|
* this method is generally preferable to method <tt>addLast</tt> which |
183 |
|
* can fail to insert an element only by throwing an exception. |
203 |
|
void addFirst(E e); |
204 |
|
|
205 |
|
/** |
206 |
< |
* Inserts the specified element to the end of this deque unless it would |
206 |
> |
* Inserts the specified element at the end of this deque unless it would |
207 |
|
* violate capacity restrictions. |
208 |
|
* |
209 |
|
* @param e the element to insert |
233 |
|
E pollLast(); |
234 |
|
|
235 |
|
/** |
236 |
< |
* Removes and returns the first element of this deque. This method |
237 |
< |
* differs from the <tt>pollFirst</tt> method only in that it throws an |
236 |
> |
* Retrieves and removes the first element of this deque. This method |
237 |
> |
* differs from the {@link #pollFirst} method only in that it throws an |
238 |
|
* exception if this deque is empty. |
239 |
|
* |
240 |
|
* @return the first element of this deque |
244 |
|
|
245 |
|
/** |
246 |
|
* Retrieves and removes the last element of this deque. This method |
247 |
< |
* differs from the <tt>pollLast</tt> method only in that it throws an |
247 |
> |
* differs from the {@link #pollLast} method only in that it throws an |
248 |
|
* exception if this deque is empty. |
249 |
|
* |
250 |
|
* @return the last element of this deque |
272 |
|
|
273 |
|
/** |
274 |
|
* Retrieves, but does not remove, the first element of this |
275 |
< |
* deque. This method differs from the <tt>peekFirst</tt> method only |
275 |
> |
* deque. This method differs from the {@link #peekFirst} method only |
276 |
|
* in that it throws an exception if this deque is empty. |
277 |
|
* |
278 |
|
* @return the first element of this deque |
282 |
|
|
283 |
|
/** |
284 |
|
* Retrieves, but does not remove, the last element of this |
285 |
< |
* deque. This method differs from the <tt>peekLast</tt> method only |
285 |
> |
* deque. This method differs from the {@link #peekLast} method only |
286 |
|
* in that it throws an exception if this deque is empty. |
287 |
|
* |
288 |
|
* @return the last element of this deque |
299 |
|
* |
300 |
|
* @param o element to be removed from this deque, if present |
301 |
|
* @return <tt>true</tt> if the deque contained the specified element |
302 |
< |
* @throws NullPointerException if the specified element is <tt>null</tt> |
302 |
> |
* @throws NullPointerException if the specified element is null and this |
303 |
> |
* deque does not permit null elements |
304 |
|
*/ |
305 |
|
boolean removeFirstOccurrence(Object o); |
306 |
|
|
313 |
|
* |
314 |
|
* @param o element to be removed from this deque, if present |
315 |
|
* @return <tt>true</tt> if the deque contained the specified element |
316 |
< |
* @throws NullPointerException if the specified element is <tt>null</tt> |
316 |
> |
* @throws NullPointerException if the specified element is null and this |
317 |
> |
* deque does not permit null elements |
318 |
|
*/ |
319 |
|
boolean removeLastOccurrence(Object o); |
320 |
|
|
324 |
|
/** |
325 |
|
* Inserts the specified element into the queue represented by this deque |
326 |
|
* unless it would violate capacity restrictions. In other words, inserts |
327 |
< |
* the specified element to the end of this deque. When using a |
327 |
> |
* the specified element at the end of this deque. When using a |
328 |
|
* capacity-restricted deque, this method is generally preferable to the |
329 |
|
* {@link #add} method, which can fail to insert an element only by |
330 |
|
* throwing an exception. |
370 |
|
|
371 |
|
/** |
372 |
|
* Retrieves and removes the head of the queue represented by this deque. |
373 |
< |
* This method differs from the <tt>poll</tt> method only in that it |
373 |
> |
* This method differs from the {@link #poll} method only in that it |
374 |
|
* throws an exception if this deque is empty. |
375 |
|
* |
376 |
|
* <p>This method is equivalent to {@link #removeFirst()}. |
393 |
|
|
394 |
|
/** |
395 |
|
* Retrieves, but does not remove, the head of the queue represented by |
396 |
< |
* this deque. This method differs from the <tt>peek</tt> method only in |
396 |
> |
* this deque. This method differs from the {@link #peek} method only in |
397 |
|
* that it throws an exception if this deque is empty. |
398 |
|
* |
399 |
|
* <p>This method is equivalent to {@link #getFirst()}. |