Debian Codegraph @

vendor/ramsey/collection/src/Queue.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\InvalidArgumentException;
18 use Ramsey\Collection\Exception\NoSuchElementException;
19 use Ramsey\Collection\Tool\TypeTrait;
20 use Ramsey\Collection\Tool\ValueToStringTrait;
21
22 use function array_key_first;
23
24 /**
25 * This class provides a basic implementation of `QueueInterface`, to minimize
26 * the effort required to implement this interface.
27 *
28 * @template T
29 * @extends AbstractArray<T>
30 * @implements QueueInterface<T>
31 */
32 class Queue extends AbstractArray implements QueueInterface
33 {
34 use TypeTrait;
35 use ValueToStringTrait;
36
37 /**
38 * Constructs a queue object of the specified type, optionally with the
39 * specified data.
40 *
41 * @param string $queueType The type or class name associated with this queue.
42 * @param array<array-key, T> $data The initial items to store in the queue.
43 */
44 public function __construct(private readonly string $queueType, array $data = [])
45 {
46 parent::__construct($data);
47 }
48
49 /**
50 * {@inheritDoc}
51 *
52 * Since arbitrary offsets may not be manipulated in a queue, this method
53 * serves only to fulfill the `ArrayAccess` interface requirements. It is
54 * invoked by other operations when adding values to the queue.
55 *
56 * @throws InvalidArgumentException if $value is of the wrong type.
57 */
58 public function offsetSet(mixed $offset, mixed $value): void
59 {
60 if ($this->checkType($this->getType(), $value) === false) {
61 throw new InvalidArgumentException(
62 'Value must be of type ' . $this->getType() . '; value is '
63 . $this->toolValueToString($value),
64 );
65 }
66
67 $this->data[] = $value;
68 }
69
70 /**
71 * @throws InvalidArgumentException if $value is of the wrong type.
72 */
73 public function add(mixed $element): bool
74 {
75 $this[] = $element;
76
77 return true;
78 }
79
80 /**
81 * @return T
82 *
83 * @throws NoSuchElementException if this queue is empty.
84 */
85 public function element(): mixed
86 {
87 return $this->peek() ?? throw new NoSuchElementException(
88 'Can\'t return element from Queue. Queue is empty.',
89 );
90 }
91
92 public function offer(mixed $element): bool
93 {
94 try {
95 return $this->add($element);
96 } catch (InvalidArgumentException) {
97 return false;
98 }
99 }
100
101 /**
102 * @return T | null
103 */
104 public function peek(): mixed
105 {
106 $index = array_key_first($this->data);
107
108 if ($index === null) {
109 return null;
110 }
111
112 return $this[$index];
113 }
114
115 /**
116 * @return T | null
117 */
118 public function poll(): mixed
119 {
120 $index = array_key_first($this->data);
121
122 if ($index === null) {
123 return null;
124 }
125
126 $head = $this[$index];
127 unset($this[$index]);
128
129 return $head;
130 }
131
132 /**
133 * @return T
134 *
135 * @throws NoSuchElementException if this queue is empty.
136 */
137 public function remove(): mixed
138 {
139 return $this->poll() ?? throw new NoSuchElementException(
140 'Can\'t return element from Queue. Queue is empty.',
141 );
142 }
143
144 public function getType(): string
145 {
146 return $this->queueType;
147 }
148 }