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.40 by jsr166, Wed Aug 23 20:17:53 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	<	*
30	<	* <table BORDER CELLPADDING=3 CELLSPACING=1>
31	<	*  <tr>
32	<	*    <td></td>
33	<	*    <td ALIGN=CENTER COLSPAN = 2> <b>First Element (Head)</b></td>
34	<	*    <td ALIGN=CENTER COLSPAN = 2> <b>Last Element (Tail)</b></td>
35	<	*  </tr>
36	<	*  <tr>
37	<	*    <td></td>
38	<	*    <td ALIGN=CENTER><em>Throws exception</em></td>
39	<	*    <td ALIGN=CENTER><em>Returns special value</em></td>
40	<	*    <td ALIGN=CENTER><em>Throws exception</em></td>
41	<	*    <td ALIGN=CENTER><em>Returns special value</em></td>
42	<	*  </tr>
43	<	*  <tr>
44	<	*    <td><b>Insert</b></td>
45	<	*    <td>{@link #addFirst addFirst(e)}</td>
46	<	*    <td>{@link #offerFirst offerFirst(e)}</td>
47	<	*    <td>{@link #addLast addLast(e)}</td>
48	<	*    <td>{@link #offerLast offerLast(e)}</td>
49	<	*  </tr>
50	<	*  <tr>
51	<	*    <td><b>Remove</b></td>
52	<	*    <td>{@link #removeFirst removeFirst()}</td>
53	<	*    <td>{@link #pollFirst pollFirst()}</td>
54	<	*    <td>{@link #removeLast removeLast()}</td>
55	<	*    <td>{@link #pollLast pollLast()}</td>
56	<	*  </tr>
57	<	*  <tr>
58	<	*    <td><b>Examine</b></td>
59	<	*    <td>{@link #getFirst getFirst()}</td>
60	<	*    <td>{@link #peekFirst peekFirst()}</td>
61	<	*    <td>{@link #getLast getLast()}</td>
62	<	*    <td>{@link #peekLast peekLast()}</td>
27	>	* <p>The twelve methods described above are summarized in the
28	>	* following table:
29	>	*
30	>	* <table class="striped">
31	>	* <caption>Summary of Deque methods</caption>
32	>	*  <thead>
33	>	*  <tr>
34	>	*    <td rowspan="2"></td>
35	>	*    <th scope="col" colspan="2"> First Element (Head)</th>
36	>	*    <th scope="col" colspan="2"> Last Element (Tail)</th>
37	>	*  </tr>
38	>	*  <tr>
39	>	*    <th scope="col" style="font-weight:normal; font-style:italic">Throws exception</th>
40	>	*    <th scope="col" style="font-weight:normal; font-style:italic">Special value</th>
41	>	*    <th scope="col" style="font-weight:normal; font-style:italic">Throws exception</th>
42	>	*    <th scope="col" style="font-weight:normal; font-style:italic">Special value</th>
43	>	*  </tr>
44	>	*  </thead>
45	>	*  <tbody>
46	>	*  <tr>
47	>	*    <th scope="row">Insert</th>
48	>	*    <td>{@link #addFirst(Object) addFirst(e)}</td>
49	>	*    <td>{@link #offerFirst(Object) offerFirst(e)}</td>
50	>	*    <td>{@link #addLast(Object) addLast(e)}</td>
51	>	*    <td>{@link #offerLast(Object) offerLast(e)}</td>
52	>	*  </tr>
53	>	*  <tr>
54	>	*    <th scope="row">Remove</th>
55	>	*    <td>{@link #removeFirst() removeFirst()}</td>
56	>	*    <td>{@link #pollFirst() pollFirst()}</td>
57	>	*    <td>{@link #removeLast() removeLast()}</td>
58	>	*    <td>{@link #pollLast() pollLast()}</td>
59		*  </tr>
60	+	*  <tr>
61	+	*    <th scope="row">Examine</th>
62	+	*    <td>{@link #getFirst() getFirst()}</td>
63	+	*    <td>{@link #peekFirst() peekFirst()}</td>
64	+	*    <td>{@link #getLast() getLast()}</td>
65	+	*    <td>{@link #peekLast() peekLast()}</td>
66	+	*  </tr>
67	+	*  </tbody>
68		* </table>
69		*
70		* <p>This interface extends the {@link Queue} interface.  When a deque is
71		* used as a queue, FIFO (First-In-First-Out) behavior results.  Elements are
72	<	* added to the end of the deque and removed from the beginning.  The methods
73	<	* inherited from the <tt>Queue</tt> interface are precisely equivalent to
74	<	* <tt>Deque</tt> methods as indicated in the following table:<p>
75	<	*
76	<	* <table BORDER CELLPADDING=3 CELLSPACING=1>
77	<	*  <tr>
78	<	*    <td ALIGN=CENTER> <b><tt>Queue</tt> Method</b></td>
79	<	*    <td ALIGN=CENTER> <b>Equivalent <tt>Deque</tt> Method</b></td>
80	<	*  </tr>
81	<	*  <tr>
82	<	*   <tr>
83	<	*    <td>{@link java.util.Queue#offer offer(e)}</td>
84	<	*    <td>{@link #offerLast offerLast(e)}</td>
85	<	*   </tr>
86	<	*   <tr>
87	<	*    <td>{@link java.util.Queue#add add(e)}</td>
88	<	*    <td>{@link #addLast addLast(e)}</td>
89	<	*   </tr>
90	<	*   <tr>
91	<	*    <td>{@link java.util.Queue#poll poll()}</td>
92	<	*    <td>{@link #pollFirst pollFirst()}</td>
93	<	*   </tr>
94	<	*   <tr>
95	<	*    <td>{@link java.util.Queue#remove remove()}</td>
96	<	*    <td>{@link #removeFirst removeFirst()}</td>
97	<	*   </tr>
98	<	*   <tr>
99	<	*    <td>{@link java.util.Queue#peek peek()}</td>
100	<	*    <td>{@link #peek peekFirst()}</td>
101	<	*   </tr>
102	<	*   <tr>
103	<	*    <td>{@link java.util.Queue#element element()}</td>
104	<	*    <td>{@link #getFirst getFirst()}</td>
105	<	*   </tr>
72	>	* added at the end of the deque and removed from the beginning.  The methods
73	>	* inherited from the {@code Queue} interface are precisely equivalent to
74	>	* {@code Deque} methods as indicated in the following table:
75	>	*
76	>	* <table class="striped">
77	>	* <caption>Comparison of Queue and Deque methods</caption>
78	>	*  <thead>
79	>	*  <tr>
80	>	*    <th scope="col"> {@code Queue} Method</th>
81	>	*    <th scope="col"> Equivalent {@code Deque} Method</th>
82	>	*  </tr>
83	>	*  </thead>
84	>	*  <tbody>
85	>	*  <tr>
86	>	*    <th scope="row">{@link #add(Object) add(e)}</th>
87	>	*    <td>{@link #addLast(Object) addLast(e)}</td>
88	>	*  </tr>
89	>	*  <tr>
90	>	*    <th scope="row">{@link #offer(Object) offer(e)}</th>
91	>	*    <td>{@link #offerLast(Object) offerLast(e)}</td>
92	>	*  </tr>
93	>	*  <tr>
94	>	*    <th scope="row">{@link #remove() remove()}</th>
95	>	*    <td>{@link #removeFirst() removeFirst()}</td>
96	>	*  </tr>
97	>	*  <tr>
98	>	*    <th scope="row">{@link #poll() poll()}</th>
99	>	*    <td>{@link #pollFirst() pollFirst()}</td>
100	>	*  </tr>
101	>	*  <tr>
102	>	*    <th scope="row">{@link #element() element()}</th>
103	>	*    <td>{@link #getFirst() getFirst()}</td>
104	>	*  </tr>
105	>	*  <tr>
106	>	*    <th scope="row">{@link #peek() peek()}</th>
107	>	*    <td>{@link #peekFirst() peekFirst()}</td>
108	>	*  </tr>
109	>	*  </tbody>
110		* </table>
111		*
112		* <p>Deques can also be used as LIFO (Last-In-First-Out) stacks.  This
113		* interface should be used in preference to the legacy {@link Stack} class.
114	<	* When a dequeue is used as a stack, elements are pushed and popped from the
114	>	* When a deque is used as a stack, elements are pushed and popped from the
115		* beginning of the deque.  Stack methods are precisely equivalent to
116	<	* <tt>Deque</tt> methods as indicated in the table below:<p>
116	>	* {@code Deque} methods as indicated in the table below:
117		*
118	<	* <table BORDER CELLPADDING=3 CELLSPACING=1>
118	>	* <table class="striped">
119	>	* <caption>Comparison of Stack and Deque methods</caption>
120	>	*  <thead>
121	>	*  <tr>
122	>	*    <th scope="col"> Stack Method</th>
123	>	*    <th scope="col"> Equivalent {@code Deque} Method</th>
124	>	*  </tr>
125	>	*  </thead>
126	>	*  <tbody>
127		*  <tr>
128	<	*    <td ALIGN=CENTER> <b>Stack Method</b></td>
129	<	*    <td ALIGN=CENTER> <b>Equivalent <tt>Deque</tt> Method</b></td>
128	>	*    <th scope="row">{@link #push(Object) push(e)}</th>
129	>	*    <td>{@link #addFirst(Object) addFirst(e)}</td>
130		*  </tr>
131		*  <tr>
132	<	*   <tr>
133	<	*    <td>{@link #push push(e)}</td>
134	<	*    <td>{@link #addFirst addFirst(e)}</td>
135	<	*   </tr>
136	<	*   <tr>
137	<	*    <td>{@link #pop pop()}</td>
138	<	*    <td>{@link #removeFirst removeFirst()}</td>
139	<	*   </tr>
124	<	*   <tr>
125	<	*    <td>{@link #peek peek()}</td>
126	<	*    <td>{@link #peekFirst peekFirst()}</td>
127	<	*   </tr>
132	>	*    <th scope="row">{@link #pop() pop()}</th>
133	>	*    <td>{@link #removeFirst() removeFirst()}</td>
134	>	*  </tr>
135	>	*  <tr>
136	>	*    <th scope="row">{@link #peek() peek()}</th>
137	>	*    <td>{@link #peekFirst() peekFirst()}</td>
138	>	*  </tr>
139	>	*  </tbody>
140		* </table>
141		*
142		* <p>Note that the {@link #peek peek} method works equally well when
143		* a deque is used as a queue or a stack; in either case, elements are
144		* drawn from the beginning of the deque.
145		*
146	<	* <p>This inteface provides two methods to to remove interior
146	>	* <p>This interface provides two methods to remove interior
147		* elements, {@link #removeFirstOccurrence removeFirstOccurrence} and
148	<	* {@link #removeLastOccurrence removeLastOccurrence}.  Unlike the
137	<	* {@link List} interface, this interface does not provide support for
138	<	* indexed access to elements.
148	>	* {@link #removeLastOccurrence removeLastOccurrence}.
149		*
150	<	* <p>While <tt>Deque</tt> implementations are not strictly required
150	>	* <p>Unlike the {@link List} interface, this interface does not
151	>	* provide support for indexed access to elements.
152	>	*
153	>	* <p>While {@code Deque} implementations are not strictly required
154		* to prohibit the insertion of null elements, they are strongly
155	<	* encouraged to do so.  Users of any <tt>Deque</tt> implementations
155	>	* encouraged to do so.  Users of any {@code Deque} implementations
156		* that do allow null elements are strongly encouraged <i>not</i> to
157		* take advantage of the ability to insert nulls.  This is so because
158	<	* <tt>null</tt> is used as a special return value by various methods
159	<	* to indicated that the deque is empty.
160	<	*
161	<	* <p><tt>Deque</tt> implementations generally do not define
162	<	* element-based versions of the <tt>equals</tt> and <tt>hashCode</tt>
158	>	* {@code null} is used as a special return value by various methods
159	>	* to indicate that the deque is empty.
160	>	*
161	>	* <p>{@code Deque} implementations generally do not define
162	>	* element-based versions of the {@code equals} and {@code hashCode}
163		* methods, but instead inherit the identity-based versions from class
164	<	* <tt>Object</tt>.
164	>	* {@code Object}.
165		*
166	<	* <p>This interface is a member of the <a
167	<	* href="{@docRoot}/../guide/collections/index.html"> Java Collections
168	<	* Framework</a>.
166	>	* <p>This interface is a member of the
167	>	* <a href="{@docRoot}/java/util/package-summary.html#CollectionsFramework">
168	>	* Java Collections Framework</a>.
169		*
170		* @author Doug Lea
171		* @author Josh Bloch
172		* @since  1.6
173	<	* @param <E> the type of elements held in this collection
173	>	* @param <E> the type of elements held in this deque
174		*/
162	–
175		public interface Deque<E> extends Queue<E> {
176		/**
177	<	* Inserts the specified element to the front this deque unless it would
177	>	* Inserts the specified element at the front of this deque if it is
178	>	* possible to do so immediately without violating capacity restrictions,
179	>	* throwing an {@code IllegalStateException} if no space is currently
180	>	* available.  When using a capacity-restricted deque, it is generally
181	>	* preferable to use method {@link #offerFirst}.
182	>	*
183	>	* @param e the element to add
184	>	* @throws IllegalStateException if the element cannot be added at this
185	>	*         time due to capacity restrictions
186	>	* @throws ClassCastException if the class of the specified element
187	>	*         prevents it from being added to this deque
188	>	* @throws NullPointerException if the specified element is null and this
189	>	*         deque does not permit null elements
190	>	* @throws IllegalArgumentException if some property of the specified
191	>	*         element prevents it from being added to this deque
192	>	*/
193	>	void addFirst(E e);
194	>
195	>	/**
196	>	* Inserts the specified element at the end of this deque if it is
197	>	* possible to do so immediately without violating capacity restrictions,
198	>	* throwing an {@code IllegalStateException} if no space is currently
199	>	* available.  When using a capacity-restricted deque, it is generally
200	>	* preferable to use method {@link #offerLast}.
201	>	*
202	>	* <p>This method is equivalent to {@link #add}.
203	>	*
204	>	* @param e the element to add
205	>	* @throws IllegalStateException if the element cannot be added at this
206	>	*         time due to capacity restrictions
207	>	* @throws ClassCastException if the class of the specified element
208	>	*         prevents it from being added to this deque
209	>	* @throws NullPointerException if the specified element is null and this
210	>	*         deque does not permit null elements
211	>	* @throws IllegalArgumentException if some property of the specified
212	>	*         element prevents it from being added to this deque
213	>	*/
214	>	void addLast(E e);
215	>
216	>	/**
217	>	* Inserts the specified element at the front of this deque unless it would
218		* violate capacity restrictions.  When using a capacity-restricted deque,
219	<	* this method is generally preferable to method <tt>addFirst</tt>, which
220	<	* can fail to insert an element only by throwing an exception.
219	>	* this method is generally preferable to the {@link #addFirst} method,
220	>	* which can fail to insert an element only by throwing an exception.
221		*
222	<	* @param e the element to insert
223	<	* @return <tt>true</tt> if it was possible to insert the element,
224	<	*     else <tt>false</tt>
225	<	* @throws NullPointerException if <tt>e</tt> is null and this
226	<	*     deque does not permit null elements
222	>	* @param e the element to add
223	>	* @return {@code true} if the element was added to this deque, else
224	>	*         {@code false}
225	>	* @throws ClassCastException if the class of the specified element
226	>	*         prevents it from being added to this deque
227	>	* @throws NullPointerException if the specified element is null and this
228	>	*         deque does not permit null elements
229	>	* @throws IllegalArgumentException if some property of the specified
230	>	*         element prevents it from being added to this deque
231		*/
232		boolean offerFirst(E e);
233
234		/**
235	<	* Inserts the specified element to the end of this deque unless it would
235	>	* Inserts the specified element at the end of this deque unless it would
236		* violate capacity restrictions.  When using a capacity-restricted deque,
237	<	* this method is generally preferable to method <tt>addLast</tt> which
238	<	* can fail to insert an element only by throwing an exception.
237	>	* this method is generally preferable to the {@link #addLast} method,
238	>	* which can fail to insert an element only by throwing an exception.
239		*
240	<	* @param e the element to insert
241	<	* @return <tt>true</tt> if it was possible to insert the element,
242	<	*     else <tt>false</tt>
243	<	* @throws NullPointerException if <tt>e</tt> is null and this
244	<	*     deque does not permit null elements
240	>	* @param e the element to add
241	>	* @return {@code true} if the element was added to this deque, else
242	>	*         {@code false}
243	>	* @throws ClassCastException if the class of the specified element
244	>	*         prevents it from being added to this deque
245	>	* @throws NullPointerException if the specified element is null and this
246	>	*         deque does not permit null elements
247	>	* @throws IllegalArgumentException if some property of the specified
248	>	*         element prevents it from being added to this deque
249		*/
250		boolean offerLast(E e);
251
252		/**
253	<	* Inserts the specified element to the front of this deque unless it
254	<	* would violate capacity restrictions.
253	>	* Retrieves and removes the first element of this deque.  This method
254	>	* differs from {@link #pollFirst pollFirst} only in that it throws an
255	>	* exception if this deque is empty.
256		*
257	<	* @param e the element to insert
258	<	* @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
257	>	* @return the head of this deque
258	>	* @throws NoSuchElementException if this deque is empty
259		*/
260	<	void addFirst(E e);
260	>	E removeFirst();
261
262		/**
263	<	* Inserts the specified element to the end of this deque unless it would
264	<	* violate capacity restrictions.
263	>	* Retrieves and removes the last element of this deque.  This method
264	>	* differs from {@link #pollLast pollLast} only in that it throws an
265	>	* exception if this deque is empty.
266		*
267	<	* @param e the element to insert
268	<	* @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
267	>	* @return the tail of this deque
268	>	* @throws NoSuchElementException if this deque is empty
269		*/
270	<	void addLast(E e);
270	>	E removeLast();
271
272		/**
273	<	* Retrieves and removes the first element of this deque, or
274	<	* <tt>null</tt> if this deque is empty.
273	>	* Retrieves and removes the first element of this deque,
274	>	* or returns {@code null} if this deque is empty.
275		*
276	<	* @return the first element of this deque, or <tt>null</tt> if
221	<	*     this deque is empty
276	>	* @return the head of this deque, or {@code null} if this deque is empty
277		*/
278		E pollFirst();
279
280		/**
281	<	* Retrieves and removes the last element of this deque, or
282	<	* <tt>null</tt> if this deque is empty.
281	>	* Retrieves and removes the last element of this deque,
282	>	* or returns {@code null} if this deque is empty.
283		*
284	<	* @return the last element of this deque, or <tt>null</tt> if
230	<	*     this deque is empty
284	>	* @return the tail of this deque, or {@code null} if this deque is empty
285		*/
286		E pollLast();
287
288		/**
289	<	* Removes and returns the first element of this deque.  This method
290	<	* differs from the <tt>pollFirst</tt> method only in that it throws an
291	<	* exception if this deque is empty.
289	>	* Retrieves, but does not remove, the first element of this deque.
290	>	*
291	>	* This method differs from {@link #peekFirst peekFirst} only in that it
292	>	* throws an exception if this deque is empty.
293		*
294	<	* @return the first element of this deque
294	>	* @return the head of this deque
295		* @throws NoSuchElementException if this deque is empty
296		*/
297	<	E removeFirst();
297	>	E getFirst();
298
299		/**
300	<	* Retrieves and removes the last element of this deque.  This method
301	<	* differs from the <tt>pollLast</tt> method only in that it throws an
302	<	* exception if this deque is empty.
300	>	* Retrieves, but does not remove, the last element of this deque.
301	>	* This method differs from {@link #peekLast peekLast} only in that it
302	>	* throws an exception if this deque is empty.
303		*
304	<	* @return the last element of this deque
304	>	* @return the tail of this deque
305		* @throws NoSuchElementException if this deque is empty
306		*/
307	<	E removeLast();
307	>	E getLast();
308
309		/**
310		* Retrieves, but does not remove, the first element of this deque,
311	<	* returning <tt>null</tt> if this deque is empty.
311	>	* or returns {@code null} if this deque is empty.
312		*
313	<	* @return the first element of this deque, or <tt>null</tt> if
259	<	*     this deque is empty
313	>	* @return the head of this deque, or {@code null} if this deque is empty
314		*/
315		E peekFirst();
316
317		/**
318		* Retrieves, but does not remove, the last element of this deque,
319	<	* returning <tt>null</tt> if this deque is empty.
319	>	* or returns {@code null} if this deque is empty.
320		*
321	<	* @return the last element of this deque, or <tt>null</tt> if this deque
268	<	*     is empty
321	>	* @return the tail of this deque, or {@code null} if this deque is empty
322		*/
323		E peekLast();
324
325		/**
326	<	* Retrieves, but does not remove, the first element of this
327	<	* deque.  This method differs from the <tt>peek</tt> method only
328	<	* in that it throws an exception if this deque is empty.
329	<	*
330	<	* @return the first element of this deque
331	<	* @throws NoSuchElementException if this deque is empty
326	>	* Removes the first occurrence of the specified element from this deque.
327	>	* If the deque does not contain the element, it is unchanged.
328	>	* More formally, removes the first element {@code e} such that
329	>	* {@code Objects.equals(o, e)} (if such an element exists).
330	>	* Returns {@code true} if this deque contained the specified element
331	>	* (or equivalently, if this deque changed as a result of the call).
332	>	*
333	>	* @param o element to be removed from this deque, if present
334	>	* @return {@code true} if an element was removed as a result of this call
335	>	* @throws ClassCastException if the class of the specified element
336	>	*         is incompatible with this deque
337	>	* (<a href="{@docRoot}/../api/java/util/Collection.html#optional-restrictions">optional</a>)
338	>	* @throws NullPointerException if the specified element is null and this
339	>	*         deque does not permit null elements
340	>	* (<a href="{@docRoot}/../api/java/util/Collection.html#optional-restrictions">optional</a>)
341	>	*/
342	>	boolean removeFirstOccurrence(Object o);
343	>
344	>	/**
345	>	* Removes the last occurrence of the specified element from this deque.
346	>	* If the deque does not contain the element, it is unchanged.
347	>	* More formally, removes the last element {@code e} such that
348	>	* {@code Objects.equals(o, e)} (if such an element exists).
349	>	* Returns {@code true} if this deque contained the specified element
350	>	* (or equivalently, if this deque changed as a result of the call).
351	>	*
352	>	* @param o element to be removed from this deque, if present
353	>	* @return {@code true} if an element was removed as a result of this call
354	>	* @throws ClassCastException if the class of the specified element
355	>	*         is incompatible with this deque
356	>	* (<a href="{@docRoot}/../api/java/util/Collection.html#optional-restrictions">optional</a>)
357	>	* @throws NullPointerException if the specified element is null and this
358	>	*         deque does not permit null elements
359	>	* (<a href="{@docRoot}/../api/java/util/Collection.html#optional-restrictions">optional</a>)
360		*/
361	<	E getFirst();
361	>	boolean removeLastOccurrence(Object o);
362
363	<	/**
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();
363	>	// *** Queue methods ***
364
365		/**
366	<	* Removes the first occurrence of the specified element in this
367	<	* deque.  If the deque does not contain the element, it is
368	<	* unchanged.  More formally, removes the first element <tt>e</tt>
369	<	* such that <tt>(o==null ? e==null : o.equals(e))</tt> (if
370	<	* such an element exists).
371	<	*
372	<	* @param e element to be removed from this deque, if present
373	<	* @return <tt>true</tt> if the deque contained the specified element
374	<	* @throws NullPointerException if the specified element is <tt>null</tt>
375	<	*/
376	<	boolean removeFirstOccurrence(Object e);
377	<
378	<	/**
379	<	* Removes the last occurrence of the specified element in this
380	<	* deque.  If the deque does not contain the element, it is
381	<	* unchanged.  More formally, removes the last element <tt>e</tt>
382	<	* such that <tt>(o==null ? e==null : o.equals(e))</tt> (if
383	<	* such an element exists).
384	<	*
385	<	* @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>
366	>	* Inserts the specified element into the queue represented by this deque
367	>	* (in other words, at the tail of this deque) if it is possible to do so
368	>	* immediately without violating capacity restrictions, returning
369	>	* {@code true} upon success and throwing an
370	>	* {@code IllegalStateException} if no space is currently available.
371	>	* When using a capacity-restricted deque, it is generally preferable to
372	>	* use {@link #offer(Object) offer}.
373	>	*
374	>	* <p>This method is equivalent to {@link #addLast}.
375	>	*
376	>	* @param e the element to add
377	>	* @return {@code true} (as specified by {@link Collection#add})
378	>	* @throws IllegalStateException if the element cannot be added at this
379	>	*         time due to capacity restrictions
380	>	* @throws ClassCastException if the class of the specified element
381	>	*         prevents it from being added to this deque
382	>	* @throws NullPointerException if the specified element is null and this
383	>	*         deque does not permit null elements
384	>	* @throws IllegalArgumentException if some property of the specified
385	>	*         element prevents it from being added to this deque
386		*/
387	<	boolean removeLastOccurrence(Object e);
317	<
318	<
319	<	// *** Queue methods ***
387	>	boolean add(E e);
388
389		/**
390		* Inserts the specified element into the queue represented by this deque
391	<	* unless it would violate capacity restrictions.  In other words, inserts
392	<	* the specified element to the end of this deque.  When using a
393	<	* capacity-restricted deque, this method is generally preferable to the
394	<	* {@link #add} method, which can fail to insert an element only by
395	<	* throwing an exception.
391	>	* (in other words, at the tail of this deque) if it is possible to do so
392	>	* immediately without violating capacity restrictions, returning
393	>	* {@code true} upon success and {@code false} if no space is currently
394	>	* available.  When using a capacity-restricted deque, this method is
395	>	* generally preferable to the {@link #add} method, which can fail to
396	>	* insert an element only by throwing an exception.
397		*
398		* <p>This method is equivalent to {@link #offerLast}.
399		*
400	<	* @param e the element to insert
401	<	* @return <tt>true</tt> if it was possible to insert the element,
402	<	*     else <tt>false</tt>
403	<	* @throws NullPointerException if <tt>e</tt> is null and this
404	<	*     deque does not permit null elements
400	>	* @param e the element to add
401	>	* @return {@code true} if the element was added to this deque, else
402	>	*         {@code false}
403	>	* @throws ClassCastException if the class of the specified element
404	>	*         prevents it from being added to this deque
405	>	* @throws NullPointerException if the specified element is null and this
406	>	*         deque does not permit null elements
407	>	* @throws IllegalArgumentException if some property of the specified
408	>	*         element prevents it from being added to this deque
409		*/
410		boolean offer(E e);
411
412		/**
413	<	* Inserts the specified element into the queue represented by this
414	<	* deque unless it would violate capacity restrictions.  In other words,
415	<	* inserts the specified element as the last element of this deque.
413	>	* Retrieves and removes the head of the queue represented by this deque
414	>	* (in other words, the first element of this deque).
415	>	* This method differs from {@link #poll() poll()} only in that it
416	>	* throws an exception if this deque is empty.
417		*
418	<	* <p>This method is equivalent to {@link #addLast}.
418	>	* <p>This method is equivalent to {@link #removeFirst()}.
419		*
420	<	* @param e the element to insert
421	<	* @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
420	>	* @return the head of the queue represented by this deque
421	>	* @throws NoSuchElementException if this deque is empty
422		*/
423	<	boolean add(E e);
423	>	E remove();
424
425		/**
426	<	* Retrieves and removes the head of the queue represented by
427	<	* this deque, or <tt>null</tt> if this deque is empty.  In other words,
428	<	* retrieves and removes the first element of this deque, or <tt>null</tt>
359	<	* if this deque is empty.
426	>	* Retrieves and removes the head of the queue represented by this deque
427	>	* (in other words, the first element of this deque), or returns
428	>	* {@code null} if this deque is empty.
429		*
430		* <p>This method is equivalent to {@link #pollFirst()}.
431		*
432	<	* @return the first element of this deque, or <tt>null</tt> if
433	<	*     this deque is empty
432	>	* @return the first element of this deque, or {@code null} if
433	>	*         this deque is empty
434		*/
435		E poll();
436
437		/**
438	<	* Retrieves and removes the head of the queue represented by this deque.
439	<	* This method differs from the <tt>poll</tt> method only in that it
440	<	* throws an exception if this deque is empty.
438	>	* Retrieves, but does not remove, the head of the queue represented by
439	>	* this deque (in other words, the first element of this deque).
440	>	* This method differs from {@link #peek peek} only in that it throws an
441	>	* exception if this deque is empty.
442		*
443	<	* <p>This method is equivalent to {@link #removeFirst()}.
443	>	* <p>This method is equivalent to {@link #getFirst()}.
444		*
445		* @return the head of the queue represented by this deque
446		* @throws NoSuchElementException if this deque is empty
447		*/
448	<	E remove();
448	>	E element();
449
450		/**
451		* Retrieves, but does not remove, the head of the queue represented by
452	<	* this deque, returning <tt>null</tt> if this deque is empty.
452	>	* this deque (in other words, the first element of this deque), or
453	>	* returns {@code null} if this deque is empty.
454		*
455	<	* <p>This method is equivalent to {@link #peekFirst()}
455	>	* <p>This method is equivalent to {@link #peekFirst()}.
456		*
457		* @return the head of the queue represented by this deque, or
458	<	*     <tt>null</tt> if this deque is empty
458	>	*         {@code null} if this deque is empty
459		*/
460		E peek();
461
462		/**
463	<	* Retrieves, but does not remove, the head of the queue represented by
464	<	* this deque.  This method differs from the <tt>peek</tt> method only in
465	<	* that it throws an exception if this deque is empty.
466	<	*
467	<	* <p>This method is equivalent to {@link #getFirst()}
468	<	*
469	<	* @return the head of the queue represented by this deque
470	<	* @throws NoSuchElementException if this deque is empty
463	>	* Adds all of the elements in the specified collection at the end
464	>	* of this deque, as if by calling {@link #addLast} on each one,
465	>	* in the order that they are returned by the collection's iterator.
466	>	*
467	>	* <p>When using a capacity-restricted deque, it is generally preferable
468	>	* to call {@link #offer(Object) offer} separately on each element.
469	>	*
470	>	* <p>An exception encountered while trying to add an element may result
471	>	* in only some of the elements having been successfully added when
472	>	* the associated exception is thrown.
473	>	*
474	>	* @param c the elements to be inserted into this deque
475	>	* @return {@code true} if this deque changed as a result of the call
476	>	* @throws IllegalStateException if not all the elements can be added at
477	>	*         this time due to insertion restrictions
478	>	* @throws ClassCastException if the class of an element of the specified
479	>	*         collection prevents it from being added to this deque
480	>	* @throws NullPointerException if the specified collection contains a
481	>	*         null element and this deque does not permit null elements,
482	>	*         or if the specified collection is null
483	>	* @throws IllegalArgumentException if some property of an element of the
484	>	*         specified collection prevents it from being added to this deque
485		*/
486	<	E element();
402	<
486	>	boolean addAll(Collection<? extends E> c);
487
488		// *** Stack methods ***
489
490		/**
491	<	* Pushes an element onto the stack represented by this deque.  In other
492	<	* words, inserts the element to the front this deque unless it would
493	<	* violate capacity restrictions.
491	>	* Pushes an element onto the stack represented by this deque (in other
492	>	* words, at the head of this deque) if it is possible to do so
493	>	* immediately without violating capacity restrictions, throwing an
494	>	* {@code IllegalStateException} if no space is currently available.
495		*
496		* <p>This method is equivalent to {@link #addFirst}.
497		*
498	<	* @throws IllegalStateException if it was not possible to insert
499	<	*    the element due to capacity restrictions
500	<	* @throws NullPointerException if <tt>e</tt> is null and this
501	<	*     deque does not permit null elements
498	>	* @param e the element to push
499	>	* @throws IllegalStateException if the element cannot be added at this
500	>	*         time due to capacity restrictions
501	>	* @throws ClassCastException if the class of the specified element
502	>	*         prevents it from being added to this deque
503	>	* @throws NullPointerException if the specified element is null and this
504	>	*         deque does not permit null elements
505	>	* @throws IllegalArgumentException if some property of the specified
506	>	*         element prevents it from being added to this deque
507		*/
508		void push(E e);
509
510		/**
511		* Pops an element from the stack represented by this deque.  In other
512	<	* words, removes and returns the the first element of this deque.
512	>	* words, removes and returns the first element of this deque.
513		*
514		* <p>This method is equivalent to {@link #removeFirst()}.
515		*
516		* @return the element at the front of this deque (which is the top
517	<	*     of the stack represented by this deque)
517	>	*         of the stack represented by this deque)
518		* @throws NoSuchElementException if this deque is empty
519		*/
520		E pop();
521
522
523	<	// *** Collection Method ***
523	>	// *** Collection methods ***
524	>
525	>	/**
526	>	* Removes the first occurrence of the specified element from this deque.
527	>	* If the deque does not contain the element, it is unchanged.
528	>	* More formally, removes the first element {@code e} such that
529	>	* {@code Objects.equals(o, e)} (if such an element exists).
530	>	* Returns {@code true} if this deque contained the specified element
531	>	* (or equivalently, if this deque changed as a result of the call).
532	>	*
533	>	* <p>This method is equivalent to {@link #removeFirstOccurrence(Object)}.
534	>	*
535	>	* @param o element to be removed from this deque, if present
536	>	* @return {@code true} if an element was removed as a result of this call
537	>	* @throws ClassCastException if the class of the specified element
538	>	*         is incompatible with this deque
539	>	* (<a href="{@docRoot}/../api/java/util/Collection.html#optional-restrictions">optional</a>)
540	>	* @throws NullPointerException if the specified element is null and this
541	>	*         deque does not permit null elements
542	>	* (<a href="{@docRoot}/../api/java/util/Collection.html#optional-restrictions">optional</a>)
543	>	*/
544	>	boolean remove(Object o);
545	>
546	>	/**
547	>	* Returns {@code true} if this deque contains the specified element.
548	>	* More formally, returns {@code true} if and only if this deque contains
549	>	* at least one element {@code e} such that {@code Objects.equals(o, e)}.
550	>	*
551	>	* @param o element whose presence in this deque is to be tested
552	>	* @return {@code true} if this deque contains the specified element
553	>	* @throws ClassCastException if the class of the specified element
554	>	*         is incompatible with this deque
555	>	* (<a href="{@docRoot}/../api/java/util/Collection.html#optional-restrictions">optional</a>)
556	>	* @throws NullPointerException if the specified element is null and this
557	>	*         deque does not permit null elements
558	>	* (<a href="{@docRoot}/../api/java/util/Collection.html#optional-restrictions">optional</a>)
559	>	*/
560	>	boolean contains(Object o);
561	>
562	>	/**
563	>	* Returns the number of elements in this deque.
564	>	*
565	>	* @return the number of elements in this deque
566	>	*/
567	>	int size();
568
569		/**
570	<	* Returns an iterator over the elements in this deque.  The elements
571	<	* will be ordered from first (head) to last (tail).
572	<	*
573	<	* @return an <tt>Iterator</tt> over the elements in this deque
570	>	* Returns an iterator over the elements in this deque in proper sequence.
571	>	* The elements will be returned in order from first (head) to last (tail).
572	>	*
573	>	* @return an iterator over the elements in this deque in proper sequence
574		*/
575		Iterator<E> iterator();
576	+
577	+	/**
578	+	* Returns an iterator over the elements in this deque in reverse
579	+	* sequential order.  The elements will be returned in order from
580	+	* last (tail) to first (head).
581	+	*
582	+	* @return an iterator over the elements in this deque in reverse
583	+	* sequence
584	+	*/
585	+	Iterator<E> descendingIterator();
586	+
587		}

Diff Legend

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