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.17 by dl, Wed Sep 14 23:49:59 2005 UTC

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

Diff Legend

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