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.8 by jsr166, Sat May 14 02:22:28 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 172 | Line 171 | public interface Deque<E> extends Queue<
171       * @param e the element to add
172       * @throws IllegalStateException if the element cannot be added at this
173       *         time due to capacity restrictions
175 –     * @throws NullPointerException if the specified element is null and this
176 –     *         deque does not permit null elements
174       * @throws ClassCastException if the class of the specified element
175       *         prevents it from being added to this deque
176 +     * @throws NullPointerException if the specified element is null and this
177 +     *         deque does not permit null elements
178       * @throws IllegalArgumentException if some property of the specified
179       *         element prevents it from being added to this deque
180       */
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
193 –     * @throws NullPointerException if the specified element is null and this
194 –     *         deque does not permit null elements
194       * @throws ClassCastException if the class of the specified element
195       *         prevents it from being added to this deque
196 +     * @throws NullPointerException if the specified element is null and this
197 +     *         deque does not permit null elements
198       * @throws IllegalArgumentException if some property of the specified
199       *         element prevents it from being added to this deque
200       */
# 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>
211 <     * @throws NullPointerException if the specified element is null and this
212 <     *         deque does not permit null elements
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
215 +     *         deque does not permit null elements
216       * @throws IllegalArgumentException if some property of the specified
217       *         element prevents it from being added to this deque
218       */
# 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>
229 <     * @throws NullPointerException if the specified element is null and this
230 <     *         deque does not permit null elements
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
233 +     *         deque does not permit null elements
234       * @throws IllegalArgumentException if some property of the specified
235       *         element prevents it from being added to this deque
236       */
# 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 311 | Line 313 | public interface Deque<E> extends Queue<
313       * Removes the first occurrence of the specified element from this deque.
314       * If the deque does not contain the element, it is unchanged.
315       * More formally, removes the first element <tt>e</tt> such that
316 <     * <tt>(o==null ? e==null : o.equals(e))</tt> (if such an element exists).
317 <     * Returns true if this deque contained the specified element (or
318 <     * equivalently, if this deque changed as a result of the call).
316 >     * <tt>(o==null&nbsp;?&nbsp;e==null&nbsp;:&nbsp;o.equals(e))</tt>
317 >     * (if such an element exists).
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
323 +     * @throws ClassCastException if the class of the specified element
324 +     *         is incompatible with this deque (optional)
325       * @throws NullPointerException if the specified element is null and this
326       *         deque does not permit null elements (optional)
322 –     * @throws ClassCastException if the class of the specified element
323 –     *         is incompatible with this collection (optional)
327       */
328      boolean removeFirstOccurrence(Object o);
329  
# Line 328 | Line 331 | public interface Deque<E> extends Queue<
331       * Removes the last occurrence of the specified element from this deque.
332       * If the deque does not contain the element, it is unchanged.
333       * More formally, removes the last element <tt>e</tt> such that
334 <     * <tt>(o==null ? e==null : o.equals(e))</tt> (if such an element exists).
335 <     * Returns true if this deque contained the specified element (or
336 <     * equivalently, if this deque changed as a result of the call).
334 >     * <tt>(o==null&nbsp;?&nbsp;e==null&nbsp;:&nbsp;o.equals(e))</tt>
335 >     * (if such an element exists).
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
341 +     * @throws ClassCastException if the class of the specified element
342 +     *         is incompatible with this deque (optional)
343       * @throws NullPointerException if the specified element is null and this
344       *         deque does not permit null elements (optional)
339 –     * @throws ClassCastException if the class of the specified element
340 –     *         is incompatible with this collection (optional)
345       */
346      boolean removeLastOccurrence(Object o);
347  
# Line 352 | 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
361 –     * @throws NullPointerException if the specified element is null and this
362 –     *         deque does not permit null elements
365       * @throws ClassCastException if the class of the specified element
366       *         prevents it from being added to this deque
367 +     * @throws NullPointerException if the specified element is null and this
368 +     *         deque does not permit null elements
369       * @throws IllegalArgumentException if some property of the specified
370       *         element prevents it from being added to this deque
371       */
# Line 381 | Line 385 | public interface Deque<E> extends Queue<
385       * @param e the element to add
386       * @return <tt>true</tt> if the element was added to this deque, else
387       *         <tt>false</tt>
384 –     * @throws NullPointerException if the specified element is null and this
385 –     *         deque does not permit null elements
388       * @throws ClassCastException if the class of the specified element
389       *         prevents it from being added to this deque
390 +     * @throws NullPointerException if the specified element is null and this
391 +     *         deque does not permit null elements
392       * @throws IllegalArgumentException if some property of the specified
393       *         element prevents it from being added to this deque
394       */
# Line 393 | 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 418 | 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 455 | Line 459 | public interface Deque<E> extends Queue<
459       * @param e the element to push
460       * @throws IllegalStateException if the element cannot be added at this
461       *         time due to capacity restrictions
458 –     * @throws NullPointerException if the specified element is null and this
459 –     *         deque does not permit null elements
462       * @throws ClassCastException if the class of the specified element
463       *         prevents it from being added to this deque
464 +     * @throws NullPointerException if the specified element is null and this
465 +     *         deque does not permit null elements
466       * @throws IllegalArgumentException if some property of the specified
467       *         element prevents it from being added to this deque
468       */
# Line 483 | Line 487 | public interface Deque<E> extends Queue<
487       * Removes the first occurrence of the specified element from this deque.
488       * If the deque does not contain the element, it is unchanged.
489       * More formally, removes the first element <tt>e</tt> such that
490 <     * <tt>(o==null ? e==null : o.equals(e))</tt> (if such an element exists).
491 <     * Returns true if this deque contained the specified element (or
492 <     * equivalently, if this deque changed as a result of the call).
490 >     * <tt>(o==null&nbsp;?&nbsp;e==null&nbsp;:&nbsp;o.equals(e))</tt>
491 >     * (if such an element exists).
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       *
497       * @param o element to be removed from this deque, if present
498       * @return <tt>true</tt> if an element was removed as a result of this call
499 +     * @throws ClassCastException if the class of the specified element
500 +     *         is incompatible with this deque (optional)
501       * @throws NullPointerException if the specified element is null and this
502       *         deque does not permit null elements (optional)
496 –     * @throws ClassCastException if the class of the specified element
497 –     *         is incompatible with this collection (optional)
503       */
504      boolean remove(Object o);
505  
506      /**
507       * Returns <tt>true</tt> if this deque contains the specified element.
508 <     * More formally, returns <tt>true</tt> if and only if this deque
509 <     * contains at least one element <tt>e</tt> such that <tt>(o==null ?
510 <     * e==null : o.equals(e))</tt>.
508 >     * More formally, returns <tt>true</tt> if and only if this deque contains
509 >     * at least one element <tt>e</tt> such that
510 >     * <tt>(o==null&nbsp;?&nbsp;e==null&nbsp;:&nbsp;o.equals(e))</tt>.
511       *
512       * @param o element whose presence in this deque is to be tested
513       * @return <tt>true</tt> if this deque contains the specified element
# Line 521 | 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