Debian Codegraph @

vendor/ramsey/collection/src/DoubleEndedQueue.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
20 use function array_key_last;
21 use function array_pop;
22 use function array_unshift;
23
24 /**
25 * This class provides a basic implementation of `DoubleEndedQueueInterface`, to
26 * minimize the effort required to implement this interface.
27 *
28 * @template T
29 * @extends Queue<T>
30 * @implements DoubleEndedQueueInterface<T>
31 */
32 class DoubleEndedQueue extends Queue implements DoubleEndedQueueInterface
33 {
34 /**
35 * Constructs a double-ended queue (dequeue) object of the specified type,
36 * optionally with the specified data.
37 *
38 * @param string $queueType The type or class name associated with this dequeue.
39 * @param array<array-key, T> $data The initial items to store in the dequeue.
40 */
41 public function __construct(private readonly string $queueType, array $data = [])
42 {
43 parent::__construct($this->queueType, $data);
44 }
45
46 /**
47 * @throws InvalidArgumentException if $element is of the wrong type
48 */
49 public function addFirst(mixed $element): bool
50 {
51 if ($this->checkType($this->getType(), $element) === false) {
52 throw new InvalidArgumentException(
53 'Value must be of type ' . $this->getType() . '; value is '
54 . $this->toolValueToString($element),
55 );
56 }
57
58 array_unshift($this->data, $element);
59
60 return true;
61 }
62
63 /**
64 * @throws InvalidArgumentException if $element is of the wrong type
65 */
66 public function addLast(mixed $element): bool
67 {
68 return $this->add($element);
69 }
70
71 public function offerFirst(mixed $element): bool
72 {
73 try {
74 return $this->addFirst($element);
75 } catch (InvalidArgumentException) {
76 return false;
77 }
78 }
79
80 public function offerLast(mixed $element): bool
81 {
82 return $this->offer($element);
83 }
84
85 /**
86 * @return T the first element in this queue.
87 *
88 * @throws NoSuchElementException if the queue is empty
89 */
90 public function removeFirst(): mixed
91 {
92 return $this->remove();
93 }
94
95 /**
96 * @return T the last element in this queue.
97 *
98 * @throws NoSuchElementException if this queue is empty.
99 */
100 public function removeLast(): mixed
101 {
102 return $this->pollLast() ?? throw new NoSuchElementException(
103 'Can\'t return element from Queue. Queue is empty.',
104 );
105 }
106
107 /**
108 * @return T | null the head of this queue, or `null` if this queue is empty.
109 */
110 public function pollFirst(): mixed
111 {
112 return $this->poll();
113 }
114
115 /**
116 * @return T | null the tail of this queue, or `null` if this queue is empty.
117 */
118 public function pollLast(): mixed
119 {
120 return array_pop($this->data);
121 }
122
123 /**
124 * @return T the head of this queue.
125 *
126 * @throws NoSuchElementException if this queue is empty.
127 */
128 public function firstElement(): mixed
129 {
130 return $this->element();
131 }
132
133 /**
134 * @return T the tail of this queue.
135 *
136 * @throws NoSuchElementException if this queue is empty.
137 */
138 public function lastElement(): mixed
139 {
140 return $this->peekLast() ?? throw new NoSuchElementException(
141 'Can\'t return element from Queue. Queue is empty.',
142 );
143 }
144
145 /**
146 * @return T | null the head of this queue, or `null` if this queue is empty.
147 */
148 public function peekFirst(): mixed
149 {
150 return $this->peek();
151 }
152
153 /**
154 * @return T | null the tail of this queue, or `null` if this queue is empty.
155 */
156 public function peekLast(): mixed
157 {
158 $lastIndex = array_key_last($this->data);
159
160 if ($lastIndex === null) {
161 return null;
162 }
163
164 return $this->data[$lastIndex];
165 }
166 }