ViewVC Help
View File | Revision Log | Show Annotations | Download File | Root Listing
root/jsr166/jsr166/src/main/java/util/Deque.java
Revision: 1.27
Committed: Fri Aug 2 22:47:35 2013 UTC (10 years, 9 months ago) by jsr166
Branch: MAIN
Changes since 1.26: +17 -13 lines
Log Message:
add links for "(optional)"

File Contents

# User Rev Content
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 dl 1.26 * <td>{@link Deque#addFirst addFirst(e)}</td>
48     * <td>{@link Deque#offerFirst offerFirst(e)}</td>
49     * <td>{@link Deque#addLast addLast(e)}</td>
50     * <td>{@link Deque#offerLast offerLast(e)}</td>
51 dl 1.1 * </tr>
52     * <tr>
53     * <td><b>Remove</b></td>
54 dl 1.26 * <td>{@link Deque#removeFirst removeFirst()}</td>
55     * <td>{@link Deque#pollFirst pollFirst()}</td>
56     * <td>{@link Deque#removeLast removeLast()}</td>
57     * <td>{@link Deque#pollLast pollLast()}</td>
58 dl 1.1 * </tr>
59     * <tr>
60     * <td><b>Examine</b></td>
61 dl 1.26 * <td>{@link Deque#getFirst getFirst()}</td>
62     * <td>{@link Deque#peekFirst peekFirst()}</td>
63     * <td>{@link Deque#getLast getLast()}</td>
64     * <td>{@link Deque#peekLast peekLast()}</td>
65 dl 1.1 * </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 jsr166 1.25 * possible to do so immediately without violating capacity restrictions,
171     * throwing an {@code IllegalStateException} if no space is currently
172     * available. When using a capacity-restricted deque, it is generally
173     * preferable to use method {@link #offerFirst}.
174 jsr166 1.8 *
175     * @param e the element to add
176     * @throws IllegalStateException if the element cannot be added at this
177     * time due to capacity restrictions
178 jsr166 1.9 * @throws ClassCastException if the class of the specified element
179     * prevents it from being added to this deque
180 jsr166 1.8 * @throws NullPointerException if the specified element is null and this
181     * deque does not permit null elements
182     * @throws IllegalArgumentException if some property of the specified
183     * element prevents it from being added to this deque
184     */
185     void addFirst(E e);
186    
187     /**
188 jsr166 1.13 * Inserts the specified element at the end of this deque if it is
189 jsr166 1.25 * possible to do so immediately without violating capacity restrictions,
190     * throwing an {@code IllegalStateException} if no space is currently
191     * available. When using a capacity-restricted deque, it is generally
192     * preferable to use method {@link #offerLast}.
193 jsr166 1.8 *
194 jsr166 1.14 * <p>This method is equivalent to {@link #add}.
195     *
196 jsr166 1.8 * @param e the element to add
197     * @throws IllegalStateException if the element cannot be added at this
198     * time due to capacity restrictions
199 jsr166 1.9 * @throws ClassCastException if the class of the specified element
200     * prevents it from being added to this deque
201 jsr166 1.8 * @throws NullPointerException if the specified element is null and this
202     * deque does not permit null elements
203     * @throws IllegalArgumentException if some property of the specified
204     * element prevents it from being added to this deque
205     */
206     void addLast(E e);
207    
208     /**
209 dl 1.3 * Inserts the specified element at the front of this deque unless it would
210 dl 1.1 * violate capacity restrictions. When using a capacity-restricted deque,
211 jsr166 1.8 * this method is generally preferable to the {@link #addFirst} method,
212     * which can fail to insert an element only by throwing an exception.
213 dl 1.1 *
214 jsr166 1.8 * @param e the element to add
215 jsr166 1.22 * @return {@code true} if the element was added to this deque, else
216     * {@code false}
217 jsr166 1.9 * @throws ClassCastException if the class of the specified element
218     * prevents it from being added to this deque
219 dl 1.3 * @throws NullPointerException if the specified element is null and this
220 jsr166 1.8 * deque does not permit null elements
221     * @throws IllegalArgumentException if some property of the specified
222     * element prevents it from being added to this deque
223 dl 1.1 */
224     boolean offerFirst(E e);
225    
226     /**
227 dl 1.4 * Inserts the specified element at the end of this deque unless it would
228 dl 1.1 * violate capacity restrictions. When using a capacity-restricted deque,
229 jsr166 1.8 * this method is generally preferable to the {@link #addLast} method,
230     * which can fail to insert an element only by throwing an exception.
231 dl 1.1 *
232 jsr166 1.8 * @param e the element to add
233 jsr166 1.22 * @return {@code true} if the element was added to this deque, else
234     * {@code false}
235 jsr166 1.9 * @throws ClassCastException if the class of the specified element
236     * prevents it from being added to this deque
237 dl 1.3 * @throws NullPointerException if the specified element is null and this
238 jsr166 1.8 * deque does not permit null elements
239     * @throws IllegalArgumentException if some property of the specified
240     * element prevents it from being added to this deque
241 dl 1.1 */
242     boolean offerLast(E e);
243    
244     /**
245 jsr166 1.8 * Retrieves and removes the first element of this deque. This method
246 jsr166 1.15 * differs from {@link #pollFirst pollFirst} only in that it throws an
247     * exception if this deque is empty.
248 dl 1.1 *
249 jsr166 1.8 * @return the head of this deque
250     * @throws NoSuchElementException if this deque is empty
251 dl 1.1 */
252 jsr166 1.8 E removeFirst();
253 dl 1.1
254     /**
255 jsr166 1.8 * Retrieves and removes the last element of this deque. This method
256 jsr166 1.15 * differs from {@link #pollLast pollLast} only in that it throws an
257     * exception if this deque is empty.
258 dl 1.1 *
259 jsr166 1.8 * @return the tail of this deque
260     * @throws NoSuchElementException if this deque is empty
261 dl 1.1 */
262 jsr166 1.8 E removeLast();
263 dl 1.1
264     /**
265 jsr166 1.8 * Retrieves and removes the first element of this deque,
266 jsr166 1.22 * or returns {@code null} if this deque is empty.
267 dl 1.1 *
268 jsr166 1.22 * @return the head of this deque, or {@code null} if this deque is empty
269 dl 1.1 */
270     E pollFirst();
271    
272     /**
273 jsr166 1.8 * Retrieves and removes the last element of this deque,
274 jsr166 1.22 * or returns {@code null} if this deque is empty.
275 dl 1.1 *
276 jsr166 1.22 * @return the tail of this deque, or {@code null} if this deque is empty
277 dl 1.1 */
278     E pollLast();
279    
280     /**
281 jsr166 1.8 * Retrieves, but does not remove, the first element of this deque.
282 jsr166 1.16 *
283 jsr166 1.15 * This method differs from {@link #peekFirst peekFirst} only in that it
284     * throws an exception if this deque is empty.
285 dl 1.1 *
286 jsr166 1.8 * @return the head of this deque
287 dl 1.1 * @throws NoSuchElementException if this deque is empty
288     */
289 jsr166 1.8 E getFirst();
290 dl 1.1
291     /**
292 jsr166 1.8 * Retrieves, but does not remove, the last element of this deque.
293 jsr166 1.15 * This method differs from {@link #peekLast peekLast} only in that it
294     * throws an exception if this deque is empty.
295 dl 1.1 *
296 jsr166 1.8 * @return the tail of this deque
297 dl 1.1 * @throws NoSuchElementException if this deque is empty
298     */
299 jsr166 1.8 E getLast();
300 dl 1.1
301     /**
302     * Retrieves, but does not remove, the first element of this deque,
303 jsr166 1.22 * or returns {@code null} if this deque is empty.
304 dl 1.1 *
305 jsr166 1.22 * @return the head of this deque, or {@code null} if this deque is empty
306 dl 1.1 */
307     E peekFirst();
308    
309     /**
310     * Retrieves, but does not remove, the last element of this deque,
311 jsr166 1.22 * or returns {@code null} if this deque is empty.
312 dl 1.1 *
313 jsr166 1.22 * @return the tail of this deque, or {@code null} if this deque is empty
314 dl 1.1 */
315     E peekLast();
316    
317     /**
318 jsr166 1.8 * Removes the first occurrence of the specified element from this deque.
319     * If the deque does not contain the element, it is unchanged.
320 jsr166 1.22 * More formally, removes the first element {@code e} such that
321 jsr166 1.9 * <tt>(o==null&nbsp;?&nbsp;e==null&nbsp;:&nbsp;o.equals(e))</tt>
322     * (if such an element exists).
323 jsr166 1.22 * Returns {@code true} if this deque contained the specified element
324 jsr166 1.12 * (or equivalently, if this deque changed as a result of the call).
325 dl 1.1 *
326 dl 1.3 * @param o element to be removed from this deque, if present
327 jsr166 1.22 * @return {@code true} if an element was removed as a result of this call
328 jsr166 1.9 * @throws ClassCastException if the class of the specified element
329 jsr166 1.27 * is incompatible with this deque
330     * (<a href="../Collection.html#optional-restrictions">optional</a>)
331     * @throws NullPointerException if the specified element is null
332     * (<a href="../Collection.html#optional-restrictions">optional</a>)
333 dl 1.1 */
334 dl 1.3 boolean removeFirstOccurrence(Object o);
335 dl 1.1
336     /**
337 jsr166 1.8 * Removes the last occurrence of the specified element from this deque.
338     * If the deque does not contain the element, it is unchanged.
339 jsr166 1.22 * More formally, removes the last element {@code e} such that
340 jsr166 1.9 * <tt>(o==null&nbsp;?&nbsp;e==null&nbsp;:&nbsp;o.equals(e))</tt>
341     * (if such an element exists).
342 jsr166 1.22 * Returns {@code true} if this deque contained the specified element
343 jsr166 1.12 * (or equivalently, if this deque changed as a result of the call).
344 dl 1.1 *
345 dl 1.3 * @param o element to be removed from this deque, if present
346 jsr166 1.22 * @return {@code true} if an element was removed as a result of this call
347 jsr166 1.9 * @throws ClassCastException if the class of the specified element
348 jsr166 1.27 * is incompatible with this deque
349     * (<a href="../Collection.html#optional-restrictions">optional</a>)
350     * @throws NullPointerException if the specified element is null
351     * (<a href="../Collection.html#optional-restrictions">optional</a>)
352 dl 1.1 */
353 dl 1.3 boolean removeLastOccurrence(Object o);
354 dl 1.1
355 jsr166 1.8 // *** Queue methods ***
356 dl 1.1
357 jsr166 1.8 /**
358     * Inserts the specified element into the queue represented by this deque
359     * (in other words, at the tail of this deque) if it is possible to do so
360     * immediately without violating capacity restrictions, returning
361 jsr166 1.22 * {@code true} upon success and throwing an
362     * {@code IllegalStateException} if no space is currently available.
363 jsr166 1.8 * When using a capacity-restricted deque, it is generally preferable to
364     * use {@link #offer(Object) offer}.
365     *
366 jsr166 1.14 * <p>This method is equivalent to {@link #addLast}.
367 jsr166 1.8 *
368     * @param e the element to add
369 jsr166 1.22 * @return {@code true} (as specified by {@link Collection#add})
370 jsr166 1.8 * @throws IllegalStateException if the element cannot be added at this
371     * time due to capacity restrictions
372 jsr166 1.9 * @throws ClassCastException if the class of the specified element
373     * prevents it from being added to this deque
374 jsr166 1.8 * @throws NullPointerException if the specified element is null and this
375     * deque does not permit null elements
376     * @throws IllegalArgumentException if some property of the specified
377     * element prevents it from being added to this deque
378     */
379     boolean add(E e);
380 dl 1.1
381     /**
382     * Inserts the specified element into the queue represented by this deque
383 jsr166 1.8 * (in other words, at the tail of this deque) if it is possible to do so
384     * immediately without violating capacity restrictions, returning
385 jsr166 1.22 * {@code true} upon success and {@code false} if no space is currently
386 jsr166 1.8 * available. When using a capacity-restricted deque, this method is
387     * generally preferable to the {@link #add} method, which can fail to
388     * insert an element only by throwing an exception.
389 dl 1.1 *
390     * <p>This method is equivalent to {@link #offerLast}.
391     *
392 jsr166 1.8 * @param e the element to add
393 jsr166 1.22 * @return {@code true} if the element was added to this deque, else
394     * {@code false}
395 jsr166 1.9 * @throws ClassCastException if the class of the specified element
396     * prevents it from being added to this deque
397 dl 1.3 * @throws NullPointerException if the specified element is null and this
398 jsr166 1.8 * deque does not permit null elements
399     * @throws IllegalArgumentException if some property of the specified
400     * element prevents it from being added to this deque
401 dl 1.1 */
402     boolean offer(E e);
403    
404     /**
405 jsr166 1.8 * Retrieves and removes the head of the queue represented by this deque
406     * (in other words, the first element of this deque).
407 jsr166 1.15 * This method differs from {@link #poll poll} only in that it throws an
408 jsr166 1.8 * exception if this deque is empty.
409 dl 1.1 *
410 jsr166 1.8 * <p>This method is equivalent to {@link #removeFirst()}.
411 dl 1.1 *
412 jsr166 1.8 * @return the head of the queue represented by this deque
413     * @throws NoSuchElementException if this deque is empty
414 dl 1.1 */
415 jsr166 1.8 E remove();
416 dl 1.1
417     /**
418 jsr166 1.8 * Retrieves and removes the head of the queue represented by this deque
419     * (in other words, the first element of this deque), or returns
420 jsr166 1.22 * {@code null} if this deque is empty.
421 dl 1.1 *
422     * <p>This method is equivalent to {@link #pollFirst()}.
423     *
424 jsr166 1.22 * @return the first element of this deque, or {@code null} if
425 jsr166 1.8 * this deque is empty
426 dl 1.1 */
427     E poll();
428    
429     /**
430 jsr166 1.8 * Retrieves, but does not remove, the head of the queue represented by
431     * this deque (in other words, the first element of this deque).
432 jsr166 1.15 * This method differs from {@link #peek peek} only in that it throws an
433 jsr166 1.8 * exception if this deque is empty.
434 dl 1.1 *
435 jsr166 1.8 * <p>This method is equivalent to {@link #getFirst()}.
436 dl 1.1 *
437     * @return the head of the queue represented by this deque
438     * @throws NoSuchElementException if this deque is empty
439     */
440 jsr166 1.8 E element();
441 dl 1.1
442     /**
443     * Retrieves, but does not remove, the head of the queue represented by
444 jsr166 1.8 * this deque (in other words, the first element of this deque), or
445 jsr166 1.22 * returns {@code null} if this deque is empty.
446 dl 1.1 *
447 dl 1.3 * <p>This method is equivalent to {@link #peekFirst()}.
448 dl 1.1 *
449     * @return the head of the queue represented by this deque, or
450 jsr166 1.22 * {@code null} if this deque is empty
451 dl 1.1 */
452     E peek();
453    
454    
455     // *** Stack methods ***
456    
457     /**
458 jsr166 1.8 * Pushes an element onto the stack represented by this deque (in other
459     * words, at the head of this deque) if it is possible to do so
460 jsr166 1.25 * immediately without violating capacity restrictions, throwing an
461 jsr166 1.22 * {@code IllegalStateException} if no space is currently available.
462 dl 1.1 *
463     * <p>This method is equivalent to {@link #addFirst}.
464     *
465 dl 1.3 * @param e the element to push
466 jsr166 1.8 * @throws IllegalStateException if the element cannot be added at this
467     * time due to capacity restrictions
468 jsr166 1.9 * @throws ClassCastException if the class of the specified element
469     * prevents it from being added to this deque
470 dl 1.3 * @throws NullPointerException if the specified element is null and this
471 jsr166 1.8 * deque does not permit null elements
472     * @throws IllegalArgumentException if some property of the specified
473     * element prevents it from being added to this deque
474 dl 1.1 */
475     void push(E e);
476    
477     /**
478     * Pops an element from the stack represented by this deque. In other
479 dl 1.2 * words, removes and returns the first element of this deque.
480 dl 1.1 *
481     * <p>This method is equivalent to {@link #removeFirst()}.
482     *
483     * @return the element at the front of this deque (which is the top
484 jsr166 1.8 * of the stack represented by this deque)
485 dl 1.1 * @throws NoSuchElementException if this deque is empty
486     */
487     E pop();
488    
489    
490 jsr166 1.8 // *** Collection methods ***
491    
492     /**
493     * Removes the first occurrence of the specified element from this deque.
494     * If the deque does not contain the element, it is unchanged.
495 jsr166 1.22 * More formally, removes the first element {@code e} such that
496 jsr166 1.9 * <tt>(o==null&nbsp;?&nbsp;e==null&nbsp;:&nbsp;o.equals(e))</tt>
497     * (if such an element exists).
498 jsr166 1.22 * Returns {@code true} if this deque contained the specified element
499 jsr166 1.12 * (or equivalently, if this deque changed as a result of the call).
500 jsr166 1.8 *
501 jsr166 1.23 * <p>This method is equivalent to {@link #removeFirstOccurrence(Object)}.
502 jsr166 1.8 *
503     * @param o element to be removed from this deque, if present
504 jsr166 1.22 * @return {@code true} if an element was removed as a result of this call
505 jsr166 1.9 * @throws ClassCastException if the class of the specified element
506 jsr166 1.27 * is incompatible with this deque
507     * (<a href="../Collection.html#optional-restrictions">optional</a>)
508     * @throws NullPointerException if the specified element is null
509     * (<a href="../Collection.html#optional-restrictions">optional</a>)
510 jsr166 1.8 */
511     boolean remove(Object o);
512    
513     /**
514 jsr166 1.22 * Returns {@code true} if this deque contains the specified element.
515     * More formally, returns {@code true} if and only if this deque contains
516     * at least one element {@code e} such that
517 jsr166 1.9 * <tt>(o==null&nbsp;?&nbsp;e==null&nbsp;:&nbsp;o.equals(e))</tt>.
518 jsr166 1.8 *
519     * @param o element whose presence in this deque is to be tested
520 jsr166 1.22 * @return {@code true} if this deque contains the specified element
521 jsr166 1.27 * @throws ClassCastException if the class of the specified element
522     * is incompatible with this deque
523     * (<a href="../Collection.html#optional-restrictions">optional</a>)
524     * @throws NullPointerException if the specified element is null
525     * (<a href="../Collection.html#optional-restrictions">optional</a>)
526 jsr166 1.8 */
527     boolean contains(Object o);
528    
529     /**
530     * Returns the number of elements in this deque.
531     *
532     * @return the number of elements in this deque
533     */
534     public int size();
535 dl 1.1
536     /**
537 jsr166 1.10 * Returns an iterator over the elements in this deque in proper sequence.
538     * The elements will be returned in order from first (head) to last (tail).
539 dl 1.3 *
540 jsr166 1.10 * @return an iterator over the elements in this deque in proper sequence
541 dl 1.1 */
542     Iterator<E> iterator();
543 dl 1.17
544     /**
545     * Returns an iterator over the elements in this deque in reverse
546     * sequential order. The elements will be returned in order from
547     * last (tail) to first (head).
548     *
549     * @return an iterator over the elements in this deque in reverse
550     * sequence
551     */
552     Iterator<E> descendingIterator();
553    
554 dl 1.1 }