[cvs] / jsr166 / src / main / java / util / Deque.java Repository:
ViewVC logotype

Diff of /jsr166/src/main/java/util/Deque.java

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.7, Mon May 2 17:34:02 2005 UTC revision 1.8, Sat May 14 02:22:28 2005 UTC
# Line 37  Line 37 
37   *  <tr>   *  <tr>
38   *    <td></td>   *    <td></td>
39   *    <td ALIGN=CENTER><em>Throws exception</em></td>   *    <td ALIGN=CENTER><em>Throws exception</em></td>
40   *    <td ALIGN=CENTER><em>Returns special value</em></td>   *    <td ALIGN=CENTER><em>Special value</em></td>
41   *    <td ALIGN=CENTER><em>Throws exception</em></td>   *    <td ALIGN=CENTER><em>Throws exception</em></td>
42   *    <td ALIGN=CENTER><em>Returns special value</em></td>   *    <td ALIGN=CENTER><em>Special value</em></td>
43   *  </tr>   *  </tr>
44   *  <tr>   *  <tr>
45   *    <td><b>Insert</b></td>   *    <td><b>Insert</b></td>
# Line 77  Line 77 
77   *    <td ALIGN=CENTER> <b>Equivalent <tt>Deque</tt> Method</b></td>   *    <td ALIGN=CENTER> <b>Equivalent <tt>Deque</tt> Method</b></td>
78   *  </tr>   *  </tr>
79   *  <tr>   *  <tr>
  *    <td>{@link java.util.Queue#offer offer(e)}</td>  
  *    <td>{@link #offerLast offerLast(e)}</td>  
  *  </tr>  
  *  <tr>  
80   *    <td>{@link java.util.Queue#add add(e)}</td>   *    <td>{@link java.util.Queue#add add(e)}</td>
81   *    <td>{@link #addLast addLast(e)}</td>   *    <td>{@link #addLast addLast(e)}</td>
82   *  </tr>   *  </tr>
83   *  <tr>   *  <tr>
84   *    <td>{@link java.util.Queue#poll poll()}</td>   *    <td>{@link java.util.Queue#offer offer(e)}</td>
85   *    <td>{@link #pollFirst pollFirst()}</td>   *    <td>{@link #offerLast offerLast(e)}</td>
86   *  </tr>   *  </tr>
87   *  <tr>   *  <tr>
88   *    <td>{@link java.util.Queue#remove remove()}</td>   *    <td>{@link java.util.Queue#remove remove()}</td>
89   *    <td>{@link #removeFirst removeFirst()}</td>   *    <td>{@link #removeFirst removeFirst()}</td>
90   *  </tr>   *  </tr>
91   *  <tr>   *  <tr>
92   *    <td>{@link java.util.Queue#peek peek()}</td>   *    <td>{@link java.util.Queue#poll poll()}</td>
93   *    <td>{@link #peek peekFirst()}</td>   *    <td>{@link #pollFirst pollFirst()}</td>
94   *  </tr>   *  </tr>
95   *  <tr>   *  <tr>
96   *    <td>{@link java.util.Queue#element element()}</td>   *    <td>{@link java.util.Queue#element element()}</td>
97   *    <td>{@link #getFirst getFirst()}</td>   *    <td>{@link #getFirst getFirst()}</td>
98   *  </tr>   *  </tr>
99     *  <tr>
100     *    <td>{@link java.util.Queue#peek peek()}</td>
101     *    <td>{@link #peek peekFirst()}</td>
102     *  </tr>
103   * </table>   * </table>
104   *   *
105   * <p>Deques can also be used as LIFO (Last-In-First-Out) stacks.  This   * <p>Deques can also be used as LIFO (Last-In-First-Out) stacks.  This
# Line 134  Line 134 
134   *   *
135   * <p>This interface provides two methods to remove interior   * <p>This interface provides two methods to remove interior
136   * elements, {@link #removeFirstOccurrence removeFirstOccurrence} and   * elements, {@link #removeFirstOccurrence removeFirstOccurrence} and
137   * {@link #removeLastOccurrence removeLastOccurrence}.  Unlike the   * {@link #removeLastOccurrence removeLastOccurrence}.
138   * {@link List} interface, this interface does not provide support for   *
139   * indexed access to elements.   * <p>Unlike the {@link List} interface, this interface does not
140     * provide support for indexed access to elements.
141   *   *
142   * <p>While <tt>Deque</tt> implementations are not strictly required   * <p>While <tt>Deque</tt> implementations are not strictly required
143   * to prohibit the insertion of null elements, they are strongly   * to prohibit the insertion of null elements, they are strongly
# Line 163  Line 164 
164    
165  public interface Deque<E> extends Queue<E> {  public interface Deque<E> extends Queue<E> {
166      /**      /**
167         * Inserts the specified element at the front of this deque if it is
168         * possible to do so immediately without violating capacity restrictions.
169         * When using a capacity-restricted deque, it is generally preferable to
170         * use method {@link #offerFirst}.
171         *
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
177         * @throws ClassCastException if the class of the specified element
178         *         prevents it from being added to this deque
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
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         * @param e the element to add
191         * @throws IllegalStateException if the element cannot be added at this
192         *         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 IllegalArgumentException if some property of the specified
198         *         element prevents it from being added to this deque
199         */
200        void addLast(E e);
201    
202        /**
203       * Inserts the specified element at the front of this deque unless it would       * Inserts the specified element at the front of this deque unless it would
204       * violate capacity restrictions.  When using a capacity-restricted deque,       * violate capacity restrictions.  When using a capacity-restricted deque,
205       * this method is generally preferable to method <tt>addFirst</tt>, which       * this method is generally preferable to the {@link #addFirst} method,
206       * can fail to insert an element only by throwing an exception.       * which can fail to insert an element only by throwing an exception.
207       *       *
208       * @param e the element to insert       * @param e the element to add
209       * @return <tt>true</tt> if it was possible to insert the element,       * @return <tt>true</tt> if it was possible to insert the element,
210       *     else <tt>false</tt>       *     else <tt>false</tt>
211       * @throws NullPointerException if the specified element is null and this       * @throws NullPointerException if the specified element is null and this
212       *     deque does not permit null elements       *     deque does not permit null elements
213         * @throws ClassCastException if the class of the specified element
214         *         prevents it from being added to this deque
215         * @throws IllegalArgumentException if some property of the specified
216         *         element prevents it from being added to this deque
217       */       */
218      boolean offerFirst(E e);      boolean offerFirst(E e);
219    
220      /**      /**
221       * Inserts the specified element at the end of this deque unless it would       * Inserts the specified element at the end of this deque unless it would
222       * violate capacity restrictions.  When using a capacity-restricted deque,       * violate capacity restrictions.  When using a capacity-restricted deque,
223       * this method is generally preferable to method <tt>addLast</tt> which       * this method is generally preferable to the {@link #addLast} method,
224       * can fail to insert an element only by throwing an exception.       * which can fail to insert an element only by throwing an exception.
225       *       *
226       * @param e the element to insert       * @param e the element to add
227       * @return <tt>true</tt> if it was possible to insert the element,       * @return <tt>true</tt> if it was possible to insert the element,
228       *     else <tt>false</tt>       *     else <tt>false</tt>
229       * @throws NullPointerException if the specified element is null and this       * @throws NullPointerException if the specified element is null and this
230       *     deque does not permit null elements       *     deque does not permit null elements
231         * @throws ClassCastException if the class of the specified element
232         *         prevents it from being added to this deque
233         * @throws IllegalArgumentException if some property of the specified
234         *         element prevents it from being added to this deque
235       */       */
236      boolean offerLast(E e);      boolean offerLast(E e);
237    
238      /**      /**
239       * Inserts the specified element at the front of this deque unless it       * Retrieves and removes the first element of this deque.  This method
240       * would violate capacity restrictions.       * differs from {@link #pollFirst} only in that it throws an exception
241         * if this deque is empty.
242       *       *
243       * @param e the element to insert       * @return the head of this deque
244       * @throws IllegalStateException if it was not possible to insert       * @throws NoSuchElementException if this deque is empty
      *    the element due to capacity restrictions  
      * @throws NullPointerException if the specified element is null and this  
      *     deque does not permit null elements  
245       */       */
246      void addFirst(E e);      E removeFirst();
247    
248      /**      /**
249       * Inserts the specified element at the end of this deque unless it would       * Retrieves and removes the last element of this deque.  This method
250       * violate capacity restrictions.       * differs from {@link #pollLast} only in that it throws an exception if
251         * this deque is empty.
252       *       *
253       * @param e the element to insert       * @return the tail of this deque
254       * @throws IllegalStateException if it was not possible to insert       * @throws NoSuchElementException if this deque is empty
      *    the element due to capacity restrictions  
      * @throws NullPointerException if the specified element is null and this  
      *     deque does not permit null elements  
255       */       */
256      void addLast(E e);      E removeLast();
257    
258      /**      /**
259       * Retrieves and removes the first element of this deque, or       * Retrieves and removes the first element of this deque,
260       * <tt>null</tt> if this deque is empty.       * or returns <tt>null</tt> if this deque is empty.
261       *       *
262       * @return the first element of this deque, or <tt>null</tt> if       * @return the head of this deque, or <tt>null</tt> if this deque is empty
      *     this deque is empty  
263       */       */
264      E pollFirst();      E pollFirst();
265    
266      /**      /**
267       * Retrieves and removes the last element of this deque, or       * Retrieves and removes the last element of this deque,
268       * <tt>null</tt> if this deque is empty.       * or returns <tt>null</tt> if this deque is empty.
269       *       *
270       * @return the last element of this deque, or <tt>null</tt> if       * @return the tail of this deque, or <tt>null</tt> if this deque is empty
      *     this deque is empty  
271       */       */
272      E pollLast();      E pollLast();
273    
274      /**      /**
275       * Retrieves and removes the first element of this deque.  This method       * Retrieves, but does not remove, the first element of this deque.
276       * differs from the {@link #pollFirst} method only in that it throws an       * This method differs from {@link #peekFirst} only in that it throws an
277       * exception if this deque is empty.       * exception if this deque is empty.
278       *       *
279       * @return the first element of this deque       * @return the head of this deque
280       * @throws NoSuchElementException if this deque is empty       * @throws NoSuchElementException if this deque is empty
281       */       */
282      E removeFirst();      E getFirst();
283    
284      /**      /**
285       * Retrieves and removes the last element of this deque.  This method       * Retrieves, but does not remove, the last element of this deque.
286       * differs from the {@link #pollLast} method only in that it throws an       * This method differs from {@link #peekLast} only in that it throws an
287       * exception if this deque is empty.       * exception if this deque is empty.
288       *       *
289       * @return the last element of this deque       * @return the tail of this deque
290       * @throws NoSuchElementException if this deque is empty       * @throws NoSuchElementException if this deque is empty
291       */       */
292      E removeLast();      E getLast();
293    
294      /**      /**
295       * Retrieves, but does not remove, the first element of this deque,       * Retrieves, but does not remove, the first element of this deque,
296       * returning <tt>null</tt> if this deque is empty.       * or returns <tt>null</tt> if this deque is empty.
297       *       *
298       * @return the first element of this deque, or <tt>null</tt> if       * @return the head of this deque, or <tt>null</tt> if this deque is empty
      *     this deque is empty  
299       */       */
300      E peekFirst();      E peekFirst();
301    
302      /**      /**
303       * Retrieves, but does not remove, the last element of this deque,       * Retrieves, but does not remove, the last element of this deque,
304       * returning <tt>null</tt> if this deque is empty.       * or returns <tt>null</tt> if this deque is empty.
305       *       *
306       * @return the last element of this deque, or <tt>null</tt> if this deque       * @return the tail of this deque, or <tt>null</tt> if this deque is empty
      *     is empty  
307       */       */
308      E peekLast();      E peekLast();
309    
310      /**      /**
311       * Retrieves, but does not remove, the first element of this       * Removes the first occurrence of the specified element from this deque.
312       * deque.  This method differs from the {@link #peekFirst} method only       * If the deque does not contain the element, it is unchanged.
313       * in that it throws an exception if this deque is empty.       * More formally, removes the first element <tt>e</tt> such that
314       *       * <tt>(o==null ? e==null : o.equals(e))</tt> (if such an element exists).
315       * @return the first element of this deque       * Returns true if this deque contained the specified element (or
316       * @throws NoSuchElementException if this deque is empty       * equivalently, if this deque changed as a result of the call).
      */  
     E getFirst();  
   
     /**  
      * Retrieves, but does not remove, the last element of this  
      * deque.  This method differs from the {@link #peekLast} method only  
      * in that it throws an exception if this deque is empty.  
      *  
      * @return the last element of this deque  
      * @throws NoSuchElementException if this deque is empty  
      */  
     E getLast();  
   
     /**  
      * Removes the first occurrence of the specified element in this  
      * deque.  If the deque does not contain the element, it is  
      * unchanged.  More formally, removes the first element <tt>e</tt>  
      * such that <tt>(o==null ? e==null : o.equals(e))</tt> (if  
      * such an element exists).  
317       *       *
318       * @param o element to be removed from this deque, if present       * @param o element to be removed from this deque, if present
319       * @return <tt>true</tt> if the deque contained the specified element       * @return <tt>true</tt> if an element was removed as a result of this call
320       * @throws NullPointerException if the specified element is null and this       * @throws NullPointerException if the specified element is null and this
321       *     deque does not permit null elements       *         deque does not permit null elements (optional)
322         * @throws ClassCastException if the class of the specified element
323         *         is incompatible with this collection (optional)
324       */       */
325      boolean removeFirstOccurrence(Object o);      boolean removeFirstOccurrence(Object o);
326    
327      /**      /**
328       * Removes the last occurrence of the specified element in this       * Removes the last occurrence of the specified element from this deque.
329       * deque.  If the deque does not contain the element, it is       * If the deque does not contain the element, it is unchanged.
330       * unchanged.  More formally, removes the last element <tt>e</tt>       * More formally, removes the last element <tt>e</tt> such that
331       * such that <tt>(o==null ? e==null : o.equals(e))</tt> (if       * <tt>(o==null ? e==null : o.equals(e))</tt> (if such an element exists).
332       * such an element exists).       * Returns true if this deque contained the specified element (or
333         * equivalently, if this deque changed as a result of the call).
334       *       *
335       * @param o element to be removed from this deque, if present       * @param o element to be removed from this deque, if present
336       * @return <tt>true</tt> if the deque contained the specified element       * @return <tt>true</tt> if an element was removed as a result of this call
337       * @throws NullPointerException if the specified element is null and this       * @throws NullPointerException if the specified element is null and this
338       *     deque does not permit null elements       *         deque does not permit null elements (optional)
339         * @throws ClassCastException if the class of the specified element
340         *         is incompatible with this collection (optional)
341       */       */
342      boolean removeLastOccurrence(Object o);      boolean removeLastOccurrence(Object o);
343    
   
344      // *** Queue methods ***      // *** Queue methods ***
345    
346      /**      /**
347       * Inserts the specified element into the queue represented by this deque       * Inserts the specified element into the queue represented by this deque
348       * unless it would violate capacity restrictions.  In other words, inserts       * (in other words, at the tail of this deque) if it is possible to do so
349       * the specified element at the end of this deque.  When using a       * immediately without violating capacity restrictions, returning
350       * capacity-restricted deque, this method is generally preferable to the       * <tt>true</tt> upon success and throwing an
351       * {@link #add} method, which can fail to insert an element only by       * <tt>IllegalStateException</tt> if no space is currently available.
352       * throwing an exception.       * When using a capacity-restricted deque, it is generally preferable to
353         * use {@link #offer(Object) offer}.
354       *       *
355       * <p>This method is equivalent to {@link #offerLast}.       * <p>This method is equivalent to {@link #addLast(Object) addLast}.
356       *       *
357       * @param e the element to insert       * @param e the element to add
358       * @return <tt>true</tt> if it was possible to insert the element,       * @return <tt>true</tt> (as per the spec for {@link Collection#add})
359       *     else <tt>false</tt>       * @throws IllegalStateException if the element cannot be added at this
360         *         time due to capacity restrictions
361       * @throws NullPointerException if the specified element is null and this       * @throws NullPointerException if the specified element is null and this
362       *     deque does not permit null elements       *     deque does not permit null elements
363         * @throws ClassCastException if the class of the specified element
364         *         prevents it from being added to this deque
365         * @throws IllegalArgumentException if some property of the specified
366         *         element prevents it from being added to this deque
367       */       */
368      boolean offer(E e);      boolean add(E e);
369    
370      /**      /**
371       * Inserts the specified element into the queue represented by this       * Inserts the specified element into the queue represented by this deque
372       * deque unless it would violate capacity restrictions.  In other words,       * (in other words, at the tail of this deque) if it is possible to do so
373       * inserts the specified element as the last element of this deque.       * immediately without violating capacity restrictions, returning
374         * <tt>true</tt> upon success and <tt>false</tt> if no space is currently
375         * available.  When using a capacity-restricted deque, this method is
376         * generally preferable to the {@link #add} method, which can fail to
377         * insert an element only by throwing an exception.
378       *       *
379       * <p>This method is equivalent to {@link #addLast}.       * <p>This method is equivalent to {@link #offerLast}.
380       *       *
381       * @param e the element to insert       * @param e the element to add
382       * @return <tt>true</tt> (as per the spec for {@link Collection#add})       * @return <tt>true</tt> if the element was added to this deque, else
383       * @throws IllegalStateException if it was not possible to insert       *         <tt>false</tt>
      *    the element due to capacity restrictions  
384       * @throws NullPointerException if the specified element is null and this       * @throws NullPointerException if the specified element is null and this
385       *     deque does not permit null elements       *     deque does not permit null elements
386         * @throws ClassCastException if the class of the specified element
387         *         prevents it from being added to this deque
388         * @throws IllegalArgumentException if some property of the specified
389         *         element prevents it from being added to this deque
390       */       */
391      boolean add(E e);      boolean offer(E e);
392    
393      /**      /**
394       * Retrieves and removes the head of the queue represented by       * Retrieves and removes the head of the queue represented by this deque
395       * this deque, or <tt>null</tt> if this deque is empty.  In other words,       * (in other words, the first element of this deque).
396       * retrieves and removes the first element of this deque, or <tt>null</tt>       * This method differs from {@link #poll} only in that it throws an
397       * if this deque is empty.       * exception if this deque is empty.
398         *
399         * <p>This method is equivalent to {@link #removeFirst()}.
400         *
401         * @return the head of the queue represented by this deque
402         * @throws NoSuchElementException if this deque is empty
403         */
404        E remove();
405    
406        /**
407         * Retrieves and removes the head of the queue represented by this deque
408         * (in other words, the first element of this deque), or returns
409         * <tt>null</tt> if this deque is empty.
410       *       *
411       * <p>This method is equivalent to {@link #pollFirst()}.       * <p>This method is equivalent to {@link #pollFirst()}.
412       *       *
# Line 369  Line 416 
416      E poll();      E poll();
417    
418      /**      /**
419       * Retrieves and removes the head of the queue represented by this deque.       * Retrieves, but does not remove, the head of the queue represented by
420       * This method differs from the {@link #poll} method only in that it       * this deque (in other words, the first element of this deque).
421       * throws an exception if this deque is empty.       * This method differs from {@link #peek} only in that it throws an
422         * exception if this deque is empty.
423       *       *
424       * <p>This method is equivalent to {@link #removeFirst()}.       * <p>This method is equivalent to {@link #getFirst()}.
425       *       *
426       * @return the head of the queue represented by this deque       * @return the head of the queue represented by this deque
427       * @throws NoSuchElementException if this deque is empty       * @throws NoSuchElementException if this deque is empty
428       */       */
429      E remove();      E element();
430    
431      /**      /**
432       * Retrieves, but does not remove, the head of the queue represented by       * Retrieves, but does not remove, the head of the queue represented by
433       * this deque, returning <tt>null</tt> if this deque is empty.       * this deque (in other words, the first element of this deque), or
434         * returns <tt>null</tt> if this deque is empty.
435       *       *
436       * <p>This method is equivalent to {@link #peekFirst()}.       * <p>This method is equivalent to {@link #peekFirst()}.
437       *       *
# Line 391  Line 440 
440       */       */
441      E peek();      E peek();
442    
     /**  
      * Retrieves, but does not remove, the head of the queue represented by  
      * this deque.  This method differs from the {@link #peek} method only in  
      * that it throws an exception if this deque is empty.  
      *  
      * <p>This method is equivalent to {@link #getFirst()}.  
      *  
      * @return the head of the queue represented by this deque  
      * @throws NoSuchElementException if this deque is empty  
      */  
     E element();  
   
443    
444      // *** Stack methods ***      // *** Stack methods ***
445    
446      /**      /**
447       * Pushes an element onto the stack represented by this deque.  In other       * Pushes an element onto the stack represented by this deque (in other
448       * words, inserts the element at the front of this deque unless it would       * words, at the head of this deque) if it is possible to do so
449       * violate capacity restrictions.       * immediately without violating capacity restrictions, returning
450         * <tt>true</tt> upon success and throwing an
451         * <tt>IllegalStateException</tt> if no space is currently available.
452       *       *
453       * <p>This method is equivalent to {@link #addFirst}.       * <p>This method is equivalent to {@link #addFirst}.
454       *       *
455       * @param e the element to push       * @param e the element to push
456       * @throws IllegalStateException if it was not possible to insert       * @throws IllegalStateException if the element cannot be added at this
457       *    the element due to capacity restrictions       *         time due to capacity restrictions
458       * @throws NullPointerException if the specified element is null and this       * @throws NullPointerException if the specified element is null and this
459       *     deque does not permit null elements       *     deque does not permit null elements
460         * @throws ClassCastException if the class of the specified element
461         *         prevents it from being added to this deque
462         * @throws IllegalArgumentException if some property of the specified
463         *         element prevents it from being added to this deque
464       */       */
465      void push(E e);      void push(E e);
466    
# Line 434  Line 477 
477      E pop();      E pop();
478    
479    
480      // *** Collection Method ***      // *** Collection methods ***
481    
482        /**
483         * Removes the first occurrence of the specified element from this deque.
484         * If the deque does not contain the element, it is unchanged.
485         * More formally, removes the first element <tt>e</tt> such that
486         * <tt>(o==null ? e==null : o.equals(e))</tt> (if such an element exists).
487         * Returns true if this deque contained the specified element (or
488         * equivalently, if this deque changed as a result of the call).
489         *
490         * <p>This method is equivalent to {@link #removeFirstOccurrence}.
491         *
492         * @param o element to be removed from this deque, if present
493         * @return <tt>true</tt> if an element was removed as a result of this call
494         * @throws NullPointerException if the specified element is null and this
495         *         deque does not permit null elements (optional)
496         * @throws ClassCastException if the class of the specified element
497         *         is incompatible with this collection (optional)
498         */
499        boolean remove(Object o);
500    
501        /**
502         * Returns <tt>true</tt> if this deque contains the specified element.
503         * More formally, returns <tt>true</tt> if and only if this deque
504         * contains at least one element <tt>e</tt> such that <tt>(o==null ?
505         * e==null : o.equals(e))</tt>.
506         *
507         * @param o element whose presence in this deque is to be tested
508         * @return <tt>true</tt> if this deque contains the specified element
509         * @throws ClassCastException if the type of the specified element
510         *         is incompatible with this deque (optional)
511         * @throws NullPointerException if the specified element is null and this
512         *         deque does not permit null elements (optional)
513         */
514        boolean contains(Object o);
515    
516        /**
517         * Returns the number of elements in this deque.
518         *
519         * @return the number of elements in this deque
520         */
521        public int size();
522    
523      /**      /**
524       * Returns an iterator over the elements in this deque.  The elements       * Returns an iterator over the elements in this deque.  The elements

Legend:
Removed from v.1.7  
changed lines
  Added in v.1.8

Doug Lea
ViewVC Help
Powered by ViewVC 1.0.8