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

Doug Lea
ViewVC Help
Powered by ViewVC 1.0.8