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.11 by jsr166, Tue May 17 16:00:48 2005 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 summarized in the
28		* following table:
29		*
30	<	* <p>
31	<	* <table BORDER CELLPADDING=3 CELLSPACING=1>
30	>	* <table class="striped">
31	>	* <caption>Summary of Deque methods</caption>
32	>	*  <thead>
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>
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	<	*    <td></td>
40	<	*    <td ALIGN=CENTER><em>Throws exception</em></td>
41	<	*    <td ALIGN=CENTER><em>Special value</em></td>
42	<	*    <td ALIGN=CENTER><em>Throws exception</em></td>
42	<	*    <td ALIGN=CENTER><em>Special value</em></td>
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	<	*    <td><b>Insert</b></td>
48	<	*    <td>{@link #addFirst addFirst(e)}</td>
49	<	*    <td>{@link #offerFirst offerFirst(e)}</td>
50	<	*    <td>{@link #addLast addLast(e)}</td>
51	<	*    <td>{@link #offerLast offerLast(e)}</td>
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	<	*    <td><b>Remove</b></td>
55	<	*    <td>{@link #removeFirst removeFirst()}</td>
56	<	*    <td>{@link #pollFirst pollFirst()}</td>
57	<	*    <td>{@link #removeLast removeLast()}</td>
58	<	*    <td>{@link #pollLast pollLast()}</td>
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	<	*    <td><b>Examine</b></td>
62	<	*    <td>{@link #getFirst getFirst()}</td>
63	<	*    <td>{@link #peekFirst peekFirst()}</td>
64	<	*    <td>{@link #getLast getLast()}</td>
65	<	*    <td>{@link #peekLast peekLast()}</td>
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 at 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:
73	>	* inherited from the {@code Queue} interface are precisely equivalent to
74	>	* {@code Deque} methods as indicated in the following table:
75		*
76	<	* <p>
77	<	* <table BORDER CELLPADDING=3 CELLSPACING=1>
76	>	* <table class="striped">
77	>	* <caption>Comparison of Queue and Deque methods</caption>
78	>	*  <thead>
79		*  <tr>
80	<	*    <td ALIGN=CENTER> <b><tt>Queue</tt> Method</b></td>
81	<	*    <td ALIGN=CENTER> <b>Equivalent <tt>Deque</tt> Method</b></td>
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	<	*    <td>{@link java.util.Queue#add add(e)}</td>
87	<	*    <td>{@link #addLast addLast(e)}</td>
86	>	*    <th scope="row">{@link #add(Object) add(e)}</th>
87	>	*    <td>{@link #addLast(Object) addLast(e)}</td>
88		*  </tr>
89		*  <tr>
90	<	*    <td>{@link java.util.Queue#offer offer(e)}</td>
91	<	*    <td>{@link #offerLast offerLast(e)}</td>
90	>	*    <th scope="row">{@link #offer(Object) offer(e)}</th>
91	>	*    <td>{@link #offerLast(Object) offerLast(e)}</td>
92		*  </tr>
93		*  <tr>
94	<	*    <td>{@link java.util.Queue#remove remove()}</td>
95	<	*    <td>{@link #removeFirst removeFirst()}</td>
94	>	*    <th scope="row">{@link #remove() remove()}</th>
95	>	*    <td>{@link #removeFirst() removeFirst()}</td>
96		*  </tr>
97		*  <tr>
98	<	*    <td>{@link java.util.Queue#poll poll()}</td>
99	<	*    <td>{@link #pollFirst pollFirst()}</td>
98	>	*    <th scope="row">{@link #poll() poll()}</th>
99	>	*    <td>{@link #pollFirst() pollFirst()}</td>
100		*  </tr>
101		*  <tr>
102	<	*    <td>{@link java.util.Queue#element element()}</td>
103	<	*    <td>{@link #getFirst getFirst()}</td>
102	>	*    <th scope="row">{@link #element() element()}</th>
103	>	*    <td>{@link #getFirst() getFirst()}</td>
104		*  </tr>
105		*  <tr>
106	<	*    <td>{@link java.util.Queue#peek peek()}</td>
107	<	*    <td>{@link #peek peekFirst()}</td>
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 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:
116	>	* {@code Deque} methods as indicated in the table below:
117		*
118	<	* <p>
119	<	* <table BORDER CELLPADDING=3 CELLSPACING=1>
118	>	* <table class="striped">
119	>	* <caption>Comparison of Stack and Deque methods</caption>
120	>	*  <thead>
121		*  <tr>
122	<	*    <td ALIGN=CENTER> <b>Stack Method</b></td>
123	<	*    <td ALIGN=CENTER> <b>Equivalent <tt>Deque</tt> Method</b></td>
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>{@link #push push(e)}</td>
129	<	*    <td>{@link #addFirst addFirst(e)}</td>
128	>	*    <th scope="row">{@link #push(Object) push(e)}</th>
129	>	*    <td>{@link #addFirst(Object) addFirst(e)}</td>
130		*  </tr>
131		*  <tr>
132	<	*    <td>{@link #pop pop()}</td>
133	<	*    <td>{@link #removeFirst removeFirst()}</td>
132	>	*    <th scope="row">{@link #pop() pop()}</th>
133	>	*    <td>{@link #removeFirst() removeFirst()}</td>
134		*  </tr>
135		*  <tr>
136	<	*    <td>{@link #peek peek()}</td>
137	<	*    <td>{@link #peekFirst peekFirst()}</td>
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
#	Line 139 | Line 150 | package java.util;
150		* <p>Unlike the {@link List} interface, this interface does not
151		* provide support for indexed access to elements.
152		*
153	<	* <p>While <tt>Deque</tt> implementations are not strictly required
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.
158	>	* {@code null} is used as a special return value by various methods
159	>	* to indicate 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>
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		*/
164	–
175		public interface Deque<E> extends Queue<E> {
176		/**
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	<	* When using a capacity-restricted deque, it is generally preferable to
180	<	* use method {@link #offerFirst}.
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
#	Line 182 | Line 193 | public interface Deque<E> extends Queue<
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	<	* When using a capacity-restricted deque, it is generally preferable to
199	<	* use method {@link #offerLast}.
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
#	Line 206 | Line 220 | public interface Deque<E> extends Queue<
220		* which can fail to insert an element only by throwing an exception.
221		*
222		* @param e the element to add
223	<	* @return <tt>true</tt> if the element was added to this deque, else
224	<	*         <tt>false</tt>
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
#	Line 224 | Line 238 | public interface Deque<E> extends Queue<
238		* which can fail to insert an element only by throwing an exception.
239		*
240		* @param e the element to add
241	<	* @return <tt>true</tt> if the element was added to this deque, else
242	<	*         <tt>false</tt>
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
#	Line 237 | Line 251 | public interface Deque<E> extends Queue<
251
252		/**
253		* Retrieves and removes the first element of this deque.  This method
254	<	* differs from {@link #pollFirst} only in that it throws an exception
255	<	* if this deque is empty.
254	>	* differs from {@link #pollFirst pollFirst} only in that it throws an
255	>	* exception if this deque is empty.
256		*
257		* @return the head of this deque
258		* @throws NoSuchElementException if this deque is empty
#	Line 247 | Line 261 | public interface Deque<E> extends Queue<
261
262		/**
263		* Retrieves and removes the last element of this deque.  This method
264	<	* differs from {@link #pollLast} only in that it throws an exception if
265	<	* this deque is empty.
264	>	* differs from {@link #pollLast pollLast} only in that it throws an
265	>	* exception if this deque is empty.
266		*
267		* @return the tail of this deque
268		* @throws NoSuchElementException if this deque is empty
#	Line 257 | Line 271 | public interface Deque<E> extends Queue<
271
272		/**
273		* Retrieves and removes the first element of this deque,
274	<	* or returns <tt>null</tt> if this deque is empty.
274	>	* or returns {@code null} if this deque is empty.
275		*
276	<	* @return the head of this deque, or <tt>null</tt> if 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,
282	<	* or returns <tt>null</tt> if this deque is empty.
282	>	* or returns {@code null} if this deque is empty.
283		*
284	<	* @return the tail of this deque, or <tt>null</tt> if 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		* Retrieves, but does not remove, the first element of this deque.
290	<	* This method differs from {@link #peekFirst} only in that it throws an
291	<	* exception if this deque is empty.
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 head of this deque
295		* @throws NoSuchElementException if this deque is empty
#	Line 283 | Line 298 | public interface Deque<E> extends Queue<
298
299		/**
300		* Retrieves, but does not remove, the last element of this deque.
301	<	* This method differs from {@link #peekLast} only in that it throws an
302	<	* exception if this deque is empty.
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 tail of this deque
305		* @throws NoSuchElementException if this deque is empty
#	Line 293 | Line 308 | public interface Deque<E> extends Queue<
308
309		/**
310		* Retrieves, but does not remove, the first element of this deque,
311	<	* or returns <tt>null</tt> if this deque is empty.
311	>	* or returns {@code null} if this deque is empty.
312		*
313	<	* @return the head of this deque, or <tt>null</tt> if 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	<	* or returns <tt>null</tt> if this deque is empty.
319	>	* or returns {@code null} if this deque is empty.
320		*
321	<	* @return the tail of this deque, or <tt>null</tt> if this deque is empty
321	>	* @return the tail of this deque, or {@code null} if this deque is empty
322		*/
323		E peekLast();
324
325		/**
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 <tt>e</tt> such that
329	<	* <tt>(o==null&nbsp;?&nbsp;e==null&nbsp;:&nbsp;o.equals(e))</tt>
330	<	* (if such an element exists).
331	<	* Returns true if this deque contained the specified element (or
317	<	* equivalently, if this deque changed as a result of the call).
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 <tt>true</tt> if an element was removed as a result of this call
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 (optional)
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 (optional)
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 <tt>e</tt> such that
348	<	* <tt>(o==null&nbsp;?&nbsp;e==null&nbsp;:&nbsp;o.equals(e))</tt>
349	<	* (if such an element exists).
350	<	* Returns true if this deque contained the specified element (or
335	<	* equivalently, if this deque changed as a result of the call).
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 <tt>true</tt> if an element was removed as a result of this call
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 (optional)
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 (optional)
358	>	*         deque does not permit null elements
359	>	* (<a href="{@docRoot}/../api/java/util/Collection.html#optional-restrictions">optional</a>)
360		*/
361		boolean removeLastOccurrence(Object o);
362
#	Line 349 | Line 366 | public interface Deque<E> extends Queue<
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	<	* <tt>true</tt> upon success and throwing an
370	<	* <tt>IllegalStateException</tt> if no space is currently available.
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(Object) addLast}.
374	>	* <p>This method is equivalent to {@link #addLast}.
375		*
376		* @param e the element to add
377	<	* @return <tt>true</tt> (as per the spec for {@link Collection#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
#	Line 373 | Line 390 | public interface Deque<E> extends Queue<
390		* Inserts the specified element into the queue represented by this deque
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	<	* <tt>true</tt> upon success and <tt>false</tt> if no space is currently
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.
#	Line 381 | Line 398 | public interface Deque<E> extends Queue<
398		* <p>This method is equivalent to {@link #offerLast}.
399		*
400		* @param e the element to add
401	<	* @return <tt>true</tt> if the element was added to this deque, else
402	<	*         <tt>false</tt>
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
#	Line 395 | Line 412 | public interface Deque<E> extends Queue<
412		/**
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} only in that it throws an
416	<	* exception if this deque is empty.
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 #removeFirst()}.
419		*
#	Line 408 | Line 425 | public interface Deque<E> extends Queue<
425		/**
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	<	* <tt>null</tt> if this deque is empty.
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
432	>	* @return the first element of this deque, or {@code null} if
433		*         this deque is empty
434		*/
435		E poll();
#	Line 420 | Line 437 | public interface Deque<E> extends Queue<
437		/**
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} only in that it throws an
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 #getFirst()}.
#	Line 433 | Line 450 | public interface Deque<E> extends Queue<
450		/**
451		* Retrieves, but does not remove, the head of the queue represented by
452		* this deque (in other words, the first element of this deque), or
453	<	* returns <tt>null</tt> if this deque is empty.
453	>	* returns {@code null} if this deque is empty.
454		*
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	+	* 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	+	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, at the head of this deque) if it is possible to do so
493	<	* immediately without violating capacity restrictions, returning
494	<	* <tt>true</tt> upon success and throwing an
453	<	* <tt>IllegalStateException</tt> if no space is currently available.
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		*
#	Line 484 | Line 525 | public interface Deque<E> extends Queue<
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 <tt>e</tt> such that
529	<	* <tt>(o==null&nbsp;?&nbsp;e==null&nbsp;:&nbsp;o.equals(e))</tt>
530	<	* (if such an element exists).
531	<	* Returns true if this deque contained the specified element (or
491	<	* equivalently, if this deque changed as a result of the call).
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}.
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 <tt>true</tt> if an element was removed as a result of this call
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 (optional)
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 (optional)
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 <tt>true</tt> if this deque contains the specified element.
548	<	* More formally, returns <tt>true</tt> if and only if this deque contains
549	<	* at least one element <tt>e</tt> such that
508	<	* <tt>(o==null&nbsp;?&nbsp;e==null&nbsp;:&nbsp;o.equals(e))</tt>.
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 <tt>true</tt> if this deque contains the specified element
553	<	* @throws ClassCastException if the type of the specified element
554	<	*         is incompatible with this deque (optional)
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 (optional)
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
#	Line 521 | Line 564 | public interface Deque<E> extends Queue<
564		*
565		* @return the number of elements in this deque
566		*/
567	<	public int size();
567	>	int size();
568
569		/**
570		* Returns an iterator over the elements in this deque in proper sequence.
#	Line 530 | Line 573 | public interface Deque<E> extends Queue<
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