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

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

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