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

Diff Legend

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