ViewVC Help

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

root/jsr166/jsr166/src/jsr166x/Deque.java

Comparing jsr166/src/jsr166x/Deque.java (file contents):
Revision 1.1 by dl, Sun Sep 5 21:28:19 2004 UTC vs.
Revision 1.13 by jsr166, Sun Jan 18 20:17:33 2015 UTC

#	Line 1 | Line 1
1		/*
2	<	* Written by Doug Lea with assistance from members of JCP JSR-166
3	<	* Expert Group and released to the public domain, as explained at
4	<	* http://creativecommons.org/licenses/publicdomain
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/publicdomain/zero/1.0/
5		*/
6
7	<	package jsr166x;
8	<	import java.util.*;
7	>	package jsr166x;     // XXX This belongs in java.util!!! XXX
8	>
9	>	import java.util.*;    // XXX This import goes away        XXX
10
11		/**
12	<	* A linear collection in which elements may be inserted and removed
13	<	* from both the beginning and end. A <tt>Deque</tt> (short for
14	<	* "double ended queue") provides uniformly named methods to
15	<	* <tt>get</tt>, <tt>peek</tt>, <tt>poll</tt>, <tt>remove</tt>,
16	<	* <tt>offer</tt>, and <tt>add</tt> the <tt>first</tt> and
17	<	* <tt>last</tt> element of the collection (for example, methods
18	<	* <tt>addFirst</tt>, <tt>pollLast</tt>). Unlike interface {@link
19	<	* List} the Deque interface does not define support for indexed
20	<	* operations or sublists.
21	<	*
22	<	* <p>A view of a subset of Deque operations can be obtained using
23	<	* method {@link #asFIFO} to support only Last-In-First-Out (LIFO)
24	<	* stack behavior, as well as method {@link #asFIFO} to support only
25	<	* First-in-First-Out (FIFO) queue behavior.  More commonly, a Deque
26	<	* is used when various mixtures of LIFO and FIFO operations are
27	<	* required.
28	<	*
29	<	* <p>Deques additionally provide a few methods to manipulate elements
30	<	* embedded within a deque, proceding from either direction:
31	<	* <tt>removeFirstOccurrence</tt>, <tt>replaceFirstOccurrence</tt>
32	<	* <tt>removeLastOccurrence</tt>, and <tt>replaceLastOccurrence</tt>.
33	<	* They also support {@link Collection} operations including
34	<	* <tt>contains</tt>, <tt>iterator</tt>, and so on.
35	<	*
36	<	* <p>The {@link #offerFirst} and {@link #offerLast} methods insert an
37	<	* element if possible, otherwise returning <tt>false</tt>.  They
38	<	* differ from {@link java.util.Collection#add Collection.add}, as
39	<	* well as {@link #addFirst} and {@link #addLast} methods, which can
40	<	* fail to add an element only by throwing an unchecked exception.
41	<	* The <tt>offer</tt> methods are designed for use when failure is a
42	<	* normal, rather than exceptional occurrence, for example, in
43	<	* fixed-capacity (or &quot;bounded&quot;) deques.
44	<	*
45	<	* <p><tt>Deque</tt> implementations generally do not allow insertion
46	<	* of <tt>null</tt> elements.  Even in implementations that permit it,
47	<	* <tt>null</tt> should not be inserted into a <tt>Deque</tt>, as
48	<	* <tt>null</tt> is also used as a special return value by the poll
49	<	* methods to indicate that the deque contains no elements.
50	<	*
51	<	* <p><tt>Deque</tt> implementations generally do not define
52	<	* element-based versions of methods <tt>equals</tt> and
53	<	* <tt>hashCode</tt> but instead inherit the identity based versions
54	<	* from class <tt>Object</tt>.
12	>	* A linear collection that supports element insertion and removal at
13	>	* both ends.  The name <i>deque</i> is short for "double ended queue"
14	>	* and is usually pronounced "deck".  Most {@code Deque}
15	>	* implementations place no fixed limits on the number of elements
16	>	* they may contain, but this interface supports capacity-restricted
17	>	* deques as well as those with no fixed size limit.
18	>	*
19	>	* <p>This interface defines methods to access the elements at both
20	>	* ends of the deque.  Methods are provided to insert, remove, and
21	>	* examine the element.  Each of these methods exists in two forms:
22	>	* one throws an exception if the operation fails, the other returns a
23	>	* special value (either {@code null} or {@code false}, depending on
24	>	* the operation).  The latter form of the insert operation is
25	>	* designed specifically for use with capacity-restricted
26	>	* {@code Deque} implementations; in most implementations, insert
27	>	* operations cannot fail.
28	>	*
29	>	* <p>The twelve methods described above are summarized in the
30	>	* following table:<p>
31	>	*
32	>	* <table BORDER CELLPADDING=3 CELLSPACING=1>
33	>	*  <tr>
34	>	*    <td></td>
35	>	*    <td ALIGN=CENTER COLSPAN = 2> <b>First Element (Head)</b></td>
36	>	*    <td ALIGN=CENTER COLSPAN = 2> <b>Last Element (Tail)</b></td>
37	>	*  </tr>
38	>	*  <tr>
39	>	*    <td></td>
40	>	*    <td ALIGN=CENTER><em>Throws exception</em></td>
41	>	*    <td ALIGN=CENTER><em>Returns special value</em></td>
42	>	*    <td ALIGN=CENTER><em>Throws exception</em></td>
43	>	*    <td ALIGN=CENTER><em>Returns special value</em></td>
44	>	*  </tr>
45	>	*  <tr>
46	>	*    <td><b>Insert</b></td>
47	>	*    <td>{@link #addFirst addFirst(e)}</td>
48	>	*    <td>{@link #offerFirst offerFirst(e)}</td>
49	>	*    <td>{@link #addLast addLast(e)}</td>
50	>	*    <td>{@link #offerLast offerLast(e)}</td>
51	>	*  </tr>
52	>	*  <tr>
53	>	*    <td><b>Remove</b></td>
54	>	*    <td>{@link #removeFirst removeFirst()}</td>
55	>	*    <td>{@link #pollFirst pollFirst()}</td>
56	>	*    <td>{@link #removeLast removeLast()}</td>
57	>	*    <td>{@link #pollLast pollLast()}</td>
58	>	*  </tr>
59	>	*  <tr>
60	>	*    <td><b>Examine</b></td>
61	>	*    <td>{@link #getFirst getFirst()}</td>
62	>	*    <td>{@link #peekFirst peekFirst()}</td>
63	>	*    <td>{@link #getLast getLast()}</td>
64	>	*    <td>{@link #peekLast peekLast()}</td>
65	>	*  </tr>
66	>	* </table>
67	>	*
68	>	* <p>This interface extends the {@link Queue} interface.  When a deque is
69	>	* used as a queue, FIFO (First-In-First-Out) behavior results.  Elements are
70	>	* added to the end of the deque and removed from the beginning.  The methods
71	>	* inherited from the {@code Queue} interface are precisely equivalent to
72	>	* {@code Deque} methods as indicated in the following table:<p>
73	>	*
74	>	* <table BORDER CELLPADDING=3 CELLSPACING=1>
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	>	*   <tr>
81	>	*    <td>{@link java.util.Queue#offer offer(e)}</td>
82	>	*    <td>{@link #offerLast offerLast(e)}</td>
83	>	*   </tr>
84	>	*   <tr>
85	>	*    <td>{@link java.util.Queue#add add(e)}</td>
86	>	*    <td>{@link #addLast addLast(e)}</td>
87	>	*   </tr>
88	>	*   <tr>
89	>	*    <td>{@link java.util.Queue#poll poll()}</td>
90	>	*    <td>{@link #pollFirst pollFirst()}</td>
91	>	*   </tr>
92	>	*   <tr>
93	>	*    <td>{@link java.util.Queue#remove remove()}</td>
94	>	*    <td>{@link #removeFirst removeFirst()}</td>
95	>	*   </tr>
96	>	*   <tr>
97	>	*    <td>{@link java.util.Queue#peek peek()}</td>
98	>	*    <td>{@link #peek peekFirst()}</td>
99	>	*   </tr>
100	>	*   <tr>
101	>	*    <td>{@link java.util.Queue#element element()}</td>
102	>	*    <td>{@link #getFirst getFirst()}</td>
103	>	*   </tr>
104	>	* </table>
105	>	*
106	>	* <p>Deques can also be used as LIFO (Last-In-First-Out) stacks.  This
107	>	* interface should be used in preference to the legacy {@link Stack} class.
108	>	* When a dequeue is used as a stack, elements are pushed and popped from the
109	>	* beginning of the deque.  Stack methods are precisely equivalent to
110	>	* {@code Deque} methods as indicated in the table below:<p>
111	>	*
112	>	* <table BORDER CELLPADDING=3 CELLSPACING=1>
113	>	*  <tr>
114	>	*    <td ALIGN=CENTER> <b>Stack Method</b></td>
115	>	*    <td ALIGN=CENTER> <b>Equivalent {@code Deque} Method</b></td>
116	>	*  </tr>
117	>	*  <tr>
118	>	*   <tr>
119	>	*    <td>{@link #push push(e)}</td>
120	>	*    <td>{@link #addFirst addFirst(e)}</td>
121	>	*   </tr>
122	>	*   <tr>
123	>	*    <td>{@link #pop pop()}</td>
124	>	*    <td>{@link #removeFirst removeFirst()}</td>
125	>	*   </tr>
126	>	*   <tr>
127	>	*    <td>{@link #peek peek()}</td>
128	>	*    <td>{@link #peekFirst peekFirst()}</td>
129	>	*   </tr>
130	>	* </table>
131	>	*
132	>	* <p>Note that the {@link #peek peek} method works equally well when
133	>	* a deque is used as a queue or a stack; in either case, elements are
134	>	* drawn from the beginning of the deque.
135	>	*
136	>	* <p>This interface provides two methods to remove interior
137	>	* elements, {@link #removeFirstOccurrence removeFirstOccurrence} and
138	>	* {@link #removeLastOccurrence removeLastOccurrence}.  Unlike the
139	>	* {@link List} interface, this interface does not provide support for
140	>	* indexed access to elements.
141	>	*
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 {@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	>	* {@code null} is used as a special return value by various methods
148	>	* to indicated 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	>	* {@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>.
158		*
159		* @author Doug Lea
160	+	* @author Josh Bloch
161	+	* @since  1.6
162		* @param <E> the type of elements held in this collection
163		*/
164	<	public interface Deque<E> extends Collection<E> {
63	<
164	>	public interface Deque<E> extends Queue<E> {
165		/**
166	<	* Inserts the specified element to the front this deque, if
167	<	* possible.  When using deques that may impose insertion
168	<	* restrictions (for example capacity bounds), method
169	<	* <tt>offerFirst</tt> is generally preferable to method
69	<	* <tt>addFirst</tt> which can fail to insert a non-duplicate
70	<	* element only by throwing an exception.
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 {@code addFirst}, which
169	>	* can fail to insert an element only by throwing an exception.
170		*
171	<	* @param o the element to insert.
172	<	* @return <tt>true</tt> if it was possible to add the element to
173	<	* this deque, else <tt>false</tt>
171	>	* @param e the element to insert
172	>	* @return {@code true} if it was possible to insert the element,
173	>	*     else {@code false}
174	>	* @throws NullPointerException if {@code e} is null and this
175	>	*     deque does not permit null elements
176		*/
177	<	boolean offerFirst(E o);
177	>	boolean offerFirst(E e);
178
179		/**
180	<	* Inserts the specified element to the end this deque, if
181	<	* possible.  When using deques that may impose insertion
182	<	* restrictions (for example capacity bounds), method
183	<	* <tt>offerFirst</tt> is generally preferable to method
83	<	* <tt>addLast</tt> which can fail to insert a non-duplicate
84	<	* element only by throwing an exception.
180	>	* Inserts the specified element to the end of this deque unless it would
181	>	* violate capacity restrictions.  When using a capacity-restricted deque,
182	>	* this method is generally preferable to method {@code addLast} which
183	>	* can fail to insert an element only by throwing an exception.
184		*
185	<	* @param o the element to insert.
186	<	* @return <tt>true</tt> if it was possible to add the element to
187	<	* this deque, else <tt>false</tt>
185	>	* @param e the element to insert
186	>	* @return {@code true} if it was possible to insert the element,
187	>	*     else {@code false}
188	>	* @throws NullPointerException if {@code e} is null and this
189	>	*     deque does not permit null elements
190		*/
191	<	boolean offerLast(E o);
191	>	boolean offerLast(E e);
192
193		/**
194	<	* Inserts the specified element to the front this deque, if
195	<	* this deque permits insertion of the given element.  This
95	<	* method has the same semantics as {@link Collection#add}.
194	>	* Inserts the specified element to the front of this deque unless it
195	>	* would violate capacity restrictions.
196		*
197	<	* @param o the element to insert.
198	<	* @return <tt>true</tt> if this deque changed as a result of this
199	<	* call, else <tt>false</tt>
197	>	* @param e the element to insert
198	>	* @throws IllegalStateException if it was not possible to insert
199	>	*    the element due to capacity restrictions
200	>	* @throws NullPointerException if {@code e} is null and this
201	>	*     deque does not permit null elements
202		*/
203	<	boolean addFirst(E o);
203	>	void addFirst(E e);
204
205		/**
206	<	* Inserts the specified element to the end this deque, if
207	<	* this deque permits insertion of the given element.  This
106	<	* method has the same semantics as {@link Collection#add}.
206	>	* Inserts the specified element to the end of this deque unless it would
207	>	* violate capacity restrictions.
208		*
209	<	* @param o the element to insert.
210	<	* @return <tt>true</tt> if this deque changed as a result of this
211	<	* call, else <tt>false</tt>
209	>	* @param e the element to insert
210	>	* @throws IllegalStateException if it was not possible to insert
211	>	*    the element due to capacity restrictions
212	>	* @throws NullPointerException if {@code e} is null and this
213	>	*     deque does not permit null elements
214		*/
215	<	boolean addLast(E o);
215	>	void addLast(E e);
216
217		/**
218		* Retrieves and removes the first element of this deque, or
219	<	* <tt>null</tt> if this deque is empty.
219	>	* {@code null} if this deque is empty.
220		*
221	<	* @return the first element of this deque, or <tt>null</tt> if
222	<	* this deque is empty.
221	>	* @return the first element of this deque, or {@code null} if
222	>	*     this deque is empty
223		*/
224		E pollFirst();
225
226		/**
227		* Retrieves and removes the last element of this deque, or
228	<	* <tt>null</tt> if this deque is empty.
228	>	* {@code null} if this deque is empty.
229		*
230	<	* @return the last element of this deque, or <tt>null</tt> if
231	<	* this deque is empty.
230	>	* @return the last element of this deque, or {@code null} if
231	>	*     this deque is empty
232		*/
233		E pollLast();
234
235		/**
236	<	* Retrieves and removes the first element of this deque.  This method
237	<	* differs from the <tt>pollFirst</tt> method in that it throws an
236	>	* Removes and returns the first element of this deque.  This method
237	>	* differs from the {@code pollFirst} method only in that it throws an
238		* exception if this deque is empty.
239		*
240	<	* @return the first element of this deque.
241	<	* @throws NoSuchElementException if this deque is empty.
240	>	* @return the first element of this deque
241	>	* @throws NoSuchElementException if this deque is empty
242		*/
243		E removeFirst();
244
245		/**
246		* Retrieves and removes the last element of this deque.  This method
247	<	* differs from the <tt>pollLast</tt> method in that it throws an
247	>	* differs from the {@code pollLast} method only in that it throws an
248		* exception if this deque is empty.
249		*
250	<	* @return the last element of this deque.
251	<	* @throws NoSuchElementException if this deque is empty.
250	>	* @return the last element of this deque
251	>	* @throws NoSuchElementException if this deque is empty
252		*/
253		E removeLast();
254
255		/**
256		* Retrieves, but does not remove, the first element of this deque,
257	<	* returning <tt>null</tt> if this deque is empty.
257	>	* returning {@code null} if this deque is empty.
258		*
259	<	* @return the first element of this deque, or <tt>null</tt> if
260	<	* this deque is empty.
259	>	* @return the first element of this deque, or {@code null} if
260	>	*     this deque is empty
261		*/
262		E peekFirst();
263
264		/**
265		* Retrieves, but does not remove, the last element of this deque,
266	<	* returning <tt>null</tt> if this deque is empty.
266	>	* returning {@code null} if this deque is empty.
267		*
268	<	* @return the last element of this deque, or <tt>null</tt> if this deque
269	<	* is empty.
268	>	* @return the last element of this deque, or {@code null} if this deque
269	>	*     is empty
270		*/
271		E peekLast();
272
273		/**
274		* Retrieves, but does not remove, the first element of this
275	<	* deque.  This method differs from the <tt>peek</tt> method only
275	>	* deque.  This method differs from the {@code peek} method only
276		* in that it throws an exception if this deque is empty.
277		*
278	<	* @return the first element of this deque.
279	<	* @throws NoSuchElementException if this deque is empty.
278	>	* @return the first element of this deque
279	>	* @throws NoSuchElementException if this deque is empty
280		*/
281		E getFirst();
282
283		/**
284		* Retrieves, but does not remove, the last element of this
285	<	* deque.  This method differs from the <tt>peek</tt> method only
285	>	* deque.  This method differs from the {@code peek} method only
286		* in that it throws an exception if this deque is empty.
287		*
288	<	* @return the last element of this deque.
289	<	* @throws NoSuchElementException if this deque is empty.
288	>	* @return the last element of this deque
289	>	* @throws NoSuchElementException if this deque is empty
290		*/
291		E getLast();
292
293		/**
294		* Removes the first occurrence of the specified element in this
295		* deque.  If the deque does not contain the element, it is
296	<	* unchanged.  More formally, removes the first element <tt>e</tt>
297	<	* such that <tt>(o==null ? e==null : o.equals(e))</tt> (if
296	>	* unchanged.  More formally, removes the first element {@code e}
297	>	* such that {@code (o==null ? e==null : o.equals(e))} (if
298		* such an element exists).
299		*
300	<	* @param o element to be removed from this deque, if present.
301	<	* @return <tt>true</tt> if the deque contained the specified element.
302	<	* @throws NullPointerException if the specified element is <tt>null</tt>
300	>	* @param e element to be removed from this deque, if present
301	>	* @return {@code true} if the deque contained the specified element
302	>	* @throws NullPointerException if the specified element is {@code null}
303		*/
304	<	boolean removeFirstOccurrence(E o);
304	>	boolean removeFirstOccurrence(Object e);
305
306		/**
307		* Removes the last occurrence of the specified element in this
308		* deque.  If the deque does not contain the element, it is
309	<	* unchanged.  More formally, removes the last element <tt>e</tt>
310	<	* such that <tt>(o==null ? e==null : o.equals(e))</tt> (if
309	>	* unchanged.  More formally, removes the last element {@code e}
310	>	* such that {@code (o==null ? e==null : o.equals(e))} (if
311		* such an element exists).
312		*
313	<	* @param o element to be removed from this deque, if present.
314	<	* @return <tt>true</tt> if the deque contained the specified element.
315	<	* @throws NullPointerException if the specified element is <tt>null</tt>
313	>	* @param e element to be removed from this deque, if present
314	>	* @return {@code true} if the deque contained the specified element
315	>	* @throws NullPointerException if the specified element is {@code null}
316		*/
317	<	boolean removeLastOccurrence(E o);
317	>	boolean removeLastOccurrence(Object e);
318	>
319	>
320	>	// *** Queue methods ***
321
322		/**
323	<	* Replaces the first occurrence of the specified element in this
324	<	* deque.  If the deque does not contain the element, it is
325	<	* unchanged.  More formally, replaces the first element <tt>e</tt>
326	<	* such that <tt>(o==null ? e==null : o.equals(e))</tt> (if
327	<	* such an element exists).
323	>	* Inserts the specified element into the queue represented by this deque
324	>	* unless it would violate capacity restrictions.  In other words, inserts
325	>	* the specified element to the end of this deque.  When using a
326	>	* capacity-restricted deque, this method is generally preferable to the
327	>	* {@link #add} method, which can fail to insert an element only by
328	>	* throwing an exception.
329		*
330	<	* @param oldElement element to be replaced in this deque, if present.
331	<	* @param newElement replacement value
332	<	* @return <tt>true</tt> if an element was replaced
330	>	* <p>This method is equivalent to {@link #offerLast}.
331	>	*
332	>	* @param e the element to insert
333	>	* @return {@code true} if it was possible to insert the element,
334	>	*     else {@code false}
335	>	* @throws NullPointerException if {@code e} is null and this
336	>	*     deque does not permit null elements
337		*/
338	<	public boolean replaceFirstOccurrence(E oldElement, E newElement);
338	>	boolean offer(E e);
339
340		/**
341	<	* Replaces the last occurrence of the specified element in this
342	<	* deque.  If the deque does not contain the element, it is
343	<	* unchanged.  More formally, replaces the last element <tt>e</tt>
344	<	* such that <tt>(o==null ? e==null : o.equals(e))</tt> (if
345	<	* such an element exists).
341	>	* Inserts the specified element into the queue represented by this
342	>	* deque unless it would violate capacity restrictions.  In other words,
343	>	* inserts the specified element as the last element of this deque.
344	>	*
345	>	* <p>This method is equivalent to {@link #addLast}.
346	>	*
347	>	* @param e the element to insert
348	>	* @return {@code true} (as per the spec for {@link Collection#add})
349	>	* @throws IllegalStateException if it was not possible to insert
350	>	*    the element due to capacity restrictions
351	>	* @throws NullPointerException if {@code e} is null and this
352	>	*     deque does not permit null elements
353	>	*/
354	>	boolean add(E e);
355	>
356	>	/**
357	>	* Retrieves and removes the head of the queue represented by
358	>	* this deque, or {@code null} if this deque is empty.  In other words,
359	>	* retrieves and removes the first element of this deque, or {@code null}
360	>	* if this deque is empty.
361	>	*
362	>	* <p>This method is equivalent to {@link #pollFirst()}.
363		*
364	<	* @param oldElement element to be replaced in this deque, if present.
365	<	* @param newElement replacement value
238	<	* @return <tt>true</tt> if an element was replaced
364	>	* @return the first element of this deque, or {@code null} if
365	>	*     this deque is empty
366		*/
367	<	public boolean replaceLastOccurrence(E oldElement, E newElement);
367	>	E poll();
368
369		/**
370	<	* Returns a view of this deque as a first-in-first-out queue,
371	<	* mapping {@link Queue#offer} to <tt>offerLast</tt>, {@link
372	<	* Queue#poll} to <tt>pollFirst</tt>, and other operations
373	<	* accordingly.
374	<	* @return a first-in-first-out view of this deque.
370	>	* Retrieves and removes the head of the queue represented by this deque.
371	>	* This method differs from the {@code poll} method only in that it
372	>	* throws an exception if this deque is empty.
373	>	*
374	>	* <p>This method is equivalent to {@link #removeFirst()}.
375	>	*
376	>	* @return the head of the queue represented by this deque
377	>	* @throws NoSuchElementException if this deque is empty
378	>	*/
379	>	E remove();
380	>
381	>	/**
382	>	* Retrieves, but does not remove, the head of the queue represented by
383	>	* this deque, returning {@code null} if this deque is empty.
384	>	*
385	>	* <p>This method is equivalent to {@link #peekFirst()}.
386	>	*
387	>	* @return the head of the queue represented by this deque, or
388	>	*     {@code null} if this deque is empty
389	>	*/
390	>	E peek();
391	>
392	>	/**
393	>	* Retrieves, but does not remove, the head of the queue represented by
394	>	* this deque.  This method differs from the {@code peek} method only in
395	>	* that it throws an exception if this deque is empty.
396	>	*
397	>	* <p>This method is equivalent to {@link #getFirst()}.
398	>	*
399	>	* @return the head of the queue represented by this deque
400	>	* @throws NoSuchElementException if this deque is empty
401	>	*/
402	>	E element();
403	>
404	>
405	>	// *** Stack methods ***
406	>
407	>	/**
408	>	* Pushes an element onto the stack represented by this deque.  In other
409	>	* words, inserts the element to the front this deque unless it would
410	>	* violate capacity restrictions.
411	>	*
412	>	* <p>This method is equivalent to {@link #addFirst}.
413	>	*
414	>	* @throws IllegalStateException if it was not possible to insert
415	>	*    the element due to capacity restrictions
416	>	* @throws NullPointerException if {@code e} is null and this
417	>	*     deque does not permit null elements
418		*/
419	<	public Queue<E> asFIFO();
419	>	void push(E e);
420
421		/**
422	<	* Returns a view of this deque as a first-in-Last-out stack,
423	<	* mapping {@link Queue#offer} to <tt>offerFirst</tt>, {@link
424	<	* Queue#poll} to <tt>pollFirst</tt>, and other operations
425	<	* accordingly.
426	<	* @return a first-in-last-out view of this deque.
422	>	* Pops an element from the stack represented by this deque.  In other
423	>	* words, removes and returns the first element of this deque.
424	>	*
425	>	* <p>This method is equivalent to {@link #removeFirst()}.
426	>	*
427	>	* @return the element at the front of this deque (which is the top
428	>	*     of the stack represented by this deque)
429	>	* @throws NoSuchElementException if this deque is empty
430		*/
431	<	public Queue<E> asLIFO();
431	>	E pop();
432	>
433	>
434	>	// *** Collection Method ***
435
436	+	/**
437	+	* Returns an iterator over the elements in this deque.  The elements
438	+	* will be ordered from first (head) to last (tail).
439	+	*
440	+	* @return an {@code Iterator} over the elements in this deque
441	+	*/
442	+	Iterator<E> iterator();
443		}

Diff Legend

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