ViewVC Help
View File | Revision Log | Show Annotations | Download File | Root Listing
root/jsr166/jsr166/src/main/java/util/Deque.java
(Generate patch)

Comparing jsr166/src/main/java/util/Deque.java (file contents):
Revision 1.13 by jsr166, Wed May 18 03:45:35 2005 UTC vs.
Revision 1.24 by jsr166, Mon Feb 11 17:27:45 2013 UTC

# Line 1 | Line 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 < * at http://creativecommons.org/licenses/publicdomain
4 > * at http://creativecommons.org/publicdomain/zero/1.0/
5   */
6  
7   package java.util;
# Line 9 | Line 9 | package java.util;
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 < * and is usually pronounced "deck".  Most <tt>Deque</tt>
12 > * and is usually pronounced "deck".  Most {@code Deque}
13   * 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.
# Line 18 | Line 18 | package java.util;
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 < * special value (either <tt>null</tt> or <tt>false</tt>, depending on
21 > * special value (either {@code null} or {@code false}, depending on
22   * the operation).  The latter form of the insert operation is
23   * designed specifically for use with capacity-restricted
24 < * <tt>Deque</tt> implementations; in most implementations, insert
24 > * {@code Deque} implementations; in most implementations, insert
25   * operations cannot fail.
26   *
27   * <p>The twelve methods described above are summarized in the
# Line 29 | Line 29 | package java.util;
29   *
30   * <p>
31   * <table BORDER CELLPADDING=3 CELLSPACING=1>
32 + * <caption>Summary of Deque methods</caption>
33   *  <tr>
34   *    <td></td>
35   *    <td ALIGN=CENTER COLSPAN = 2> <b>First Element (Head)</b></td>
# Line 67 | Line 68 | package java.util;
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   * added at the end of the deque and removed from the beginning.  The methods
71 < * inherited from the <tt>Queue</tt> interface are precisely equivalent to
72 < * <tt>Deque</tt> methods as indicated in the following table:
71 > * inherited from the {@code Queue} interface are precisely equivalent to
72 > * {@code Deque} methods as indicated in the following table:
73   *
74   * <p>
75   * <table BORDER CELLPADDING=3 CELLSPACING=1>
76 + * <caption>Comparison of Queue and Deque methods</caption>
77   *  <tr>
78 < *    <td ALIGN=CENTER> <b><tt>Queue</tt> Method</b></td>
79 < *    <td ALIGN=CENTER> <b>Equivalent <tt>Deque</tt> Method</b></td>
78 > *    <td ALIGN=CENTER> <b>{@code Queue} Method</b></td>
79 > *    <td ALIGN=CENTER> <b>Equivalent {@code Deque} Method</b></td>
80   *  </tr>
81   *  <tr>
82   *    <td>{@link java.util.Queue#add add(e)}</td>
# Line 106 | Line 108 | package java.util;
108   * interface should be used in preference to the legacy {@link Stack} class.
109   * When a deque is used as a stack, elements are pushed and popped from the
110   * beginning of the deque.  Stack methods are precisely equivalent to
111 < * <tt>Deque</tt> methods as indicated in the table below:
111 > * {@code Deque} methods as indicated in the table below:
112   *
113   * <p>
114   * <table BORDER CELLPADDING=3 CELLSPACING=1>
115 + * <caption>Comparison of Stack and Deque methods</caption>
116   *  <tr>
117   *    <td ALIGN=CENTER> <b>Stack Method</b></td>
118 < *    <td ALIGN=CENTER> <b>Equivalent <tt>Deque</tt> Method</b></td>
118 > *    <td ALIGN=CENTER> <b>Equivalent {@code Deque} Method</b></td>
119   *  </tr>
120   *  <tr>
121   *    <td>{@link #push push(e)}</td>
# Line 139 | Line 142 | package java.util;
142   * <p>Unlike the {@link List} interface, this interface does not
143   * provide support for indexed access to elements.
144   *
145 < * <p>While <tt>Deque</tt> implementations are not strictly required
145 > * <p>While {@code Deque} implementations are not strictly required
146   * to prohibit the insertion of null elements, they are strongly
147 < * encouraged to do so.  Users of any <tt>Deque</tt> implementations
147 > * encouraged to do so.  Users of any {@code Deque} implementations
148   * 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 < * <tt>null</tt> is used as a special return value by various methods
150 > * {@code null} is used as a special return value by various methods
151   * to indicated that the deque is empty.
152   *
153 < * <p><tt>Deque</tt> implementations generally do not define
154 < * element-based versions of the <tt>equals</tt> and <tt>hashCode</tt>
153 > * <p>{@code Deque} implementations generally do not define
154 > * element-based versions of the {@code equals} and {@code hashCode}
155   * methods, but instead inherit the identity-based versions from class
156 < * <tt>Object</tt>.
156 > * {@code Object}.
157   *
158   * <p>This interface is a member of the <a
159 < * href="{@docRoot}/../guide/collections/index.html"> Java Collections
159 > * href="{@docRoot}/../technotes/guides/collections/index.html"> Java Collections
160   * Framework</a>.
161   *
162   * @author Doug Lea
# Line 161 | Line 164 | package java.util;
164   * @since  1.6
165   * @param <E> the type of elements held in this collection
166   */
164 –
167   public interface Deque<E> extends Queue<E> {
168      /**
169       * Inserts the specified element at the front of this deque if it is
# Line 187 | Line 189 | public interface Deque<E> extends Queue<
189       * When using a capacity-restricted deque, it is generally preferable to
190       * use method {@link #offerLast}.
191       *
192 +     * <p>This method is equivalent to {@link #add}.
193 +     *
194       * @param e the element to add
195       * @throws IllegalStateException if the element cannot be added at this
196       *         time due to capacity restrictions
# Line 206 | Line 210 | public interface Deque<E> extends Queue<
210       * which can fail to insert an element only by throwing an exception.
211       *
212       * @param e the element to add
213 <     * @return <tt>true</tt> if the element was added to this deque, else
214 <     *         <tt>false</tt>
213 >     * @return {@code true} if the element was added to this deque, else
214 >     *         {@code false}
215       * @throws ClassCastException if the class of the specified element
216       *         prevents it from being added to this deque
217       * @throws NullPointerException if the specified element is null and this
# Line 224 | Line 228 | public interface Deque<E> extends Queue<
228       * which can fail to insert an element only by throwing an exception.
229       *
230       * @param e the element to add
231 <     * @return <tt>true</tt> if the element was added to this deque, else
232 <     *         <tt>false</tt>
231 >     * @return {@code true} if the element was added to this deque, else
232 >     *         {@code false}
233       * @throws ClassCastException if the class of the specified element
234       *         prevents it from being added to this deque
235       * @throws NullPointerException if the specified element is null and this
# Line 237 | Line 241 | public interface Deque<E> extends Queue<
241  
242      /**
243       * Retrieves and removes the first element of this deque.  This method
244 <     * differs from {@link #pollFirst} only in that it throws an exception
245 <     * if this deque is empty.
244 >     * differs from {@link #pollFirst pollFirst} only in that it throws an
245 >     * exception if this deque is empty.
246       *
247       * @return the head of this deque
248       * @throws NoSuchElementException if this deque is empty
# Line 247 | Line 251 | public interface Deque<E> extends Queue<
251  
252      /**
253       * Retrieves and removes the last element of this deque.  This method
254 <     * differs from {@link #pollLast} only in that it throws an exception if
255 <     * this deque is empty.
254 >     * differs from {@link #pollLast pollLast} only in that it throws an
255 >     * exception if this deque is empty.
256       *
257       * @return the tail of this deque
258       * @throws NoSuchElementException if this deque is empty
# Line 257 | Line 261 | public interface Deque<E> extends Queue<
261  
262      /**
263       * Retrieves and removes the first element of this deque,
264 <     * or returns <tt>null</tt> if this deque is empty.
264 >     * or returns {@code null} if this deque is empty.
265       *
266 <     * @return the head of this deque, or <tt>null</tt> if this deque is empty
266 >     * @return the head of this deque, or {@code null} if this deque is empty
267       */
268      E pollFirst();
269  
270      /**
271       * Retrieves and removes the last element of this deque,
272 <     * or returns <tt>null</tt> if this deque is empty.
272 >     * or returns {@code null} if this deque is empty.
273       *
274 <     * @return the tail of this deque, or <tt>null</tt> if this deque is empty
274 >     * @return the tail of this deque, or {@code null} if this deque is empty
275       */
276      E pollLast();
277  
278      /**
279       * Retrieves, but does not remove, the first element of this deque.
280 <     * This method differs from {@link #peekFirst} only in that it throws an
281 <     * exception if this deque is empty.
280 >     *
281 >     * This method differs from {@link #peekFirst peekFirst} only in that it
282 >     * throws an exception if this deque is empty.
283       *
284       * @return the head of this deque
285       * @throws NoSuchElementException if this deque is empty
# Line 283 | Line 288 | public interface Deque<E> extends Queue<
288  
289      /**
290       * Retrieves, but does not remove, the last element of this deque.
291 <     * This method differs from {@link #peekLast} only in that it throws an
292 <     * exception if this deque is empty.
291 >     * This method differs from {@link #peekLast peekLast} only in that it
292 >     * throws an exception if this deque is empty.
293       *
294       * @return the tail of this deque
295       * @throws NoSuchElementException if this deque is empty
# Line 293 | Line 298 | public interface Deque<E> extends Queue<
298  
299      /**
300       * Retrieves, but does not remove, the first element of this deque,
301 <     * or returns <tt>null</tt> if this deque is empty.
301 >     * or returns {@code null} if this deque is empty.
302       *
303 <     * @return the head of this deque, or <tt>null</tt> if this deque is empty
303 >     * @return the head of this deque, or {@code null} if this deque is empty
304       */
305      E peekFirst();
306  
307      /**
308       * Retrieves, but does not remove, the last element of this deque,
309 <     * or returns <tt>null</tt> if this deque is empty.
309 >     * or returns {@code null} if this deque is empty.
310       *
311 <     * @return the tail of this deque, or <tt>null</tt> if this deque is empty
311 >     * @return the tail of this deque, or {@code null} if this deque is empty
312       */
313      E peekLast();
314  
315      /**
316       * Removes the first occurrence of the specified element from this deque.
317       * If the deque does not contain the element, it is unchanged.
318 <     * More formally, removes the first element <tt>e</tt> such that
318 >     * More formally, removes the first element {@code e} such that
319       * <tt>(o==null&nbsp;?&nbsp;e==null&nbsp;:&nbsp;o.equals(e))</tt>
320       * (if such an element exists).
321 <     * Returns <tt>true</tt> if this deque contained the specified element
321 >     * Returns {@code true} if this deque contained the specified element
322       * (or equivalently, if this deque changed as a result of the call).
323       *
324       * @param o element to be removed from this deque, if present
325 <     * @return <tt>true</tt> if an element was removed as a result of this call
325 >     * @return {@code true} if an element was removed as a result of this call
326       * @throws ClassCastException if the class of the specified element
327       *         is incompatible with this deque (optional)
328       * @throws NullPointerException if the specified element is null and this
# Line 328 | Line 333 | public interface Deque<E> extends Queue<
333      /**
334       * Removes the last occurrence of the specified element from this deque.
335       * If the deque does not contain the element, it is unchanged.
336 <     * More formally, removes the last element <tt>e</tt> such that
336 >     * More formally, removes the last element {@code e} such that
337       * <tt>(o==null&nbsp;?&nbsp;e==null&nbsp;:&nbsp;o.equals(e))</tt>
338       * (if such an element exists).
339 <     * Returns <tt>true</tt> if this deque contained the specified element
339 >     * Returns {@code true} if this deque contained the specified element
340       * (or equivalently, if this deque changed as a result of the call).
341       *
342       * @param o element to be removed from this deque, if present
343 <     * @return <tt>true</tt> if an element was removed as a result of this call
343 >     * @return {@code true} if an element was removed as a result of this call
344       * @throws ClassCastException if the class of the specified element
345       *         is incompatible with this deque (optional)
346       * @throws NullPointerException if the specified element is null and this
# Line 349 | Line 354 | public interface Deque<E> extends Queue<
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 <     * <tt>true</tt> upon success and throwing an
358 <     * <tt>IllegalStateException</tt> if no space is currently available.
357 >     * {@code true} upon success and throwing an
358 >     * {@code IllegalStateException} if no space is currently available.
359       * When using a capacity-restricted deque, it is generally preferable to
360       * use {@link #offer(Object) offer}.
361       *
362 <     * <p>This method is equivalent to {@link #addLast(Object) addLast}.
362 >     * <p>This method is equivalent to {@link #addLast}.
363       *
364       * @param e the element to add
365 <     * @return <tt>true</tt> (as per the spec for {@link Collection#add})
365 >     * @return {@code true} (as specified by {@link Collection#add})
366       * @throws IllegalStateException if the element cannot be added at this
367       *         time due to capacity restrictions
368       * @throws ClassCastException if the class of the specified element
# Line 373 | Line 378 | public interface Deque<E> extends Queue<
378       * Inserts the specified element into the queue represented by this deque
379       * (in other words, at the tail of this deque) if it is possible to do so
380       * immediately without violating capacity restrictions, returning
381 <     * <tt>true</tt> upon success and <tt>false</tt> if no space is currently
381 >     * {@code true} upon success and {@code false} if no space is currently
382       * 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.
# Line 381 | Line 386 | public interface Deque<E> extends Queue<
386       * <p>This method is equivalent to {@link #offerLast}.
387       *
388       * @param e the element to add
389 <     * @return <tt>true</tt> if the element was added to this deque, else
390 <     *         <tt>false</tt>
389 >     * @return {@code true} if the element was added to this deque, else
390 >     *         {@code false}
391       * @throws ClassCastException if the class of the specified element
392       *         prevents it from being added to this deque
393       * @throws NullPointerException if the specified element is null and this
# Line 395 | Line 400 | public interface Deque<E> extends Queue<
400      /**
401       * Retrieves and removes the head of the queue represented by this deque
402       * (in other words, the first element of this deque).
403 <     * This method differs from {@link #poll} only in that it throws an
403 >     * This method differs from {@link #poll poll} only in that it throws an
404       * exception if this deque is empty.
405       *
406       * <p>This method is equivalent to {@link #removeFirst()}.
# Line 408 | Line 413 | public interface Deque<E> extends Queue<
413      /**
414       * 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 <     * <tt>null</tt> if this deque is empty.
416 >     * {@code null} if this deque is empty.
417       *
418       * <p>This method is equivalent to {@link #pollFirst()}.
419       *
420 <     * @return the first element of this deque, or <tt>null</tt> if
420 >     * @return the first element of this deque, or {@code null} if
421       *         this deque is empty
422       */
423      E poll();
# Line 420 | Line 425 | public interface Deque<E> extends Queue<
425      /**
426       * 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 <     * This method differs from {@link #peek} only in that it throws an
428 >     * This method differs from {@link #peek peek} only in that it throws an
429       * exception if this deque is empty.
430       *
431       * <p>This method is equivalent to {@link #getFirst()}.
# Line 433 | Line 438 | public interface Deque<E> extends Queue<
438      /**
439       * Retrieves, but does not remove, the head of the queue represented by
440       * this deque (in other words, the first element of this deque), or
441 <     * returns <tt>null</tt> if this deque is empty.
441 >     * returns {@code null} if this deque is empty.
442       *
443       * <p>This method is equivalent to {@link #peekFirst()}.
444       *
445       * @return the head of the queue represented by this deque, or
446 <     *         <tt>null</tt> if this deque is empty
446 >     *         {@code null} if this deque is empty
447       */
448      E peek();
449  
# Line 449 | Line 454 | public interface Deque<E> extends Queue<
454       * 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 <     * <tt>true</tt> upon success and throwing an
458 <     * <tt>IllegalStateException</tt> if no space is currently available.
457 >     * {@code true} upon success and throwing an
458 >     * {@code IllegalStateException} if no space is currently available.
459       *
460       * <p>This method is equivalent to {@link #addFirst}.
461       *
# Line 484 | Line 489 | public interface Deque<E> extends Queue<
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 <     * More formally, removes the first element <tt>e</tt> such that
492 >     * More formally, removes the first element {@code e} such that
493       * <tt>(o==null&nbsp;?&nbsp;e==null&nbsp;:&nbsp;o.equals(e))</tt>
494       * (if such an element exists).
495 <     * Returns <tt>true</tt> if this deque contained the specified element
495 >     * Returns {@code true} if this deque contained the specified element
496       * (or equivalently, if this deque changed as a result of the call).
497       *
498 <     * <p>This method is equivalent to {@link #removeFirstOccurrence}.
498 >     * <p>This method is equivalent to {@link #removeFirstOccurrence(Object)}.
499       *
500       * @param o element to be removed from this deque, if present
501 <     * @return <tt>true</tt> if an element was removed as a result of this call
501 >     * @return {@code true} if an element was removed as a result of this call
502       * @throws ClassCastException if the class of the specified element
503       *         is incompatible with this deque (optional)
504       * @throws NullPointerException if the specified element is null and this
# Line 502 | Line 507 | public interface Deque<E> extends Queue<
507      boolean remove(Object o);
508  
509      /**
510 <     * Returns <tt>true</tt> if this deque contains the specified element.
511 <     * More formally, returns <tt>true</tt> if and only if this deque contains
512 <     * at least one element <tt>e</tt> such that
510 >     * 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       * <tt>(o==null&nbsp;?&nbsp;e==null&nbsp;:&nbsp;o.equals(e))</tt>.
514       *
515       * @param o element whose presence in this deque is to be tested
516 <     * @return <tt>true</tt> if this deque contains the specified element
516 >     * @return {@code true} if this deque contains the specified element
517       * @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
# Line 530 | Line 535 | public interface Deque<E> extends Queue<
535       * @return an iterator over the elements in this deque in proper sequence
536       */
537      Iterator<E> iterator();
538 +
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   }

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines