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.23 by jsr166, Mon Feb 11 07:42:43 2013 UTC vs.
Revision 1.39 by jsr166, Wed May 31 19:02:33 2017 UTC

#	Line 27 | Line 27 | package java.util;
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="plain">
31	>	* <caption>Summary of Deque methods</caption>
32		*  <tr>
33		*    <td></td>
34	<	*    <td ALIGN=CENTER COLSPAN = 2> <b>First Element (Head)</b></td>
35	<	*    <td ALIGN=CENTER COLSPAN = 2> <b>Last Element (Tail)</b></td>
34	>	*    <td style="text-align:center" COLSPAN = 2> <b>First Element (Head)</b></td>
35	>	*    <td style="text-align:center" COLSPAN = 2> <b>Last Element (Tail)</b></td>
36		*  </tr>
37		*  <tr>
38		*    <td></td>
39	<	*    <td ALIGN=CENTER><em>Throws exception</em></td>
40	<	*    <td ALIGN=CENTER><em>Special value</em></td>
41	<	*    <td ALIGN=CENTER><em>Throws exception</em></td>
42	<	*    <td ALIGN=CENTER><em>Special value</em></td>
39	>	*    <td style="text-align:center"><em>Throws exception</em></td>
40	>	*    <td style="text-align:center"><em>Special value</em></td>
41	>	*    <td style="text-align:center"><em>Throws exception</em></td>
42	>	*    <td style="text-align:center"><em>Special value</em></td>
43		*  </tr>
44		*  <tr>
45		*    <td><b>Insert</b></td>
46	<	*    <td>{@link #addFirst addFirst(e)}</td>
47	<	*    <td>{@link #offerFirst offerFirst(e)}</td>
48	<	*    <td>{@link #addLast addLast(e)}</td>
49	<	*    <td>{@link #offerLast offerLast(e)}</td>
46	>	*    <td>{@link #addFirst(Object) addFirst(e)}</td>
47	>	*    <td>{@link #offerFirst(Object) offerFirst(e)}</td>
48	>	*    <td>{@link #addLast(Object) addLast(e)}</td>
49	>	*    <td>{@link #offerLast(Object) offerLast(e)}</td>
50		*  </tr>
51		*  <tr>
52		*    <td><b>Remove</b></td>
53	<	*    <td>{@link #removeFirst removeFirst()}</td>
54	<	*    <td>{@link #pollFirst pollFirst()}</td>
55	<	*    <td>{@link #removeLast removeLast()}</td>
56	<	*    <td>{@link #pollLast pollLast()}</td>
53	>	*    <td>{@link #removeFirst() removeFirst()}</td>
54	>	*    <td>{@link #pollFirst() pollFirst()}</td>
55	>	*    <td>{@link #removeLast() removeLast()}</td>
56	>	*    <td>{@link #pollLast() pollLast()}</td>
57		*  </tr>
58		*  <tr>
59		*    <td><b>Examine</b></td>
60	<	*    <td>{@link #getFirst getFirst()}</td>
61	<	*    <td>{@link #peekFirst peekFirst()}</td>
62	<	*    <td>{@link #getLast getLast()}</td>
63	<	*    <td>{@link #peekLast peekLast()}</td>
60	>	*    <td>{@link #getFirst() getFirst()}</td>
61	>	*    <td>{@link #peekFirst() peekFirst()}</td>
62	>	*    <td>{@link #getLast() getLast()}</td>
63	>	*    <td>{@link #peekLast() peekLast()}</td>
64		*  </tr>
65		* </table>
66		*
#	Line 70 | Line 70 | package java.util;
70		* inherited from the {@code Queue} interface are precisely equivalent to
71		* {@code Deque} methods as indicated in the following table:
72		*
73	<	* <p>
74	<	* <table BORDER CELLPADDING=3 CELLSPACING=1>
73	>	* <table class="plain">
74	>	* <caption>Comparison of Queue and Deque methods</caption>
75		*  <tr>
76	<	*    <td ALIGN=CENTER> <b>{@code Queue} Method</b></td>
77	<	*    <td ALIGN=CENTER> <b>Equivalent {@code Deque} Method</b></td>
76	>	*    <td style="text-align:center"> <b>{@code Queue} Method</b></td>
77	>	*    <td style="text-align:center"> <b>Equivalent {@code Deque} Method</b></td>
78		*  </tr>
79		*  <tr>
80	<	*    <td>{@link java.util.Queue#add add(e)}</td>
81	<	*    <td>{@link #addLast addLast(e)}</td>
80	>	*    <td>{@link #add(Object) add(e)}</td>
81	>	*    <td>{@link #addLast(Object) addLast(e)}</td>
82		*  </tr>
83		*  <tr>
84	<	*    <td>{@link java.util.Queue#offer offer(e)}</td>
85	<	*    <td>{@link #offerLast offerLast(e)}</td>
84	>	*    <td>{@link #offer(Object) offer(e)}</td>
85	>	*    <td>{@link #offerLast(Object) offerLast(e)}</td>
86		*  </tr>
87		*  <tr>
88	<	*    <td>{@link java.util.Queue#remove remove()}</td>
89	<	*    <td>{@link #removeFirst removeFirst()}</td>
88	>	*    <td>{@link #remove() remove()}</td>
89	>	*    <td>{@link #removeFirst() removeFirst()}</td>
90		*  </tr>
91		*  <tr>
92	<	*    <td>{@link java.util.Queue#poll poll()}</td>
93	<	*    <td>{@link #pollFirst pollFirst()}</td>
92	>	*    <td>{@link #poll() poll()}</td>
93	>	*    <td>{@link #pollFirst() pollFirst()}</td>
94		*  </tr>
95		*  <tr>
96	<	*    <td>{@link java.util.Queue#element element()}</td>
97	<	*    <td>{@link #getFirst getFirst()}</td>
96	>	*    <td>{@link #element() element()}</td>
97	>	*    <td>{@link #getFirst() getFirst()}</td>
98		*  </tr>
99		*  <tr>
100	<	*    <td>{@link java.util.Queue#peek peek()}</td>
101	<	*    <td>{@link #peek peekFirst()}</td>
100	>	*    <td>{@link #peek() peek()}</td>
101	>	*    <td>{@link #peekFirst() peekFirst()}</td>
102		*  </tr>
103		* </table>
104		*
#	Line 108 | Line 108 | package java.util;
108		* beginning of the deque.  Stack methods are precisely equivalent to
109		* {@code Deque} methods as indicated in the table below:
110		*
111	<	* <p>
112	<	* <table BORDER CELLPADDING=3 CELLSPACING=1>
111	>	* <table class="plain">
112	>	* <caption>Comparison of Stack and Deque methods</caption>
113		*  <tr>
114	<	*    <td ALIGN=CENTER> <b>Stack Method</b></td>
115	<	*    <td ALIGN=CENTER> <b>Equivalent {@code Deque} Method</b></td>
114	>	*    <td style="text-align:center"> <b>Stack Method</b></td>
115	>	*    <td style="text-align:center"> <b>Equivalent {@code Deque} Method</b></td>
116		*  </tr>
117		*  <tr>
118	<	*    <td>{@link #push push(e)}</td>
119	<	*    <td>{@link #addFirst addFirst(e)}</td>
118	>	*    <td>{@link #push(Object) push(e)}</td>
119	>	*    <td>{@link #addFirst(Object) addFirst(e)}</td>
120		*  </tr>
121		*  <tr>
122	<	*    <td>{@link #pop pop()}</td>
123	<	*    <td>{@link #removeFirst removeFirst()}</td>
122	>	*    <td>{@link #pop() pop()}</td>
123	>	*    <td>{@link #removeFirst() removeFirst()}</td>
124		*  </tr>
125		*  <tr>
126	<	*    <td>{@link #peek peek()}</td>
127	<	*    <td>{@link #peekFirst peekFirst()}</td>
126	>	*    <td>{@link #peek() peek()}</td>
127	>	*    <td>{@link #peekFirst() peekFirst()}</td>
128		*  </tr>
129		* </table>
130		*
#	Line 145 | Line 145 | package java.util;
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.
148	>	* to indicate that the deque is empty.
149		*
150		* <p>{@code Deque} implementations generally do not define
151		* element-based versions of the {@code equals} and {@code hashCode}
152		* methods, but instead inherit the identity-based versions from class
153		* {@code Object}.
154		*
155	<	* <p>This interface is a member of the <a
156	<	* href="{@docRoot}/../technotes/guides/collections/index.html"> Java Collections
157	<	* Framework</a>.
155	>	* <p>This interface is a member of the
156	>	* <a href="{@docRoot}/java/util/package-summary.html#CollectionsFramework">
157	>	* Java Collections Framework</a>.
158		*
159		* @author Doug Lea
160		* @author Josh Bloch
161		* @since  1.6
162	<	* @param <E> the type of elements held in this collection
162	>	* @param <E> the type of elements held in this deque
163		*/
164		public interface Deque<E> extends Queue<E> {
165		/**
166		* Inserts the specified element at the front of this deque if it is
167	<	* possible to do so immediately without violating capacity restrictions.
168	<	* When using a capacity-restricted deque, it is generally preferable to
169	<	* use method {@link #offerFirst}.
167	>	* possible to do so immediately without violating capacity restrictions,
168	>	* throwing an {@code IllegalStateException} if no space is currently
169	>	* available.  When using a capacity-restricted deque, it is generally
170	>	* preferable to use method {@link #offerFirst}.
171		*
172		* @param e the element to add
173		* @throws IllegalStateException if the element cannot be added at this
#	Line 182 | Line 183 | public interface Deque<E> extends Queue<
183
184		/**
185		* Inserts the specified element at the end of this deque if it is
186	<	* possible to do so immediately without violating capacity restrictions.
187	<	* When using a capacity-restricted deque, it is generally preferable to
188	<	* use method {@link #offerLast}.
186	>	* possible to do so immediately without violating capacity restrictions,
187	>	* throwing an {@code IllegalStateException} if no space is currently
188	>	* available.  When using a capacity-restricted deque, it is generally
189	>	* preferable to use method {@link #offerLast}.
190		*
191		* <p>This method is equivalent to {@link #add}.
192		*
#	Line 313 | Line 315 | public interface Deque<E> extends Queue<
315		* Removes the first occurrence of the specified element from this deque.
316		* If the deque does not contain the element, it is unchanged.
317		* More formally, removes the first element {@code e} such that
318	<	* <tt>(o==null&nbsp;?&nbsp;e==null&nbsp;:&nbsp;o.equals(e))</tt>
317	<	* (if such an element exists).
318	>	* {@code Objects.equals(o, e)} (if such an element exists).
319		* Returns {@code true} if this deque contained the specified element
320		* (or equivalently, if this deque changed as a result of the call).
321		*
322		* @param o element to be removed from this deque, if present
323		* @return {@code true} if an element was removed as a result of this call
324		* @throws ClassCastException if the class of the specified element
325	<	*         is incompatible with this deque (optional)
325	>	*         is incompatible with this deque
326	>	* (<a href="{@docRoot}/../api/java/util/Collection.html#optional-restrictions">optional</a>)
327		* @throws NullPointerException if the specified element is null and this
328	<	*         deque does not permit null elements (optional)
328	>	*         deque does not permit null elements
329	>	* (<a href="{@docRoot}/../api/java/util/Collection.html#optional-restrictions">optional</a>)
330		*/
331		boolean removeFirstOccurrence(Object o);
332
#	Line 331 | Line 334 | public interface Deque<E> extends Queue<
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&nbsp;?&nbsp;e==null&nbsp;:&nbsp;o.equals(e))</tt>
335	<	* (if such an element exists).
337	>	* {@code Objects.equals(o, e)} (if such an element exists).
338		* Returns {@code true} if this deque contained the specified element
339		* (or equivalently, if this deque changed as a result of the call).
340		*
341		* @param o element to be removed from this deque, if present
342		* @return {@code true} if an element was removed as a result of this call
343		* @throws ClassCastException if the class of the specified element
344	<	*         is incompatible with this deque (optional)
344	>	*         is incompatible with this deque
345	>	* (<a href="{@docRoot}/../api/java/util/Collection.html#optional-restrictions">optional</a>)
346		* @throws NullPointerException if the specified element is null and this
347	<	*         deque does not permit null elements (optional)
347	>	*         deque does not permit null elements
348	>	* (<a href="{@docRoot}/../api/java/util/Collection.html#optional-restrictions">optional</a>)
349		*/
350		boolean removeLastOccurrence(Object o);
351
#	Line 397 | Line 401 | public interface Deque<E> extends Queue<
401		/**
402		* Retrieves and removes the head of the queue represented by this deque
403		* (in other words, the first element of this deque).
404	<	* This method differs from {@link #poll poll} only in that it throws an
405	<	* exception if this deque is empty.
404	>	* This method differs from {@link #poll() poll()} only in that it
405	>	* throws an exception if this deque is empty.
406		*
407		* <p>This method is equivalent to {@link #removeFirst()}.
408		*
#	Line 444 | Line 448 | public interface Deque<E> extends Queue<
448		*/
449		E peek();
450
451	+	/**
452	+	* Adds all of the elements in the specified collection at the end
453	+	* of this deque, as if by calling {@link #addLast} on each one,
454	+	* in the order that they are returned by the collection's iterator.
455	+	*
456	+	* <p>When using a capacity-restricted deque, it is generally preferable
457	+	* to call {@link #offer(Object) offer} separately on each element.
458	+	*
459	+	* <p>An exception encountered while trying to add an element may result
460	+	* in only some of the elements having been successfully added when
461	+	* the associated exception is thrown.
462	+	*
463	+	* @param c the elements to be inserted into this deque
464	+	* @return {@code true} if this deque changed as a result of the call
465	+	* @throws IllegalStateException if not all the elements can be added at
466	+	*         this time due to insertion restrictions
467	+	* @throws ClassCastException if the class of an element of the specified
468	+	*         collection prevents it from being added to this deque
469	+	* @throws NullPointerException if the specified collection contains a
470	+	*         null element and this deque does not permit null elements,
471	+	*         or if the specified collection is null
472	+	* @throws IllegalArgumentException if some property of an element of the
473	+	*         specified collection prevents it from being added to this deque
474	+	*/
475	+	boolean addAll(Collection<? extends E> c);
476
477		// *** Stack methods ***
478
479		/**
480		* Pushes an element onto the stack represented by this deque (in other
481		* words, at the head of this deque) if it is possible to do so
482	<	* immediately without violating capacity restrictions, returning
454	<	* {@code true} upon success and throwing an
482	>	* immediately without violating capacity restrictions, throwing an
483		* {@code IllegalStateException} if no space is currently available.
484		*
485		* <p>This method is equivalent to {@link #addFirst}.
#	Line 487 | Line 515 | public interface Deque<E> extends Queue<
515		* Removes the first occurrence of the specified element from this deque.
516		* If the deque does not contain the element, it is unchanged.
517		* More formally, removes the first element {@code e} such that
518	<	* <tt>(o==null&nbsp;?&nbsp;e==null&nbsp;:&nbsp;o.equals(e))</tt>
491	<	* (if such an element exists).
518	>	* {@code Objects.equals(o, e)} (if such an element exists).
519		* Returns {@code true} if this deque contained the specified element
520		* (or equivalently, if this deque changed as a result of the call).
521		*
#	Line 497 | Line 524 | public interface Deque<E> extends Queue<
524		* @param o element to be removed from this deque, if present
525		* @return {@code true} if an element was removed as a result of this call
526		* @throws ClassCastException if the class of the specified element
527	<	*         is incompatible with this deque (optional)
527	>	*         is incompatible with this deque
528	>	* (<a href="{@docRoot}/../api/java/util/Collection.html#optional-restrictions">optional</a>)
529		* @throws NullPointerException if the specified element is null and this
530	<	*         deque does not permit null elements (optional)
530	>	*         deque does not permit null elements
531	>	* (<a href="{@docRoot}/../api/java/util/Collection.html#optional-restrictions">optional</a>)
532		*/
533		boolean remove(Object o);
534
535		/**
536		* Returns {@code true} if this deque contains the specified element.
537		* More formally, returns {@code true} if and only if this deque contains
538	<	* at least one element {@code e} such that
510	<	* <tt>(o==null&nbsp;?&nbsp;e==null&nbsp;:&nbsp;o.equals(e))</tt>.
538	>	* at least one element {@code e} such that {@code Objects.equals(o, e)}.
539		*
540		* @param o element whose presence in this deque is to be tested
541		* @return {@code true} if this deque contains the specified element
542	<	* @throws ClassCastException if the type of the specified element
543	<	*         is incompatible with this deque (optional)
542	>	* @throws ClassCastException if the class of the specified element
543	>	*         is incompatible with this deque
544	>	* (<a href="{@docRoot}/../api/java/util/Collection.html#optional-restrictions">optional</a>)
545		* @throws NullPointerException if the specified element is null and this
546	<	*         deque does not permit null elements (optional)
546	>	*         deque does not permit null elements
547	>	* (<a href="{@docRoot}/../api/java/util/Collection.html#optional-restrictions">optional</a>)
548		*/
549		boolean contains(Object o);
550
#	Line 523 | Line 553 | public interface Deque<E> extends Queue<
553		*
554		* @return the number of elements in this deque
555		*/
556	<	public int size();
556	>	int size();
557
558		/**
559		* Returns an iterator over the elements in this deque in proper sequence.

Diff Legend

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