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.20 by jsr166, Tue Mar 15 19:47:02 2011 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 172 | Line 172 | public interface Deque<E> extends Queue<
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 –     * @throws NullPointerException if the specified element is null and this
176 –     *         deque does not permit null elements
175       * @throws ClassCastException if the class of the specified element
176       *         prevents it from being added to this deque
177 +     * @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 <     * Inserts the specified element at the end of this deque  if it is
185 >     * Inserts the specified element at the end of this deque if it is
186       * possible to do so immediately without violating capacity restrictions.
187       * When using a capacity-restricted deque, it is generally preferable to
188       * use method {@link #offerLast}.
189       *
190 +     * <p>This method is equivalent to {@link #add}.
191 +     *
192       * @param e the element to add
193       * @throws IllegalStateException if the element cannot be added at this
194       *         time due to capacity restrictions
193 –     * @throws NullPointerException if the specified element is null and this
194 –     *         deque does not permit null elements
195       * @throws ClassCastException if the class of the specified element
196       *         prevents it from being added to this deque
197 +     * @throws NullPointerException if the specified element is null and this
198 +     *         deque does not permit null elements
199       * @throws IllegalArgumentException if some property of the specified
200       *         element prevents it from being added to this deque
201       */
# Line 206 | Line 208 | public interface Deque<E> extends Queue<
208       * which can fail to insert an element only by throwing an exception.
209       *
210       * @param e the element to add
211 <     * @return <tt>true</tt> if it was possible to insert the element,
212 <     *         else <tt>false</tt>
211 <     * @throws NullPointerException if the specified element is null and this
212 <     *         deque does not permit null elements
211 >     * @return <tt>true</tt> if the element was added to this deque, else
212 >     *         <tt>false</tt>
213       * @throws ClassCastException if the class of the specified element
214       *         prevents it from being added to this deque
215 +     * @throws NullPointerException if the specified element is null and this
216 +     *         deque does not permit null elements
217       * @throws IllegalArgumentException if some property of the specified
218       *         element prevents it from being added to this deque
219       */
# Line 224 | Line 226 | public interface Deque<E> extends Queue<
226       * which can fail to insert an element only by throwing an exception.
227       *
228       * @param e the element to add
229 <     * @return <tt>true</tt> if it was possible to insert the element,
230 <     *         else <tt>false</tt>
229 <     * @throws NullPointerException if the specified element is null and this
230 <     *         deque does not permit null elements
229 >     * @return <tt>true</tt> if the element was added to this deque, else
230 >     *         <tt>false</tt>
231       * @throws ClassCastException if the class of the specified element
232       *         prevents it from being added to this deque
233 +     * @throws NullPointerException if the specified element is null and this
234 +     *         deque does not permit null elements
235       * @throws IllegalArgumentException if some property of the specified
236       *         element prevents it from being added to this deque
237       */
# Line 237 | Line 239 | public interface Deque<E> extends Queue<
239  
240      /**
241       * Retrieves and removes the first element of this deque.  This method
242 <     * differs from {@link #pollFirst} only in that it throws an exception
243 <     * if this deque is empty.
242 >     * differs from {@link #pollFirst pollFirst} only in that it throws an
243 >     * exception if this deque is empty.
244       *
245       * @return the head of this deque
246       * @throws NoSuchElementException if this deque is empty
# Line 247 | Line 249 | public interface Deque<E> extends Queue<
249  
250      /**
251       * Retrieves and removes the last element of this deque.  This method
252 <     * differs from {@link #pollLast} only in that it throws an exception if
253 <     * this deque is empty.
252 >     * differs from {@link #pollLast pollLast} only in that it throws an
253 >     * exception if this deque is empty.
254       *
255       * @return the tail of this deque
256       * @throws NoSuchElementException if this deque is empty
# Line 273 | Line 275 | public interface Deque<E> extends Queue<
275  
276      /**
277       * Retrieves, but does not remove, the first element of this deque.
278 <     * This method differs from {@link #peekFirst} only in that it throws an
279 <     * exception if this deque is empty.
278 >     *
279 >     * This method differs from {@link #peekFirst peekFirst} only in that it
280 >     * throws an exception if this deque is empty.
281       *
282       * @return the head of this deque
283       * @throws NoSuchElementException if this deque is empty
# Line 283 | Line 286 | public interface Deque<E> extends Queue<
286  
287      /**
288       * Retrieves, but does not remove, the last element of this deque.
289 <     * This method differs from {@link #peekLast} only in that it throws an
290 <     * exception if this deque is empty.
289 >     * This method differs from {@link #peekLast peekLast} only in that it
290 >     * throws an exception if this deque is empty.
291       *
292       * @return the tail of this deque
293       * @throws NoSuchElementException if this deque is empty
# Line 311 | Line 314 | public interface Deque<E> extends Queue<
314       * Removes the first occurrence of the specified element from this deque.
315       * If the deque does not contain the element, it is unchanged.
316       * More formally, removes the first element <tt>e</tt> such that
317 <     * <tt>(o==null ? e==null : o.equals(e))</tt> (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).
317 >     * <tt>(o==null&nbsp;?&nbsp;e==null&nbsp;:&nbsp;o.equals(e))</tt>
318 >     * (if such an element exists).
319 >     * Returns <tt>true</tt> if this deque contained the specified element
320 >     * (or equivalently, if this deque changed as a result of the call).
321       *
322       * @param o element to be removed from this deque, if present
323       * @return <tt>true</tt> if an element was removed as a result of this call
324 +     * @throws ClassCastException if the class of the specified element
325 +     *         is incompatible with this deque (optional)
326       * @throws NullPointerException if the specified element is null and this
327       *         deque does not permit null elements (optional)
322 –     * @throws ClassCastException if the class of the specified element
323 –     *         is incompatible with this collection (optional)
328       */
329      boolean removeFirstOccurrence(Object o);
330  
# Line 328 | Line 332 | public interface Deque<E> extends Queue<
332       * Removes the last occurrence of the specified element from this deque.
333       * If the deque does not contain the element, it is unchanged.
334       * More formally, removes the last element <tt>e</tt> such that
335 <     * <tt>(o==null ? e==null : o.equals(e))</tt> (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).
335 >     * <tt>(o==null&nbsp;?&nbsp;e==null&nbsp;:&nbsp;o.equals(e))</tt>
336 >     * (if such an element exists).
337 >     * Returns <tt>true</tt> if this deque contained the specified element
338 >     * (or equivalently, if this deque changed as a result of the call).
339       *
340       * @param o element to be removed from this deque, if present
341       * @return <tt>true</tt> if an element was removed as a result of this call
342 +     * @throws ClassCastException if the class of the specified element
343 +     *         is incompatible with this deque (optional)
344       * @throws NullPointerException if the specified element is null and this
345       *         deque does not permit null elements (optional)
339 –     * @throws ClassCastException if the class of the specified element
340 –     *         is incompatible with this collection (optional)
346       */
347      boolean removeLastOccurrence(Object o);
348  
# Line 352 | Line 357 | public interface Deque<E> extends Queue<
357       * When using a capacity-restricted deque, it is generally preferable to
358       * use {@link #offer(Object) offer}.
359       *
360 <     * <p>This method is equivalent to {@link #addLast(Object) addLast}.
360 >     * <p>This method is equivalent to {@link #addLast}.
361       *
362       * @param e the element to add
363 <     * @return <tt>true</tt> (as per the spec for {@link Collection#add})
363 >     * @return <tt>true</tt> (as specified by {@link Collection#add})
364       * @throws IllegalStateException if the element cannot be added at this
365       *         time due to capacity restrictions
361 –     * @throws NullPointerException if the specified element is null and this
362 –     *         deque does not permit null elements
366       * @throws ClassCastException if the class of the specified element
367       *         prevents it from being added to this deque
368 +     * @throws NullPointerException if the specified element is null and this
369 +     *         deque does not permit null elements
370       * @throws IllegalArgumentException if some property of the specified
371       *         element prevents it from being added to this deque
372       */
# Line 381 | Line 386 | public interface Deque<E> extends Queue<
386       * @param e the element to add
387       * @return <tt>true</tt> if the element was added to this deque, else
388       *         <tt>false</tt>
384 –     * @throws NullPointerException if the specified element is null and this
385 –     *         deque does not permit null elements
389       * @throws ClassCastException if the class of the specified element
390       *         prevents it from being added to this deque
391 +     * @throws NullPointerException if the specified element is null and this
392 +     *         deque does not permit null elements
393       * @throws IllegalArgumentException if some property of the specified
394       *         element prevents it from being added to this deque
395       */
# Line 393 | Line 398 | public interface Deque<E> extends Queue<
398      /**
399       * Retrieves and removes the head of the queue represented by this deque
400       * (in other words, the first element of this deque).
401 <     * This method differs from {@link #poll} only in that it throws an
401 >     * This method differs from {@link #poll poll} only in that it throws an
402       * exception if this deque is empty.
403       *
404       * <p>This method is equivalent to {@link #removeFirst()}.
# Line 418 | Line 423 | public interface Deque<E> extends Queue<
423      /**
424       * Retrieves, but does not remove, the head of the queue represented by
425       * this deque (in other words, the first element of this deque).
426 <     * This method differs from {@link #peek} only in that it throws an
426 >     * This method differs from {@link #peek peek} only in that it throws an
427       * exception if this deque is empty.
428       *
429       * <p>This method is equivalent to {@link #getFirst()}.
# Line 455 | Line 460 | public interface Deque<E> extends Queue<
460       * @param e the element to push
461       * @throws IllegalStateException if the element cannot be added at this
462       *         time due to capacity restrictions
458 –     * @throws NullPointerException if the specified element is null and this
459 –     *         deque does not permit null elements
463       * @throws ClassCastException if the class of the specified element
464       *         prevents it from being added to this deque
465 +     * @throws NullPointerException if the specified element is null and this
466 +     *         deque does not permit null elements
467       * @throws IllegalArgumentException if some property of the specified
468       *         element prevents it from being added to this deque
469       */
# Line 483 | Line 488 | public interface Deque<E> extends Queue<
488       * Removes the first occurrence of the specified element from this deque.
489       * If the deque does not contain the element, it is unchanged.
490       * More formally, removes the first element <tt>e</tt> such that
491 <     * <tt>(o==null ? e==null : o.equals(e))</tt> (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).
491 >     * <tt>(o==null&nbsp;?&nbsp;e==null&nbsp;:&nbsp;o.equals(e))</tt>
492 >     * (if such an element exists).
493 >     * Returns <tt>true</tt> if this deque contained the specified element
494 >     * (or equivalently, if this deque changed as a result of the call).
495       *
496       * <p>This method is equivalent to {@link #removeFirstOccurrence}.
497       *
498       * @param o element to be removed from this deque, if present
499       * @return <tt>true</tt> if an element was removed as a result of this call
500 +     * @throws ClassCastException if the class of the specified element
501 +     *         is incompatible with this deque (optional)
502       * @throws NullPointerException if the specified element is null and this
503       *         deque does not permit null elements (optional)
496 –     * @throws ClassCastException if the class of the specified element
497 –     *         is incompatible with this collection (optional)
504       */
505      boolean remove(Object o);
506  
507      /**
508       * Returns <tt>true</tt> if this deque contains the specified element.
509 <     * More formally, returns <tt>true</tt> if and only if this deque
510 <     * contains at least one element <tt>e</tt> such that <tt>(o==null ?
511 <     * e==null : o.equals(e))</tt>.
509 >     * More formally, returns <tt>true</tt> if and only if this deque contains
510 >     * at least one element <tt>e</tt> such that
511 >     * <tt>(o==null&nbsp;?&nbsp;e==null&nbsp;:&nbsp;o.equals(e))</tt>.
512       *
513       * @param o element whose presence in this deque is to be tested
514       * @return <tt>true</tt> if this deque contains the specified element
# Line 521 | Line 527 | public interface Deque<E> extends Queue<
527      public int size();
528  
529      /**
530 <     * Returns an iterator over the elements in this deque.  The elements
531 <     * will be ordered from first (head) to last (tail).
530 >     * Returns an iterator over the elements in this deque in proper sequence.
531 >     * The elements will be returned in order from first (head) to last (tail).
532       *
533 <     * @return an <tt>Iterator</tt> over the elements in this deque
533 >     * @return an iterator over the elements in this deque in proper sequence
534       */
535      Iterator<E> iterator();
536 +
537 +    /**
538 +     * Returns an iterator over the elements in this deque in reverse
539 +     * sequential order.  The elements will be returned in order from
540 +     * last (tail) to first (head).
541 +     *
542 +     * @return an iterator over the elements in this deque in reverse
543 +     * sequence
544 +     */
545 +    Iterator<E> descendingIterator();
546 +
547   }

Diff Legend

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