Debian Codegraph @

vendor/ramsey/collection/src/Map/AbstractMap.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\Map;
16
17 use Ramsey\Collection\AbstractArray;
18 use Ramsey\Collection\Exception\InvalidArgumentException;
19 use Traversable;
20
21 use function array_key_exists;
22 use function array_keys;
23 use function in_array;
24 use function var_export;
25
26 /**
27 * This class provides a basic implementation of `MapInterface`, to minimize the
28 * effort required to implement this interface.
29 *
30 * @template K of array-key
31 * @template T
32 * @extends AbstractArray<T>
33 * @implements MapInterface<K, T>
34 */
35 abstract class AbstractMap extends AbstractArray implements MapInterface
36 {
37 /**
38 * @param array<K, T> $data The initial items to add to this map.
39 */
40 public function __construct(array $data = [])
41 {
42 parent::__construct($data);
43 }
44
45 /**
46 * @return Traversable<K, T>
47 */
48 public function getIterator(): Traversable
49 {
50 return parent::getIterator();
51 }
52
53 /**
54 * @param K $offset The offset to set
55 * @param T $value The value to set at the given offset.
56 *
57 * @inheritDoc
58 */
59 public function offsetSet(mixed $offset, mixed $value): void
60 {
61 if ($offset === null) {
62 throw new InvalidArgumentException(
63 'Map elements are key/value pairs; a key must be provided for '
64 . 'value ' . var_export($value, true),
65 );
66 }
67
68 $this->data[$offset] = $value;
69 }
70
71 public function containsKey(int | string $key): bool
72 {
73 return array_key_exists($key, $this->data);
74 }
75
76 public function containsValue(mixed $value): bool
77 {
78 return in_array($value, $this->data, true);
79 }
80
81 /**
82 * @inheritDoc
83 */
84 public function keys(): array
85 {
86 /** @var list<K> */
87 return array_keys($this->data);
88 }
89
90 /**
91 * @param K $key The key to return from the map.
92 * @param T | null $defaultValue The default value to use if `$key` is not found.
93 *
94 * @return T | null the value or `null` if the key could not be found.
95 */
96 public function get(int | string $key, mixed $defaultValue = null): mixed
97 {
98 return $this[$key] ?? $defaultValue;
99 }
100
101 /**
102 * @param K $key The key to put or replace in the map.
103 * @param T $value The value to store at `$key`.
104 *
105 * @return T | null the previous value associated with key, or `null` if
106 * there was no mapping for `$key`.
107 */
108 public function put(int | string $key, mixed $value): mixed
109 {
110 $previousValue = $this->get($key);
111 $this[$key] = $value;
112
113 return $previousValue;
114 }
115
116 /**
117 * @param K $key The key to put in the map.
118 * @param T $value The value to store at `$key`.
119 *
120 * @return T | null the previous value associated with key, or `null` if
121 * there was no mapping for `$key`.
122 */
123 public function putIfAbsent(int | string $key, mixed $value): mixed
124 {
125 $currentValue = $this->get($key);
126
127 if ($currentValue === null) {
128 $this[$key] = $value;
129 }
130
131 return $currentValue;
132 }
133
134 /**
135 * @param K $key The key to remove from the map.
136 *
137 * @return T | null the previous value associated with key, or `null` if
138 * there was no mapping for `$key`.
139 */
140 public function remove(int | string $key): mixed
141 {
142 $previousValue = $this->get($key);
143 unset($this[$key]);
144
145 return $previousValue;
146 }
147
148 public function removeIf(int | string $key, mixed $value): bool
149 {
150 if ($this->get($key) === $value) {
151 unset($this[$key]);
152
153 return true;
154 }
155
156 return false;
157 }
158
159 /**
160 * @param K $key The key to replace.
161 * @param T $value The value to set at `$key`.
162 *
163 * @return T | null the previous value associated with key, or `null` if
164 * there was no mapping for `$key`.
165 */
166 public function replace(int | string $key, mixed $value): mixed
167 {
168 $currentValue = $this->get($key);
169
170 if ($this->containsKey($key)) {
171 $this[$key] = $value;
172 }
173
174 return $currentValue;
175 }
176
177 public function replaceIf(int | string $key, mixed $oldValue, mixed $newValue): bool
178 {
179 if ($this->get($key) === $oldValue) {
180 $this[$key] = $newValue;
181
182 return true;
183 }
184
185 return false;
186 }
187
188 /**
189 * @return array<K, T>
190 */
191 public function __serialize(): array
192 {
193 /** @var array<K, T> */
194 return parent::__serialize();
195 }
196
197 /**
198 * @return array<K, T>
199 */
200 public function toArray(): array
201 {
202 /** @var array<K, T> */
203 return parent::toArray();
204 }
205 }