media-cloud-sync / includes / sdk / google / ramsey / collection / src / DoubleEndedQueueInterface.php

DoubleEndedQueueInterface.php in Media Cloud Sync 1.4.1, at includes/sdk/google/ramsey/collection/src/DoubleEndedQueueInterface.php

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