defender-security / vendor / ramsey / collection / src / Map / MapInterface.php

MapInterface.php in Defender Security – Malware Scanner, Login Security & Firewall 3.0.1, at vendor/ramsey/collection/src/Map/MapInterface.php

150 lines 5.0 KB

Raw Download Zip

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 T
25	* @template-extends ArrayInterface<T>
26	*/
27	interface MapInterface extends ArrayInterface
28	{
29	/**
30	* Returns `true` if this map contains a mapping for the specified key.
31	*
32	* @param array-key $key The key to check in the map.
33	*/
34	public function containsKey($key): bool;
35
36	/**
37	* Returns `true` if this map maps one or more keys to the specified value.
38	*
39	* This performs a strict type check on the value.
40	*
41	* @param T $value The value to check in the map.
42	*/
43	// phpcs:ignore SlevomatCodingStandard.TypeHints.ParameterTypeHint.MissingNativeTypeHint
44	public function containsValue($value): bool;
45
46	/**
47	* Return an array of the keys contained in this map.
48	*
49	* @return list<array-key>
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 array-key $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	// phpcs:ignore SlevomatCodingStandard.TypeHints.ParameterTypeHint.MissingNativeTypeHint
64	public function get($key, $defaultValue = null);
65
66	/**
67	* Associates the specified value with the specified key in this map.
68	*
69	* If the map previously contained a mapping for the key, the old value is
70	* replaced by the specified value.
71	*
72	* @param array-key $key The key to put or replace in the map.
73	* @param T $value The value to store at `$key`.
74	*
75	* @return T\|null the previous value associated with key, or `null` if
76	* there was no mapping for `$key`.
77	*/
78	// phpcs:ignore SlevomatCodingStandard.TypeHints.ParameterTypeHint.MissingNativeTypeHint
79	public function put($key, $value);
80
81	/**
82	* Associates the specified value with the specified key in this map only if
83	* it is not already set.
84	*
85	* If there is already a value associated with `$key`, this returns that
86	* value without replacing it.
87	*
88	* @param array-key $key The key to put in the map.
89	* @param T $value The value to store at `$key`.
90	*
91	* @return T\|null the previous value associated with key, or `null` if
92	* there was no mapping for `$key`.
93	*/
94	// phpcs:ignore SlevomatCodingStandard.TypeHints.ParameterTypeHint.MissingNativeTypeHint
95	public function putIfAbsent($key, $value);
96
97	/**
98	* Removes the mapping for a key from this map if it is present.
99	*
100	* @param array-key $key The key to remove from the map.
101	*
102	* @return T\|null the previous value associated with key, or `null` if
103	* there was no mapping for `$key`.
104	*/
105	// phpcs:ignore SlevomatCodingStandard.TypeHints.ParameterTypeHint.MissingNativeTypeHint
106	public function remove($key);
107
108	/**
109	* Removes the entry for the specified key only if it is currently mapped to
110	* the specified value.
111	*
112	* This performs a strict type check on the value.
113	*
114	* @param array-key $key The key to remove from the map.
115	* @param T $value The value to match.
116	*
117	* @return bool true if the value was removed.
118	*/
119	// phpcs:ignore SlevomatCodingStandard.TypeHints.ParameterTypeHint.MissingNativeTypeHint
120	public function removeIf($key, $value): bool;
121
122	/**
123	* Replaces the entry for the specified key only if it is currently mapped
124	* to some value.
125	*
126	* @param array-key $key The key to replace.
127	* @param T $value The value to set at `$key`.
128	*
129	* @return T\|null the previous value associated with key, or `null` if
130	* there was no mapping for `$key`.
131	*/
132	// phpcs:ignore SlevomatCodingStandard.TypeHints.ParameterTypeHint.MissingNativeTypeHint
133	public function replace($key, $value);
134
135	/**
136	* Replaces the entry for the specified key only if currently mapped to the
137	* specified value.
138	*
139	* This performs a strict type check on the value.
140	*
141	* @param array-key $key The key to remove from the map.
142	* @param T $oldValue The value to match.
143	* @param T $newValue The value to use as a replacement.
144	*
145	* @return bool true if the value was replaced.
146	*/
147	// phpcs:ignore SlevomatCodingStandard.TypeHints.ParameterTypeHint.MissingNativeTypeHint
148	public function replaceIf($key, $oldValue, $newValue): bool;
149	}
150