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

QueueInterface.php in Media Cloud Sync 1.0.3, at includes/sdk/google/ramsey/collection/src/QueueInterface.php

196 lines 7.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 queue is a collection in which the entities in the collection are kept in
19	* order.
20	*
21	* The principal operations on the queue are the addition of entities to the end
22	* (tail), also known as enqueue, and removal of entities from the front
23	* (head), also known as dequeue. This makes the queue a first-in-first-out
24	* (FIFO) data structure.
25	*
26	* Besides basic array operations, queues provide additional insertion,
27	* extraction, and inspection operations. Each of these methods exists in two
28	* forms: one throws an exception if the operation fails, the other returns a
29	* special value (either `null` or `false`, depending on the operation). The
30	* latter form of the insert operation is designed specifically for use with
31	* capacity-restricted `QueueInterface` implementations; in most
32	* implementations, insert operations cannot fail.
33	*
34	* <table>
35	* <caption>Summary of QueueInterface methods</caption>
36	* <thead>
37	* <tr>
38	* <td></td>
39	* <td><em>Throws exception</em></td>
40	* <td><em>Returns special value</em></td>
41	* </tr>
42	* </thead>
43	* <tbody>
44	* <tr>
45	* <th>Insert</th>
46	* <td><code>add()</code></td>
47	* <td><code>offer()</code></td>
48	* </tr>
49	* <tr>
50	* <th>Remove</th>
51	* <td><code>remove()</code></td>
52	* <td><code>poll()</code></td>
53	* </tr>
54	* <tr>
55	* <th>Examine</th>
56	* <td><code>element()</code></td>
57	* <td><code>peek()</code></td>
58	* </tr>
59	* </tbody>
60	* </table>
61	*
62	* Queues typically, but do not necessarily, order elements in a FIFO
63	* (first-in-first-out) manner. Among the exceptions are priority queues, which
64	* order elements according to a supplied comparator, or the elements' natural
65	* ordering, and LIFO queues (or stacks) which order the elements LIFO
66	* (last-in-first-out). Whatever the ordering used, the head of the queue is
67	* that element which would be removed by a call to remove() or poll(). In a
68	* FIFO queue, all new elements are inserted at the tail of the queue. Other
69	* kinds of queues may use different placement rules. Every `QueueInterface`
70	* implementation must specify its ordering properties.
71	*
72	* The `offer()` method inserts an element if possible, otherwise returning
73	* `false`. This differs from the `add()` method, which can fail to add an
74	* element only by throwing an unchecked exception. The `offer()` method is
75	* designed for use when failure is a normal, rather than exceptional
76	* occurrence, for example, in fixed-capacity (or "bounded") queues.
77	*
78	* The `remove()` and `poll()` methods remove and return the head of the queue.
79	* Exactly which element is removed from the queue is a function of the queue's
80	* ordering policy, which differs from implementation to implementation. The
81	* `remove()` and `poll()` methods differ only in their behavior when the queue
82	* is empty: the `remove()` method throws an exception, while the `poll()`
83	* method returns `null`.
84	*
85	* The `element()` and `peek()` methods return, but do not remove, the head of
86	* the queue.
87	*
88	* `QueueInterface` implementations generally do not allow insertion of `null`
89	* elements, although some implementations do not prohibit insertion of `null`.
90	* Even in the implementations that permit it, `null` should not be inserted
91	* into a queue, as `null` is also used as a special return value by the
92	* `poll()` method to indicate that the queue contains no elements.
93	*
94	* @template T
95	* @extends ArrayInterface<T>
96	*/
97	interface QueueInterface extends ArrayInterface
98	{
99	/**
100	* Ensures that this queue contains the specified element (optional
101	* operation).
102	*
103	* Returns `true` if this queue changed as a result of the call. (Returns
104	* `false` if this queue does not permit duplicates and already contains the
105	* specified element.)
106	*
107	* Queues that support this operation may place limitations on what elements
108	* may be added to this queue. In particular, some queues will refuse to add
109	* `null` elements, and others will impose restrictions on the type of
110	* elements that may be added. Queue classes should clearly specify in their
111	* documentation any restrictions on what elements may be added.
112	*
113	* If a queue refuses to add a particular element for any reason other than
114	* that it already contains the element, it must throw an exception (rather
115	* than returning `false`). This preserves the invariant that a queue always
116	* contains the specified element after this call returns.
117	*
118	* @see self::offer()
119	*
120	* @param T $element The element to add to this queue.
121	*
122	* @return bool `true` if this queue changed as a result of the call.
123	*
124	* @throws RuntimeException if a queue refuses to add a particular element
125	* for any reason other than that it already contains the element.
126	* Implementations should use a more-specific exception that extends
127	* `\RuntimeException`.
128	*/
129	// phpcs:ignore SlevomatCodingStandard.TypeHints.ParameterTypeHint.MissingNativeTypeHint
130	public function add($element): bool;
131	/**
132	* Retrieves, but does not remove, the head of this queue.
133	*
134	* This method differs from `peek()` only in that it throws an exception if
135	* this queue is empty.
136	*
137	* @see self::peek()
138	*
139	* @return T the head of this queue.
140	*
141	* @throws NoSuchElementException if this queue is empty.
142	*/
143	public function element();
144	/**
145	* Inserts the specified element into this queue if it is possible to do so
146	* immediately without violating capacity restrictions.
147	*
148	* When using a capacity-restricted queue, this method is generally
149	* preferable to `add()`, which can fail to insert an element only by
150	* throwing an exception.
151	*
152	* @see self::add()
153	*
154	* @param T $element The element to add to this queue.
155	*
156	* @return bool `true` if the element was added to this queue, else `false`.
157	*/
158	// phpcs:ignore SlevomatCodingStandard.TypeHints.ParameterTypeHint.MissingNativeTypeHint
159	public function offer($element): bool;
160	/**
161	* Retrieves, but does not remove, the head of this queue, or returns `null`
162	* if this queue is empty.
163	*
164	* @see self::element()
165	*
166	* @return T\|null the head of this queue, or `null` if this queue is empty.
167	*/
168	public function peek();
169	/**
170	* Retrieves and removes the head of this queue, or returns `null`
171	* if this queue is empty.
172	*
173	* @see self::remove()
174	*
175	* @return T\|null the head of this queue, or `null` if this queue is empty.
176	*/
177	public function poll();
178	/**
179	* Retrieves and removes the head of this queue.
180	*
181	* This method differs from `poll()` only in that it throws an exception if
182	* this queue is empty.
183	*
184	* @see self::poll()
185	*
186	* @return T the head of this queue.
187	*
188	* @throws NoSuchElementException if this queue is empty.
189	*/
190	public function remove();
191	/**
192	* Returns the type associated with this queue.
193	*/
194	public function getType(): string;
195	}
196