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.31 by jsr166, Wed Dec 31 22:40:51 2014 UTC vs.
Revision 1.41 by jsr166, Thu Apr 5 00:03:34 2018 UTC

#	Line 27 | Line 27 | package java.util;
27		* <p>The twelve methods described above are summarized in the
28		* following table:
29		*
30	<	* <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 Deque#addFirst addFirst(e)}</td>
49	<	*    <td>{@link Deque#offerFirst offerFirst(e)}</td>
50	<	*    <td>{@link Deque#addLast addLast(e)}</td>
51	<	*    <td>{@link Deque#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 Deque#removeFirst removeFirst()}</td>
56	<	*    <td>{@link Deque#pollFirst pollFirst()}</td>
57	<	*    <td>{@link Deque#removeLast removeLast()}</td>
58	<	*    <td>{@link Deque#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 Deque#getFirst getFirst()}</td>
63	<	*    <td>{@link Deque#peekFirst peekFirst()}</td>
64	<	*    <td>{@link Deque#getLast getLast()}</td>
65	<	*    <td>{@link Deque#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
#	Line 70 | Line 73 | package java.util;
73		* inherited from the {@code Queue} interface are precisely equivalent to
74		* {@code Deque} methods as indicated in the following table:
75		*
76	<	* <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>{@code Queue} Method</b></td>
81	<	*    <td ALIGN=CENTER> <b>Equivalent {@code Deque} 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	<	* {@code Deque} methods as indicated in the table below:
115	>	* beginning of the deque.  Stack methods are equivalent to {@code Deque}
116	>	* methods as indicated in the table below:
117		*
118	<	* <table BORDER CELLPADDING=3 CELLSPACING=1>
118	>	* <table class="striped">
119		* <caption>Comparison of Stack and Deque methods</caption>
120	+	*  <thead>
121		*  <tr>
122	<	*    <td ALIGN=CENTER> <b>Stack Method</b></td>
123	<	*    <td ALIGN=CENTER> <b>Equivalent {@code Deque} 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 #getFirst() getFirst()}</td>
138		*  </tr>
139	+	*  </tbody>
140		* </table>
141		*
142		* <p>Note that the {@link #peek peek} method works equally well when
#	Line 145 | Line 156 | package java.util;
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		* {@code null} is used as a special return value by various methods
159	<	* to indicated that the deque is empty.
159	>	* to indicate that the deque is empty.
160		*
161		* <p>{@code Deque} implementations generally do not define
162		* element-based versions of the {@code equals} and {@code hashCode}
163		* methods, but instead inherit the identity-based versions from class
164		* {@code Object}.
165		*
166	<	* <p>This interface is a member of the <a
167	<	* href="{@docRoot}/../technotes/guides/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
#	Line 323 | Line 334 | public interface Deque<E> extends Queue<
334		* @return {@code true} if an element was removed as a result of this call
335		* @throws ClassCastException if the class of the specified element
336		*         is incompatible with this deque
337	<	*         (<a href="../Collection.html#optional-restrictions">optional</a>)
338	<	* @throws NullPointerException if the specified element is null
339	<	*         (<a href="../Collection.html#optional-restrictions">optional</a>)
337	>	* (<a href="{@docRoot}/../api/java/util/Collection.html#optional-restrictions">optional</a>)
338	>	* @throws NullPointerException if the specified element is null and this
339	>	*         deque does not permit null elements
340	>	* (<a href="{@docRoot}/../api/java/util/Collection.html#optional-restrictions">optional</a>)
341		*/
342		boolean removeFirstOccurrence(Object o);
343
#	Line 341 | Line 353 | public interface Deque<E> extends Queue<
353		* @return {@code true} if an element was removed as a result of this call
354		* @throws ClassCastException if the class of the specified element
355		*         is incompatible with this deque
356	<	*         (<a href="../Collection.html#optional-restrictions">optional</a>)
357	<	* @throws NullPointerException if the specified element is null
358	<	*         (<a href="../Collection.html#optional-restrictions">optional</a>)
356	>	* (<a href="{@docRoot}/../api/java/util/Collection.html#optional-restrictions">optional</a>)
357	>	* @throws NullPointerException if the specified element is null and this
358	>	*         deque does not permit null elements
359	>	* (<a href="{@docRoot}/../api/java/util/Collection.html#optional-restrictions">optional</a>)
360		*/
361		boolean removeLastOccurrence(Object o);
362
#	Line 399 | 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 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 446 | Line 459 | public interface Deque<E> extends Queue<
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
#	Line 498 | Line 536 | public interface Deque<E> extends Queue<
536		* @return {@code true} if an element was removed as a result of this call
537		* @throws ClassCastException if the class of the specified element
538		*         is incompatible with this deque
539	<	*         (<a href="../Collection.html#optional-restrictions">optional</a>)
540	<	* @throws NullPointerException if the specified element is null
541	<	*         (<a href="../Collection.html#optional-restrictions">optional</a>)
539	>	* (<a href="{@docRoot}/../api/java/util/Collection.html#optional-restrictions">optional</a>)
540	>	* @throws NullPointerException if the specified element is null and this
541	>	*         deque does not permit null elements
542	>	* (<a href="{@docRoot}/../api/java/util/Collection.html#optional-restrictions">optional</a>)
543		*/
544		boolean remove(Object o);
545
#	Line 513 | Line 552 | public interface Deque<E> extends Queue<
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="../Collection.html#optional-restrictions">optional</a>)
556	<	* @throws NullPointerException if the specified element is null
557	<	*         (<a href="../Collection.html#optional-restrictions">optional</a>)
555	>	* (<a href="{@docRoot}/../api/java/util/Collection.html#optional-restrictions">optional</a>)
556	>	* @throws NullPointerException if the specified element is null and this
557	>	*         deque does not permit null elements
558	>	* (<a href="{@docRoot}/../api/java/util/Collection.html#optional-restrictions">optional</a>)
559		*/
560		boolean contains(Object o);
561

Diff Legend

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