[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.27 - (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 : 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 }

Doug Lea
ViewVC Help
Powered by ViewVC 1.0.8