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.9 by jsr166, Mon May 16 04:58:20 2005 UTC vs.
Revision 1.21 by jsr166, Sun Oct 21 06:40:20 2012 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 153 | Line 153 | package java.util;
153   * <tt>Object</tt>.
154   *
155   * <p>This interface is a member of the <a
156 < * href="{@docRoot}/../guide/collections/index.html"> Java Collections
156 > * href="{@docRoot}/../technotes/guides/collections/index.html"> Java Collections
157   * Framework</a>.
158   *
159   * @author Doug Lea
# Line 161 | Line 161 | package java.util;
161   * @since  1.6
162   * @param <E> the type of elements held in this collection
163   */
164 –
164   public interface Deque<E> extends Queue<E> {
165      /**
166       * Inserts the specified element at the front of this deque if it is
# Line 182 | Line 181 | public interface Deque<E> extends Queue<
181      void addFirst(E e);
182  
183      /**
184 <     * Inserts the specified element at the end of this deque  if it is
184 >     * Inserts the specified element at the end of this deque if it is
185       * possible to do so immediately without violating capacity restrictions.
186       * When using a capacity-restricted deque, it is generally preferable to
187       * use method {@link #offerLast}.
188       *
189 +     * <p>This method is equivalent to {@link #add}.
190 +     *
191       * @param e the element to add
192       * @throws IllegalStateException if the element cannot be added at this
193       *         time due to capacity restrictions
# Line 206 | Line 207 | public interface Deque<E> extends Queue<
207       * which can fail to insert an element only by throwing an exception.
208       *
209       * @param e the element to add
210 <     * @return <tt>true</tt> if it was possible to insert the element,
211 <     *         else <tt>false</tt>
210 >     * @return <tt>true</tt> if the element was added to this deque, else
211 >     *         <tt>false</tt>
212       * @throws ClassCastException if the class of the specified element
213       *         prevents it from being added to this deque
214       * @throws NullPointerException if the specified element is null and this
# Line 224 | Line 225 | public interface Deque<E> extends Queue<
225       * which can fail to insert an element only by throwing an exception.
226       *
227       * @param e the element to add
228 <     * @return <tt>true</tt> if it was possible to insert the element,
229 <     *         else <tt>false</tt>
228 >     * @return <tt>true</tt> if the element was added to this deque, else
229 >     *         <tt>false</tt>
230       * @throws ClassCastException if the class of the specified element
231       *         prevents it from being added to this deque
232       * @throws NullPointerException if the specified element is null and this
# Line 237 | Line 238 | public interface Deque<E> extends Queue<
238  
239      /**
240       * Retrieves and removes the first element of this deque.  This method
241 <     * differs from {@link #pollFirst} only in that it throws an exception
242 <     * if this deque is empty.
241 >     * differs from {@link #pollFirst pollFirst} only in that it throws an
242 >     * exception if this deque is empty.
243       *
244       * @return the head of this deque
245       * @throws NoSuchElementException if this deque is empty
# Line 247 | Line 248 | public interface Deque<E> extends Queue<
248  
249      /**
250       * Retrieves and removes the last element of this deque.  This method
251 <     * differs from {@link #pollLast} only in that it throws an exception if
252 <     * this deque is empty.
251 >     * differs from {@link #pollLast pollLast} only in that it throws an
252 >     * exception if this deque is empty.
253       *
254       * @return the tail of this deque
255       * @throws NoSuchElementException if this deque is empty
# Line 273 | Line 274 | public interface Deque<E> extends Queue<
274  
275      /**
276       * Retrieves, but does not remove, the first element of this deque.
277 <     * This method differs from {@link #peekFirst} only in that it throws an
278 <     * exception if this deque is empty.
277 >     *
278 >     * This method differs from {@link #peekFirst peekFirst} only in that it
279 >     * throws an exception if this deque is empty.
280       *
281       * @return the head of this deque
282       * @throws NoSuchElementException if this deque is empty
# Line 283 | Line 285 | public interface Deque<E> extends Queue<
285  
286      /**
287       * Retrieves, but does not remove, the last element of this deque.
288 <     * This method differs from {@link #peekLast} only in that it throws an
289 <     * exception if this deque is empty.
288 >     * This method differs from {@link #peekLast peekLast} only in that it
289 >     * throws an exception if this deque is empty.
290       *
291       * @return the tail of this deque
292       * @throws NoSuchElementException if this deque is empty
# Line 313 | Line 315 | public interface Deque<E> extends Queue<
315       * More formally, removes the first element <tt>e</tt> such that
316       * <tt>(o==null&nbsp;?&nbsp;e==null&nbsp;:&nbsp;o.equals(e))</tt>
317       * (if such an element exists).
318 <     * Returns true if this deque contained the specified element (or
319 <     * equivalently, if this deque changed as a result of the call).
318 >     * Returns <tt>true</tt> if this deque contained the specified element
319 >     * (or equivalently, if this deque changed as a result of the call).
320       *
321       * @param o element to be removed from this deque, if present
322       * @return <tt>true</tt> if an element was removed as a result of this call
# Line 331 | Line 333 | public interface Deque<E> extends Queue<
333       * More formally, removes the last element <tt>e</tt> such that
334       * <tt>(o==null&nbsp;?&nbsp;e==null&nbsp;:&nbsp;o.equals(e))</tt>
335       * (if such an element exists).
336 <     * Returns true if this deque contained the specified element (or
337 <     * equivalently, if this deque changed as a result of the call).
336 >     * Returns <tt>true</tt> if this deque contained the specified element
337 >     * (or equivalently, if this deque changed as a result of the call).
338       *
339       * @param o element to be removed from this deque, if present
340       * @return <tt>true</tt> if an element was removed as a result of this call
# Line 354 | Line 356 | public interface Deque<E> extends Queue<
356       * When using a capacity-restricted deque, it is generally preferable to
357       * use {@link #offer(Object) offer}.
358       *
359 <     * <p>This method is equivalent to {@link #addLast(Object) addLast}.
359 >     * <p>This method is equivalent to {@link #addLast}.
360       *
361       * @param e the element to add
362 <     * @return <tt>true</tt> (as per the spec for {@link Collection#add})
362 >     * @return <tt>true</tt> (as specified by {@link Collection#add})
363       * @throws IllegalStateException if the element cannot be added at this
364       *         time due to capacity restrictions
365       * @throws ClassCastException if the class of the specified element
# Line 395 | Line 397 | public interface Deque<E> extends Queue<
397      /**
398       * Retrieves and removes the head of the queue represented by this deque
399       * (in other words, the first element of this deque).
400 <     * This method differs from {@link #poll} only in that it throws an
400 >     * This method differs from {@link #poll poll} only in that it throws an
401       * exception if this deque is empty.
402       *
403       * <p>This method is equivalent to {@link #removeFirst()}.
# Line 420 | Line 422 | public interface Deque<E> extends Queue<
422      /**
423       * Retrieves, but does not remove, the head of the queue represented by
424       * this deque (in other words, the first element of this deque).
425 <     * This method differs from {@link #peek} only in that it throws an
425 >     * This method differs from {@link #peek peek} only in that it throws an
426       * exception if this deque is empty.
427       *
428       * <p>This method is equivalent to {@link #getFirst()}.
# Line 487 | Line 489 | public interface Deque<E> extends Queue<
489       * More formally, removes the first element <tt>e</tt> such that
490       * <tt>(o==null&nbsp;?&nbsp;e==null&nbsp;:&nbsp;o.equals(e))</tt>
491       * (if such an element exists).
492 <     * Returns true if this deque contained the specified element (or
493 <     * equivalently, if this deque changed as a result of the call).
492 >     * Returns <tt>true</tt> if this deque contained the specified element
493 >     * (or equivalently, if this deque changed as a result of the call).
494       *
495       * <p>This method is equivalent to {@link #removeFirstOccurrence}.
496       *
# Line 524 | Line 526 | public interface Deque<E> extends Queue<
526      public int size();
527  
528      /**
529 <     * Returns an iterator over the elements in this deque.  The elements
530 <     * will be ordered from first (head) to last (tail).
529 >     * Returns an iterator over the elements in this deque in proper sequence.
530 >     * The elements will be returned in order from first (head) to last (tail).
531       *
532 <     * @return an <tt>Iterator</tt> over the elements in this deque
532 >     * @return an iterator over the elements in this deque in proper sequence
533       */
534      Iterator<E> iterator();
535 +
536 +    /**
537 +     * Returns an iterator over the elements in this deque in reverse
538 +     * sequential order.  The elements will be returned in order from
539 +     * last (tail) to first (head).
540 +     *
541 +     * @return an iterator over the elements in this deque in reverse
542 +     * sequence
543 +     */
544 +    Iterator<E> descendingIterator();
545 +
546   }

Diff Legend

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