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="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 Deque#addFirst addFirst(e)}</td> |
47 |
< |
* <td>{@link Deque#offerFirst offerFirst(e)}</td> |
48 |
< |
* <td>{@link Deque#addLast addLast(e)}</td> |
49 |
< |
* <td>{@link Deque#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 Deque#removeFirst removeFirst()}</td> |
54 |
< |
* <td>{@link Deque#pollFirst pollFirst()}</td> |
55 |
< |
* <td>{@link Deque#removeLast removeLast()}</td> |
56 |
< |
* <td>{@link Deque#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 Deque#getFirst getFirst()}</td> |
61 |
< |
* <td>{@link Deque#peekFirst peekFirst()}</td> |
62 |
< |
* <td>{@link Deque#getLast getLast()}</td> |
63 |
< |
* <td>{@link Deque#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 |
|
* |
70 |
|
* inherited from the {@code Queue} interface are precisely equivalent to |
71 |
|
* {@code Deque} methods as indicated in the following table: |
72 |
|
* |
73 |
< |
* <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 |
|
* |
108 |
|
* beginning of the deque. Stack methods are precisely equivalent to |
109 |
|
* {@code Deque} methods as indicated in the table below: |
110 |
|
* |
111 |
< |
* <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 |
|
* |
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 |
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 |
|
* |
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 |
|
|