Debian Codegraph @

vendor/ramsey/collection/src/DoubleEndedQueueInterface.php

raw
1 <?php
2
3 /**
4 * This file is part of the ramsey/collection library
5 *
6 * For the full copyright and license information, please view the LICENSE
7 * file that was distributed with this source code.
8 *
9 * @copyright Copyright (c) Ben Ramsey <[email protected]>
10 * @license http://opensource.org/licenses/MIT MIT
11 */
12
13 declare(strict_types=1);
14
15 namespace Ramsey\Collection;
16
17 use Ramsey\Collection\Exception\NoSuchElementException;
18 use RuntimeException;
19
20 /**
21 * A linear collection that supports element insertion and removal at both ends.
22 *
23 * Most `DoubleEndedQueueInterface` implementations place no fixed limits on the
24 * number of elements they may contain, but this interface supports
25 * capacity-restricted double-ended queues as well as those with no fixed size
26 * limit.
27 *
28 * This interface defines methods to access the elements at both ends of the
29 * double-ended queue. Methods are provided to insert, remove, and examine the
30 * element. Each of these methods exists in two forms: one throws an exception
31 * if the operation fails, the other returns a special value (either `null` or
32 * `false`, depending on the operation). The latter form of the insert operation
33 * is designed specifically for use with capacity-restricted implementations; in
34 * most implementations, insert operations cannot fail.
35 *
36 * The twelve methods described above are summarized in the following table:
37 *
38 * <table>
39 * <caption>Summary of DoubleEndedQueueInterface methods</caption>
40 * <thead>
41 * <tr>
42 * <th></th>
43 * <th colspan=2>First Element (Head)</th>
44 * <th colspan=2>Last Element (Tail)</th>
45 * </tr>
46 * <tr>
47 * <td></td>
48 * <td><em>Throws exception</em></td>
49 * <td><em>Special value</em></td>
50 * <td><em>Throws exception</em></td>
51 * <td><em>Special value</em></td>
52 * </tr>
53 * </thead>
54 * <tbody>
55 * <tr>
56 * <th>Insert</th>
57 * <td><code>addFirst()</code></td>
58 * <td><code>offerFirst()</code></td>
59 * <td><code>addLast()</code></td>
60 * <td><code>offerLast()</code></td>
61 * </tr>
62 * <tr>
63 * <th>Remove</th>
64 * <td><code>removeFirst()</code></td>
65 * <td><code>pollFirst()</code></td>
66 * <td><code>removeLast()</code></td>
67 * <td><code>pollLast()</code></td>
68 * </tr>
69 * <tr>
70 * <th>Examine</th>
71 * <td><code>firstElement()</code></td>
72 * <td><code>peekFirst()</code></td>
73 * <td><code>lastElement()</code></td>
74 * <td><code>peekLast()</code></td>
75 * </tr>
76 * </tbody>
77 * </table>
78 *
79 * This interface extends the `QueueInterface`. When a double-ended queue is
80 * used as a queue, FIFO (first-in-first-out) behavior results. Elements are
81 * added at the end of the double-ended queue and removed from the beginning.
82 * The methods inherited from the `QueueInterface` are precisely equivalent to
83 * `DoubleEndedQueueInterface` methods as indicated in the following table:
84 *
85 * <table>
86 * <caption>Comparison of QueueInterface and DoubleEndedQueueInterface methods</caption>
87 * <thead>
88 * <tr>
89 * <th>QueueInterface Method</th>
90 * <th>DoubleEndedQueueInterface Method</th>
91 * </tr>
92 * </thead>
93 * <tbody>
94 * <tr>
95 * <td><code>add()</code></td>
96 * <td><code>addLast()</code></td>
97 * </tr>
98 * <tr>
99 * <td><code>offer()</code></td>
100 * <td><code>offerLast()</code></td>
101 * </tr>
102 * <tr>
103 * <td><code>remove()</code></td>
104 * <td><code>removeFirst()</code></td>
105 * </tr>
106 * <tr>
107 * <td><code>poll()</code></td>
108 * <td><code>pollFirst()</code></td>
109 * </tr>
110 * <tr>
111 * <td><code>element()</code></td>
112 * <td><code>firstElement()</code></td>
113 * </tr>
114 * <tr>
115 * <td><code>peek()</code></td>
116 * <td><code>peekFirst()</code></td>
117 * </tr>
118 * </tbody>
119 * </table>
120 *
121 * Double-ended queues can also be used as LIFO (last-in-first-out) stacks. When
122 * a double-ended queue is used as a stack, elements are pushed and popped from
123 * the beginning of the double-ended queue. Stack concepts are precisely
124 * equivalent to `DoubleEndedQueueInterface` methods as indicated in the table
125 * below:
126 *
127 * <table>
128 * <caption>Comparison of stack concepts and DoubleEndedQueueInterface methods</caption>
129 * <thead>
130 * <tr>
131 * <th>Stack concept</th>
132 * <th>DoubleEndedQueueInterface Method</th>
133 * </tr>
134 * </thead>
135 * <tbody>
136 * <tr>
137 * <td><em>push</em></td>
138 * <td><code>addFirst()</code></td>
139 * </tr>
140 * <tr>
141 * <td><em>pop</em></td>
142 * <td><code>removeFirst()</code></td>
143 * </tr>
144 * <tr>
145 * <td><em>peek</em></td>
146 * <td><code>peekFirst()</code></td>
147 * </tr>
148 * </tbody>
149 * </table>
150 *
151 * Note that the `peek()` method works equally well when a double-ended queue is
152 * used as a queue or a stack; in either case, elements are drawn from the
153 * beginning of the double-ended queue.
154 *
155 * While `DoubleEndedQueueInterface` implementations are not strictly required
156 * to prohibit the insertion of `null` elements, they are strongly encouraged to
157 * do so. Users of any `DoubleEndedQueueInterface` implementations that do allow
158 * `null` elements are strongly encouraged *not* to take advantage of the
159 * ability to insert nulls. This is so because `null` is used as a special
160 * return value by various methods to indicated that the double-ended queue is
161 * empty.
162 *
163 * @template T
164 * @extends QueueInterface<T>
165 */
166 interface DoubleEndedQueueInterface extends QueueInterface
167 {
168 /**
169 * Inserts the specified element at the front of this queue if it is
170 * possible to do so immediately without violating capacity restrictions.
171 *
172 * When using a capacity-restricted double-ended queue, it is generally
173 * preferable to use the `offerFirst()` method.
174 *
175 * @param T $element The element to add to the front of this queue.
176 *
177 * @return bool `true` if this queue changed as a result of the call.
178 *
179 * @throws RuntimeException if a queue refuses to add a particular element
180 * for any reason other than that it already contains the element.
181 * Implementations should use a more-specific exception that extends
182 * `\RuntimeException`.
183 */
184 public function addFirst(mixed $element): bool;
185
186 /**
187 * Inserts the specified element at the end of this queue if it is possible
188 * to do so immediately without violating capacity restrictions.
189 *
190 * When using a capacity-restricted double-ended queue, it is generally
191 * preferable to use the `offerLast()` method.
192 *
193 * This method is equivalent to `add()`.
194 *
195 * @param T $element The element to add to the end of this queue.
196 *
197 * @return bool `true` if this queue changed as a result of the call.
198 *
199 * @throws RuntimeException if a queue refuses to add a particular element
200 * for any reason other than that it already contains the element.
201 * Implementations should use a more-specific exception that extends
202 * `\RuntimeException`.
203 */
204 public function addLast(mixed $element): bool;
205
206 /**
207 * Inserts the specified element at the front of this queue if it is
208 * possible to do so immediately without violating capacity restrictions.
209 *
210 * When using a capacity-restricted queue, this method is generally
211 * preferable to `addFirst()`, which can fail to insert an element only by
212 * throwing an exception.
213 *
214 * @param T $element The element to add to the front of this queue.
215 *
216 * @return bool `true` if the element was added to this queue, else `false`.
217 */
218 public function offerFirst(mixed $element): bool;
219
220 /**
221 * Inserts the specified element at the end of this queue if it is possible
222 * to do so immediately without violating capacity restrictions.
223 *
224 * When using a capacity-restricted queue, this method is generally
225 * preferable to `addLast()` which can fail to insert an element only by
226 * throwing an exception.
227 *
228 * @param T $element The element to add to the end of this queue.
229 *
230 * @return bool `true` if the element was added to this queue, else `false`.
231 */
232 public function offerLast(mixed $element): bool;
233
234 /**
235 * Retrieves and removes the head of this queue.
236 *
237 * This method differs from `pollFirst()` only in that it throws an
238 * exception if this queue is empty.
239 *
240 * @return T the first element in this queue.
241 *
242 * @throws NoSuchElementException if this queue is empty.
243 */
244 public function removeFirst(): mixed;
245
246 /**
247 * Retrieves and removes the tail of this queue.
248 *
249 * This method differs from `pollLast()` only in that it throws an exception
250 * if this queue is empty.
251 *
252 * @return T the last element in this queue.
253 *
254 * @throws NoSuchElementException if this queue is empty.
255 */
256 public function removeLast(): mixed;
257
258 /**
259 * Retrieves and removes the head of this queue, or returns `null` if this
260 * queue is empty.
261 *
262 * @return T | null the head of this queue, or `null` if this queue is empty.
263 */
264 public function pollFirst(): mixed;
265
266 /**
267 * Retrieves and removes the tail of this queue, or returns `null` if this
268 * queue is empty.
269 *
270 * @return T | null the tail of this queue, or `null` if this queue is empty.
271 */
272 public function pollLast(): mixed;
273
274 /**
275 * Retrieves, but does not remove, the head of this queue.
276 *
277 * This method differs from `peekFirst()` only in that it throws an
278 * exception if this queue is empty.
279 *
280 * @return T the head of this queue.
281 *
282 * @throws NoSuchElementException if this queue is empty.
283 */
284 public function firstElement(): mixed;
285
286 /**
287 * Retrieves, but does not remove, the tail of this queue.
288 *
289 * This method differs from `peekLast()` only in that it throws an exception
290 * if this queue is empty.
291 *
292 * @return T the tail of this queue.
293 *
294 * @throws NoSuchElementException if this queue is empty.
295 */
296 public function lastElement(): mixed;
297
298 /**
299 * Retrieves, but does not remove, the head of this queue, or returns `null`
300 * if this queue is empty.
301 *
302 * @return T | null the head of this queue, or `null` if this queue is empty.
303 */
304 public function peekFirst(): mixed;
305
306 /**
307 * Retrieves, but does not remove, the tail of this queue, or returns `null`
308 * if this queue is empty.
309 *
310 * @return T | null the tail of this queue, or `null` if this queue is empty.
311 */
312 public function peekLast(): mixed;
313 }