defender-security / vendor / ramsey / collection / src / DoubleEndedQueueInterface.php

DoubleEndedQueueInterface.php in Defender Security – Malware Scanner, Login Security & Firewall 5.7.0, at vendor/ramsey/collection/src/DoubleEndedQueueInterface.php

318 lines 10.4 KB

Raw Download Zip

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	// phpcs:ignore SlevomatCodingStandard.TypeHints.ParameterTypeHint.MissingNativeTypeHint
185	public function addFirst($element): bool;
186
187	/**
188	* Inserts the specified element at the end of this queue if it is possible
189	* to do so immediately without violating capacity restrictions.
190	*
191	* When using a capacity-restricted double-ended queue, it is generally
192	* preferable to use the `offerLast()` method.
193	*
194	* This method is equivalent to `add()`.
195	*
196	* @param T $element The element to add to the end of this queue.
197	*
198	* @return bool `true` if this queue changed as a result of the call.
199	*
200	* @throws RuntimeException if a queue refuses to add a particular element
201	* for any reason other than that it already contains the element.
202	* Implementations should use a more-specific exception that extends
203	* `\RuntimeException`.
204	*/
205	// phpcs:ignore SlevomatCodingStandard.TypeHints.ParameterTypeHint.MissingNativeTypeHint
206	public function addLast($element): bool;
207
208	/**
209	* Inserts the specified element at the front of this queue if it is
210	* possible to do so immediately without violating capacity restrictions.
211	*
212	* When using a capacity-restricted queue, this method is generally
213	* preferable to `addFirst()`, which can fail to insert an element only by
214	* throwing an exception.
215	*
216	* @param T $element The element to add to the front of this queue.
217	*
218	* @return bool `true` if the element was added to this queue, else `false`.
219	*/
220	// phpcs:ignore SlevomatCodingStandard.TypeHints.ParameterTypeHint.MissingNativeTypeHint
221	public function offerFirst($element): bool;
222
223	/**
224	* Inserts the specified element at the end of this queue if it is possible
225	* to do so immediately without violating capacity restrictions.
226	*
227	* When using a capacity-restricted queue, this method is generally
228	* preferable to `addLast()` which can fail to insert an element only by
229	* throwing an exception.
230	*
231	* @param T $element The element to add to the end of this queue.
232	*
233	* @return bool `true` if the element was added to this queue, else `false`.
234	*/
235	// phpcs:ignore SlevomatCodingStandard.TypeHints.ParameterTypeHint.MissingNativeTypeHint
236	public function offerLast($element): bool;
237
238	/**
239	* Retrieves and removes the head of this queue.
240	*
241	* This method differs from `pollFirst()` only in that it throws an
242	* exception if this queue is empty.
243	*
244	* @return T the first element in this queue.
245	*
246	* @throws NoSuchElementException if this queue is empty.
247	*/
248	public function removeFirst();
249
250	/**
251	* Retrieves and removes the tail of this queue.
252	*
253	* This method differs from `pollLast()` only in that it throws an exception
254	* if this queue is empty.
255	*
256	* @return T the last element in this queue.
257	*
258	* @throws NoSuchElementException if this queue is empty.
259	*/
260	public function removeLast();
261
262	/**
263	* Retrieves and removes the head of this queue, or returns `null` if this
264	* queue is empty.
265	*
266	* @return T\|null the head of this queue, or `null` if this queue is empty.
267	*/
268	public function pollFirst();
269
270	/**
271	* Retrieves and removes the tail of this queue, or returns `null` if this
272	* queue is empty.
273	*
274	* @return T\|null the tail of this queue, or `null` if this queue is empty.
275	*/
276	public function pollLast();
277
278	/**
279	* Retrieves, but does not remove, the head of this queue.
280	*
281	* This method differs from `peekFirst()` only in that it throws an
282	* exception if this queue is empty.
283	*
284	* @return T the head of this queue.
285	*
286	* @throws NoSuchElementException if this queue is empty.
287	*/
288	public function firstElement();
289
290	/**
291	* Retrieves, but does not remove, the tail of this queue.
292	*
293	* This method differs from `peekLast()` only in that it throws an exception
294	* if this queue is empty.
295	*
296	* @return T the tail of this queue.
297	*
298	* @throws NoSuchElementException if this queue is empty.
299	*/
300	public function lastElement();
301
302	/**
303	* Retrieves, but does not remove, the head of this queue, or returns `null`
304	* if this queue is empty.
305	*
306	* @return T\|null the head of this queue, or `null` if this queue is empty.
307	*/
308	public function peekFirst();
309
310	/**
311	* Retrieves, but does not remove, the tail of this queue, or returns `null`
312	* if this queue is empty.
313	*
314	* @return T\|null the tail of this queue, or `null` if this queue is empty.
315	*/
316	public function peekLast();
317	}
318