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

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

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