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.1 by dl, Tue Dec 28 12:14:07 2004 UTC vs.
Revision 1.36 by jsr166, Sat May 6 06:49:45 2017 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 are summarized in the
28	<	* follwoing 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 #addFirst(Object) addFirst(e)}</td>
47	>	*    <td>{@link #offerFirst(Object) offerFirst(e)}</td>
48	>	*    <td>{@link #addLast(Object) addLast(e)}</td>
49	>	*    <td>{@link #offerLast(Object) 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 #removeFirst() removeFirst()}</td>
54	>	*    <td>{@link #pollFirst() pollFirst()}</td>
55	>	*    <td>{@link #removeLast() removeLast()}</td>
56	>	*    <td>{@link #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 #getFirst() getFirst()}</td>
61	>	*    <td>{@link #peekFirst() peekFirst()}</td>
62	>	*    <td>{@link #getLast() getLast()}</td>
63	>	*    <td>{@link #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>{@code Queue} Method</b></td>
77	+	*    <td ALIGN=CENTER> <b>Equivalent {@code Deque} Method</b></td>
78	+	*  </tr>
79	+	*  <tr>
80	+	*    <td>{@link #add(Object) add(e)}</td>
81	+	*    <td>{@link #addLast(Object) addLast(e)}</td>
82	+	*  </tr>
83	+	*  <tr>
84	+	*    <td>{@link #offer(Object) offer(e)}</td>
85	+	*    <td>{@link #offerLast(Object) offerLast(e)}</td>
86	+	*  </tr>
87		*  <tr>
88	<	*    <td ALIGN=CENTER> <b><tt>Queue</tt> Method</b></td>
89	<	*    <td ALIGN=CENTER> <b>Equivalent <tt>Deque</tt> Method</b></td>
88	>	*    <td>{@link #remove() remove()}</td>
89	>	*    <td>{@link #removeFirst() removeFirst()}</td>
90		*  </tr>
91		*  <tr>
92	<	*   <tr>
93	<	*    <td>{@link java.util.Queue#offer offer(e)}</td>
94	<	*    <td>{@link #offerLast offerLast(e)}</td>
95	<	*   </tr>
96	<	*   <tr>
97	<	*    <td>{@link java.util.Queue#add add(e)}</td>
98	<	*    <td>{@link #addLast addLast(e)}</td>
99	<	*   </tr>
100	<	*   <tr>
101	<	*    <td>{@link java.util.Queue#poll poll()}</td>
102	<	*    <td>{@link #pollFirst pollFirst()}</td>
89	<	*   </tr>
90	<	*   <tr>
91	<	*    <td>{@link java.util.Queue#remove remove()}</td>
92	<	*    <td>{@link #removeFirst removeFirst()}</td>
93	<	*   </tr>
94	<	*   <tr>
95	<	*    <td>{@link java.util.Queue#peek peek()}</td>
96	<	*    <td>{@link #peek peekFirst()}</td>
97	<	*   </tr>
98	<	*   <tr>
99	<	*    <td>{@link java.util.Queue#element element()}</td>
100	<	*    <td>{@link #getFirst getFirst()}</td>
101	<	*   </tr>
92	>	*    <td>{@link #poll() poll()}</td>
93	>	*    <td>{@link #pollFirst() pollFirst()}</td>
94	>	*  </tr>
95	>	*  <tr>
96	>	*    <td>{@link #element() element()}</td>
97	>	*    <td>{@link #getFirst() getFirst()}</td>
98	>	*  </tr>
99	>	*  <tr>
100	>	*    <td>{@link #peek() peek()}</td>
101	>	*    <td>{@link #peekFirst() 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>
118	>	*    <td>{@link #push(Object) push(e)}</td>
119	>	*    <td>{@link #addFirst(Object) addFirst(e)}</td>
120		*  </tr>
121		*  <tr>
122	<	*   <tr>
123	<	*    <td>{@link #push push(e)}</td>
124	<	*    <td>{@link #addFirst addFirst(e)}</td>
125	<	*   </tr>
126	<	*   <tr>
127	<	*    <td>{@link #pop pop()}</td>
128	<	*    <td>{@link #removeFirst removeFirst()}</td>
123	<	*   </tr>
124	<	*   <tr>
125	<	*    <td>{@link #peek peek()}</td>
126	<	*    <td>{@link #peekFirst peekFirst()}</td>
127	<	*   </tr>
122	>	*    <td>{@link #pop() pop()}</td>
123	>	*    <td>{@link #removeFirst() removeFirst()}</td>
124	>	*  </tr>
125	>	*  <tr>
126	>	*    <td>{@link #peek() peek()}</td>
127	>	*    <td>{@link #peekFirst() peekFirst()}</td>
128	>	*  </tr>
129		* </table>
130		*
131		* <p>Note that the {@link #peek peek} method works equally well when
132		* a deque is used as a queue or a stack; in either case, elements are
133		* drawn from the beginning of the deque.
134		*
135	<	* <p>This inteface provides two methods to to remove interior
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
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>
147	>	* {@code null} is used as a special return value by various methods
148	>	* to indicate that the deque is empty.
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
157	<	* Framework</a>.
155	>	* <p>This interface is a member of the
156	>	* <a href="{@docRoot}/java/util/package-summary.html#CollectionsFramework">
157	>	* Java Collections Framework</a>.
158		*
159		* @author Doug Lea
160		* @author Josh Bloch
161		* @since  1.6
162	<	* @param <E> the type of elements held in this collection
162	>	* @param <E> the type of elements held in this deque
163		*/
162	–
164		public interface Deque<E> extends Queue<E> {
165		/**
166	<	* Inserts the specified element to the front 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.
170	<	*
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
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	<	* violate capacity restrictions.  When using a capacity-restricted deque,
181	<	* this method is generally preferable to method <tt>addLast</tt> which
182	<	* can fail to insert an element only by throwing an exception.
183	<	*
184	<	* @param e the element to insert
185	<	* @return <tt>true</tt> if it was possible to insert the element,
186	<	*     else <tt>false</tt>
187	<	* @throws NullPointerException if <tt>e</tt> is null and this
188	<	*     deque does not permit null elements
189	<	*/
190	<	boolean offerLast(E e);
191	<
192	<	/**
193	<	* Inserts the specified element to the front of this deque unless it
194	<	* would violate capacity restrictions.
195	<	*
196	<	* @param e the element to insert
197	<	* @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
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 to the end of this deque unless it would
186	<	* violate capacity restrictions.
187	<	*
188	<	* @param e the element to insert
189	<	* @throws IllegalStateException if it was not possible to insert
190	<	*    the element due to capacity restrictions
191	<	* @throws NullPointerException if <tt>e</tt> is null and this
192	<	*     deque does not permit null elements
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	<	* Retrieves and removes the first element of this deque, or
207	<	* <tt>null</tt> if this deque is empty.
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 the {@link #addFirst} method,
209	>	* which can fail to insert an element only by throwing an exception.
210		*
211	<	* @return the first element of this deque, or <tt>null</tt> if
212	<	*     this deque is empty
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	<	E pollFirst();
221	>	boolean offerFirst(E e);
222
223		/**
224	<	* Retrieves and removes the last element of this deque, or
225	<	* <tt>null</tt> if this deque is empty.
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 the {@link #addLast} method,
227	>	* which can fail to insert an element only by throwing an exception.
228		*
229	<	* @return the last element of this deque, or <tt>null</tt> if
230	<	*     this deque is empty
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	<	E pollLast();
239	>	boolean offerLast(E e);
240
241		/**
242	<	* Removes and returns the first element of this deque.  This method
243	<	* differs from the <tt>pollFirst</tt> method only in that it throws an
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	<	* @return the first element of this deque
246	>	* @return the head of this deque
247		* @throws NoSuchElementException if this deque is empty
248		*/
249		E removeFirst();
250
251		/**
252		* Retrieves and removes the last element of this deque.  This method
253	<	* differs from the <tt>pollLast</tt> method only in that it throws an
253	>	* differs from {@link #pollLast pollLast} only in that it throws an
254		* exception if this deque is empty.
255		*
256	<	* @return the last element of this deque
256	>	* @return the tail of this deque
257		* @throws NoSuchElementException if this deque is empty
258		*/
259		E removeLast();
260
261		/**
262	<	* Retrieves, but does not remove, the first element of this deque,
263	<	* returning <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
259	<	*     this deque is empty
265	>	* @return the head of this deque, or {@code null} if this deque is empty
266		*/
267	<	E peekFirst();
267	>	E pollFirst();
268
269		/**
270	<	* Retrieves, but does not remove, the last element of this deque,
271	<	* returning <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 this deque
268	<	*     is empty
273	>	* @return the tail of this deque, or {@code null} if this deque is empty
274		*/
275	<	E peekLast();
275	>	E pollLast();
276
277		/**
278	<	* Retrieves, but does not remove, the first element of this
274	<	* deque.  This method differs from the <tt>peek</tt> method only
275	<	* in that it throws an exception if this deque is empty.
278	>	* Retrieves, but does not remove, the first element of this deque.
279		*
280	<	* @return the first element of this deque
280	>	* This method differs from {@link #peekFirst peekFirst} only in that it
281	>	* throws an exception if this deque is empty.
282	>	*
283	>	* @return the head of this deque
284		* @throws NoSuchElementException if this deque is empty
285		*/
286		E getFirst();
287
288		/**
289	<	* Retrieves, but does not remove, the last element of this
290	<	* deque.  This method differs from the <tt>peek</tt> method only
291	<	* in that it throws an 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 getLast();
297
298		/**
299	<	* Removes the first occurrence of the specified element in this
300	<	* deque.  If the deque does not contain the element, it is
301	<	* unchanged.  More formally, removes the first element <tt>e</tt>
302	<	* such that <tt>(o==null ? e==null : o.equals(e))</tt> (if
297	<	* such an element exists).
298	<	*
299	<	* @param e element to be removed from this deque, if present
300	<	* @return <tt>true</tt> if the deque contained the specified element
301	<	* @throws NullPointerException if the specified element is <tt>null</tt>
302	<	*/
303	<	boolean removeFirstOccurrence(Object e);
304	<
305	<	/**
306	<	* Removes the last occurrence of the specified element in this
307	<	* deque.  If the deque does not contain the element, it is
308	<	* unchanged.  More formally, removes the last element <tt>e</tt>
309	<	* such that <tt>(o==null ? e==null : o.equals(e))</tt> (if
310	<	* such an element exists).
311	<	*
312	<	* @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>
299	>	* Retrieves, but does not remove, the first element of this deque,
300	>	* or returns {@code null} if this deque is empty.
301	>	*
302	>	* @return the head of this deque, or {@code null} if this deque is empty
303		*/
304	<	boolean removeLastOccurrence(Object e);
317	<
318	<
319	<	// *** Queue methods ***
304	>	E peekFirst();
305
306		/**
307	<	* Inserts the specified element into the queue represented by this deque
308	<	* unless it would violate capacity restrictions.  In other words, inserts
324	<	* the specified element to 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.
328	<	*
329	<	* <p>This method is equivalent to {@link #offerLast}.
307	>	* Retrieves, but does not remove, the last element of this deque,
308	>	* or returns {@code null} if this deque is empty.
309		*
310	<	* @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
335	<	*     deque does not permit null elements
310	>	* @return the tail of this deque, or {@code null} if this deque is empty
311		*/
312	<	boolean offer(E e);
312	>	E peekLast();
313	>
314	>	/**
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	>	* {@code Objects.equals(o, e)} (if such an element exists).
319	>	* Returns {@code true} if this deque contained the specified element
320	>	* (or equivalently, if this deque changed as a result of the call).
321	>	*
322	>	* @param o element to be removed from this deque, if present
323	>	* @return {@code true} if an element was removed as a result of this call
324	>	* @throws ClassCastException if the class of the specified element
325	>	*         is incompatible with this deque
326	>	* (<a href="{@docRoot}/../api/java/util/Collection.html#optional-restrictions">optional</a>)
327	>	* @throws NullPointerException if the specified element is null and this
328	>	*         deque does not permit null elements
329	>	* (<a href="{@docRoot}/../api/java/util/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	>	* {@code Objects.equals(o, e)} (if such an element exists).
338	>	* Returns {@code true} if this deque contained the specified element
339	>	* (or equivalently, if this deque changed as a result of the call).
340	>	*
341	>	* @param o element to be removed from this deque, if present
342	>	* @return {@code true} if an element was removed as a result of this call
343	>	* @throws ClassCastException if the class of the specified element
344	>	*         is incompatible with this deque
345	>	* (<a href="{@docRoot}/../api/java/util/Collection.html#optional-restrictions">optional</a>)
346	>	* @throws NullPointerException if the specified element is null and this
347	>	*         deque does not permit null elements
348	>	* (<a href="{@docRoot}/../api/java/util/Collection.html#optional-restrictions">optional</a>)
349	>	*/
350	>	boolean removeLastOccurrence(Object o);
351	>
352	>	// *** Queue methods ***
353
354		/**
355	<	* Inserts the specified element into the queue represented by this
356	<	* deque unless it would violate capacity restrictions.  In other words,
357	<	* inserts the specified element as the last element of this deque.
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 insert
366	<	* @return <tt>true</tt> (as per the spec for {@link Collection#add})
367	<	* @throws IllegalStateException if it was not possible to insert
368	<	*    the element due to capacity restrictions
369	<	* @throws NullPointerException if <tt>e</tt> is null and this
370	<	*     deque does not permit null elements
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 add(E e);
377
378		/**
379	<	* Retrieves and removes the head of the queue represented by
380	<	* this deque, or <tt>null</tt> if this deque is empty.  In other words,
381	<	* retrieves and removes the first element of this deque, or <tt>null</tt>
382	<	* if this deque is empty.
379	>	* Inserts the specified element into the queue represented by this deque
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 #pollFirst()}.
387	>	* <p>This method is equivalent to {@link #offerLast}.
388		*
389	<	* @return the first element of this deque, or <tt>null</tt> if
390	<	*     this deque is empty
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	<	E poll();
399	>	boolean offer(E e);
400
401		/**
402	<	* Retrieves and removes the head of the queue represented by this deque.
403	<	* This method differs from the <tt>poll</tt> method only in that it
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
405		* throws an exception if this deque is empty.
406		*
407		* <p>This method is equivalent to {@link #removeFirst()}.
#	Line 378 | Line 412 | public interface Deque<E> extends Queue<
412		E remove();
413
414		/**
415	<	* Retrieves, but does not remove, the head of the queue represented by
416	<	* this deque, returning <tt>null</tt> 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 #peekFirst()}
419	>	* <p>This method is equivalent to {@link #pollFirst()}.
420		*
421	<	* @return the head of the queue represented by this deque, or
422	<	*     <tt>null</tt> if this deque is empty
421	>	* @return the first element of this deque, or {@code null} if
422	>	*         this deque is empty
423		*/
424	<	E peek();
424	>	E poll();
425
426		/**
427		* Retrieves, but does not remove, the head of the queue represented by
428	<	* this deque.  This method differs from the <tt>peek</tt> method only in
429	<	* that it throws an exception if this deque is empty.
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 #getFirst()}
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 element();
438
439	+	/**
440	+	* Retrieves, but does not remove, the head of the queue represented by
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()}.
445	+	*
446	+	* @return the head of the queue represented by this deque, or
447	+	*         {@code null} if this deque is empty
448	+	*/
449	+	E peek();
450	+
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
474		/**
475		* Pops an element from the stack represented by this deque.  In other
476	<	* words, removes and returns the the first element of this deque.
476	>	* words, removes and returns the first element of this deque.
477		*
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	>	* 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	>	* {@code Objects.equals(o, e)} (if such an element exists).
494	>	* Returns {@code true} if this deque contained the specified element
495	>	* (or equivalently, if this deque changed as a result of the call).
496	>	*
497	>	* <p>This method is equivalent to {@link #removeFirstOccurrence(Object)}.
498	>	*
499	>	* @param o element to be removed from this deque, if present
500	>	* @return {@code true} if an element was removed as a result of this call
501	>	* @throws ClassCastException if the class of the specified element
502	>	*         is incompatible with this deque
503	>	* (<a href="{@docRoot}/../api/java/util/Collection.html#optional-restrictions">optional</a>)
504	>	* @throws NullPointerException if the specified element is null and this
505	>	*         deque does not permit null elements
506	>	* (<a href="{@docRoot}/../api/java/util/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 {@code Objects.equals(o, e)}.
514	>	*
515	>	* @param o element whose presence in this deque is to be tested
516	>	* @return {@code true} if this deque contains the specified element
517	>	* @throws ClassCastException if the class of the specified element
518	>	*         is incompatible with this deque
519	>	* (<a href="{@docRoot}/../api/java/util/Collection.html#optional-restrictions">optional</a>)
520	>	* @throws NullPointerException if the specified element is null and this
521	>	*         deque does not permit null elements
522	>	* (<a href="{@docRoot}/../api/java/util/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	>	int size();
532
533		/**
534	<	* Returns an iterator over the elements in this deque.  The elements
535	<	* will be ordered from first (head) to last (tail).
536	<	*
537	<	* @return an <tt>Iterator</tt> over the elements in this deque
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