ViewVC Help

View File | Revision Log | Show Annotations | Download File | Root Listing

root/jsr166/jsr166/src/main/java/util/Deque.java

Comparing jsr166/src/main/java/util/Deque.java (file contents):
Revision 1.2 by dl, Tue Mar 8 12:27:06 2005 UTC vs.
Revision 1.7 by jsr166, Mon May 2 17:34:02 2005 UTC

#	Line 24 | Line 24 | package java.util;
24		* <tt>Deque</tt> implementations; in most implementations, insert
25		* operations cannot fail.
26		*
27	<	* <p>The twelve methods described above are summarized in the
28	<	* following table:<p>
29	<	*
27	>	* <p>The twelve methods described above are summarized in the
28	>	* following table:
29	>	*
30	>	* <p>
31		* <table BORDER CELLPADDING=3 CELLSPACING=1>
32		*  <tr>
33		*    <td></td>
#	Line 65 | Line 66 | package java.util;
66		*
67		* <p>This interface extends the {@link Queue} interface.  When a deque is
68		* used as a queue, FIFO (First-In-First-Out) behavior results.  Elements are
69	<	* added to the end of the deque and removed from the beginning.  The methods
69	>	* added at the end of the deque and removed from the beginning.  The methods
70		* inherited from the <tt>Queue</tt> interface are precisely equivalent to
71	<	* <tt>Deque</tt> methods as indicated in the following table:<p>
71	>	* <tt>Deque</tt> methods as indicated in the following table:
72		*
73	+	* <p>
74		* <table BORDER CELLPADDING=3 CELLSPACING=1>
75		*  <tr>
76		*    <td ALIGN=CENTER> <b><tt>Queue</tt> Method</b></td>
77		*    <td ALIGN=CENTER> <b>Equivalent <tt>Deque</tt> Method</b></td>
78		*  </tr>
79		*  <tr>
78	–	*   <tr>
80		*    <td>{@link java.util.Queue#offer offer(e)}</td>
81		*    <td>{@link #offerLast offerLast(e)}</td>
82	<	*   </tr>
83	<	*   <tr>
82	>	*  </tr>
83	>	*  <tr>
84		*    <td>{@link java.util.Queue#add add(e)}</td>
85		*    <td>{@link #addLast addLast(e)}</td>
86	<	*   </tr>
87	<	*   <tr>
86	>	*  </tr>
87	>	*  <tr>
88		*    <td>{@link java.util.Queue#poll poll()}</td>
89		*    <td>{@link #pollFirst pollFirst()}</td>
90	<	*   </tr>
91	<	*   <tr>
90	>	*  </tr>
91	>	*  <tr>
92		*    <td>{@link java.util.Queue#remove remove()}</td>
93		*    <td>{@link #removeFirst removeFirst()}</td>
94	<	*   </tr>
95	<	*   <tr>
94	>	*  </tr>
95	>	*  <tr>
96		*    <td>{@link java.util.Queue#peek peek()}</td>
97		*    <td>{@link #peek peekFirst()}</td>
98	<	*   </tr>
99	<	*   <tr>
98	>	*  </tr>
99	>	*  <tr>
100		*    <td>{@link java.util.Queue#element element()}</td>
101		*    <td>{@link #getFirst getFirst()}</td>
102	<	*   </tr>
102	>	*  </tr>
103		* </table>
104		*
105		* <p>Deques can also be used as LIFO (Last-In-First-Out) stacks.  This
106		* interface should be used in preference to the legacy {@link Stack} class.
107	<	* When a dequeue is used as a stack, elements are pushed and popped from the
107	>	* When a deque is used as a stack, elements are pushed and popped from the
108		* beginning of the deque.  Stack methods are precisely equivalent to
109	<	* <tt>Deque</tt> methods as indicated in the table below:<p>
109	>	* <tt>Deque</tt> methods as indicated in the table below:
110		*
111	+	* <p>
112		* <table BORDER CELLPADDING=3 CELLSPACING=1>
113		*  <tr>
114		*    <td ALIGN=CENTER> <b>Stack Method</b></td>
115		*    <td ALIGN=CENTER> <b>Equivalent <tt>Deque</tt> Method</b></td>
116		*  </tr>
117		*  <tr>
116	–	*   <tr>
118		*    <td>{@link #push push(e)}</td>
119		*    <td>{@link #addFirst addFirst(e)}</td>
120	<	*   </tr>
121	<	*   <tr>
120	>	*  </tr>
121	>	*  <tr>
122		*    <td>{@link #pop pop()}</td>
123		*    <td>{@link #removeFirst removeFirst()}</td>
124	<	*   </tr>
125	<	*   <tr>
124	>	*  </tr>
125	>	*  <tr>
126		*    <td>{@link #peek peek()}</td>
127		*    <td>{@link #peekFirst peekFirst()}</td>
128	<	*   </tr>
128	>	*  </tr>
129		* </table>
130		*
131		* <p>Note that the {@link #peek peek} method works equally well when
#	Line 144 | Line 145 | package java.util;
145		* take advantage of the ability to insert nulls.  This is so because
146		* <tt>null</tt> is used as a special return value by various methods
147		* to indicated that the deque is empty.
148	<	*
148	>	*
149		* <p><tt>Deque</tt> implementations generally do not define
150		* element-based versions of the <tt>equals</tt> and <tt>hashCode</tt>
151		* methods, but instead inherit the identity-based versions from class
#	Line 162 | Line 163 | package java.util;
163
164		public interface Deque<E> extends Queue<E> {
165		/**
166	<	* Inserts the specified element to the front this deque unless it would
166	>	* Inserts the specified element at the front of this deque unless it would
167		* violate capacity restrictions.  When using a capacity-restricted deque,
168		* this method is generally preferable to method <tt>addFirst</tt>, which
169		* can fail to insert an element only by throwing an exception.
#	Line 170 | Line 171 | public interface Deque<E> extends Queue<
171		* @param e the element to insert
172		* @return <tt>true</tt> if it was possible to insert the element,
173		*     else <tt>false</tt>
174	<	* @throws NullPointerException if <tt>e</tt> is null and this
174	>	* @throws NullPointerException if the specified element is null and this
175		*     deque does not permit null elements
176		*/
177		boolean offerFirst(E e);
178
179		/**
180	<	* Inserts the specified element to the end of this deque unless it would
180	>	* Inserts the specified element at the end of this deque unless it would
181		* violate capacity restrictions.  When using a capacity-restricted deque,
182		* this method is generally preferable to method <tt>addLast</tt> which
183		* can fail to insert an element only by throwing an exception.
#	Line 184 | Line 185 | public interface Deque<E> extends Queue<
185		* @param e the element to insert
186		* @return <tt>true</tt> if it was possible to insert the element,
187		*     else <tt>false</tt>
188	<	* @throws NullPointerException if <tt>e</tt> is null and this
188	>	* @throws NullPointerException if the specified element is null and this
189		*     deque does not permit null elements
190		*/
191		boolean offerLast(E e);
192
193		/**
194	<	* Inserts the specified element to the front of this deque unless it
194	>	* Inserts the specified element at the front of this deque unless it
195		* would violate capacity restrictions.
196		*
197		* @param e the element to insert
198		* @throws IllegalStateException if it was not possible to insert
199		*    the element due to capacity restrictions
200	<	* @throws NullPointerException if <tt>e</tt> is null and this
200	>	* @throws NullPointerException if the specified element is null and this
201		*     deque does not permit null elements
202		*/
203		void addFirst(E e);
204
205		/**
206	<	* Inserts the specified element to the end of this deque unless it would
206	>	* Inserts the specified element at the end of this deque unless it would
207		* violate capacity restrictions.
208		*
209		* @param e the element to insert
210		* @throws IllegalStateException if it was not possible to insert
211		*    the element due to capacity restrictions
212	<	* @throws NullPointerException if <tt>e</tt> is null and this
212	>	* @throws NullPointerException if the specified element is null and this
213		*     deque does not permit null elements
214		*/
215		void addLast(E e);
#	Line 232 | Line 233 | public interface Deque<E> extends Queue<
233		E pollLast();
234
235		/**
236	<	* Removes and returns the first element of this deque.  This method
237	<	* differs from the <tt>pollFirst</tt> method only in that it throws an
236	>	* Retrieves and removes the first element of this deque.  This method
237	>	* differs from the {@link #pollFirst} method only in that it throws an
238		* exception if this deque is empty.
239		*
240		* @return the first element of this deque
#	Line 243 | Line 244 | public interface Deque<E> extends Queue<
244
245		/**
246		* Retrieves and removes the last element of this deque.  This method
247	<	* differs from the <tt>pollLast</tt> method only in that it throws an
247	>	* differs from the {@link #pollLast} method only in that it throws an
248		* exception if this deque is empty.
249		*
250		* @return the last element of this deque
#	Line 271 | Line 272 | public interface Deque<E> extends Queue<
272
273		/**
274		* Retrieves, but does not remove, the first element of this
275	<	* deque.  This method differs from the <tt>peek</tt> method only
275	>	* deque.  This method differs from the {@link #peekFirst} method only
276		* in that it throws an exception if this deque is empty.
277		*
278		* @return the first element of this deque
#	Line 281 | Line 282 | public interface Deque<E> extends Queue<
282
283		/**
284		* Retrieves, but does not remove, the last element of this
285	<	* deque.  This method differs from the <tt>peek</tt> method only
285	>	* deque.  This method differs from the {@link #peekLast} method only
286		* in that it throws an exception if this deque is empty.
287		*
288		* @return the last element of this deque
#	Line 296 | Line 297 | public interface Deque<E> extends Queue<
297		* such that <tt>(o==null ? e==null : o.equals(e))</tt> (if
298		* such an element exists).
299		*
300	<	* @param e element to be removed from this deque, if present
300	>	* @param o element to be removed from this deque, if present
301		* @return <tt>true</tt> if the deque contained the specified element
302	<	* @throws NullPointerException if the specified element is <tt>null</tt>
302	>	* @throws NullPointerException if the specified element is null and this
303	>	*     deque does not permit null elements
304		*/
305	<	boolean removeFirstOccurrence(Object e);
305	>	boolean removeFirstOccurrence(Object o);
306
307		/**
308		* Removes the last occurrence of the specified element in this
#	Line 309 | Line 311 | public interface Deque<E> extends Queue<
311		* such that <tt>(o==null ? e==null : o.equals(e))</tt> (if
312		* such an element exists).
313		*
314	<	* @param e element to be removed from this deque, if present
314	>	* @param o element to be removed from this deque, if present
315		* @return <tt>true</tt> if the deque contained the specified element
316	<	* @throws NullPointerException if the specified element is <tt>null</tt>
316	>	* @throws NullPointerException if the specified element is null and this
317	>	*     deque does not permit null elements
318		*/
319	<	boolean removeLastOccurrence(Object e);
319	>	boolean removeLastOccurrence(Object o);
320
321
322		// *** Queue methods ***
#	Line 321 | Line 324 | public interface Deque<E> extends Queue<
324		/**
325		* Inserts the specified element into the queue represented by this deque
326		* unless it would violate capacity restrictions.  In other words, inserts
327	<	* the specified element to the end of this deque.  When using a
327	>	* the specified element at the end of this deque.  When using a
328		* capacity-restricted deque, this method is generally preferable to the
329		* {@link #add} method, which can fail to insert an element only by
330		* throwing an exception.
#	Line 331 | Line 334 | public interface Deque<E> extends Queue<
334		* @param e the element to insert
335		* @return <tt>true</tt> if it was possible to insert the element,
336		*     else <tt>false</tt>
337	<	* @throws NullPointerException if <tt>e</tt> is null and this
337	>	* @throws NullPointerException if the specified element is null and this
338		*     deque does not permit null elements
339		*/
340		boolean offer(E e);
#	Line 339 | Line 342 | public interface Deque<E> extends Queue<
342		/**
343		* Inserts the specified element into the queue represented by this
344		* deque unless it would violate capacity restrictions.  In other words,
345	<	* inserts the specified element as the last element of this deque.
345	>	* inserts the specified element as the last element of this deque.
346		*
347		* <p>This method is equivalent to {@link #addLast}.
348		*
#	Line 347 | Line 350 | public interface Deque<E> extends Queue<
350		* @return <tt>true</tt> (as per the spec for {@link Collection#add})
351		* @throws IllegalStateException if it was not possible to insert
352		*    the element due to capacity restrictions
353	<	* @throws NullPointerException if <tt>e</tt> is null and this
353	>	* @throws NullPointerException if the specified element is null and this
354		*     deque does not permit null elements
355		*/
356		boolean add(E e);
#	Line 367 | Line 370 | public interface Deque<E> extends Queue<
370
371		/**
372		* Retrieves and removes the head of the queue represented by this deque.
373	<	* This method differs from the <tt>poll</tt> method only in that it
373	>	* This method differs from the {@link #poll} method only in that it
374		* throws an exception if this deque is empty.
375		*
376		* <p>This method is equivalent to {@link #removeFirst()}.
#	Line 381 | Line 384 | public interface Deque<E> extends Queue<
384		* Retrieves, but does not remove, the head of the queue represented by
385		* this deque, returning <tt>null</tt> if this deque is empty.
386		*
387	<	* <p>This method is equivalent to {@link #peekFirst()}
387	>	* <p>This method is equivalent to {@link #peekFirst()}.
388		*
389		* @return the head of the queue represented by this deque, or
390		*     <tt>null</tt> if this deque is empty
#	Line 390 | Line 393 | public interface Deque<E> extends Queue<
393
394		/**
395		* Retrieves, but does not remove, the head of the queue represented by
396	<	* this deque.  This method differs from the <tt>peek</tt> method only in
396	>	* this deque.  This method differs from the {@link #peek} method only in
397		* that it throws an exception if this deque is empty.
398		*
399	<	* <p>This method is equivalent to {@link #getFirst()}
399	>	* <p>This method is equivalent to {@link #getFirst()}.
400		*
401		* @return the head of the queue represented by this deque
402		* @throws NoSuchElementException if this deque is empty
#	Line 405 | Line 408 | public interface Deque<E> extends Queue<
408
409		/**
410		* Pushes an element onto the stack represented by this deque.  In other
411	<	* words, inserts the element to the front this deque unless it would
411	>	* words, inserts the element at the front of this deque unless it would
412		* violate capacity restrictions.
413		*
414		* <p>This method is equivalent to {@link #addFirst}.
415		*
416	+	* @param e the element to push
417		* @throws IllegalStateException if it was not possible to insert
418		*    the element due to capacity restrictions
419	<	* @throws NullPointerException if <tt>e</tt> is null and this
419	>	* @throws NullPointerException if the specified element is null and this
420		*     deque does not permit null elements
421		*/
422		void push(E e);
#	Line 435 | Line 439 | public interface Deque<E> extends Queue<
439		/**
440		* Returns an iterator over the elements in this deque.  The elements
441		* will be ordered from first (head) to last (tail).
442	<	*
442	>	*
443		* @return an <tt>Iterator</tt> over the elements in this deque
444		*/
445		Iterator<E> iterator();

Diff Legend

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