39 * A linear collection that supports element insertion and removal at
40 * both ends. The name <i>deque</i> is short for "double ended queue"
41 * and is usually pronounced "deck". Most {@code Deque}
42 * implementations place no fixed limits on the number of elements
43 * they may contain, but this interface supports capacity-restricted
44 * deques as well as those with no fixed size limit.
45 *
46 * <p>This interface defines methods to access the elements at both
47 * ends of the deque. Methods are provided to insert, remove, and
48 * examine the element. Each of these methods exists in two forms:
49 * one throws an exception if the operation fails, the other returns a
50 * special value (either {@code null} or {@code false}, depending on
51 * the operation). The latter form of the insert operation is
52 * designed specifically for use with capacity-restricted
53 * {@code Deque} implementations; in most implementations, insert
54 * operations cannot fail.
55 *
56 * <p>The twelve methods described above are summarized in the
57 * following table:
58 *
59 * <table BORDER CELLPADDING=3 CELLSPACING=1>
60 * <caption>Summary of Deque methods</caption>
61 * <tr>
62 * <td></td>
63 * <td style="text-align:center" COLSPAN = 2> <b>First Element (Head)</b></td>
64 * <td style="text-align:center" COLSPAN = 2> <b>Last Element (Tail)</b></td>
65 * </tr>
66 * <tr>
67 * <td></td>
68 * <td style="text-align:center"><em>Throws exception</em></td>
69 * <td style="text-align:center"><em>Special value</em></td>
70 * <td style="text-align:center"><em>Throws exception</em></td>
71 * <td style="text-align:center"><em>Special value</em></td>
72 * </tr>
73 * <tr>
74 * <td><b>Insert</b></td>
75 * <td>{@link Deque#addFirst addFirst(e)}</td>
76 * <td>{@link Deque#offerFirst offerFirst(e)}</td>
77 * <td>{@link Deque#addLast addLast(e)}</td>
78 * <td>{@link Deque#offerLast offerLast(e)}</td>
79 * </tr>
82 * <td>{@link Deque#removeFirst removeFirst()}</td>
83 * <td>{@link Deque#pollFirst pollFirst()}</td>
84 * <td>{@link Deque#removeLast removeLast()}</td>
85 * <td>{@link Deque#pollLast pollLast()}</td>
86 * </tr>
87 * <tr>
88 * <td><b>Examine</b></td>
89 * <td>{@link Deque#getFirst getFirst()}</td>
90 * <td>{@link Deque#peekFirst peekFirst()}</td>
91 * <td>{@link Deque#getLast getLast()}</td>
92 * <td>{@link Deque#peekLast peekLast()}</td>
93 * </tr>
94 * </table>
95 *
96 * <p>This interface extends the {@link Queue} interface. When a deque is
97 * used as a queue, FIFO (First-In-First-Out) behavior results. Elements are
98 * added at the end of the deque and removed from the beginning. The methods
99 * inherited from the {@code Queue} interface are precisely equivalent to
100 * {@code Deque} methods as indicated in the following table:
101 *
102 * <table BORDER CELLPADDING=3 CELLSPACING=1>
103 * <caption>Comparison of Queue and Deque methods</caption>
104 * <tr>
105 * <td style="text-align:center"> <b>{@code Queue} Method</b></td>
106 * <td style="text-align:center"> <b>Equivalent {@code Deque} Method</b></td>
107 * </tr>
108 * <tr>
109 * <td>{@link java.util.Queue#add add(e)}</td>
110 * <td>{@link #addLast addLast(e)}</td>
111 * </tr>
112 * <tr>
113 * <td>{@link java.util.Queue#offer offer(e)}</td>
114 * <td>{@link #offerLast offerLast(e)}</td>
115 * </tr>
116 * <tr>
117 * <td>{@link java.util.Queue#remove remove()}</td>
118 * <td>{@link #removeFirst removeFirst()}</td>
119 * </tr>
120 * <tr>
121 * <td>{@link java.util.Queue#poll poll()}</td>
122 * <td>{@link #pollFirst pollFirst()}</td>
123 * </tr>
124 * <tr>
125 * <td>{@link java.util.Queue#element element()}</td>
126 * <td>{@link #getFirst getFirst()}</td>
127 * </tr>
128 * <tr>
129 * <td>{@link java.util.Queue#peek peek()}</td>
130 * <td>{@link #peek peekFirst()}</td>
131 * </tr>
132 * </table>
133 *
134 * <p>Deques can also be used as LIFO (Last-In-First-Out) stacks. This
135 * interface should be used in preference to the legacy {@link Stack} class.
136 * When a deque is used as a stack, elements are pushed and popped from the
137 * beginning of the deque. Stack methods are precisely equivalent to
138 * {@code Deque} methods as indicated in the table below:
139 *
140 * <table BORDER CELLPADDING=3 CELLSPACING=1>
141 * <caption>Comparison of Stack and Deque methods</caption>
142 * <tr>
143 * <td style="text-align:center"> <b>Stack Method</b></td>
144 * <td style="text-align:center"> <b>Equivalent {@code Deque} Method</b></td>
145 * </tr>
146 * <tr>
147 * <td>{@link #push push(e)}</td>
148 * <td>{@link #addFirst addFirst(e)}</td>
149 * </tr>
150 * <tr>
151 * <td>{@link #pop pop()}</td>
152 * <td>{@link #removeFirst removeFirst()}</td>
153 * </tr>
154 * <tr>
155 * <td>{@link #peek peek()}</td>
156 * <td>{@link #peekFirst peekFirst()}</td>
157 * </tr>
158 * </table>
159 *
160 * <p>Note that the {@link #peek peek} method works equally well when
|
39 * A linear collection that supports element insertion and removal at
40 * both ends. The name <i>deque</i> is short for "double ended queue"
41 * and is usually pronounced "deck". Most {@code Deque}
42 * implementations place no fixed limits on the number of elements
43 * they may contain, but this interface supports capacity-restricted
44 * deques as well as those with no fixed size limit.
45 *
46 * <p>This interface defines methods to access the elements at both
47 * ends of the deque. Methods are provided to insert, remove, and
48 * examine the element. Each of these methods exists in two forms:
49 * one throws an exception if the operation fails, the other returns a
50 * special value (either {@code null} or {@code false}, depending on
51 * the operation). The latter form of the insert operation is
52 * designed specifically for use with capacity-restricted
53 * {@code Deque} implementations; in most implementations, insert
54 * operations cannot fail.
55 *
56 * <p>The twelve methods described above are summarized in the
57 * following table:
58 *
59 * <table class="plain">
60 * <caption>Summary of Deque methods</caption>
61 * <tr>
62 * <td></td>
63 * <td style="text-align:center" COLSPAN = 2> <b>First Element (Head)</b></td>
64 * <td style="text-align:center" COLSPAN = 2> <b>Last Element (Tail)</b></td>
65 * </tr>
66 * <tr>
67 * <td></td>
68 * <td style="text-align:center"><em>Throws exception</em></td>
69 * <td style="text-align:center"><em>Special value</em></td>
70 * <td style="text-align:center"><em>Throws exception</em></td>
71 * <td style="text-align:center"><em>Special value</em></td>
72 * </tr>
73 * <tr>
74 * <td><b>Insert</b></td>
75 * <td>{@link Deque#addFirst addFirst(e)}</td>
76 * <td>{@link Deque#offerFirst offerFirst(e)}</td>
77 * <td>{@link Deque#addLast addLast(e)}</td>
78 * <td>{@link Deque#offerLast offerLast(e)}</td>
79 * </tr>
82 * <td>{@link Deque#removeFirst removeFirst()}</td>
83 * <td>{@link Deque#pollFirst pollFirst()}</td>
84 * <td>{@link Deque#removeLast removeLast()}</td>
85 * <td>{@link Deque#pollLast pollLast()}</td>
86 * </tr>
87 * <tr>
88 * <td><b>Examine</b></td>
89 * <td>{@link Deque#getFirst getFirst()}</td>
90 * <td>{@link Deque#peekFirst peekFirst()}</td>
91 * <td>{@link Deque#getLast getLast()}</td>
92 * <td>{@link Deque#peekLast peekLast()}</td>
93 * </tr>
94 * </table>
95 *
96 * <p>This interface extends the {@link Queue} interface. When a deque is
97 * used as a queue, FIFO (First-In-First-Out) behavior results. Elements are
98 * added at the end of the deque and removed from the beginning. The methods
99 * inherited from the {@code Queue} interface are precisely equivalent to
100 * {@code Deque} methods as indicated in the following table:
101 *
102 * <table class="plain">
103 * <caption>Comparison of Queue and Deque methods</caption>
104 * <tr>
105 * <td style="text-align:center"> <b>{@code Queue} Method</b></td>
106 * <td style="text-align:center"> <b>Equivalent {@code Deque} Method</b></td>
107 * </tr>
108 * <tr>
109 * <td>{@link java.util.Queue#add add(e)}</td>
110 * <td>{@link #addLast addLast(e)}</td>
111 * </tr>
112 * <tr>
113 * <td>{@link java.util.Queue#offer offer(e)}</td>
114 * <td>{@link #offerLast offerLast(e)}</td>
115 * </tr>
116 * <tr>
117 * <td>{@link java.util.Queue#remove remove()}</td>
118 * <td>{@link #removeFirst removeFirst()}</td>
119 * </tr>
120 * <tr>
121 * <td>{@link java.util.Queue#poll poll()}</td>
122 * <td>{@link #pollFirst pollFirst()}</td>
123 * </tr>
124 * <tr>
125 * <td>{@link java.util.Queue#element element()}</td>
126 * <td>{@link #getFirst getFirst()}</td>
127 * </tr>
128 * <tr>
129 * <td>{@link java.util.Queue#peek peek()}</td>
130 * <td>{@link #peek peekFirst()}</td>
131 * </tr>
132 * </table>
133 *
134 * <p>Deques can also be used as LIFO (Last-In-First-Out) stacks. This
135 * interface should be used in preference to the legacy {@link Stack} class.
136 * When a deque is used as a stack, elements are pushed and popped from the
137 * beginning of the deque. Stack methods are precisely equivalent to
138 * {@code Deque} methods as indicated in the table below:
139 *
140 * <table class="plain">
141 * <caption>Comparison of Stack and Deque methods</caption>
142 * <tr>
143 * <td style="text-align:center"> <b>Stack Method</b></td>
144 * <td style="text-align:center"> <b>Equivalent {@code Deque} Method</b></td>
145 * </tr>
146 * <tr>
147 * <td>{@link #push push(e)}</td>
148 * <td>{@link #addFirst addFirst(e)}</td>
149 * </tr>
150 * <tr>
151 * <td>{@link #pop pop()}</td>
152 * <td>{@link #removeFirst removeFirst()}</td>
153 * </tr>
154 * <tr>
155 * <td>{@link #peek peek()}</td>
156 * <td>{@link #peekFirst peekFirst()}</td>
157 * </tr>
158 * </table>
159 *
160 * <p>Note that the {@link #peek peek} method works equally well when
|