[cvs] / jsr166 / src / main / java / util / Deque.java Repository:
ViewVC logotype

Annotation of /jsr166/src/main/java/util/Deque.java

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.24 - (view) (download)

1 : dl 1.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 : jsr166 1.20 * at http://creativecommons.org/publicdomain/zero/1.0/
5 : dl 1.1 */
6 :    
7 :     package java.util;
8 :    
9 :     /**
10 :     * A linear collection that supports element insertion and removal at
11 :     * both ends. The name <i>deque</i> is short for "double ended queue"
12 : jsr166 1.22 * and is usually pronounced "deck". Most {@code Deque}
13 : dl 1.1 * implementations place no fixed limits on the number of elements
14 :     * they may contain, but this interface supports capacity-restricted
15 :     * deques as well as those with no fixed size limit.
16 :     *
17 :     * <p>This interface defines methods to access the elements at both
18 :     * ends of the deque. Methods are provided to insert, remove, and
19 :     * examine the element. Each of these methods exists in two forms:
20 :     * one throws an exception if the operation fails, the other returns a
21 : jsr166 1.22 * special value (either {@code null} or {@code false}, depending on
22 : dl 1.1 * the operation). The latter form of the insert operation is
23 :     * designed specifically for use with capacity-restricted
24 : jsr166 1.22 * {@code Deque} implementations; in most implementations, insert
25 : dl 1.1 * operations cannot fail.
26 :     *
27 : dl 1.3 * <p>The twelve methods described above are summarized in the
28 : jsr166 1.5 * following table:
29 : dl 1.3 *
30 : jsr166 1.7 * <p>
31 :     * <table BORDER CELLPADDING=3 CELLSPACING=1>
32 : jsr166 1.24 * <caption>Summary of Deque methods</caption>
33 : dl 1.1 * <tr>
34 :     * <td></td>
35 :     * <td ALIGN=CENTER COLSPAN = 2> <b>First Element (Head)</b></td>
36 :     * <td ALIGN=CENTER COLSPAN = 2> <b>Last Element (Tail)</b></td>
37 :     * </tr>
38 :     * <tr>
39 :     * <td></td>
40 :     * <td ALIGN=CENTER><em>Throws exception</em></td>
41 : jsr166 1.8 * <td ALIGN=CENTER><em>Special value</em></td>
42 : dl 1.1 * <td ALIGN=CENTER><em>Throws exception</em></td>
43 : jsr166 1.8 * <td ALIGN=CENTER><em>Special value</em></td>
44 : dl 1.1 * </tr>
45 :     * <tr>
46 :     * <td><b>Insert</b></td>
47 :     * <td>{@link #addFirst addFirst(e)}</td>
48 :     * <td>{@link #offerFirst offerFirst(e)}</td>
49 :     * <td>{@link #addLast addLast(e)}</td>
50 :     * <td>{@link #offerLast offerLast(e)}</td>
51 :     * </tr>
52 :     * <tr>
53 :     * <td><b>Remove</b></td>
54 :     * <td>{@link #removeFirst removeFirst()}</td>
55 :     * <td>{@link #pollFirst pollFirst()}</td>
56 :     * <td>{@link #removeLast removeLast()}</td>
57 :     * <td>{@link #pollLast pollLast()}</td>
58 :     * </tr>
59 :     * <tr>
60 :     * <td><b>Examine</b></td>
61 :     * <td>{@link #getFirst getFirst()}</td>
62 :     * <td>{@link #peekFirst peekFirst()}</td>
63 :     * <td>{@link #getLast getLast()}</td>
64 :     * <td>{@link #peekLast peekLast()}</td>
65 :     * </tr>
66 :     * </table>
67 :     *
68 :     * <p>This interface extends the {@link Queue} interface. When a deque is
69 :     * used as a queue, FIFO (First-In-First-Out) behavior results. Elements are
70 : dl 1.4 * added at the end of the deque and removed from the beginning. The methods
71 : jsr166 1.22 * inherited from the {@code Queue} interface are precisely equivalent to
72 :     * {@code Deque} methods as indicated in the following table:
73 : dl 1.1 *
74 : jsr166 1.7 * <p>
75 :     * <table BORDER CELLPADDING=3 CELLSPACING=1>
76 : jsr166 1.24 * <caption>Comparison of Queue and Deque methods</caption>
77 : dl 1.1 * <tr>
78 : jsr166 1.22 * <td ALIGN=CENTER> <b>{@code Queue} Method</b></td>
79 :     * <td ALIGN=CENTER> <b>Equivalent {@code Deque} Method</b></td>
80 : dl 1.1 * </tr>
81 :     * <tr>
82 : jsr166 1.8 * <td>{@link java.util.Queue#add add(e)}</td>
83 :     * <td>{@link #addLast addLast(e)}</td>
84 :     * </tr>
85 :     * <tr>
86 : dl 1.1 * <td>{@link java.util.Queue#offer offer(e)}</td>
87 :     * <td>{@link #offerLast offerLast(e)}</td>
88 : jsr166 1.5 * </tr>
89 :     * <tr>
90 : jsr166 1.8 * <td>{@link java.util.Queue#remove remove()}</td>
91 :     * <td>{@link #removeFirst removeFirst()}</td>
92 : jsr166 1.5 * </tr>
93 :     * <tr>
94 : dl 1.1 * <td>{@link java.util.Queue#poll poll()}</td>
95 :     * <td>{@link #pollFirst pollFirst()}</td>
96 : jsr166 1.5 * </tr>
97 :     * <tr>
98 : jsr166 1.8 * <td>{@link java.util.Queue#element element()}</td>
99 :     * <td>{@link #getFirst getFirst()}</td>
100 : jsr166 1.5 * </tr>
101 :     * <tr>
102 : dl 1.1 * <td>{@link java.util.Queue#peek peek()}</td>
103 :     * <td>{@link #peek peekFirst()}</td>
104 : jsr166 1.5 * </tr>
105 : dl 1.1 * </table>
106 :     *
107 :     * <p>Deques can also be used as LIFO (Last-In-First-Out) stacks. This
108 :     * interface should be used in preference to the legacy {@link Stack} class.
109 : dl 1.3 * When a deque is used as a stack, elements are pushed and popped from the
110 : dl 1.1 * beginning of the deque. Stack methods are precisely equivalent to
111 : jsr166 1.22 * {@code Deque} methods as indicated in the table below:
112 : dl 1.1 *
113 : jsr166 1.7 * <p>
114 :     * <table BORDER CELLPADDING=3 CELLSPACING=1>
115 : jsr166 1.24 * <caption>Comparison of Stack and Deque methods</caption>
116 : dl 1.1 * <tr>
117 :     * <td ALIGN=CENTER> <b>Stack Method</b></td>
118 : jsr166 1.22 * <td ALIGN=CENTER> <b>Equivalent {@code Deque} Method</b></td>
119 : dl 1.1 * </tr>
120 :     * <tr>
121 :     * <td>{@link #push push(e)}</td>
122 :     * <td>{@link #addFirst addFirst(e)}</td>
123 : jsr166 1.5 * </tr>
124 :     * <tr>
125 : dl 1.1 * <td>{@link #pop pop()}</td>
126 :     * <td>{@link #removeFirst removeFirst()}</td>
127 : jsr166 1.5 * </tr>
128 :     * <tr>
129 : dl 1.1 * <td>{@link #peek peek()}</td>
130 :     * <td>{@link #peekFirst peekFirst()}</td>
131 : jsr166 1.5 * </tr>
132 : dl 1.1 * </table>
133 :     *
134 :     * <p>Note that the {@link #peek peek} method works equally well when
135 :     * a deque is used as a queue or a stack; in either case, elements are
136 :     * drawn from the beginning of the deque.
137 :     *
138 : dl 1.2 * <p>This interface provides two methods to remove interior
139 : dl 1.1 * elements, {@link #removeFirstOccurrence removeFirstOccurrence} and
140 : jsr166 1.8 * {@link #removeLastOccurrence removeLastOccurrence}.
141 :     *
142 :     * <p>Unlike the {@link List} interface, this interface does not
143 :     * provide support for indexed access to elements.
144 : dl 1.1 *
145 : jsr166 1.22 * <p>While {@code Deque} implementations are not strictly required
146 : dl 1.1 * to prohibit the insertion of null elements, they are strongly
147 : jsr166 1.22 * encouraged to do so. Users of any {@code Deque} implementations
148 : dl 1.1 * that do allow null elements are strongly encouraged <i>not</i> to
149 :     * take advantage of the ability to insert nulls. This is so because
150 : jsr166 1.22 * {@code null} is used as a special return value by various methods
151 : dl 1.1 * to indicated that the deque is empty.
152 : dl 1.3 *
153 : jsr166 1.22 * <p>{@code Deque} implementations generally do not define
154 :     * element-based versions of the {@code equals} and {@code hashCode}
155 : dl 1.1 * methods, but instead inherit the identity-based versions from class
156 : jsr166 1.22 * {@code Object}.
157 : dl 1.1 *
158 :     * <p>This interface is a member of the <a
159 : jsr166 1.19 * href="{@docRoot}/../technotes/guides/collections/index.html"> Java Collections
160 : dl 1.1 * Framework</a>.
161 :     *
162 :     * @author Doug Lea
163 :     * @author Josh Bloch
164 :     * @since 1.6
165 :     * @param <E> the type of elements held in this collection
166 :     */
167 :     public interface Deque<E> extends Queue<E> {
168 :     /**
169 : jsr166 1.8 * Inserts the specified element at the front of this deque if it is
170 :     * possible to do so immediately without violating capacity restrictions.
171 :     * When using a capacity-restricted deque, it is generally preferable to
172 :     * use method {@link #offerFirst}.
173 :     *
174 :     * @param e the element to add
175 :     * @throws IllegalStateException if the element cannot be added at this
176 :     * time due to capacity restrictions
177 : jsr166 1.9 * @throws ClassCastException if the class of the specified element
178 :     * prevents it from being added to this deque
179 : jsr166 1.8 * @throws NullPointerException if the specified element is null and this
180 :     * deque does not permit null elements
181 :     * @throws IllegalArgumentException if some property of the specified
182 :     * element prevents it from being added to this deque
183 :     */
184 :     void addFirst(E e);
185 :    
186 :     /**
187 : jsr166 1.13 * Inserts the specified element at the end of this deque if it is
188 : jsr166 1.8 * possible to do so immediately without violating capacity restrictions.
189 :     * When using a capacity-restricted deque, it is generally preferable to
190 :     * use method {@link #offerLast}.
191 :     *
192 : jsr166 1.14 * <p>This method is equivalent to {@link #add}.
193 :     *
194 : jsr166 1.8 * @param e the element to add
195 :     * @throws IllegalStateException if the element cannot be added at this
196 :     * time due to capacity restrictions
197 : jsr166 1.9 * @throws ClassCastException if the class of the specified element
198 :     * prevents it from being added to this deque
199 : jsr166 1.8 * @throws NullPointerException if the specified element is null and this
200 :     * deque does not permit null elements
201 :     * @throws IllegalArgumentException if some property of the specified
202 :     * element prevents it from being added to this deque
203 :     */
204 :     void addLast(E e);
205 :    
206 :     /**
207 : dl 1.3 * Inserts the specified element at the front of this deque unless it would
208 : dl 1.1 * violate capacity restrictions. When using a capacity-restricted deque,
209 : jsr166 1.8 * this method is generally preferable to the {@link #addFirst} method,
210 :     * which can fail to insert an element only by throwing an exception.
211 : dl 1.1 *
212 : jsr166 1.8 * @param e the element to add
213 : jsr166 1.22 * @return {@code true} if the element was added to this deque, else
214 :     * {@code false}
215 : jsr166 1.9 * @throws ClassCastException if the class of the specified element
216 :     * prevents it from being added to this deque
217 : dl 1.3 * @throws NullPointerException if the specified element is null and this
218 : jsr166 1.8 * deque does not permit null elements
219 :     * @throws IllegalArgumentException if some property of the specified
220 :     * element prevents it from being added to this deque
221 : dl 1.1 */
222 :     boolean offerFirst(E e);
223 :    
224 :     /**
225 : dl 1.4 * Inserts the specified element at the end of this deque unless it would
226 : dl 1.1 * violate capacity restrictions. When using a capacity-restricted deque,
227 : jsr166 1.8 * this method is generally preferable to the {@link #addLast} method,
228 :     * which can fail to insert an element only by throwing an exception.
229 : dl 1.1 *
230 : jsr166 1.8 * @param e the element to add
231 : jsr166 1.22 * @return {@code true} if the element was added to this deque, else
232 :     * {@code false}
233 : jsr166 1.9 * @throws ClassCastException if the class of the specified element
234 :     * prevents it from being added to this deque
235 : dl 1.3 * @throws NullPointerException if the specified element is null and this
236 : jsr166 1.8 * deque does not permit null elements
237 :     * @throws IllegalArgumentException if some property of the specified
238 :     * element prevents it from being added to this deque
239 : dl 1.1 */
240 :     boolean offerLast(E e);
241 :    
242 :     /**
243 : jsr166 1.8 * Retrieves and removes the first element of this deque. This method
244 : jsr166 1.15 * differs from {@link #pollFirst pollFirst} only in that it throws an
245 :     * exception if this deque is empty.
246 : dl 1.1 *
247 : jsr166 1.8 * @return the head of this deque
248 :     * @throws NoSuchElementException if this deque is empty
249 : dl 1.1 */
250 : jsr166 1.8 E removeFirst();
251 : dl 1.1
252 :     /**
253 : jsr166 1.8 * Retrieves and removes the last element of this deque. This method
254 : jsr166 1.15 * differs from {@link #pollLast pollLast} only in that it throws an
255 :     * exception if this deque is empty.
256 : dl 1.1 *
257 : jsr166 1.8 * @return the tail of this deque
258 :     * @throws NoSuchElementException if this deque is empty
259 : dl 1.1 */
260 : jsr166 1.8 E removeLast();
261 : dl 1.1
262 :     /**
263 : jsr166 1.8 * Retrieves and removes the first element of this deque,
264 : jsr166 1.22 * or returns {@code null} if this deque is empty.
265 : dl 1.1 *
266 : jsr166 1.22 * @return the head of this deque, or {@code null} if this deque is empty
267 : dl 1.1 */
268 :     E pollFirst();
269 :    
270 :     /**
271 : jsr166 1.8 * Retrieves and removes the last element of this deque,
272 : jsr166 1.22 * or returns {@code null} if this deque is empty.
273 : dl 1.1 *
274 : jsr166 1.22 * @return the tail of this deque, or {@code null} if this deque is empty
275 : dl 1.1 */
276 :     E pollLast();
277 :    
278 :     /**
279 : jsr166 1.8 * Retrieves, but does not remove, the first element of this deque.
280 : jsr166 1.16 *
281 : jsr166 1.15 * This method differs from {@link #peekFirst peekFirst} only in that it
282 :     * throws an exception if this deque is empty.
283 : dl 1.1 *
284 : jsr166 1.8 * @return the head of this deque
285 : dl 1.1 * @throws NoSuchElementException if this deque is empty
286 :     */
287 : jsr166 1.8 E getFirst();
288 : dl 1.1
289 :     /**
290 : jsr166 1.8 * Retrieves, but does not remove, the last element of this deque.
291 : jsr166 1.15 * This method differs from {@link #peekLast peekLast} only in that it
292 :     * throws an exception if this deque is empty.
293 : dl 1.1 *
294 : jsr166 1.8 * @return the tail of this deque
295 : dl 1.1 * @throws NoSuchElementException if this deque is empty
296 :     */
297 : jsr166 1.8 E getLast();
298 : dl 1.1
299 :     /**
300 :     * Retrieves, but does not remove, the first element of this deque,
301 : jsr166 1.22 * or returns {@code null} if this deque is empty.
302 : dl 1.1 *
303 : jsr166 1.22 * @return the head of this deque, or {@code null} if this deque is empty
304 : dl 1.1 */
305 :     E peekFirst();
306 :    
307 :     /**
308 :     * Retrieves, but does not remove, the last element of this deque,
309 : jsr166 1.22 * or returns {@code null} if this deque is empty.
310 : dl 1.1 *
311 : jsr166 1.22 * @return the tail of this deque, or {@code null} if this deque is empty
312 : dl 1.1 */
313 :     E peekLast();
314 :    
315 :     /**
316 : jsr166 1.8 * Removes the first occurrence of the specified element from this deque.
317 :     * If the deque does not contain the element, it is unchanged.
318 : jsr166 1.22 * More formally, removes the first element {@code e} such that
319 : jsr166 1.9 * <tt>(o==null&nbsp;?&nbsp;e==null&nbsp;:&nbsp;o.equals(e))</tt>
320 :     * (if such an element exists).
321 : jsr166 1.22 * Returns {@code true} if this deque contained the specified element
322 : jsr166 1.12 * (or equivalently, if this deque changed as a result of the call).
323 : dl 1.1 *
324 : dl 1.3 * @param o element to be removed from this deque, if present
325 : jsr166 1.22 * @return {@code true} if an element was removed as a result of this call
326 : jsr166 1.9 * @throws ClassCastException if the class of the specified element
327 :     * is incompatible with this deque (optional)
328 : dl 1.4 * @throws NullPointerException if the specified element is null and this
329 : jsr166 1.8 * deque does not permit null elements (optional)
330 : dl 1.1 */
331 : dl 1.3 boolean removeFirstOccurrence(Object o);
332 : dl 1.1
333 :     /**
334 : jsr166 1.8 * Removes the last occurrence of the specified element from this deque.
335 :     * If the deque does not contain the element, it is unchanged.
336 : jsr166 1.22 * More formally, removes the last element {@code e} such that
337 : jsr166 1.9 * <tt>(o==null&nbsp;?&nbsp;e==null&nbsp;:&nbsp;o.equals(e))</tt>
338 :     * (if such an element exists).
339 : jsr166 1.22 * Returns {@code true} if this deque contained the specified element
340 : jsr166 1.12 * (or equivalently, if this deque changed as a result of the call).
341 : dl 1.1 *
342 : dl 1.3 * @param o element to be removed from this deque, if present
343 : jsr166 1.22 * @return {@code true} if an element was removed as a result of this call
344 : jsr166 1.9 * @throws ClassCastException if the class of the specified element
345 :     * is incompatible with this deque (optional)
346 : dl 1.4 * @throws NullPointerException if the specified element is null and this
347 : jsr166 1.8 * deque does not permit null elements (optional)
348 : dl 1.1 */
349 : dl 1.3 boolean removeLastOccurrence(Object o);
350 : dl 1.1
351 : jsr166 1.8 // *** Queue methods ***
352 : dl 1.1
353 : jsr166 1.8 /**
354 :     * Inserts the specified element into the queue represented by this deque
355 :     * (in other words, at the tail of this deque) if it is possible to do so
356 :     * immediately without violating capacity restrictions, returning
357 : jsr166 1.22 * {@code true} upon success and throwing an
358 :     * {@code IllegalStateException} if no space is currently available.
359 : jsr166 1.8 * When using a capacity-restricted deque, it is generally preferable to
360 :     * use {@link #offer(Object) offer}.
361 :     *
362 : jsr166 1.14 * <p>This method is equivalent to {@link #addLast}.
363 : jsr166 1.8 *
364 :     * @param e the element to add
365 : jsr166 1.22 * @return {@code true} (as specified by {@link Collection#add})
366 : jsr166 1.8 * @throws IllegalStateException if the element cannot be added at this
367 :     * time due to capacity restrictions
368 : jsr166 1.9 * @throws ClassCastException if the class of the specified element
369 :     * prevents it from being added to this deque
370 : jsr166 1.8 * @throws NullPointerException if the specified element is null and this
371 :     * deque does not permit null elements
372 :     * @throws IllegalArgumentException if some property of the specified
373 :     * element prevents it from being added to this deque
374 :     */
375 :     boolean add(E e);
376 : dl 1.1
377 :     /**
378 :     * Inserts the specified element into the queue represented by this deque
379 : jsr166 1.8 * (in other words, at the tail of this deque) if it is possible to do so
380 :     * immediately without violating capacity restrictions, returning
381 : jsr166 1.22 * {@code true} upon success and {@code false} if no space is currently
382 : jsr166 1.8 * available. When using a capacity-restricted deque, this method is
383 :     * generally preferable to the {@link #add} method, which can fail to
384 :     * insert an element only by throwing an exception.
385 : dl 1.1 *
386 :     * <p>This method is equivalent to {@link #offerLast}.
387 :     *
388 : jsr166 1.8 * @param e the element to add
389 : jsr166 1.22 * @return {@code true} if the element was added to this deque, else
390 :     * {@code false}
391 : jsr166 1.9 * @throws ClassCastException if the class of the specified element
392 :     * prevents it from being added to this deque
393 : dl 1.3 * @throws NullPointerException if the specified element is null and this
394 : jsr166 1.8 * deque does not permit null elements
395 :     * @throws IllegalArgumentException if some property of the specified
396 :     * element prevents it from being added to this deque
397 : dl 1.1 */
398 :     boolean offer(E e);
399 :    
400 :     /**
401 : jsr166 1.8 * Retrieves and removes the head of the queue represented by this deque
402 :     * (in other words, the first element of this deque).
403 : jsr166 1.15 * This method differs from {@link #poll poll} only in that it throws an
404 : jsr166 1.8 * exception if this deque is empty.
405 : dl 1.1 *
406 : jsr166 1.8 * <p>This method is equivalent to {@link #removeFirst()}.
407 : dl 1.1 *
408 : jsr166 1.8 * @return the head of the queue represented by this deque
409 :     * @throws NoSuchElementException if this deque is empty
410 : dl 1.1 */
411 : jsr166 1.8 E remove();
412 : dl 1.1
413 :     /**
414 : jsr166 1.8 * Retrieves and removes the head of the queue represented by this deque
415 :     * (in other words, the first element of this deque), or returns
416 : jsr166 1.22 * {@code null} if this deque is empty.
417 : dl 1.1 *
418 :     * <p>This method is equivalent to {@link #pollFirst()}.
419 :     *
420 : jsr166 1.22 * @return the first element of this deque, or {@code null} if
421 : jsr166 1.8 * this deque is empty
422 : dl 1.1 */
423 :     E poll();
424 :    
425 :     /**
426 : jsr166 1.8 * Retrieves, but does not remove, the head of the queue represented by
427 :     * this deque (in other words, the first element of this deque).
428 : jsr166 1.15 * This method differs from {@link #peek peek} only in that it throws an
429 : jsr166 1.8 * exception if this deque is empty.
430 : dl 1.1 *
431 : jsr166 1.8 * <p>This method is equivalent to {@link #getFirst()}.
432 : dl 1.1 *
433 :     * @return the head of the queue represented by this deque
434 :     * @throws NoSuchElementException if this deque is empty
435 :     */
436 : jsr166 1.8 E element();
437 : dl 1.1
438 :     /**
439 :     * Retrieves, but does not remove, the head of the queue represented by
440 : jsr166 1.8 * this deque (in other words, the first element of this deque), or
441 : jsr166 1.22 * returns {@code null} if this deque is empty.
442 : dl 1.1 *
443 : dl 1.3 * <p>This method is equivalent to {@link #peekFirst()}.
444 : dl 1.1 *
445 :     * @return the head of the queue represented by this deque, or
446 : jsr166 1.22 * {@code null} if this deque is empty
447 : dl 1.1 */
448 :     E peek();
449 :    
450 :    
451 :     // *** Stack methods ***
452 :    
453 :     /**
454 : jsr166 1.8 * Pushes an element onto the stack represented by this deque (in other
455 :     * words, at the head of this deque) if it is possible to do so
456 :     * immediately without violating capacity restrictions, returning
457 : jsr166 1.22 * {@code true} upon success and throwing an
458 :     * {@code IllegalStateException} if no space is currently available.
459 : dl 1.1 *
460 :     * <p>This method is equivalent to {@link #addFirst}.
461 :     *
462 : dl 1.3 * @param e the element to push
463 : jsr166 1.8 * @throws IllegalStateException if the element cannot be added at this
464 :     * time due to capacity restrictions
465 : jsr166 1.9 * @throws ClassCastException if the class of the specified element
466 :     * prevents it from being added to this deque
467 : dl 1.3 * @throws NullPointerException if the specified element is null and this
468 : jsr166 1.8 * deque does not permit null elements
469 :     * @throws IllegalArgumentException if some property of the specified
470 :     * element prevents it from being added to this deque
471 : dl 1.1 */
472 :     void push(E e);
473 :    
474 :     /**
475 :     * Pops an element from the stack represented by this deque. In other
476 : dl 1.2 * words, removes and returns the first element of this deque.
477 : dl 1.1 *
478 :     * <p>This method is equivalent to {@link #removeFirst()}.
479 :     *
480 :     * @return the element at the front of this deque (which is the top
481 : jsr166 1.8 * of the stack represented by this deque)
482 : dl 1.1 * @throws NoSuchElementException if this deque is empty
483 :     */
484 :     E pop();
485 :    
486 :    
487 : jsr166 1.8 // *** Collection methods ***
488 :    
489 :     /**
490 :     * Removes the first occurrence of the specified element from this deque.
491 :     * If the deque does not contain the element, it is unchanged.
492 : jsr166 1.22 * More formally, removes the first element {@code e} such that
493 : jsr166 1.9 * <tt>(o==null&nbsp;?&nbsp;e==null&nbsp;:&nbsp;o.equals(e))</tt>
494 :     * (if such an element exists).
495 : jsr166 1.22 * Returns {@code true} if this deque contained the specified element
496 : jsr166 1.12 * (or equivalently, if this deque changed as a result of the call).
497 : jsr166 1.8 *
498 : jsr166 1.23 * <p>This method is equivalent to {@link #removeFirstOccurrence(Object)}.
499 : jsr166 1.8 *
500 :     * @param o element to be removed from this deque, if present
501 : jsr166 1.22 * @return {@code true} if an element was removed as a result of this call
502 : jsr166 1.9 * @throws ClassCastException if the class of the specified element
503 :     * is incompatible with this deque (optional)
504 : jsr166 1.8 * @throws NullPointerException if the specified element is null and this
505 :     * deque does not permit null elements (optional)
506 :     */
507 :     boolean remove(Object o);
508 :    
509 :     /**
510 : jsr166 1.22 * Returns {@code true} if this deque contains the specified element.
511 :     * More formally, returns {@code true} if and only if this deque contains
512 :     * at least one element {@code e} such that
513 : jsr166 1.9 * <tt>(o==null&nbsp;?&nbsp;e==null&nbsp;:&nbsp;o.equals(e))</tt>.
514 : jsr166 1.8 *
515 :     * @param o element whose presence in this deque is to be tested
516 : jsr166 1.22 * @return {@code true} if this deque contains the specified element
517 : jsr166 1.8 * @throws ClassCastException if the type of the specified element
518 :     * is incompatible with this deque (optional)
519 :     * @throws NullPointerException if the specified element is null and this
520 :     * deque does not permit null elements (optional)
521 :     */
522 :     boolean contains(Object o);
523 :    
524 :     /**
525 :     * Returns the number of elements in this deque.
526 :     *
527 :     * @return the number of elements in this deque
528 :     */
529 :     public int size();
530 : dl 1.1
531 :     /**
532 : jsr166 1.10 * Returns an iterator over the elements in this deque in proper sequence.
533 :     * The elements will be returned in order from first (head) to last (tail).
534 : dl 1.3 *
535 : jsr166 1.10 * @return an iterator over the elements in this deque in proper sequence
536 : dl 1.1 */
537 :     Iterator<E> iterator();
538 : dl 1.17
539 :     /**
540 :     * Returns an iterator over the elements in this deque in reverse
541 :     * sequential order. The elements will be returned in order from
542 :     * last (tail) to first (head).
543 :     *
544 :     * @return an iterator over the elements in this deque in reverse
545 :     * sequence
546 :     */
547 :     Iterator<E> descendingIterator();
548 :    
549 : dl 1.1 }

Doug Lea
ViewVC Help
Powered by ViewVC 1.0.8