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

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

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