[ViewVC] Diff of: jsr166/jsr166/src/main/java/util/Deque.java

Comparing jsr166/src/main/java/util/Deque.java (file contents):
Revision 1.7 by jsr166, Mon May 2 17:34:02 2005 UTC vs.
Revision 1.24 by jsr166, Mon Feb 11 17:27:45 2013 UTC

#	Line 1 \| Line 1
1		/*
2		* Written by Doug Lea and Josh Bloch with assistance from members of
3		* JCP JSR-166 Expert Group and released to the public domain, as explained
4	<	* at http://creativecommons.org/licenses/publicdomain
4	>	* at http://creativecommons.org/publicdomain/zero/1.0/
5		*/
6
7		package java.util;
#	Line 9 \| Line 9 \| package java.util;
9		/**
10		* A linear collection that supports element insertion and removal at
11		* both ends. The name <i>deque</i> is short for "double ended queue"
12	<	* and is usually pronounced "deck". Most <tt>Deque</tt>
12	>	* and is usually pronounced "deck". Most {@code Deque}
13		* implementations place no fixed limits on the number of elements
14		* they may contain, but this interface supports capacity-restricted
15		* deques as well as those with no fixed size limit.
#	Line 18 \| Line 18 \| package java.util;
18		* ends of the deque. Methods are provided to insert, remove, and
19		* examine the element. Each of these methods exists in two forms:
20		* one throws an exception if the operation fails, the other returns a
21	<	* special value (either <tt>null</tt> or <tt>false</tt>, depending on
21	>	* special value (either {@code null} or {@code false}, depending on
22		* the operation). The latter form of the insert operation is
23		* designed specifically for use with capacity-restricted
24	<	* <tt>Deque</tt> implementations; in most implementations, insert
24	>	* {@code Deque} implementations; in most implementations, insert
25		* operations cannot fail.
26		*
27		* <p>The twelve methods described above are summarized in the
#	Line 29 \| Line 29 \| package java.util;
29		*
30		* <p>
31		* <table BORDER CELLPADDING=3 CELLSPACING=1>
32	+	* <caption>Summary of Deque methods</caption>
33		* <tr>
34		* <td></td>
35		* <td ALIGN=CENTER COLSPAN = 2> <b>First Element (Head)</b></td>
#	Line 37 \| Line 38 \| package java.util;
38		* <tr>
39		* <td></td>
40		* <td ALIGN=CENTER><em>Throws exception</em></td>
41	<	* <td ALIGN=CENTER><em>Returns special value</em></td>
41	>	* <td ALIGN=CENTER><em>Special value</em></td>
42		* <td ALIGN=CENTER><em>Throws exception</em></td>
43	<	* <td ALIGN=CENTER><em>Returns special value</em></td>
43	>	* <td ALIGN=CENTER><em>Special value</em></td>
44		* </tr>
45		* <tr>
46		* <td><b>Insert</b></td>
#	Line 67 \| Line 68 \| package java.util;
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 at the end of the deque and removed from the beginning. The methods
71	<	* inherited from the <tt>Queue</tt> interface are precisely equivalent to
72	<	* <tt>Deque</tt> methods as indicated in the following table:
71	>	* inherited from the {@code Queue} interface are precisely equivalent to
72	>	* {@code Deque} methods as indicated in the following table:
73		*
74		* <p>
75		* <table BORDER CELLPADDING=3 CELLSPACING=1>
76	+	* <caption>Comparison of Queue and Deque methods</caption>
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>
78	<	* </tr>
79	<	* <tr>
80	<	* <td>{@link java.util.Queue#offer offer(e)}</td>
81	<	* <td>{@link #offerLast offerLast(e)}</td>
78	>	* <td ALIGN=CENTER> <b>{@code Queue} Method</b></td>
79	>	* <td ALIGN=CENTER> <b>Equivalent {@code Deque} Method</b></td>
80		* </tr>
81		* <tr>
82		* <td>{@link java.util.Queue#add add(e)}</td>
83		* <td>{@link #addLast addLast(e)}</td>
84		* </tr>
85		* <tr>
86	<	* <td>{@link java.util.Queue#poll poll()}</td>
87	<	* <td>{@link #pollFirst pollFirst()}</td>
86	>	* <td>{@link java.util.Queue#offer offer(e)}</td>
87	>	* <td>{@link #offerLast offerLast(e)}</td>
88		* </tr>
89		* <tr>
90		* <td>{@link java.util.Queue#remove remove()}</td>
91		* <td>{@link #removeFirst removeFirst()}</td>
92		* </tr>
93		* <tr>
94	<	* <td>{@link java.util.Queue#peek peek()}</td>
95	<	* <td>{@link #peek peekFirst()}</td>
94	>	* <td>{@link java.util.Queue#poll poll()}</td>
95	>	* <td>{@link #pollFirst pollFirst()}</td>
96		* </tr>
97		* <tr>
98		* <td>{@link java.util.Queue#element element()}</td>
99		* <td>{@link #getFirst getFirst()}</td>
100		* </tr>
101	+	* <tr>
102	+	* <td>{@link java.util.Queue#peek peek()}</td>
103	+	* <td>{@link #peek peekFirst()}</td>
104	+	* </tr>
105		* </table>
106		*
107		* <p>Deques can also be used as LIFO (Last-In-First-Out) stacks. This
108		* interface should be used in preference to the legacy {@link Stack} class.
109		* When a deque is used as a stack, elements are pushed and popped from the
110		* beginning of the deque. Stack methods are precisely equivalent to
111	<	* <tt>Deque</tt> methods as indicated in the table below:
111	>	* {@code Deque} methods as indicated in the table below:
112		*
113		* <p>
114		* <table BORDER CELLPADDING=3 CELLSPACING=1>
115	+	* <caption>Comparison of Stack and Deque methods</caption>
116		* <tr>
117		* <td ALIGN=CENTER> <b>Stack Method</b></td>
118	<	* <td ALIGN=CENTER> <b>Equivalent <tt>Deque</tt> Method</b></td>
118	>	* <td ALIGN=CENTER> <b>Equivalent {@code Deque} Method</b></td>
119		* </tr>
120		* <tr>
121		* <td>{@link #push push(e)}</td>
#	Line 134 \| Line 137 \| package java.util;
137		*
138		* <p>This interface provides two methods to remove interior
139		* elements, {@link #removeFirstOccurrence removeFirstOccurrence} and
140	<	* {@link #removeLastOccurrence removeLastOccurrence}. Unlike the
141	<	* {@link List} interface, this interface does not provide support for
142	<	* indexed access to elements.
140	>	* {@link #removeLastOccurrence removeLastOccurrence}.
141	>	*
142	>	* <p>Unlike the {@link List} interface, this interface does not
143	>	* provide support for indexed access to elements.
144		*
145	<	* <p>While <tt>Deque</tt> implementations are not strictly required
145	>	* <p>While {@code Deque} implementations are not strictly required
146		* to prohibit the insertion of null elements, they are strongly
147	<	* encouraged to do so. Users of any <tt>Deque</tt> implementations
147	>	* encouraged to do so. Users of any {@code Deque} implementations
148		* that do allow null elements are strongly encouraged <i>not</i> to
149		* take advantage of the ability to insert nulls. This is so because
150	<	* <tt>null</tt> is used as a special return value by various methods
150	>	* {@code null} is used as a special return value by various methods
151		* to indicated that the deque is empty.
152		*
153	<	* <p><tt>Deque</tt> implementations generally do not define
154	<	* element-based versions of the <tt>equals</tt> and <tt>hashCode</tt>
153	>	* <p>{@code Deque} implementations generally do not define
154	>	* element-based versions of the {@code equals} and {@code hashCode}
155		* methods, but instead inherit the identity-based versions from class
156	<	* <tt>Object</tt>.
156	>	* {@code Object}.
157		*
158		* <p>This interface is a member of the <a
159	<	* href="{@docRoot}/../guide/collections/index.html"> Java Collections
159	>	* href="{@docRoot}/../technotes/guides/collections/index.html"> Java Collections
160		* Framework</a>.
161		*
162		* @author Doug Lea
#	Line 160 \| Line 164 \| package java.util;
164		* @since 1.6
165		* @param <E> the type of elements held in this collection
166		*/
163	–
167		public interface Deque<E> extends Queue<E> {
168		/**
169	+	* Inserts the specified element at the front of this deque if it is
170	+	* possible to do so immediately without violating capacity restrictions.
171	+	* When using a capacity-restricted deque, it is generally preferable to
172	+	* use method {@link #offerFirst}.
173	+	*
174	+	* @param e the element to add
175	+	* @throws IllegalStateException if the element cannot be added at this
176	+	* time due to capacity restrictions
177	+	* @throws ClassCastException if the class of the specified element
178	+	* prevents it from being added to this deque
179	+	* @throws NullPointerException if the specified element is null and this
180	+	* deque does not permit null elements
181	+	* @throws IllegalArgumentException if some property of the specified
182	+	* element prevents it from being added to this deque
183	+	*/
184	+	void addFirst(E e);
185	+
186	+	/**
187	+	* Inserts the specified element at the end of this deque if it is
188	+	* possible to do so immediately without violating capacity restrictions.
189	+	* When using a capacity-restricted deque, it is generally preferable to
190	+	* use method {@link #offerLast}.
191	+	*
192	+	* <p>This method is equivalent to {@link #add}.
193	+	*
194	+	* @param e the element to add
195	+	* @throws IllegalStateException if the element cannot be added at this
196	+	* time due to capacity restrictions
197	+	* @throws ClassCastException if the class of the specified element
198	+	* prevents it from being added to this deque
199	+	* @throws NullPointerException if the specified element is null and this
200	+	* deque does not permit null elements
201	+	* @throws IllegalArgumentException if some property of the specified
202	+	* element prevents it from being added to this deque
203	+	*/
204	+	void addLast(E e);
205	+
206	+	/**
207		* Inserts the specified element at the front of this deque unless it would
208		* violate capacity restrictions. When using a capacity-restricted deque,
209	<	* this method is generally preferable to method <tt>addFirst</tt>, which
210	<	* can fail to insert an element only by throwing an exception.
209	>	* this method is generally preferable to the {@link #addFirst} method,
210	>	* which can fail to insert an element only by throwing an exception.
211		*
212	<	* @param e the element to insert
213	<	* @return <tt>true</tt> if it was possible to insert the element,
214	<	* else <tt>false</tt>
212	>	* @param e the element to add
213	>	* @return {@code true} if the element was added to this deque, else
214	>	* {@code false}
215	>	* @throws ClassCastException if the class of the specified element
216	>	* prevents it from being added to this deque
217		* @throws NullPointerException if the specified element is null and this
218	<	* deque does not permit null elements
218	>	* deque does not permit null elements
219	>	* @throws IllegalArgumentException if some property of the specified
220	>	* element prevents it from being added to this deque
221		*/
222		boolean offerFirst(E e);
223
224		/**
225		* Inserts the specified element at the end of this deque unless it would
226		* violate capacity restrictions. When using a capacity-restricted deque,
227	<	* this method is generally preferable to method <tt>addLast</tt> which
228	<	* can fail to insert an element only by throwing an exception.
227	>	* this method is generally preferable to the {@link #addLast} method,
228	>	* which can fail to insert an element only by throwing an exception.
229		*
230	<	* @param e the element to insert
231	<	* @return <tt>true</tt> if it was possible to insert the element,
232	<	* else <tt>false</tt>
230	>	* @param e the element to add
231	>	* @return {@code true} if the element was added to this deque, else
232	>	* {@code false}
233	>	* @throws ClassCastException if the class of the specified element
234	>	* prevents it from being added to this deque
235		* @throws NullPointerException if the specified element is null and this
236	<	* deque does not permit null elements
236	>	* deque does not permit null elements
237	>	* @throws IllegalArgumentException if some property of the specified
238	>	* element prevents it from being added to this deque
239		*/
240		boolean offerLast(E e);
241
242		/**
243	<	* Inserts the specified element at the front of this deque unless it
244	<	* would violate capacity restrictions.
243	>	* Retrieves and removes the first element of this deque. This method
244	>	* differs from {@link #pollFirst pollFirst} only in that it throws an
245	>	* exception if this deque is empty.
246		*
247	<	* @param e the element to insert
248	<	* @throws IllegalStateException if it was not possible to insert
199	<	* the element due to capacity restrictions
200	<	* @throws NullPointerException if the specified element is null and this
201	<	* deque does not permit null elements
247	>	* @return the head of this deque
248	>	* @throws NoSuchElementException if this deque is empty
249		*/
250	<	void addFirst(E e);
250	>	E removeFirst();
251
252		/**
253	<	* Inserts the specified element at the end of this deque unless it would
254	<	* violate capacity restrictions.
253	>	* Retrieves and removes the last element of this deque. This method
254	>	* differs from {@link #pollLast pollLast} 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
211	<	* the element due to capacity restrictions
212	<	* @throws NullPointerException if the specified element is null and this
213	<	* deque does not permit null elements
257	>	* @return the tail of this deque
258	>	* @throws NoSuchElementException if this deque is empty
259		*/
260	<	void addLast(E e);
260	>	E removeLast();
261
262		/**
263	<	* Retrieves and removes the first element of this deque, or
264	<	* <tt>null</tt> if this deque is empty.
263	>	* Retrieves and removes the first element of this deque,
264	>	* or returns {@code null} if this deque is empty.
265		*
266	<	* @return the first element of this deque, or <tt>null</tt> if
222	<	* this deque is empty
266	>	* @return the head of this deque, or {@code null} if this deque is empty
267		*/
268		E pollFirst();
269
270		/**
271	<	* Retrieves and removes the last element of this deque, or
272	<	* <tt>null</tt> if this deque is empty.
271	>	* Retrieves and removes the last element of this deque,
272	>	* or returns {@code null} if this deque is empty.
273		*
274	<	* @return the last element of this deque, or <tt>null</tt> if
231	<	* this deque is empty
274	>	* @return the tail of this deque, or {@code null} if this deque is empty
275		*/
276		E pollLast();
277
278		/**
279	<	* Retrieves and removes the first element of this deque. This method
280	<	* differs from the {@link #pollFirst} method only in that it throws an
281	<	* exception if this deque is empty.
279	>	* Retrieves, but does not remove, the first element of this deque.
280	>	*
281	>	* This method differs from {@link #peekFirst peekFirst} only in that it
282	>	* throws an exception if this deque is empty.
283		*
284	<	* @return the first element of this deque
284	>	* @return the head of this deque
285		* @throws NoSuchElementException if this deque is empty
286		*/
287	<	E removeFirst();
287	>	E getFirst();
288
289		/**
290	<	* Retrieves and removes the last element of this deque. This method
291	<	* differs from the {@link #pollLast} method only in that it throws an
292	<	* exception if this deque is empty.
290	>	* Retrieves, but does not remove, the last element of this deque.
291	>	* This method differs from {@link #peekLast peekLast} only in that it
292	>	* throws an exception if this deque is empty.
293		*
294	<	* @return the last element of this deque
294	>	* @return the tail of this deque
295		* @throws NoSuchElementException if this deque is empty
296		*/
297	<	E removeLast();
297	>	E getLast();
298
299		/**
300		* Retrieves, but does not remove, the first element of this deque,
301	<	* returning <tt>null</tt> if this deque is empty.
301	>	* or returns {@code null} if this deque is empty.
302		*
303	<	* @return the first element of this deque, or <tt>null</tt> if
260	<	* this deque is empty
303	>	* @return the head of this deque, or {@code null} if this deque is empty
304		*/
305		E peekFirst();
306
307		/**
308		* Retrieves, but does not remove, the last element of this deque,
309	<	* returning <tt>null</tt> if this deque is empty.
309	>	* or returns {@code null} if this deque is empty.
310		*
311	<	* @return the last element of this deque, or <tt>null</tt> if this deque
269	<	* is empty
311	>	* @return the tail of this deque, or {@code null} if this deque is empty
312		*/
313		E peekLast();
314
315		/**
316	<	* Retrieves, but does not remove, the first element of this
317	<	* deque. This method differs from the {@link #peekFirst} method only
318	<	* in that it throws an exception if this deque is empty.
319	<	*
320	<	* @return the first element of this deque
321	<	* @throws NoSuchElementException if this deque is empty
322	<	*/
281	<	E getFirst();
282	<
283	<	/**
284	<	* Retrieves, but does not remove, the last element of this
285	<	* deque. This method differs from the {@link #peekLast} 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
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
298	<	* such an element exists).
316	>	* Removes the first occurrence of the specified element from this deque.
317	>	* If the deque does not contain the element, it is unchanged.
318	>	* More formally, removes the first element {@code e} such that
319	>	* <tt>(o==null ? e==null : o.equals(e))</tt>
320	>	* (if such an element exists).
321	>	* Returns {@code true} if this deque contained the specified element
322	>	* (or equivalently, if this deque changed as a result of the call).
323		*
324		* @param o element to be removed from this deque, if present
325	<	* @return <tt>true</tt> if the deque contained the specified element
325	>	* @return {@code true} if an element was removed as a result of this call
326	>	* @throws ClassCastException if the class of the specified element
327	>	* is incompatible with this deque (optional)
328		* @throws NullPointerException if the specified element is null and this
329	<	* deque does not permit null elements
329	>	* deque does not permit null elements (optional)
330		*/
331		boolean removeFirstOccurrence(Object o);
332
333		/**
334	<	* Removes the last occurrence of the specified element in this
335	<	* deque. If the deque does not contain the element, it is
336	<	* unchanged. More formally, removes the last element <tt>e</tt>
337	<	* such that <tt>(o==null ? e==null : o.equals(e))</tt> (if
338	<	* such an element exists).
334	>	* Removes the last occurrence of the specified element from this deque.
335	>	* If the deque does not contain the element, it is unchanged.
336	>	* More formally, removes the last element {@code e} such that
337	>	* <tt>(o==null ? e==null : o.equals(e))</tt>
338	>	* (if such an element exists).
339	>	* Returns {@code true} if this deque contained the specified element
340	>	* (or equivalently, if this deque changed as a result of the call).
341		*
342		* @param o element to be removed from this deque, if present
343	<	* @return <tt>true</tt> if the deque contained the specified element
343	>	* @return {@code true} if an element was removed as a result of this call
344	>	* @throws ClassCastException if the class of the specified element
345	>	* is incompatible with this deque (optional)
346		* @throws NullPointerException if the specified element is null and this
347	<	* deque does not permit null elements
347	>	* deque does not permit null elements (optional)
348		*/
349		boolean removeLastOccurrence(Object o);
350
321	–
351		// * Queue methods *
352
353		/**
354		* Inserts the specified element into the queue represented by this deque
355	<	* unless it would violate capacity restrictions. In other words, inserts
356	<	* the specified element at the end of this deque. When using a
357	<	* capacity-restricted deque, this method is generally preferable to the
358	<	* {@link #add} method, which can fail to insert an element only by
359	<	* throwing an exception.
360	<	*
332	<	* <p>This method is equivalent to {@link #offerLast}.
333	<	*
334	<	* @param e the element to insert
335	<	* @return <tt>true</tt> if it was possible to insert the element,
336	<	* else <tt>false</tt>
337	<	* @throws NullPointerException if the specified element is null and this
338	<	* deque does not permit null elements
339	<	*/
340	<	boolean offer(E e);
341	<
342	<	/**
343	<	* Inserts the specified element into the queue represented by this
344	<	* deque unless it would violate capacity restrictions. In other words,
345	<	* inserts the specified element as the last element of this deque.
355	>	* (in other words, at the tail of this deque) if it is possible to do so
356	>	* immediately without violating capacity restrictions, returning
357	>	* {@code true} upon success and throwing an
358	>	* {@code IllegalStateException} if no space is currently available.
359	>	* When using a capacity-restricted deque, it is generally preferable to
360	>	* use {@link #offer(Object) offer}.
361		*
362		* <p>This method is equivalent to {@link #addLast}.
363		*
364	<	* @param e the element to insert
365	<	* @return <tt>true</tt> (as per the spec for {@link Collection#add})
366	<	* @throws IllegalStateException if it was not possible to insert
367	<	* the element due to capacity restrictions
364	>	* @param e the element to add
365	>	* @return {@code true} (as specified by {@link Collection#add})
366	>	* @throws IllegalStateException if the element cannot be added at this
367	>	* time due to capacity restrictions
368	>	* @throws ClassCastException if the class of the specified element
369	>	* prevents it from being added to this deque
370		* @throws NullPointerException if the specified element is null and this
371	<	* deque does not permit null elements
371	>	* deque does not permit null elements
372	>	* @throws IllegalArgumentException if some property of the specified
373	>	* element prevents it from being added to this deque
374		*/
375		boolean add(E e);
376
377		/**
378	<	* Retrieves and removes the head of the queue represented by
379	<	* this deque, or <tt>null</tt> if this deque is empty. In other words,
380	<	* retrieves and removes the first element of this deque, or <tt>null</tt>
381	<	* if this deque is empty.
378	>	* Inserts the specified element into the queue represented by this deque
379	>	* (in other words, at the tail of this deque) if it is possible to do so
380	>	* immediately without violating capacity restrictions, returning
381	>	* {@code true} upon success and {@code false} if no space is currently
382	>	* available. When using a capacity-restricted deque, this method is
383	>	* generally preferable to the {@link #add} method, which can fail to
384	>	* insert an element only by throwing an exception.
385		*
386	<	* <p>This method is equivalent to {@link #pollFirst()}.
386	>	* <p>This method is equivalent to {@link #offerLast}.
387		*
388	<	* @return the first element of this deque, or <tt>null</tt> if
389	<	* this deque is empty
388	>	* @param e the element to add
389	>	* @return {@code true} if the element was added to this deque, else
390	>	* {@code false}
391	>	* @throws ClassCastException if the class of the specified element
392	>	* prevents it from being added to this deque
393	>	* @throws NullPointerException if the specified element is null and this
394	>	* deque does not permit null elements
395	>	* @throws IllegalArgumentException if some property of the specified
396	>	* element prevents it from being added to this deque
397		*/
398	<	E poll();
398	>	boolean offer(E e);
399
400		/**
401	<	* Retrieves and removes the head of the queue represented by this deque.
402	<	* This method differs from the {@link #poll} method only in that it
403	<	* throws an exception if this deque is empty.
401	>	* Retrieves and removes the head of the queue represented by this deque
402	>	* (in other words, the first element of this deque).
403	>	* This method differs from {@link #poll poll} only in that it throws an
404	>	* exception if this deque is empty.
405		*
406		* <p>This method is equivalent to {@link #removeFirst()}.
407		*
#	Line 381 \| Line 411 \| public interface Deque<E> extends Queue<
411		E remove();
412
413		/**
414	<	* Retrieves, but does not remove, the head of the queue represented by
415	<	* this deque, returning <tt>null</tt> if this deque is empty.
414	>	* Retrieves and removes the head of the queue represented by this deque
415	>	* (in other words, the first element of this deque), or returns
416	>	* {@code null} if this deque is empty.
417		*
418	<	* <p>This method is equivalent to {@link #peekFirst()}.
418	>	* <p>This method is equivalent to {@link #pollFirst()}.
419		*
420	<	* @return the head of the queue represented by this deque, or
421	<	* <tt>null</tt> if this deque is empty
420	>	* @return the first element of this deque, or {@code null} if
421	>	* this deque is empty
422		*/
423	<	E peek();
423	>	E poll();
424
425		/**
426		* Retrieves, but does not remove, the head of the queue represented by
427	<	* this deque. This method differs from the {@link #peek} method only in
428	<	* that it throws an exception if this deque is empty.
427	>	* this deque (in other words, the first element of this deque).
428	>	* This method differs from {@link #peek peek} only in that it throws an
429	>	* exception if this deque is empty.
430		*
431		* <p>This method is equivalent to {@link #getFirst()}.
432		*
#	Line 403 \| Line 435 \| public interface Deque<E> extends Queue<
435		*/
436		E element();
437
438	+	/**
439	+	* Retrieves, but does not remove, the head of the queue represented by
440	+	* this deque (in other words, the first element of this deque), or
441	+	* returns {@code null} if this deque is empty.
442	+	*
443	+	* <p>This method is equivalent to {@link #peekFirst()}.
444	+	*
445	+	* @return the head of the queue represented by this deque, or
446	+	* {@code null} if this deque is empty
447	+	*/
448	+	E peek();
449	+
450
451		// * Stack methods *
452
453		/**
454	<	* Pushes an element onto the stack represented by this deque. In other
455	<	* words, inserts the element at the front of this deque unless it would
456	<	* violate capacity restrictions.
454	>	* Pushes an element onto the stack represented by this deque (in other
455	>	* words, at the head of this deque) if it is possible to do so
456	>	* immediately without violating capacity restrictions, returning
457	>	* {@code true} upon success and throwing an
458	>	* {@code IllegalStateException} if no space is currently available.
459		*
460		* <p>This method is equivalent to {@link #addFirst}.
461		*
462		* @param e the element to push
463	<	* @throws IllegalStateException if it was not possible to insert
464	<	* the element due to capacity restrictions
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
468	>	* deque does not permit null elements
469	>	* @throws IllegalArgumentException if some property of the specified
470	>	* element prevents it from being added to this deque
471		*/
472		void push(E e);
473
#	Line 428 \| Line 478 \| public interface Deque<E> extends Queue<
478		* <p>This method is equivalent to {@link #removeFirst()}.
479		*
480		* @return the element at the front of this deque (which is the top
481	<	* of the stack represented by this deque)
481	>	* of the stack represented by this deque)
482		* @throws NoSuchElementException if this deque is empty
483		*/
484		E pop();
485
486
487	<	// * Collection Method *
487	>	// * Collection methods *
488
489		/**
490	<	* Returns an iterator over the elements in this deque. The elements
491	<	* will be ordered from first (head) to last (tail).
490	>	* Removes the first occurrence of the specified element from this deque.
491	>	* If the deque does not contain the element, it is unchanged.
492	>	* More formally, removes the first element {@code e} such that
493	>	* <tt>(o==null ? e==null : o.equals(e))</tt>
494	>	* (if such an element exists).
495	>	* Returns {@code true} if this deque contained the specified element
496	>	* (or equivalently, if this deque changed as a result of the call).
497		*
498	<	* @return an <tt>Iterator</tt> over the elements in this deque
498	>	* <p>This method is equivalent to {@link #removeFirstOccurrence(Object)}.
499	>	*
500	>	* @param o element to be removed from this deque, if present
501	>	* @return {@code true} if an element was removed as a result of this call
502	>	* @throws ClassCastException if the class of the specified element
503	>	* is incompatible with this deque (optional)
504	>	* @throws NullPointerException if the specified element is null and this
505	>	* deque does not permit null elements (optional)
506	>	*/
507	>	boolean remove(Object o);
508	>
509	>	/**
510	>	* Returns {@code true} if this deque contains the specified element.
511	>	* More formally, returns {@code true} if and only if this deque contains
512	>	* at least one element {@code e} such that
513	>	* <tt>(o==null ? e==null : o.equals(e))</tt>.
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 type of the specified element
518	>	* is incompatible with this deque (optional)
519	>	* @throws NullPointerException if the specified element is null and this
520	>	* deque does not permit null elements (optional)
521	>	*/
522	>	boolean contains(Object o);
523	>
524	>	/**
525	>	* Returns the number of elements in this deque.
526	>	*
527	>	* @return the number of elements in this deque
528	>	*/
529	>	public int size();
530	>
531	>	/**
532	>	* Returns an iterator over the elements in this deque in proper sequence.
533	>	* The elements will be returned in order from first (head) to last (tail).
534	>	*
535	>	* @return an iterator over the elements in this deque in proper sequence
536		*/
537		Iterator<E> iterator();
538	+
539	+	/**
540	+	* Returns an iterator over the elements in this deque in reverse
541	+	* sequential order. The elements will be returned in order from
542	+	* last (tail) to first (head).
543	+	*
544	+	* @return an iterator over the elements in this deque in reverse
545	+	* sequence
546	+	*/
547	+	Iterator<E> descendingIterator();
548	+
549		}

Diff Legend

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

Comparing jsr166/src/main/java/util/Deque.java (file contents): Revision 1.7 by jsr166, Mon May 2 17:34:02 2005 UTC vs. Revision 1.24 by jsr166, Mon Feb 11 17:27:45 2013 UTC

Diff Legend

Comparing jsr166/src/main/java/util/Deque.java (file contents):
Revision 1.7 by jsr166, Mon May 2 17:34:02 2005 UTC vs.
Revision 1.24 by jsr166, Mon Feb 11 17:27:45 2013 UTC