Debian Codegraph @

vendor/ramsey/collection/src/QueueInterface.php

raw
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 public function add(mixed $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(): mixed;
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 public function offer(mixed $element): bool;
163
164 /**
165 * Retrieves, but does not remove, the head of this queue, or returns `null`
166 * if this queue is empty.
167 *
168 * @see self::element()
169 *
170 * @return T | null the head of this queue, or `null` if this queue is empty.
171 */
172 public function peek(): mixed;
173
174 /**
175 * Retrieves and removes the head of this queue, or returns `null`
176 * if this queue is empty.
177 *
178 * @see self::remove()
179 *
180 * @return T | null the head of this queue, or `null` if this queue is empty.
181 */
182 public function poll(): mixed;
183
184 /**
185 * Retrieves and removes the head of this queue.
186 *
187 * This method differs from `poll()` only in that it throws an exception if
188 * this queue is empty.
189 *
190 * @see self::poll()
191 *
192 * @return T the head of this queue.
193 *
194 * @throws NoSuchElementException if this queue is empty.
195 */
196 public function remove(): mixed;
197
198 /**
199 * Returns the type associated with this queue.
200 */
201 public function getType(): string;
202 }