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.28 by jsr166, Tue Nov 12 23:23:05 2013 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 9 | Line 9 | package java.util;
9		/**
10		* A linear collection that supports element insertion and removal at
11		* both ends.  The name <i>deque</i> is short for "double ended queue"
12	<	* and is usually pronounced "deck".  Most <tt>Deque</tt>
12	>	* and is usually pronounced "deck".  Most {@code Deque}
13		* implementations place no fixed limits on the number of elements
14		* they may contain, but this interface supports capacity-restricted
15		* deques as well as those with no fixed size limit.
#	Line 18 | Line 18 | package java.util;
18		* ends of the deque.  Methods are provided to insert, remove, and
19		* examine the element.  Each of these methods exists in two forms:
20		* one throws an exception if the operation fails, the other returns a
21	<	* special value (either <tt>null</tt> or <tt>false</tt>, depending on
21	>	* special value (either {@code null} or {@code false}, depending on
22		* the operation).  The latter form of the insert operation is
23		* designed specifically for use with capacity-restricted
24	<	* <tt>Deque</tt> implementations; in most implementations, insert
24	>	* {@code Deque} 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		* <table BORDER CELLPADDING=3 CELLSPACING=1>
31	+	* <caption>Summary of Deque methods</caption>
32		*  <tr>
33		*    <td></td>
34		*    <td ALIGN=CENTER COLSPAN = 2> <b>First Element (Head)</b></td>
#	Line 36 | Line 37 | package java.util;
37		*  <tr>
38		*    <td></td>
39		*    <td ALIGN=CENTER><em>Throws exception</em></td>
40	<	*    <td ALIGN=CENTER><em>Returns special value</em></td>
40	>	*    <td ALIGN=CENTER><em>Special value</em></td>
41		*    <td ALIGN=CENTER><em>Throws exception</em></td>
42	<	*    <td ALIGN=CENTER><em>Returns special value</em></td>
42	>	*    <td ALIGN=CENTER><em>Special value</em></td>
43		*  </tr>
44		*  <tr>
45		*    <td><b>Insert</b></td>
46	<	*    <td>{@link #addFirst addFirst(e)}</td>
47	<	*    <td>{@link #offerFirst offerFirst(e)}</td>
48	<	*    <td>{@link #addLast addLast(e)}</td>
49	<	*    <td>{@link #offerLast offerLast(e)}</td>
46	>	*    <td>{@link Deque#addFirst addFirst(e)}</td>
47	>	*    <td>{@link Deque#offerFirst offerFirst(e)}</td>
48	>	*    <td>{@link Deque#addLast addLast(e)}</td>
49	>	*    <td>{@link Deque#offerLast offerLast(e)}</td>
50		*  </tr>
51		*  <tr>
52		*    <td><b>Remove</b></td>
53	<	*    <td>{@link #removeFirst removeFirst()}</td>
54	<	*    <td>{@link #pollFirst pollFirst()}</td>
55	<	*    <td>{@link #removeLast removeLast()}</td>
56	<	*    <td>{@link #pollLast pollLast()}</td>
53	>	*    <td>{@link Deque#removeFirst removeFirst()}</td>
54	>	*    <td>{@link Deque#pollFirst pollFirst()}</td>
55	>	*    <td>{@link Deque#removeLast removeLast()}</td>
56	>	*    <td>{@link Deque#pollLast pollLast()}</td>
57		*  </tr>
58		*  <tr>
59		*    <td><b>Examine</b></td>
60	<	*    <td>{@link #getFirst getFirst()}</td>
61	<	*    <td>{@link #peekFirst peekFirst()}</td>
62	<	*    <td>{@link #getLast getLast()}</td>
63	<	*    <td>{@link #peekLast peekLast()}</td>
60	>	*    <td>{@link Deque#getFirst getFirst()}</td>
61	>	*    <td>{@link Deque#peekFirst peekFirst()}</td>
62	>	*    <td>{@link Deque#getLast getLast()}</td>
63	>	*    <td>{@link Deque#peekLast peekLast()}</td>
64		*  </tr>
65		* </table>
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
70	<	* inherited from the <tt>Queue</tt> interface are precisely equivalent to
71	<	* <tt>Deque</tt> methods as indicated in the following table:<p>
69	>	* added at the end of the deque and removed from the beginning.  The methods
70	>	* inherited from the {@code Queue} interface are precisely equivalent to
71	>	* {@code Deque} methods as indicated in the following table:
72		*
73		* <table BORDER CELLPADDING=3 CELLSPACING=1>
74	+	* <caption>Comparison of Queue and Deque methods</caption>
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>
76	>	*    <td ALIGN=CENTER> <b>{@code Queue} Method</b></td>
77	>	*    <td ALIGN=CENTER> <b>Equivalent {@code Deque} Method</b></td>
78		*  </tr>
79		*  <tr>
78	–	*   <tr>
79	–	*    <td>{@link java.util.Queue#offer offer(e)}</td>
80	–	*    <td>{@link #offerLast offerLast(e)}</td>
81	–	*   </tr>
82	–	*   <tr>
80		*    <td>{@link java.util.Queue#add add(e)}</td>
81		*    <td>{@link #addLast addLast(e)}</td>
82	<	*   </tr>
83	<	*   <tr>
84	<	*    <td>{@link java.util.Queue#poll poll()}</td>
85	<	*    <td>{@link #pollFirst pollFirst()}</td>
86	<	*   </tr>
87	<	*   <tr>
82	>	*  </tr>
83	>	*  <tr>
84	>	*    <td>{@link java.util.Queue#offer offer(e)}</td>
85	>	*    <td>{@link #offerLast offerLast(e)}</td>
86	>	*  </tr>
87	>	*  <tr>
88		*    <td>{@link java.util.Queue#remove remove()}</td>
89		*    <td>{@link #removeFirst removeFirst()}</td>
90	<	*   </tr>
91	<	*   <tr>
92	<	*    <td>{@link java.util.Queue#peek peek()}</td>
93	<	*    <td>{@link #peek peekFirst()}</td>
94	<	*   </tr>
95	<	*   <tr>
90	>	*  </tr>
91	>	*  <tr>
92	>	*    <td>{@link java.util.Queue#poll poll()}</td>
93	>	*    <td>{@link #pollFirst pollFirst()}</td>
94	>	*  </tr>
95	>	*  <tr>
96		*    <td>{@link java.util.Queue#element element()}</td>
97		*    <td>{@link #getFirst getFirst()}</td>
98	<	*   </tr>
98	>	*  </tr>
99	>	*  <tr>
100	>	*    <td>{@link java.util.Queue#peek peek()}</td>
101	>	*    <td>{@link #peek peekFirst()}</td>
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	>	* {@code Deque} methods as indicated in the table below:
110		*
111		* <table BORDER CELLPADDING=3 CELLSPACING=1>
112	+	* <caption>Comparison of Stack and Deque methods</caption>
113		*  <tr>
114		*    <td ALIGN=CENTER> <b>Stack Method</b></td>
115	<	*    <td ALIGN=CENTER> <b>Equivalent <tt>Deque</tt> Method</b></td>
115	>	*    <td ALIGN=CENTER> <b>Equivalent {@code Deque} 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 133 | Line 134 | package java.util;
134		*
135		* <p>This interface provides two methods to remove interior
136		* elements, {@link #removeFirstOccurrence removeFirstOccurrence} and
137	<	* {@link #removeLastOccurrence removeLastOccurrence}.  Unlike the
138	<	* {@link List} interface, this interface does not provide support for
139	<	* indexed access to elements.
137	>	* {@link #removeLastOccurrence removeLastOccurrence}.
138	>	*
139	>	* <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
142	>	* <p>While {@code Deque} implementations are not strictly required
143		* to prohibit the insertion of null elements, they are strongly
144	<	* encouraged to do so.  Users of any <tt>Deque</tt> implementations
144	>	* encouraged to do so.  Users of any {@code Deque} implementations
145		* that do allow null elements are strongly encouraged <i>not</i> to
146		* take advantage of the ability to insert nulls.  This is so because
147	<	* <tt>null</tt> is used as a special return value by various methods
147	>	* {@code null} is used as a special return value by various methods
148		* to indicated that the deque is empty.
149	<	*
150	<	* <p><tt>Deque</tt> implementations generally do not define
151	<	* element-based versions of the <tt>equals</tt> and <tt>hashCode</tt>
149	>	*
150	>	* <p>{@code Deque} implementations generally do not define
151	>	* element-based versions of the {@code equals} and {@code hashCode}
152		* methods, but instead inherit the identity-based versions from class
153	<	* <tt>Object</tt>.
153	>	* {@code Object}.
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 159 | Line 161 | package java.util;
161		* @since  1.6
162		* @param <E> the type of elements held in this collection
163		*/
162	–
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 if it is
167	>	* possible to do so immediately without violating capacity restrictions,
168	>	* throwing an {@code IllegalStateException} if no space is currently
169	>	* available.  When using a capacity-restricted deque, it is generally
170	>	* preferable to 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 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
186	>	* possible to do so immediately without violating capacity restrictions,
187	>	* throwing an {@code IllegalStateException} if no space is currently
188	>	* available.  When using a capacity-restricted deque, it is generally
189	>	* preferable to 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
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	>	*/
203	>	void addLast(E e);
204	>
205	>	/**
206	>	* Inserts the specified element at the front of this deque unless it would
207		* violate capacity restrictions.  When using a capacity-restricted deque,
208	<	* this method is generally preferable to method <tt>addFirst</tt>, which
209	<	* can fail to insert an element only by throwing an exception.
208	>	* this method is generally preferable to the {@link #addFirst} method,
209	>	* which can fail to insert an element only by throwing an exception.
210		*
211	<	* @param e the element to insert
212	<	* @return <tt>true</tt> if it was possible to insert the element,
213	<	*     else <tt>false</tt>
214	<	* @throws NullPointerException if <tt>e</tt> is null and this
215	<	*     deque does not permit null elements
211	>	* @param e the element to add
212	>	* @return {@code true} if the element was added to this deque, else
213	>	*         {@code false}
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		*/
221		boolean offerFirst(E e);
222
223		/**
224	<	* Inserts the specified element to the end of this deque unless it would
224	>	* Inserts the specified element at the end of this deque unless it would
225		* violate capacity restrictions.  When using a capacity-restricted deque,
226	<	* this method is generally preferable to method <tt>addLast</tt> which
227	<	* can fail to insert an element only by throwing an exception.
226	>	* this method is generally preferable to the {@link #addLast} method,
227	>	* which can fail to insert an element only by throwing an exception.
228		*
229	<	* @param e the element to insert
230	<	* @return <tt>true</tt> if it was possible to insert the element,
231	<	*     else <tt>false</tt>
232	<	* @throws NullPointerException if <tt>e</tt> is null and this
233	<	*     deque does not permit null elements
229	>	* @param e the element to add
230	>	* @return {@code true} if the element was added to this deque, else
231	>	*         {@code false}
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		*/
239		boolean offerLast(E e);
240
241		/**
242	<	* Inserts the specified element to the front of this deque unless it
243	<	* would violate capacity restrictions.
242	>	* Retrieves and removes the first element of this deque.  This method
243	>	* differs from {@link #pollFirst pollFirst} only in that it throws an
244	>	* exception if this deque is empty.
245		*
246	<	* @param e the element to insert
247	<	* @throws IllegalStateException if it was not possible to insert
198	<	*    the element due to capacity restrictions
199	<	* @throws NullPointerException if <tt>e</tt> is null and this
200	<	*     deque does not permit null elements
246	>	* @return the head of this deque
247	>	* @throws NoSuchElementException if this deque is empty
248		*/
249	<	void addFirst(E e);
249	>	E removeFirst();
250
251		/**
252	<	* Inserts the specified element to the end of this deque unless it would
253	<	* violate capacity restrictions.
252	>	* Retrieves and removes the last element of this deque.  This method
253	>	* differs from {@link #pollLast pollLast} only in that it throws an
254	>	* exception if this deque is empty.
255		*
256	<	* @param e the element to insert
257	<	* @throws IllegalStateException if it was not possible to insert
210	<	*    the element due to capacity restrictions
211	<	* @throws NullPointerException if <tt>e</tt> is null and this
212	<	*     deque does not permit null elements
256	>	* @return the tail of this deque
257	>	* @throws NoSuchElementException if this deque is empty
258		*/
259	<	void addLast(E e);
259	>	E removeLast();
260
261		/**
262	<	* Retrieves and removes the first element of this deque, or
263	<	* <tt>null</tt> if this deque is empty.
262	>	* Retrieves and removes the first element of this deque,
263	>	* or returns {@code null} if this deque is empty.
264		*
265	<	* @return the first element of this deque, or <tt>null</tt> if
221	<	*     this deque is empty
265	>	* @return the head of this deque, or {@code null} if this deque is empty
266		*/
267		E pollFirst();
268
269		/**
270	<	* Retrieves and removes the last element of this deque, or
271	<	* <tt>null</tt> if this deque is empty.
270	>	* Retrieves and removes the last element of this deque,
271	>	* or returns {@code null} if this deque is empty.
272		*
273	<	* @return the last element of this deque, or <tt>null</tt> if
230	<	*     this deque is empty
273	>	* @return the tail of this deque, or {@code null} if this deque is empty
274		*/
275		E pollLast();
276
277		/**
278	<	* Removes and returns the first element of this deque.  This method
279	<	* differs from the <tt>pollFirst</tt> method only in that it throws an
280	<	* exception if this deque is empty.
278	>	* Retrieves, but does not remove, the first element of this deque.
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 first element of this deque
283	>	* @return the head of this deque
284		* @throws NoSuchElementException if this deque is empty
285		*/
286	<	E removeFirst();
286	>	E getFirst();
287
288		/**
289	<	* Retrieves and removes the last element of this deque.  This method
290	<	* differs from the <tt>pollLast</tt> method only in that it throws an
291	<	* exception if this deque is empty.
289	>	* Retrieves, but does not remove, the last element of this deque.
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 last element of this deque
293	>	* @return the tail of this deque
294		* @throws NoSuchElementException if this deque is empty
295		*/
296	<	E removeLast();
296	>	E getLast();
297
298		/**
299		* Retrieves, but does not remove, the first element of this deque,
300	<	* returning <tt>null</tt> if this deque is empty.
300	>	* or returns {@code null} if this deque is empty.
301		*
302	<	* @return the first element of this deque, or <tt>null</tt> if
259	<	*     this deque is empty
302	>	* @return the head of this deque, or {@code null} if this deque is empty
303		*/
304		E peekFirst();
305
306		/**
307		* Retrieves, but does not remove, the last element of this deque,
308	<	* returning <tt>null</tt> if this deque is empty.
308	>	* or returns {@code null} if this deque is empty.
309		*
310	<	* @return the last element of this deque, or <tt>null</tt> if this deque
268	<	*     is empty
310	>	* @return the tail of this deque, or {@code null} if this deque is empty
311		*/
312		E peekLast();
313
314		/**
315	<	* Retrieves, but does not remove, the first element of this
316	<	* deque.  This method differs from the <tt>peek</tt> method only
317	<	* in that it throws an exception if this deque is empty.
318	<	*
319	<	* @return the first element of this deque
320	<	* @throws NoSuchElementException if this deque is empty
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 {@code e} such that
318	>	* <tt>(o==null&nbsp;?&nbsp;e==null&nbsp;:&nbsp;o.equals(e))</tt>
319	>	* (if such an element exists).
320	>	* Returns {@code true} 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 {@code true} 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
327	>	*         (<a href="../Collection.html#optional-restrictions">optional</a>)
328	>	* @throws NullPointerException if the specified element is null
329	>	*         (<a href="../Collection.html#optional-restrictions">optional</a>)
330	>	*/
331	>	boolean removeFirstOccurrence(Object o);
332	>
333	>	/**
334	>	* Removes the last occurrence of the specified element from this deque.
335	>	* If the deque does not contain the element, it is unchanged.
336	>	* More formally, removes the last element {@code e} such that
337	>	* <tt>(o==null&nbsp;?&nbsp;e==null&nbsp;:&nbsp;o.equals(e))</tt>
338	>	* (if such an element exists).
339	>	* Returns {@code true} if this deque contained the specified element
340	>	* (or equivalently, if this deque changed as a result of the call).
341	>	*
342	>	* @param o element to be removed from this deque, if present
343	>	* @return {@code true} if an element was removed as a result of this call
344	>	* @throws ClassCastException if the class of the specified element
345	>	*         is incompatible with this deque
346	>	*         (<a href="../Collection.html#optional-restrictions">optional</a>)
347	>	* @throws NullPointerException if the specified element is null
348	>	*         (<a href="../Collection.html#optional-restrictions">optional</a>)
349		*/
350	<	E getFirst();
350	>	boolean removeLastOccurrence(Object o);
351
352	<	/**
283	<	* Retrieves, but does not remove, the last element of this
284	<	* deque.  This method differs from the <tt>peek</tt> method only
285	<	* in that it throws an exception if this deque is empty.
286	<	*
287	<	* @return the last element of this deque
288	<	* @throws NoSuchElementException if this deque is empty
289	<	*/
290	<	E getLast();
352	>	// *** Queue methods ***
353
354		/**
355	<	* Removes the first occurrence of the specified element in this
356	<	* deque.  If the deque does not contain the element, it is
357	<	* unchanged.  More formally, removes the first element <tt>e</tt>
358	<	* such that <tt>(o==null ? e==null : o.equals(e))</tt> (if
359	<	* such an element exists).
360	<	*
361	<	* @param e element to be removed from this deque, if present
362	<	* @return <tt>true</tt> if the deque contained the specified element
363	<	* @throws NullPointerException if the specified element is <tt>null</tt>
364	<	*/
365	<	boolean removeFirstOccurrence(Object e);
366	<
367	<	/**
368	<	* Removes the last occurrence of the specified element in this
369	<	* deque.  If the deque does not contain the element, it is
370	<	* unchanged.  More formally, removes the last element <tt>e</tt>
371	<	* such that <tt>(o==null ? e==null : o.equals(e))</tt> (if
372	<	* such an element exists).
373	<	*
374	<	* @param e element to be removed from this deque, if present
313	<	* @return <tt>true</tt> if the deque contained the specified element
314	<	* @throws NullPointerException if the specified element is <tt>null</tt>
355	>	* Inserts the specified element into the queue represented by this deque
356	>	* (in other words, at the tail of this deque) if it is possible to do so
357	>	* immediately without violating capacity restrictions, returning
358	>	* {@code true} upon success and throwing an
359	>	* {@code IllegalStateException} if no space is currently available.
360	>	* When using a capacity-restricted deque, it is generally preferable to
361	>	* use {@link #offer(Object) offer}.
362	>	*
363	>	* <p>This method is equivalent to {@link #addLast}.
364	>	*
365	>	* @param e the element to add
366	>	* @return {@code true} (as specified by {@link Collection#add})
367	>	* @throws IllegalStateException if the element cannot be added at this
368	>	*         time due to capacity restrictions
369	>	* @throws ClassCastException if the class of the specified element
370	>	*         prevents it from being added to this deque
371	>	* @throws NullPointerException if the specified element is null and this
372	>	*         deque does not permit null elements
373	>	* @throws IllegalArgumentException if some property of the specified
374	>	*         element prevents it from being added to this deque
375		*/
376	<	boolean removeLastOccurrence(Object e);
317	<
318	<
319	<	// *** Queue methods ***
376	>	boolean add(E e);
377
378		/**
379		* Inserts the specified element into the queue represented by this deque
380	<	* unless it would violate capacity restrictions.  In other words, inserts
381	<	* the specified element to the end of this deque.  When using a
382	<	* capacity-restricted deque, this method is generally preferable to the
383	<	* {@link #add} method, which can fail to insert an element only by
384	<	* throwing an exception.
380	>	* (in other words, at the tail of this deque) if it is possible to do so
381	>	* immediately without violating capacity restrictions, returning
382	>	* {@code true} upon success and {@code false} if no space is currently
383	>	* available.  When using a capacity-restricted deque, this method is
384	>	* generally preferable to the {@link #add} method, which can fail to
385	>	* insert an element only by throwing an exception.
386		*
387		* <p>This method is equivalent to {@link #offerLast}.
388		*
389	<	* @param e the element to insert
390	<	* @return <tt>true</tt> if it was possible to insert the element,
391	<	*     else <tt>false</tt>
392	<	* @throws NullPointerException if <tt>e</tt> is null and this
393	<	*     deque does not permit null elements
389	>	* @param e the element to add
390	>	* @return {@code true} if the element was added to this deque, else
391	>	*         {@code false}
392	>	* @throws ClassCastException if the class of the specified element
393	>	*         prevents it from being added to this deque
394	>	* @throws NullPointerException if the specified element is null and this
395	>	*         deque does not permit null elements
396	>	* @throws IllegalArgumentException if some property of the specified
397	>	*         element prevents it from being added to this deque
398		*/
399		boolean offer(E e);
400
401		/**
402	<	* Inserts the specified element into the queue represented by this
403	<	* deque unless it would violate capacity restrictions.  In other words,
404	<	* inserts the specified element as the last element of this deque.
402	>	* Retrieves and removes the head of the queue represented by this deque
403	>	* (in other words, the first element of this deque).
404	>	* This method differs from {@link #poll poll} only in that it throws an
405	>	* exception if this deque is empty.
406		*
407	<	* <p>This method is equivalent to {@link #addLast}.
407	>	* <p>This method is equivalent to {@link #removeFirst()}.
408		*
409	<	* @param e the element to insert
410	<	* @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
351	<	*     deque does not permit null elements
409	>	* @return the head of the queue represented by this deque
410	>	* @throws NoSuchElementException if this deque is empty
411		*/
412	<	boolean add(E e);
412	>	E remove();
413
414		/**
415	<	* Retrieves and removes the head of the queue represented by
416	<	* this deque, or <tt>null</tt> if this deque is empty.  In other words,
417	<	* retrieves and removes the first element of this deque, or <tt>null</tt>
359	<	* if this deque is empty.
415	>	* Retrieves and removes the head of the queue represented by this deque
416	>	* (in other words, the first element of this deque), or returns
417	>	* {@code null} if this deque is empty.
418		*
419		* <p>This method is equivalent to {@link #pollFirst()}.
420		*
421	<	* @return the first element of this deque, or <tt>null</tt> if
422	<	*     this deque is empty
421	>	* @return the first element of this deque, or {@code null} if
422	>	*         this deque is empty
423		*/
424		E poll();
425
426		/**
427	<	* Retrieves and removes the head of the queue represented by this deque.
428	<	* This method differs from the <tt>poll</tt> method only in that it
429	<	* throws an exception if this deque is empty.
427	>	* Retrieves, but does not remove, the head of the queue represented by
428	>	* this deque (in other words, the first element of this deque).
429	>	* This method differs from {@link #peek peek} only in that it throws an
430	>	* exception if this deque is empty.
431		*
432	<	* <p>This method is equivalent to {@link #removeFirst()}.
432	>	* <p>This method is equivalent to {@link #getFirst()}.
433		*
434		* @return the head of the queue represented by this deque
435		* @throws NoSuchElementException if this deque is empty
436		*/
437	<	E remove();
437	>	E element();
438
439		/**
440		* Retrieves, but does not remove, the head of the queue represented by
441	<	* this deque, returning <tt>null</tt> if this deque is empty.
441	>	* this deque (in other words, the first element of this deque), or
442	>	* returns {@code null} if this deque is empty.
443		*
444	<	* <p>This method is equivalent to {@link #peekFirst()}
444	>	* <p>This method is equivalent to {@link #peekFirst()}.
445		*
446		* @return the head of the queue represented by this deque, or
447	<	*     <tt>null</tt> if this deque is empty
447	>	*         {@code null} if this deque is empty
448		*/
449		E peek();
450
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
394	–	* that it throws an exception if this deque is empty.
395	–	*
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
400	–	*/
401	–	E element();
402	–
451
452		// *** Stack methods ***
453
454		/**
455	<	* Pushes an element onto the stack represented by this deque.  In other
456	<	* words, inserts the element to the front this deque unless it would
457	<	* violate capacity restrictions.
455	>	* Pushes an element onto the stack represented by this deque (in other
456	>	* words, at the head of this deque) if it is possible to do so
457	>	* immediately without violating capacity restrictions, throwing an
458	>	* {@code IllegalStateException} if no space is currently available.
459		*
460		* <p>This method is equivalent to {@link #addFirst}.
461		*
462	<	* @throws IllegalStateException if it was not possible to insert
463	<	*    the element due to capacity restrictions
464	<	* @throws NullPointerException if <tt>e</tt> is null and this
465	<	*     deque does not permit null elements
462	>	* @param e the element to push
463	>	* @throws IllegalStateException if the element cannot be added at this
464	>	*         time due to capacity restrictions
465	>	* @throws ClassCastException if the class of the specified element
466	>	*         prevents it from being added to this deque
467	>	* @throws NullPointerException if the specified element is null and this
468	>	*         deque does not permit null elements
469	>	* @throws IllegalArgumentException if some property of the specified
470	>	*         element prevents it from being added to this deque
471		*/
472		void push(E e);
473
#	Line 424 | Line 478 | public interface Deque<E> extends Queue<
478		* <p>This method is equivalent to {@link #removeFirst()}.
479		*
480		* @return the element at the front of this deque (which is the top
481	<	*     of the stack represented by this deque)
481	>	*         of the stack represented by this deque)
482		* @throws NoSuchElementException if this deque is empty
483		*/
484		E pop();
485
486
487	<	// *** Collection Method ***
487	>	// *** Collection methods ***
488
489		/**
490	<	* Returns an iterator over the elements in this deque.  The elements
491	<	* will be ordered from first (head) to last (tail).
492	<	*
493	<	* @return an <tt>Iterator</tt> over the elements in this deque
490	>	* Removes the first occurrence of the specified element from this deque.
491	>	* If the deque does not contain the element, it is unchanged.
492	>	* More formally, removes the first element {@code e} such that
493	>	* <tt>(o==null&nbsp;?&nbsp;e==null&nbsp;:&nbsp;o.equals(e))</tt>
494	>	* (if such an element exists).
495	>	* Returns {@code true} if this deque contained the specified element
496	>	* (or equivalently, if this deque changed as a result of the call).
497	>	*
498	>	* <p>This method is equivalent to {@link #removeFirstOccurrence(Object)}.
499	>	*
500	>	* @param o element to be removed from this deque, if present
501	>	* @return {@code true} if an element was removed as a result of this call
502	>	* @throws ClassCastException if the class of the specified element
503	>	*         is incompatible with this deque
504	>	*         (<a href="../Collection.html#optional-restrictions">optional</a>)
505	>	* @throws NullPointerException if the specified element is null
506	>	*         (<a href="../Collection.html#optional-restrictions">optional</a>)
507	>	*/
508	>	boolean remove(Object o);
509	>
510	>	/**
511	>	* Returns {@code true} if this deque contains the specified element.
512	>	* More formally, returns {@code true} if and only if this deque contains
513	>	* at least one element {@code e} such that
514	>	* <tt>(o==null&nbsp;?&nbsp;e==null&nbsp;:&nbsp;o.equals(e))</tt>.
515	>	*
516	>	* @param o element whose presence in this deque is to be tested
517	>	* @return {@code true} if this deque contains the specified element
518	>	* @throws ClassCastException if the class of the specified element
519	>	*         is incompatible with this deque
520	>	*         (<a href="../Collection.html#optional-restrictions">optional</a>)
521	>	* @throws NullPointerException if the specified element is null
522	>	*         (<a href="../Collection.html#optional-restrictions">optional</a>)
523	>	*/
524	>	boolean contains(Object o);
525	>
526	>	/**
527	>	* Returns the number of elements in this deque.
528	>	*
529	>	* @return the number of elements in this deque
530	>	*/
531	>	public int size();
532	>
533	>	/**
534	>	* Returns an iterator over the elements in this deque in proper sequence.
535	>	* The elements will be returned in order from first (head) to last (tail).
536	>	*
537	>	* @return an iterator over the elements in this deque in proper sequence
538		*/
539		Iterator<E> iterator();
540	+
541	+	/**
542	+	* Returns an iterator over the elements in this deque in reverse
543	+	* sequential order.  The elements will be returned in order from
544	+	* last (tail) to first (head).
545	+	*
546	+	* @return an iterator over the elements in this deque in reverse
547	+	* sequence
548	+	*/
549	+	Iterator<E> descendingIterator();
550	+
551		}

Diff Legend

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