Debian Codegraph @

vendor/ramsey/collection/src/Map/MapInterface.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\ArrayInterface;
18
19 /**
20 * An object that maps keys to values.
21 *
22 * A map cannot contain duplicate keys; each key can map to at most one value.
23 *
24 * @template K of array-key
25 * @template T
26 * @extends ArrayInterface<T>
27 */
28 interface MapInterface extends ArrayInterface
29 {
30 /**
31 * Returns `true` if this map contains a mapping for the specified key.
32 *
33 * @param K $key The key to check in the map.
34 */
35 public function containsKey(int | string $key): bool;
36
37 /**
38 * Returns `true` if this map maps one or more keys to the specified value.
39 *
40 * This performs a strict type check on the value.
41 *
42 * @param T $value The value to check in the map.
43 */
44 public function containsValue(mixed $value): bool;
45
46 /**
47 * Return an array of the keys contained in this map.
48 *
49 * @return list<K>
50 */
51 public function keys(): array;
52
53 /**
54 * Returns the value to which the specified key is mapped, `null` if this
55 * map contains no mapping for the key, or (optionally) `$defaultValue` if
56 * this map contains no mapping for the key.
57 *
58 * @param K $key The key to return from the map.
59 * @param T | null $defaultValue The default value to use if `$key` is not found.
60 *
61 * @return T | null the value or `null` if the key could not be found.
62 */
63 public function get(int | string $key, mixed $defaultValue = null): mixed;
64
65 /**
66 * Associates the specified value with the specified key in this map.
67 *
68 * If the map previously contained a mapping for the key, the old value is
69 * replaced by the specified value.
70 *
71 * @param K $key The key to put or replace in the map.
72 * @param T $value The value to store at `$key`.
73 *
74 * @return T | null the previous value associated with key, or `null` if
75 * there was no mapping for `$key`.
76 */
77 public function put(int | string $key, mixed $value): mixed;
78
79 /**
80 * Associates the specified value with the specified key in this map only if
81 * it is not already set.
82 *
83 * If there is already a value associated with `$key`, this returns that
84 * value without replacing it.
85 *
86 * @param K $key The key to put in the map.
87 * @param T $value The value to store at `$key`.
88 *
89 * @return T | null the previous value associated with key, or `null` if
90 * there was no mapping for `$key`.
91 */
92 public function putIfAbsent(int | string $key, mixed $value): mixed;
93
94 /**
95 * Removes the mapping for a key from this map if it is present.
96 *
97 * @param K $key The key to remove from the map.
98 *
99 * @return T | null the previous value associated with key, or `null` if
100 * there was no mapping for `$key`.
101 */
102 public function remove(int | string $key): mixed;
103
104 /**
105 * Removes the entry for the specified key only if it is currently mapped to
106 * the specified value.
107 *
108 * This performs a strict type check on the value.
109 *
110 * @param K $key The key to remove from the map.
111 * @param T $value The value to match.
112 *
113 * @return bool true if the value was removed.
114 */
115 public function removeIf(int | string $key, mixed $value): bool;
116
117 /**
118 * Replaces the entry for the specified key only if it is currently mapped
119 * to some value.
120 *
121 * @param K $key The key to replace.
122 * @param T $value The value to set at `$key`.
123 *
124 * @return T | null the previous value associated with key, or `null` if
125 * there was no mapping for `$key`.
126 */
127 public function replace(int | string $key, mixed $value): mixed;
128
129 /**
130 * Replaces the entry for the specified key only if currently mapped to the
131 * specified value.
132 *
133 * This performs a strict type check on the value.
134 *
135 * @param K $key The key to remove from the map.
136 * @param T $oldValue The value to match.
137 * @param T $newValue The value to use as a replacement.
138 *
139 * @return bool true if the value was replaced.
140 */
141 public function replaceIf(int | string $key, mixed $oldValue, mixed $newValue): bool;
142 }