author | smarks |
Fri, 06 May 2016 11:33:32 -0700 | |
changeset 37802 | 91fc9ac7b8b3 |
parent 35396 | c58a744d0bb4 |
child 38567 | 6d4c5a278fff |
permissions | -rw-r--r-- |
2 | 1 |
/* |
34527
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
2 |
* Copyright (c) 1997, 2015, Oracle and/or its affiliates. All rights reserved. |
2 | 3 |
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
4 |
* |
|
5 |
* This code is free software; you can redistribute it and/or modify it |
|
6 |
* under the terms of the GNU General Public License version 2 only, as |
|
5506 | 7 |
* published by the Free Software Foundation. Oracle designates this |
2 | 8 |
* particular file as subject to the "Classpath" exception as provided |
5506 | 9 |
* by Oracle in the LICENSE file that accompanied this code. |
2 | 10 |
* |
11 |
* This code is distributed in the hope that it will be useful, but WITHOUT |
|
12 |
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
|
13 |
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
|
14 |
* version 2 for more details (a copy is included in the LICENSE file that |
|
15 |
* accompanied this code). |
|
16 |
* |
|
17 |
* You should have received a copy of the GNU General Public License version |
|
18 |
* 2 along with this work; if not, write to the Free Software Foundation, |
|
19 |
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. |
|
20 |
* |
|
5506 | 21 |
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA |
22 |
* or visit www.oracle.com if you need additional information or have any |
|
23 |
* questions. |
|
2 | 24 |
*/ |
25 |
||
26 |
package java.util; |
|
27 |
||
16867 | 28 |
import java.util.function.BiConsumer; |
29 |
import java.util.function.BiFunction; |
|
30 |
import java.util.function.Function; |
|
18571 | 31 |
import java.io.Serializable; |
16867 | 32 |
|
2 | 33 |
/** |
34 |
* An object that maps keys to values. A map cannot contain duplicate keys; |
|
35 |
* each key can map to at most one value. |
|
36 |
* |
|
32108
aa5490a167ee
8133188: docs: replace <tt> tags (obsolete in html5) for java.util
avstepan
parents:
29743
diff
changeset
|
37 |
* <p>This interface takes the place of the {@code Dictionary} class, which |
2 | 38 |
* was a totally abstract class rather than an interface. |
39 |
* |
|
32108
aa5490a167ee
8133188: docs: replace <tt> tags (obsolete in html5) for java.util
avstepan
parents:
29743
diff
changeset
|
40 |
* <p>The {@code Map} interface provides three <i>collection views</i>, which |
2 | 41 |
* allow a map's contents to be viewed as a set of keys, collection of values, |
42 |
* or set of key-value mappings. The <i>order</i> of a map is defined as |
|
43 |
* the order in which the iterators on the map's collection views return their |
|
32108
aa5490a167ee
8133188: docs: replace <tt> tags (obsolete in html5) for java.util
avstepan
parents:
29743
diff
changeset
|
44 |
* elements. Some map implementations, like the {@code TreeMap} class, make |
aa5490a167ee
8133188: docs: replace <tt> tags (obsolete in html5) for java.util
avstepan
parents:
29743
diff
changeset
|
45 |
* specific guarantees as to their order; others, like the {@code HashMap} |
2 | 46 |
* class, do not. |
47 |
* |
|
48 |
* <p>Note: great care must be exercised if mutable objects are used as map |
|
49 |
* keys. The behavior of a map is not specified if the value of an object is |
|
32108
aa5490a167ee
8133188: docs: replace <tt> tags (obsolete in html5) for java.util
avstepan
parents:
29743
diff
changeset
|
50 |
* changed in a manner that affects {@code equals} comparisons while the |
2 | 51 |
* object is a key in the map. A special case of this prohibition is that it |
52 |
* is not permissible for a map to contain itself as a key. While it is |
|
53 |
* permissible for a map to contain itself as a value, extreme caution is |
|
32108
aa5490a167ee
8133188: docs: replace <tt> tags (obsolete in html5) for java.util
avstepan
parents:
29743
diff
changeset
|
54 |
* advised: the {@code equals} and {@code hashCode} methods are no longer |
2 | 55 |
* well defined on such a map. |
56 |
* |
|
57 |
* <p>All general-purpose map implementation classes should provide two |
|
58 |
* "standard" constructors: a void (no arguments) constructor which creates an |
|
32108
aa5490a167ee
8133188: docs: replace <tt> tags (obsolete in html5) for java.util
avstepan
parents:
29743
diff
changeset
|
59 |
* empty map, and a constructor with a single argument of type {@code Map}, |
2 | 60 |
* which creates a new map with the same key-value mappings as its argument. |
61 |
* In effect, the latter constructor allows the user to copy any map, |
|
62 |
* producing an equivalent map of the desired class. There is no way to |
|
63 |
* enforce this recommendation (as interfaces cannot contain constructors) but |
|
64 |
* all of the general-purpose map implementations in the JDK comply. |
|
65 |
* |
|
66 |
* <p>The "destructive" methods contained in this interface, that is, the |
|
67 |
* methods that modify the map on which they operate, are specified to throw |
|
32108
aa5490a167ee
8133188: docs: replace <tt> tags (obsolete in html5) for java.util
avstepan
parents:
29743
diff
changeset
|
68 |
* {@code UnsupportedOperationException} if this map does not support the |
2 | 69 |
* operation. If this is the case, these methods may, but are not required |
32108
aa5490a167ee
8133188: docs: replace <tt> tags (obsolete in html5) for java.util
avstepan
parents:
29743
diff
changeset
|
70 |
* to, throw an {@code UnsupportedOperationException} if the invocation would |
2 | 71 |
* have no effect on the map. For example, invoking the {@link #putAll(Map)} |
72 |
* method on an unmodifiable map may, but is not required to, throw the |
|
73 |
* exception if the map whose mappings are to be "superimposed" is empty. |
|
74 |
* |
|
75 |
* <p>Some map implementations have restrictions on the keys and values they |
|
76 |
* may contain. For example, some implementations prohibit null keys and |
|
77 |
* values, and some have restrictions on the types of their keys. Attempting |
|
78 |
* to insert an ineligible key or value throws an unchecked exception, |
|
32108
aa5490a167ee
8133188: docs: replace <tt> tags (obsolete in html5) for java.util
avstepan
parents:
29743
diff
changeset
|
79 |
* typically {@code NullPointerException} or {@code ClassCastException}. |
2 | 80 |
* Attempting to query the presence of an ineligible key or value may throw an |
81 |
* exception, or it may simply return false; some implementations will exhibit |
|
82 |
* the former behavior and some will exhibit the latter. More generally, |
|
83 |
* attempting an operation on an ineligible key or value whose completion |
|
84 |
* would not result in the insertion of an ineligible element into the map may |
|
85 |
* throw an exception or it may succeed, at the option of the implementation. |
|
86 |
* Such exceptions are marked as "optional" in the specification for this |
|
87 |
* interface. |
|
88 |
* |
|
89 |
* <p>Many methods in Collections Framework interfaces are defined |
|
90 |
* in terms of the {@link Object#equals(Object) equals} method. For |
|
91 |
* example, the specification for the {@link #containsKey(Object) |
|
32108
aa5490a167ee
8133188: docs: replace <tt> tags (obsolete in html5) for java.util
avstepan
parents:
29743
diff
changeset
|
92 |
* containsKey(Object key)} method says: "returns {@code true} if and |
aa5490a167ee
8133188: docs: replace <tt> tags (obsolete in html5) for java.util
avstepan
parents:
29743
diff
changeset
|
93 |
* only if this map contains a mapping for a key {@code k} such that |
aa5490a167ee
8133188: docs: replace <tt> tags (obsolete in html5) for java.util
avstepan
parents:
29743
diff
changeset
|
94 |
* {@code (key==null ? k==null : key.equals(k))}." This specification should |
aa5490a167ee
8133188: docs: replace <tt> tags (obsolete in html5) for java.util
avstepan
parents:
29743
diff
changeset
|
95 |
* <i>not</i> be construed to imply that invoking {@code Map.containsKey} |
aa5490a167ee
8133188: docs: replace <tt> tags (obsolete in html5) for java.util
avstepan
parents:
29743
diff
changeset
|
96 |
* with a non-null argument {@code key} will cause {@code key.equals(k)} to |
aa5490a167ee
8133188: docs: replace <tt> tags (obsolete in html5) for java.util
avstepan
parents:
29743
diff
changeset
|
97 |
* be invoked for any key {@code k}. Implementations are free to |
aa5490a167ee
8133188: docs: replace <tt> tags (obsolete in html5) for java.util
avstepan
parents:
29743
diff
changeset
|
98 |
* implement optimizations whereby the {@code equals} invocation is avoided, |
2 | 99 |
* for example, by first comparing the hash codes of the two keys. (The |
100 |
* {@link Object#hashCode()} specification guarantees that two objects with |
|
101 |
* unequal hash codes cannot be equal.) More generally, implementations of |
|
102 |
* the various Collections Framework interfaces are free to take advantage of |
|
103 |
* the specified behavior of underlying {@link Object} methods wherever the |
|
104 |
* implementor deems it appropriate. |
|
105 |
* |
|
20491
eb2dfc7436af
7057785: Add note about optional support of recursive methods for self-referential Collection/Map
mduigou
parents:
20189
diff
changeset
|
106 |
* <p>Some map operations which perform recursive traversal of the map may fail |
eb2dfc7436af
7057785: Add note about optional support of recursive methods for self-referential Collection/Map
mduigou
parents:
20189
diff
changeset
|
107 |
* with an exception for self-referential instances where the map directly or |
eb2dfc7436af
7057785: Add note about optional support of recursive methods for self-referential Collection/Map
mduigou
parents:
20189
diff
changeset
|
108 |
* indirectly contains itself. This includes the {@code clone()}, |
eb2dfc7436af
7057785: Add note about optional support of recursive methods for self-referential Collection/Map
mduigou
parents:
20189
diff
changeset
|
109 |
* {@code equals()}, {@code hashCode()} and {@code toString()} methods. |
eb2dfc7436af
7057785: Add note about optional support of recursive methods for self-referential Collection/Map
mduigou
parents:
20189
diff
changeset
|
110 |
* Implementations may optionally handle the self-referential scenario, however |
eb2dfc7436af
7057785: Add note about optional support of recursive methods for self-referential Collection/Map
mduigou
parents:
20189
diff
changeset
|
111 |
* most current implementations do not do so. |
eb2dfc7436af
7057785: Add note about optional support of recursive methods for self-referential Collection/Map
mduigou
parents:
20189
diff
changeset
|
112 |
* |
34527
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
113 |
* <h2><a name="immutable">Immutable Map Static Factory Methods</a></h2> |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
114 |
* <p>The {@link Map#of() Map.of()} and |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
115 |
* {@link Map#ofEntries(Map.Entry...) Map.ofEntries()} |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
116 |
* static factory methods provide a convenient way to create immutable maps. |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
117 |
* The {@code Map} |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
118 |
* instances created by these methods have the following characteristics: |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
119 |
* |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
120 |
* <ul> |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
121 |
* <li>They are <em>structurally immutable</em>. Keys and values cannot be added, |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
122 |
* removed, or updated. Attempts to do so result in {@code UnsupportedOperationException}. |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
123 |
* However, if the contained keys or values are themselves mutable, this may cause the |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
124 |
* Map to behave inconsistently or its contents to appear to change. |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
125 |
* <li>They disallow {@code null} keys and values. Attempts to create them with |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
126 |
* {@code null} keys or values result in {@code NullPointerException}. |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
127 |
* <li>They are serializable if all keys and values are serializable. |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
128 |
* <li>They reject duplicate keys at creation time. Duplicate keys |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
129 |
* passed to a static factory method result in {@code IllegalArgumentException}. |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
130 |
* <li>The iteration order of mappings is unspecified and is subject to change. |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
131 |
* <li>They are <a href="../lang/doc-files/ValueBased.html">value-based</a>. |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
132 |
* Callers should make no assumptions about the identity of the returned instances. |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
133 |
* Factories are free to create new instances or reuse existing ones. Therefore, |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
134 |
* identity-sensitive operations on these instances (reference equality ({@code ==}), |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
135 |
* identity hash code, and synchronization) are unreliable and should be avoided. |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
136 |
* </ul> |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
137 |
* |
20491
eb2dfc7436af
7057785: Add note about optional support of recursive methods for self-referential Collection/Map
mduigou
parents:
20189
diff
changeset
|
138 |
* <p>This interface is a member of the |
eb2dfc7436af
7057785: Add note about optional support of recursive methods for self-referential Collection/Map
mduigou
parents:
20189
diff
changeset
|
139 |
* <a href="{@docRoot}/../technotes/guides/collections/index.html"> |
eb2dfc7436af
7057785: Add note about optional support of recursive methods for self-referential Collection/Map
mduigou
parents:
20189
diff
changeset
|
140 |
* Java Collections Framework</a>. |
eb2dfc7436af
7057785: Add note about optional support of recursive methods for self-referential Collection/Map
mduigou
parents:
20189
diff
changeset
|
141 |
* |
2 | 142 |
* @param <K> the type of keys maintained by this map |
143 |
* @param <V> the type of mapped values |
|
144 |
* |
|
145 |
* @author Josh Bloch |
|
146 |
* @see HashMap |
|
147 |
* @see TreeMap |
|
148 |
* @see Hashtable |
|
149 |
* @see SortedMap |
|
150 |
* @see Collection |
|
151 |
* @see Set |
|
152 |
* @since 1.2 |
|
153 |
*/ |
|
34527
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
154 |
public interface Map<K, V> { |
2 | 155 |
// Query Operations |
156 |
||
157 |
/** |
|
158 |
* Returns the number of key-value mappings in this map. If the |
|
32108
aa5490a167ee
8133188: docs: replace <tt> tags (obsolete in html5) for java.util
avstepan
parents:
29743
diff
changeset
|
159 |
* map contains more than {@code Integer.MAX_VALUE} elements, returns |
aa5490a167ee
8133188: docs: replace <tt> tags (obsolete in html5) for java.util
avstepan
parents:
29743
diff
changeset
|
160 |
* {@code Integer.MAX_VALUE}. |
2 | 161 |
* |
162 |
* @return the number of key-value mappings in this map |
|
163 |
*/ |
|
164 |
int size(); |
|
165 |
||
166 |
/** |
|
32108
aa5490a167ee
8133188: docs: replace <tt> tags (obsolete in html5) for java.util
avstepan
parents:
29743
diff
changeset
|
167 |
* Returns {@code true} if this map contains no key-value mappings. |
2 | 168 |
* |
32108
aa5490a167ee
8133188: docs: replace <tt> tags (obsolete in html5) for java.util
avstepan
parents:
29743
diff
changeset
|
169 |
* @return {@code true} if this map contains no key-value mappings |
2 | 170 |
*/ |
171 |
boolean isEmpty(); |
|
172 |
||
173 |
/** |
|
32108
aa5490a167ee
8133188: docs: replace <tt> tags (obsolete in html5) for java.util
avstepan
parents:
29743
diff
changeset
|
174 |
* Returns {@code true} if this map contains a mapping for the specified |
aa5490a167ee
8133188: docs: replace <tt> tags (obsolete in html5) for java.util
avstepan
parents:
29743
diff
changeset
|
175 |
* key. More formally, returns {@code true} if and only if |
aa5490a167ee
8133188: docs: replace <tt> tags (obsolete in html5) for java.util
avstepan
parents:
29743
diff
changeset
|
176 |
* this map contains a mapping for a key {@code k} such that |
aa5490a167ee
8133188: docs: replace <tt> tags (obsolete in html5) for java.util
avstepan
parents:
29743
diff
changeset
|
177 |
* {@code Objects.equals(key, k)}. (There can be |
2 | 178 |
* at most one such mapping.) |
179 |
* |
|
180 |
* @param key key whose presence in this map is to be tested |
|
32108
aa5490a167ee
8133188: docs: replace <tt> tags (obsolete in html5) for java.util
avstepan
parents:
29743
diff
changeset
|
181 |
* @return {@code true} if this map contains a mapping for the specified |
2 | 182 |
* key |
183 |
* @throws ClassCastException if the key is of an inappropriate type for |
|
9503
588cf31d584a
6546713: link the word (optional) in exception specifications to the text which provides explanation and context.
mduigou
parents:
5506
diff
changeset
|
184 |
* this map |
23738 | 185 |
* (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>) |
2 | 186 |
* @throws NullPointerException if the specified key is null and this map |
9503
588cf31d584a
6546713: link the word (optional) in exception specifications to the text which provides explanation and context.
mduigou
parents:
5506
diff
changeset
|
187 |
* does not permit null keys |
23738 | 188 |
* (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>) |
2 | 189 |
*/ |
190 |
boolean containsKey(Object key); |
|
191 |
||
192 |
/** |
|
32108
aa5490a167ee
8133188: docs: replace <tt> tags (obsolete in html5) for java.util
avstepan
parents:
29743
diff
changeset
|
193 |
* Returns {@code true} if this map maps one or more keys to the |
aa5490a167ee
8133188: docs: replace <tt> tags (obsolete in html5) for java.util
avstepan
parents:
29743
diff
changeset
|
194 |
* specified value. More formally, returns {@code true} if and only if |
aa5490a167ee
8133188: docs: replace <tt> tags (obsolete in html5) for java.util
avstepan
parents:
29743
diff
changeset
|
195 |
* this map contains at least one mapping to a value {@code v} such that |
aa5490a167ee
8133188: docs: replace <tt> tags (obsolete in html5) for java.util
avstepan
parents:
29743
diff
changeset
|
196 |
* {@code Objects.equals(value, v)}. This operation |
2 | 197 |
* will probably require time linear in the map size for most |
32108
aa5490a167ee
8133188: docs: replace <tt> tags (obsolete in html5) for java.util
avstepan
parents:
29743
diff
changeset
|
198 |
* implementations of the {@code Map} interface. |
2 | 199 |
* |
200 |
* @param value value whose presence in this map is to be tested |
|
32108
aa5490a167ee
8133188: docs: replace <tt> tags (obsolete in html5) for java.util
avstepan
parents:
29743
diff
changeset
|
201 |
* @return {@code true} if this map maps one or more keys to the |
2 | 202 |
* specified value |
203 |
* @throws ClassCastException if the value is of an inappropriate type for |
|
9503
588cf31d584a
6546713: link the word (optional) in exception specifications to the text which provides explanation and context.
mduigou
parents:
5506
diff
changeset
|
204 |
* this map |
23738 | 205 |
* (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>) |
2 | 206 |
* @throws NullPointerException if the specified value is null and this |
9503
588cf31d584a
6546713: link the word (optional) in exception specifications to the text which provides explanation and context.
mduigou
parents:
5506
diff
changeset
|
207 |
* map does not permit null values |
23738 | 208 |
* (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>) |
2 | 209 |
*/ |
210 |
boolean containsValue(Object value); |
|
211 |
||
212 |
/** |
|
213 |
* Returns the value to which the specified key is mapped, |
|
214 |
* or {@code null} if this map contains no mapping for the key. |
|
215 |
* |
|
216 |
* <p>More formally, if this map contains a mapping from a key |
|
32108
aa5490a167ee
8133188: docs: replace <tt> tags (obsolete in html5) for java.util
avstepan
parents:
29743
diff
changeset
|
217 |
* {@code k} to a value {@code v} such that |
aa5490a167ee
8133188: docs: replace <tt> tags (obsolete in html5) for java.util
avstepan
parents:
29743
diff
changeset
|
218 |
* {@code Objects.equals(key, k)}, |
aa5490a167ee
8133188: docs: replace <tt> tags (obsolete in html5) for java.util
avstepan
parents:
29743
diff
changeset
|
219 |
* then this method returns {@code v}; otherwise |
2 | 220 |
* it returns {@code null}. (There can be at most one such mapping.) |
221 |
* |
|
222 |
* <p>If this map permits null values, then a return value of |
|
223 |
* {@code null} does not <i>necessarily</i> indicate that the map |
|
224 |
* contains no mapping for the key; it's also possible that the map |
|
225 |
* explicitly maps the key to {@code null}. The {@link #containsKey |
|
226 |
* containsKey} operation may be used to distinguish these two cases. |
|
227 |
* |
|
228 |
* @param key the key whose associated value is to be returned |
|
229 |
* @return the value to which the specified key is mapped, or |
|
230 |
* {@code null} if this map contains no mapping for the key |
|
231 |
* @throws ClassCastException if the key is of an inappropriate type for |
|
9503
588cf31d584a
6546713: link the word (optional) in exception specifications to the text which provides explanation and context.
mduigou
parents:
5506
diff
changeset
|
232 |
* this map |
23738 | 233 |
* (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>) |
2 | 234 |
* @throws NullPointerException if the specified key is null and this map |
9503
588cf31d584a
6546713: link the word (optional) in exception specifications to the text which provides explanation and context.
mduigou
parents:
5506
diff
changeset
|
235 |
* does not permit null keys |
23738 | 236 |
* (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>) |
2 | 237 |
*/ |
238 |
V get(Object key); |
|
239 |
||
240 |
// Modification Operations |
|
241 |
||
242 |
/** |
|
243 |
* Associates the specified value with the specified key in this map |
|
244 |
* (optional operation). If the map previously contained a mapping for |
|
245 |
* the key, the old value is replaced by the specified value. (A map |
|
32108
aa5490a167ee
8133188: docs: replace <tt> tags (obsolete in html5) for java.util
avstepan
parents:
29743
diff
changeset
|
246 |
* {@code m} is said to contain a mapping for a key {@code k} if and only |
2 | 247 |
* if {@link #containsKey(Object) m.containsKey(k)} would return |
32108
aa5490a167ee
8133188: docs: replace <tt> tags (obsolete in html5) for java.util
avstepan
parents:
29743
diff
changeset
|
248 |
* {@code true}.) |
2 | 249 |
* |
250 |
* @param key key with which the specified value is to be associated |
|
251 |
* @param value value to be associated with the specified key |
|
32108
aa5490a167ee
8133188: docs: replace <tt> tags (obsolete in html5) for java.util
avstepan
parents:
29743
diff
changeset
|
252 |
* @return the previous value associated with {@code key}, or |
aa5490a167ee
8133188: docs: replace <tt> tags (obsolete in html5) for java.util
avstepan
parents:
29743
diff
changeset
|
253 |
* {@code null} if there was no mapping for {@code key}. |
aa5490a167ee
8133188: docs: replace <tt> tags (obsolete in html5) for java.util
avstepan
parents:
29743
diff
changeset
|
254 |
* (A {@code null} return can also indicate that the map |
aa5490a167ee
8133188: docs: replace <tt> tags (obsolete in html5) for java.util
avstepan
parents:
29743
diff
changeset
|
255 |
* previously associated {@code null} with {@code key}, |
aa5490a167ee
8133188: docs: replace <tt> tags (obsolete in html5) for java.util
avstepan
parents:
29743
diff
changeset
|
256 |
* if the implementation supports {@code null} values.) |
aa5490a167ee
8133188: docs: replace <tt> tags (obsolete in html5) for java.util
avstepan
parents:
29743
diff
changeset
|
257 |
* @throws UnsupportedOperationException if the {@code put} operation |
2 | 258 |
* is not supported by this map |
259 |
* @throws ClassCastException if the class of the specified key or value |
|
260 |
* prevents it from being stored in this map |
|
261 |
* @throws NullPointerException if the specified key or value is null |
|
262 |
* and this map does not permit null keys or values |
|
263 |
* @throws IllegalArgumentException if some property of the specified key |
|
264 |
* or value prevents it from being stored in this map |
|
265 |
*/ |
|
266 |
V put(K key, V value); |
|
267 |
||
268 |
/** |
|
269 |
* Removes the mapping for a key from this map if it is present |
|
270 |
* (optional operation). More formally, if this map contains a mapping |
|
32108
aa5490a167ee
8133188: docs: replace <tt> tags (obsolete in html5) for java.util
avstepan
parents:
29743
diff
changeset
|
271 |
* from key {@code k} to value {@code v} such that |
aa5490a167ee
8133188: docs: replace <tt> tags (obsolete in html5) for java.util
avstepan
parents:
29743
diff
changeset
|
272 |
* {@code Objects.equals(key, k)}, that mapping |
2 | 273 |
* is removed. (The map can contain at most one such mapping.) |
274 |
* |
|
275 |
* <p>Returns the value to which this map previously associated the key, |
|
32108
aa5490a167ee
8133188: docs: replace <tt> tags (obsolete in html5) for java.util
avstepan
parents:
29743
diff
changeset
|
276 |
* or {@code null} if the map contained no mapping for the key. |
2 | 277 |
* |
278 |
* <p>If this map permits null values, then a return value of |
|
32108
aa5490a167ee
8133188: docs: replace <tt> tags (obsolete in html5) for java.util
avstepan
parents:
29743
diff
changeset
|
279 |
* {@code null} does not <i>necessarily</i> indicate that the map |
2 | 280 |
* contained no mapping for the key; it's also possible that the map |
32108
aa5490a167ee
8133188: docs: replace <tt> tags (obsolete in html5) for java.util
avstepan
parents:
29743
diff
changeset
|
281 |
* explicitly mapped the key to {@code null}. |
2 | 282 |
* |
283 |
* <p>The map will not contain a mapping for the specified key once the |
|
284 |
* call returns. |
|
285 |
* |
|
286 |
* @param key key whose mapping is to be removed from the map |
|
32108
aa5490a167ee
8133188: docs: replace <tt> tags (obsolete in html5) for java.util
avstepan
parents:
29743
diff
changeset
|
287 |
* @return the previous value associated with {@code key}, or |
aa5490a167ee
8133188: docs: replace <tt> tags (obsolete in html5) for java.util
avstepan
parents:
29743
diff
changeset
|
288 |
* {@code null} if there was no mapping for {@code key}. |
aa5490a167ee
8133188: docs: replace <tt> tags (obsolete in html5) for java.util
avstepan
parents:
29743
diff
changeset
|
289 |
* @throws UnsupportedOperationException if the {@code remove} operation |
2 | 290 |
* is not supported by this map |
291 |
* @throws ClassCastException if the key is of an inappropriate type for |
|
9503
588cf31d584a
6546713: link the word (optional) in exception specifications to the text which provides explanation and context.
mduigou
parents:
5506
diff
changeset
|
292 |
* this map |
23738 | 293 |
* (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>) |
2 | 294 |
* @throws NullPointerException if the specified key is null and this |
9503
588cf31d584a
6546713: link the word (optional) in exception specifications to the text which provides explanation and context.
mduigou
parents:
5506
diff
changeset
|
295 |
* map does not permit null keys |
23738 | 296 |
* (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>) |
2 | 297 |
*/ |
298 |
V remove(Object key); |
|
299 |
||
300 |
||
301 |
// Bulk Operations |
|
302 |
||
303 |
/** |
|
304 |
* Copies all of the mappings from the specified map to this map |
|
305 |
* (optional operation). The effect of this call is equivalent to that |
|
306 |
* of calling {@link #put(Object,Object) put(k, v)} on this map once |
|
32108
aa5490a167ee
8133188: docs: replace <tt> tags (obsolete in html5) for java.util
avstepan
parents:
29743
diff
changeset
|
307 |
* for each mapping from key {@code k} to value {@code v} in the |
2 | 308 |
* specified map. The behavior of this operation is undefined if the |
309 |
* specified map is modified while the operation is in progress. |
|
310 |
* |
|
311 |
* @param m mappings to be stored in this map |
|
32108
aa5490a167ee
8133188: docs: replace <tt> tags (obsolete in html5) for java.util
avstepan
parents:
29743
diff
changeset
|
312 |
* @throws UnsupportedOperationException if the {@code putAll} operation |
2 | 313 |
* is not supported by this map |
314 |
* @throws ClassCastException if the class of a key or value in the |
|
315 |
* specified map prevents it from being stored in this map |
|
316 |
* @throws NullPointerException if the specified map is null, or if |
|
317 |
* this map does not permit null keys or values, and the |
|
318 |
* specified map contains null keys or values |
|
319 |
* @throws IllegalArgumentException if some property of a key or value in |
|
320 |
* the specified map prevents it from being stored in this map |
|
321 |
*/ |
|
322 |
void putAll(Map<? extends K, ? extends V> m); |
|
323 |
||
324 |
/** |
|
325 |
* Removes all of the mappings from this map (optional operation). |
|
326 |
* The map will be empty after this call returns. |
|
327 |
* |
|
32108
aa5490a167ee
8133188: docs: replace <tt> tags (obsolete in html5) for java.util
avstepan
parents:
29743
diff
changeset
|
328 |
* @throws UnsupportedOperationException if the {@code clear} operation |
2 | 329 |
* is not supported by this map |
330 |
*/ |
|
331 |
void clear(); |
|
332 |
||
333 |
||
334 |
// Views |
|
335 |
||
336 |
/** |
|
337 |
* Returns a {@link Set} view of the keys contained in this map. |
|
338 |
* The set is backed by the map, so changes to the map are |
|
339 |
* reflected in the set, and vice-versa. If the map is modified |
|
340 |
* while an iteration over the set is in progress (except through |
|
32108
aa5490a167ee
8133188: docs: replace <tt> tags (obsolete in html5) for java.util
avstepan
parents:
29743
diff
changeset
|
341 |
* the iterator's own {@code remove} operation), the results of |
2 | 342 |
* the iteration are undefined. The set supports element removal, |
343 |
* which removes the corresponding mapping from the map, via the |
|
32108
aa5490a167ee
8133188: docs: replace <tt> tags (obsolete in html5) for java.util
avstepan
parents:
29743
diff
changeset
|
344 |
* {@code Iterator.remove}, {@code Set.remove}, |
aa5490a167ee
8133188: docs: replace <tt> tags (obsolete in html5) for java.util
avstepan
parents:
29743
diff
changeset
|
345 |
* {@code removeAll}, {@code retainAll}, and {@code clear} |
aa5490a167ee
8133188: docs: replace <tt> tags (obsolete in html5) for java.util
avstepan
parents:
29743
diff
changeset
|
346 |
* operations. It does not support the {@code add} or {@code addAll} |
2 | 347 |
* operations. |
348 |
* |
|
349 |
* @return a set view of the keys contained in this map |
|
350 |
*/ |
|
351 |
Set<K> keySet(); |
|
352 |
||
353 |
/** |
|
354 |
* Returns a {@link Collection} view of the values contained in this map. |
|
355 |
* The collection is backed by the map, so changes to the map are |
|
356 |
* reflected in the collection, and vice-versa. If the map is |
|
357 |
* modified while an iteration over the collection is in progress |
|
32108
aa5490a167ee
8133188: docs: replace <tt> tags (obsolete in html5) for java.util
avstepan
parents:
29743
diff
changeset
|
358 |
* (except through the iterator's own {@code remove} operation), |
2 | 359 |
* the results of the iteration are undefined. The collection |
360 |
* supports element removal, which removes the corresponding |
|
32108
aa5490a167ee
8133188: docs: replace <tt> tags (obsolete in html5) for java.util
avstepan
parents:
29743
diff
changeset
|
361 |
* mapping from the map, via the {@code Iterator.remove}, |
aa5490a167ee
8133188: docs: replace <tt> tags (obsolete in html5) for java.util
avstepan
parents:
29743
diff
changeset
|
362 |
* {@code Collection.remove}, {@code removeAll}, |
aa5490a167ee
8133188: docs: replace <tt> tags (obsolete in html5) for java.util
avstepan
parents:
29743
diff
changeset
|
363 |
* {@code retainAll} and {@code clear} operations. It does not |
aa5490a167ee
8133188: docs: replace <tt> tags (obsolete in html5) for java.util
avstepan
parents:
29743
diff
changeset
|
364 |
* support the {@code add} or {@code addAll} operations. |
2 | 365 |
* |
366 |
* @return a collection view of the values contained in this map |
|
367 |
*/ |
|
368 |
Collection<V> values(); |
|
369 |
||
370 |
/** |
|
371 |
* Returns a {@link Set} view of the mappings contained in this map. |
|
372 |
* The set is backed by the map, so changes to the map are |
|
373 |
* reflected in the set, and vice-versa. If the map is modified |
|
374 |
* while an iteration over the set is in progress (except through |
|
32108
aa5490a167ee
8133188: docs: replace <tt> tags (obsolete in html5) for java.util
avstepan
parents:
29743
diff
changeset
|
375 |
* the iterator's own {@code remove} operation, or through the |
aa5490a167ee
8133188: docs: replace <tt> tags (obsolete in html5) for java.util
avstepan
parents:
29743
diff
changeset
|
376 |
* {@code setValue} operation on a map entry returned by the |
2 | 377 |
* iterator) the results of the iteration are undefined. The set |
378 |
* supports element removal, which removes the corresponding |
|
32108
aa5490a167ee
8133188: docs: replace <tt> tags (obsolete in html5) for java.util
avstepan
parents:
29743
diff
changeset
|
379 |
* mapping from the map, via the {@code Iterator.remove}, |
aa5490a167ee
8133188: docs: replace <tt> tags (obsolete in html5) for java.util
avstepan
parents:
29743
diff
changeset
|
380 |
* {@code Set.remove}, {@code removeAll}, {@code retainAll} and |
aa5490a167ee
8133188: docs: replace <tt> tags (obsolete in html5) for java.util
avstepan
parents:
29743
diff
changeset
|
381 |
* {@code clear} operations. It does not support the |
aa5490a167ee
8133188: docs: replace <tt> tags (obsolete in html5) for java.util
avstepan
parents:
29743
diff
changeset
|
382 |
* {@code add} or {@code addAll} operations. |
2 | 383 |
* |
384 |
* @return a set view of the mappings contained in this map |
|
385 |
*/ |
|
386 |
Set<Map.Entry<K, V>> entrySet(); |
|
387 |
||
388 |
/** |
|
32108
aa5490a167ee
8133188: docs: replace <tt> tags (obsolete in html5) for java.util
avstepan
parents:
29743
diff
changeset
|
389 |
* A map entry (key-value pair). The {@code Map.entrySet} method returns |
2 | 390 |
* a collection-view of the map, whose elements are of this class. The |
391 |
* <i>only</i> way to obtain a reference to a map entry is from the |
|
32108
aa5490a167ee
8133188: docs: replace <tt> tags (obsolete in html5) for java.util
avstepan
parents:
29743
diff
changeset
|
392 |
* iterator of this collection-view. These {@code Map.Entry} objects are |
2 | 393 |
* valid <i>only</i> for the duration of the iteration; more formally, |
394 |
* the behavior of a map entry is undefined if the backing map has been |
|
395 |
* modified after the entry was returned by the iterator, except through |
|
32108
aa5490a167ee
8133188: docs: replace <tt> tags (obsolete in html5) for java.util
avstepan
parents:
29743
diff
changeset
|
396 |
* the {@code setValue} operation on the map entry. |
2 | 397 |
* |
398 |
* @see Map#entrySet() |
|
399 |
* @since 1.2 |
|
400 |
*/ |
|
34527
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
401 |
interface Entry<K, V> { |
2 | 402 |
/** |
403 |
* Returns the key corresponding to this entry. |
|
404 |
* |
|
405 |
* @return the key corresponding to this entry |
|
406 |
* @throws IllegalStateException implementations may, but are not |
|
407 |
* required to, throw this exception if the entry has been |
|
408 |
* removed from the backing map. |
|
409 |
*/ |
|
410 |
K getKey(); |
|
411 |
||
412 |
/** |
|
413 |
* Returns the value corresponding to this entry. If the mapping |
|
414 |
* has been removed from the backing map (by the iterator's |
|
32108
aa5490a167ee
8133188: docs: replace <tt> tags (obsolete in html5) for java.util
avstepan
parents:
29743
diff
changeset
|
415 |
* {@code remove} operation), the results of this call are undefined. |
2 | 416 |
* |
417 |
* @return the value corresponding to this entry |
|
418 |
* @throws IllegalStateException implementations may, but are not |
|
419 |
* required to, throw this exception if the entry has been |
|
420 |
* removed from the backing map. |
|
421 |
*/ |
|
422 |
V getValue(); |
|
423 |
||
424 |
/** |
|
425 |
* Replaces the value corresponding to this entry with the specified |
|
426 |
* value (optional operation). (Writes through to the map.) The |
|
427 |
* behavior of this call is undefined if the mapping has already been |
|
32108
aa5490a167ee
8133188: docs: replace <tt> tags (obsolete in html5) for java.util
avstepan
parents:
29743
diff
changeset
|
428 |
* removed from the map (by the iterator's {@code remove} operation). |
2 | 429 |
* |
430 |
* @param value new value to be stored in this entry |
|
431 |
* @return old value corresponding to the entry |
|
32108
aa5490a167ee
8133188: docs: replace <tt> tags (obsolete in html5) for java.util
avstepan
parents:
29743
diff
changeset
|
432 |
* @throws UnsupportedOperationException if the {@code put} operation |
2 | 433 |
* is not supported by the backing map |
434 |
* @throws ClassCastException if the class of the specified value |
|
435 |
* prevents it from being stored in the backing map |
|
436 |
* @throws NullPointerException if the backing map does not permit |
|
437 |
* null values, and the specified value is null |
|
438 |
* @throws IllegalArgumentException if some property of this value |
|
439 |
* prevents it from being stored in the backing map |
|
440 |
* @throws IllegalStateException implementations may, but are not |
|
441 |
* required to, throw this exception if the entry has been |
|
442 |
* removed from the backing map. |
|
443 |
*/ |
|
444 |
V setValue(V value); |
|
445 |
||
446 |
/** |
|
447 |
* Compares the specified object with this entry for equality. |
|
32108
aa5490a167ee
8133188: docs: replace <tt> tags (obsolete in html5) for java.util
avstepan
parents:
29743
diff
changeset
|
448 |
* Returns {@code true} if the given object is also a map entry and |
2 | 449 |
* the two entries represent the same mapping. More formally, two |
32108
aa5490a167ee
8133188: docs: replace <tt> tags (obsolete in html5) for java.util
avstepan
parents:
29743
diff
changeset
|
450 |
* entries {@code e1} and {@code e2} represent the same mapping |
2 | 451 |
* if<pre> |
452 |
* (e1.getKey()==null ? |
|
453 |
* e2.getKey()==null : e1.getKey().equals(e2.getKey())) && |
|
454 |
* (e1.getValue()==null ? |
|
455 |
* e2.getValue()==null : e1.getValue().equals(e2.getValue())) |
|
456 |
* </pre> |
|
32108
aa5490a167ee
8133188: docs: replace <tt> tags (obsolete in html5) for java.util
avstepan
parents:
29743
diff
changeset
|
457 |
* This ensures that the {@code equals} method works properly across |
aa5490a167ee
8133188: docs: replace <tt> tags (obsolete in html5) for java.util
avstepan
parents:
29743
diff
changeset
|
458 |
* different implementations of the {@code Map.Entry} interface. |
2 | 459 |
* |
460 |
* @param o object to be compared for equality with this map entry |
|
32108
aa5490a167ee
8133188: docs: replace <tt> tags (obsolete in html5) for java.util
avstepan
parents:
29743
diff
changeset
|
461 |
* @return {@code true} if the specified object is equal to this map |
2 | 462 |
* entry |
463 |
*/ |
|
464 |
boolean equals(Object o); |
|
465 |
||
466 |
/** |
|
467 |
* Returns the hash code value for this map entry. The hash code |
|
32108
aa5490a167ee
8133188: docs: replace <tt> tags (obsolete in html5) for java.util
avstepan
parents:
29743
diff
changeset
|
468 |
* of a map entry {@code e} is defined to be: <pre> |
2 | 469 |
* (e.getKey()==null ? 0 : e.getKey().hashCode()) ^ |
470 |
* (e.getValue()==null ? 0 : e.getValue().hashCode()) |
|
471 |
* </pre> |
|
32108
aa5490a167ee
8133188: docs: replace <tt> tags (obsolete in html5) for java.util
avstepan
parents:
29743
diff
changeset
|
472 |
* This ensures that {@code e1.equals(e2)} implies that |
aa5490a167ee
8133188: docs: replace <tt> tags (obsolete in html5) for java.util
avstepan
parents:
29743
diff
changeset
|
473 |
* {@code e1.hashCode()==e2.hashCode()} for any two Entries |
aa5490a167ee
8133188: docs: replace <tt> tags (obsolete in html5) for java.util
avstepan
parents:
29743
diff
changeset
|
474 |
* {@code e1} and {@code e2}, as required by the general |
aa5490a167ee
8133188: docs: replace <tt> tags (obsolete in html5) for java.util
avstepan
parents:
29743
diff
changeset
|
475 |
* contract of {@code Object.hashCode}. |
2 | 476 |
* |
477 |
* @return the hash code value for this map entry |
|
478 |
* @see Object#hashCode() |
|
479 |
* @see Object#equals(Object) |
|
480 |
* @see #equals(Object) |
|
481 |
*/ |
|
482 |
int hashCode(); |
|
18571 | 483 |
|
484 |
/** |
|
485 |
* Returns a comparator that compares {@link Map.Entry} in natural order on key. |
|
486 |
* |
|
487 |
* <p>The returned comparator is serializable and throws {@link |
|
488 |
* NullPointerException} when comparing an entry with a null key. |
|
489 |
* |
|
490 |
* @param <K> the {@link Comparable} type of then map keys |
|
491 |
* @param <V> the type of the map values |
|
492 |
* @return a comparator that compares {@link Map.Entry} in natural order on key. |
|
493 |
* @see Comparable |
|
20868
dcad3ccb889a
8026768: java.util.Map.Entry comparingBy methods missing @since 1.8
henryjen
parents:
20491
diff
changeset
|
494 |
* @since 1.8 |
18571 | 495 |
*/ |
34527
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
496 |
public static <K extends Comparable<? super K>, V> Comparator<Map.Entry<K, V>> comparingByKey() { |
18571 | 497 |
return (Comparator<Map.Entry<K, V>> & Serializable) |
498 |
(c1, c2) -> c1.getKey().compareTo(c2.getKey()); |
|
499 |
} |
|
500 |
||
501 |
/** |
|
502 |
* Returns a comparator that compares {@link Map.Entry} in natural order on value. |
|
503 |
* |
|
504 |
* <p>The returned comparator is serializable and throws {@link |
|
505 |
* NullPointerException} when comparing an entry with null values. |
|
506 |
* |
|
507 |
* @param <K> the type of the map keys |
|
508 |
* @param <V> the {@link Comparable} type of the map values |
|
509 |
* @return a comparator that compares {@link Map.Entry} in natural order on value. |
|
510 |
* @see Comparable |
|
20868
dcad3ccb889a
8026768: java.util.Map.Entry comparingBy methods missing @since 1.8
henryjen
parents:
20491
diff
changeset
|
511 |
* @since 1.8 |
18571 | 512 |
*/ |
34527
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
513 |
public static <K, V extends Comparable<? super V>> Comparator<Map.Entry<K, V>> comparingByValue() { |
18571 | 514 |
return (Comparator<Map.Entry<K, V>> & Serializable) |
515 |
(c1, c2) -> c1.getValue().compareTo(c2.getValue()); |
|
516 |
} |
|
517 |
||
518 |
/** |
|
519 |
* Returns a comparator that compares {@link Map.Entry} by key using the given |
|
520 |
* {@link Comparator}. |
|
521 |
* |
|
522 |
* <p>The returned comparator is serializable if the specified comparator |
|
523 |
* is also serializable. |
|
524 |
* |
|
525 |
* @param <K> the type of the map keys |
|
526 |
* @param <V> the type of the map values |
|
527 |
* @param cmp the key {@link Comparator} |
|
528 |
* @return a comparator that compares {@link Map.Entry} by the key. |
|
20868
dcad3ccb889a
8026768: java.util.Map.Entry comparingBy methods missing @since 1.8
henryjen
parents:
20491
diff
changeset
|
529 |
* @since 1.8 |
18571 | 530 |
*/ |
531 |
public static <K, V> Comparator<Map.Entry<K, V>> comparingByKey(Comparator<? super K> cmp) { |
|
532 |
Objects.requireNonNull(cmp); |
|
533 |
return (Comparator<Map.Entry<K, V>> & Serializable) |
|
534 |
(c1, c2) -> cmp.compare(c1.getKey(), c2.getKey()); |
|
535 |
} |
|
536 |
||
537 |
/** |
|
538 |
* Returns a comparator that compares {@link Map.Entry} by value using the given |
|
539 |
* {@link Comparator}. |
|
540 |
* |
|
541 |
* <p>The returned comparator is serializable if the specified comparator |
|
542 |
* is also serializable. |
|
543 |
* |
|
544 |
* @param <K> the type of the map keys |
|
545 |
* @param <V> the type of the map values |
|
546 |
* @param cmp the value {@link Comparator} |
|
547 |
* @return a comparator that compares {@link Map.Entry} by the value. |
|
20868
dcad3ccb889a
8026768: java.util.Map.Entry comparingBy methods missing @since 1.8
henryjen
parents:
20491
diff
changeset
|
548 |
* @since 1.8 |
18571 | 549 |
*/ |
550 |
public static <K, V> Comparator<Map.Entry<K, V>> comparingByValue(Comparator<? super V> cmp) { |
|
551 |
Objects.requireNonNull(cmp); |
|
552 |
return (Comparator<Map.Entry<K, V>> & Serializable) |
|
553 |
(c1, c2) -> cmp.compare(c1.getValue(), c2.getValue()); |
|
554 |
} |
|
2 | 555 |
} |
556 |
||
557 |
// Comparison and hashing |
|
558 |
||
559 |
/** |
|
560 |
* Compares the specified object with this map for equality. Returns |
|
32108
aa5490a167ee
8133188: docs: replace <tt> tags (obsolete in html5) for java.util
avstepan
parents:
29743
diff
changeset
|
561 |
* {@code true} if the given object is also a map and the two maps |
aa5490a167ee
8133188: docs: replace <tt> tags (obsolete in html5) for java.util
avstepan
parents:
29743
diff
changeset
|
562 |
* represent the same mappings. More formally, two maps {@code m1} and |
aa5490a167ee
8133188: docs: replace <tt> tags (obsolete in html5) for java.util
avstepan
parents:
29743
diff
changeset
|
563 |
* {@code m2} represent the same mappings if |
aa5490a167ee
8133188: docs: replace <tt> tags (obsolete in html5) for java.util
avstepan
parents:
29743
diff
changeset
|
564 |
* {@code m1.entrySet().equals(m2.entrySet())}. This ensures that the |
aa5490a167ee
8133188: docs: replace <tt> tags (obsolete in html5) for java.util
avstepan
parents:
29743
diff
changeset
|
565 |
* {@code equals} method works properly across different implementations |
aa5490a167ee
8133188: docs: replace <tt> tags (obsolete in html5) for java.util
avstepan
parents:
29743
diff
changeset
|
566 |
* of the {@code Map} interface. |
2 | 567 |
* |
568 |
* @param o object to be compared for equality with this map |
|
32108
aa5490a167ee
8133188: docs: replace <tt> tags (obsolete in html5) for java.util
avstepan
parents:
29743
diff
changeset
|
569 |
* @return {@code true} if the specified object is equal to this map |
2 | 570 |
*/ |
571 |
boolean equals(Object o); |
|
572 |
||
573 |
/** |
|
574 |
* Returns the hash code value for this map. The hash code of a map is |
|
575 |
* defined to be the sum of the hash codes of each entry in the map's |
|
32108
aa5490a167ee
8133188: docs: replace <tt> tags (obsolete in html5) for java.util
avstepan
parents:
29743
diff
changeset
|
576 |
* {@code entrySet()} view. This ensures that {@code m1.equals(m2)} |
aa5490a167ee
8133188: docs: replace <tt> tags (obsolete in html5) for java.util
avstepan
parents:
29743
diff
changeset
|
577 |
* implies that {@code m1.hashCode()==m2.hashCode()} for any two maps |
aa5490a167ee
8133188: docs: replace <tt> tags (obsolete in html5) for java.util
avstepan
parents:
29743
diff
changeset
|
578 |
* {@code m1} and {@code m2}, as required by the general contract of |
2 | 579 |
* {@link Object#hashCode}. |
580 |
* |
|
581 |
* @return the hash code value for this map |
|
582 |
* @see Map.Entry#hashCode() |
|
583 |
* @see Object#equals(Object) |
|
584 |
* @see #equals(Object) |
|
585 |
*/ |
|
586 |
int hashCode(); |
|
9503
588cf31d584a
6546713: link the word (optional) in exception specifications to the text which provides explanation and context.
mduigou
parents:
5506
diff
changeset
|
587 |
|
16867 | 588 |
// Defaultable methods |
589 |
||
590 |
/** |
|
21339 | 591 |
* Returns the value to which the specified key is mapped, or |
592 |
* {@code defaultValue} if this map contains no mapping for the key. |
|
20868
dcad3ccb889a
8026768: java.util.Map.Entry comparingBy methods missing @since 1.8
henryjen
parents:
20491
diff
changeset
|
593 |
* |
21352
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
594 |
* @implSpec |
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
595 |
* The default implementation makes no guarantees about synchronization |
20868
dcad3ccb889a
8026768: java.util.Map.Entry comparingBy methods missing @since 1.8
henryjen
parents:
20491
diff
changeset
|
596 |
* or atomicity properties of this method. Any implementation providing |
dcad3ccb889a
8026768: java.util.Map.Entry comparingBy methods missing @since 1.8
henryjen
parents:
20491
diff
changeset
|
597 |
* atomicity guarantees must override this method and document its |
dcad3ccb889a
8026768: java.util.Map.Entry comparingBy methods missing @since 1.8
henryjen
parents:
20491
diff
changeset
|
598 |
* concurrency properties. |
dcad3ccb889a
8026768: java.util.Map.Entry comparingBy methods missing @since 1.8
henryjen
parents:
20491
diff
changeset
|
599 |
* |
dcad3ccb889a
8026768: java.util.Map.Entry comparingBy methods missing @since 1.8
henryjen
parents:
20491
diff
changeset
|
600 |
* @param key the key whose associated value is to be returned |
dcad3ccb889a
8026768: java.util.Map.Entry comparingBy methods missing @since 1.8
henryjen
parents:
20491
diff
changeset
|
601 |
* @param defaultValue the default mapping of the key |
dcad3ccb889a
8026768: java.util.Map.Entry comparingBy methods missing @since 1.8
henryjen
parents:
20491
diff
changeset
|
602 |
* @return the value to which the specified key is mapped, or |
dcad3ccb889a
8026768: java.util.Map.Entry comparingBy methods missing @since 1.8
henryjen
parents:
20491
diff
changeset
|
603 |
* {@code defaultValue} if this map contains no mapping for the key |
dcad3ccb889a
8026768: java.util.Map.Entry comparingBy methods missing @since 1.8
henryjen
parents:
20491
diff
changeset
|
604 |
* @throws ClassCastException if the key is of an inappropriate type for |
dcad3ccb889a
8026768: java.util.Map.Entry comparingBy methods missing @since 1.8
henryjen
parents:
20491
diff
changeset
|
605 |
* this map |
23738 | 606 |
* (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>) |
20868
dcad3ccb889a
8026768: java.util.Map.Entry comparingBy methods missing @since 1.8
henryjen
parents:
20491
diff
changeset
|
607 |
* @throws NullPointerException if the specified key is null and this map |
dcad3ccb889a
8026768: java.util.Map.Entry comparingBy methods missing @since 1.8
henryjen
parents:
20491
diff
changeset
|
608 |
* does not permit null keys |
23738 | 609 |
* (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>) |
20868
dcad3ccb889a
8026768: java.util.Map.Entry comparingBy methods missing @since 1.8
henryjen
parents:
20491
diff
changeset
|
610 |
* @since 1.8 |
dcad3ccb889a
8026768: java.util.Map.Entry comparingBy methods missing @since 1.8
henryjen
parents:
20491
diff
changeset
|
611 |
*/ |
16867 | 612 |
default V getOrDefault(Object key, V defaultValue) { |
613 |
V v; |
|
614 |
return (((v = get(key)) != null) || containsKey(key)) |
|
615 |
? v |
|
616 |
: defaultValue; |
|
617 |
} |
|
618 |
||
619 |
/** |
|
21339 | 620 |
* Performs the given action for each entry in this map until all entries |
621 |
* have been processed or the action throws an exception. Unless |
|
622 |
* otherwise specified by the implementing class, actions are performed in |
|
623 |
* the order of entry set iteration (if an iteration order is specified.) |
|
16867 | 624 |
* Exceptions thrown by the action are relayed to the caller. |
625 |
* |
|
21352
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
626 |
* @implSpec |
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
627 |
* The default implementation is equivalent to, for this {@code map}: |
16867 | 628 |
* <pre> {@code |
22055
d9836bf9992a
8029055: Map.merge implementations should refuse null value param
mduigou
parents:
21352
diff
changeset
|
629 |
* for (Map.Entry<K, V> entry : map.entrySet()) |
16867 | 630 |
* action.accept(entry.getKey(), entry.getValue()); |
631 |
* }</pre> |
|
632 |
* |
|
21352
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
633 |
* The default implementation makes no guarantees about synchronization |
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
634 |
* or atomicity properties of this method. Any implementation providing |
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
635 |
* atomicity guarantees must override this method and document its |
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
636 |
* concurrency properties. |
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
637 |
* |
16867 | 638 |
* @param action The action to be performed for each entry |
639 |
* @throws NullPointerException if the specified action is null |
|
640 |
* @throws ConcurrentModificationException if an entry is found to be |
|
641 |
* removed during iteration |
|
642 |
* @since 1.8 |
|
643 |
*/ |
|
644 |
default void forEach(BiConsumer<? super K, ? super V> action) { |
|
645 |
Objects.requireNonNull(action); |
|
646 |
for (Map.Entry<K, V> entry : entrySet()) { |
|
647 |
K k; |
|
648 |
V v; |
|
649 |
try { |
|
650 |
k = entry.getKey(); |
|
651 |
v = entry.getValue(); |
|
35396
c58a744d0bb4
8145164: Default implementation of ConcurrentMap::compute can throw NPE
dl
parents:
34682
diff
changeset
|
652 |
} catch (IllegalStateException ise) { |
18280
6c3c0ff49eb5
8016446: Improve forEach/replaceAll for Map, HashMap, Hashtable, IdentityHashMap, WeakHashMap, TreeMap, ConcurrentMap
mduigou
parents:
16867
diff
changeset
|
653 |
// this usually means the entry is no longer in the map. |
16867 | 654 |
throw new ConcurrentModificationException(ise); |
655 |
} |
|
656 |
action.accept(k, v); |
|
657 |
} |
|
658 |
} |
|
659 |
||
660 |
/** |
|
661 |
* Replaces each entry's value with the result of invoking the given |
|
21339 | 662 |
* function on that entry until all entries have been processed or the |
663 |
* function throws an exception. Exceptions thrown by the function are |
|
664 |
* relayed to the caller. |
|
16867 | 665 |
* |
666 |
* @implSpec |
|
667 |
* <p>The default implementation is equivalent to, for this {@code map}: |
|
668 |
* <pre> {@code |
|
22055
d9836bf9992a
8029055: Map.merge implementations should refuse null value param
mduigou
parents:
21352
diff
changeset
|
669 |
* for (Map.Entry<K, V> entry : map.entrySet()) |
16867 | 670 |
* entry.setValue(function.apply(entry.getKey(), entry.getValue())); |
671 |
* }</pre> |
|
672 |
* |
|
21352
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
673 |
* <p>The default implementation makes no guarantees about synchronization |
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
674 |
* or atomicity properties of this method. Any implementation providing |
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
675 |
* atomicity guarantees must override this method and document its |
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
676 |
* concurrency properties. |
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
677 |
* |
16867 | 678 |
* @param function the function to apply to each entry |
679 |
* @throws UnsupportedOperationException if the {@code set} operation |
|
680 |
* is not supported by this map's entry set iterator. |
|
681 |
* @throws ClassCastException if the class of a replacement value |
|
682 |
* prevents it from being stored in this map |
|
683 |
* @throws NullPointerException if the specified function is null, or the |
|
684 |
* specified replacement value is null, and this map does not permit null |
|
685 |
* values |
|
686 |
* @throws ClassCastException if a replacement value is of an inappropriate |
|
687 |
* type for this map |
|
23738 | 688 |
* (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>) |
16867 | 689 |
* @throws NullPointerException if function or a replacement value is null, |
690 |
* and this map does not permit null keys or values |
|
23738 | 691 |
* (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>) |
16867 | 692 |
* @throws IllegalArgumentException if some property of a replacement value |
693 |
* prevents it from being stored in this map |
|
23738 | 694 |
* (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>) |
16867 | 695 |
* @throws ConcurrentModificationException if an entry is found to be |
696 |
* removed during iteration |
|
697 |
* @since 1.8 |
|
698 |
*/ |
|
699 |
default void replaceAll(BiFunction<? super K, ? super V, ? extends V> function) { |
|
700 |
Objects.requireNonNull(function); |
|
701 |
for (Map.Entry<K, V> entry : entrySet()) { |
|
702 |
K k; |
|
703 |
V v; |
|
704 |
try { |
|
705 |
k = entry.getKey(); |
|
706 |
v = entry.getValue(); |
|
35396
c58a744d0bb4
8145164: Default implementation of ConcurrentMap::compute can throw NPE
dl
parents:
34682
diff
changeset
|
707 |
} catch (IllegalStateException ise) { |
18280
6c3c0ff49eb5
8016446: Improve forEach/replaceAll for Map, HashMap, Hashtable, IdentityHashMap, WeakHashMap, TreeMap, ConcurrentMap
mduigou
parents:
16867
diff
changeset
|
708 |
// this usually means the entry is no longer in the map. |
16867 | 709 |
throw new ConcurrentModificationException(ise); |
710 |
} |
|
18280
6c3c0ff49eb5
8016446: Improve forEach/replaceAll for Map, HashMap, Hashtable, IdentityHashMap, WeakHashMap, TreeMap, ConcurrentMap
mduigou
parents:
16867
diff
changeset
|
711 |
|
6c3c0ff49eb5
8016446: Improve forEach/replaceAll for Map, HashMap, Hashtable, IdentityHashMap, WeakHashMap, TreeMap, ConcurrentMap
mduigou
parents:
16867
diff
changeset
|
712 |
// ise thrown from function is not a cme. |
6c3c0ff49eb5
8016446: Improve forEach/replaceAll for Map, HashMap, Hashtable, IdentityHashMap, WeakHashMap, TreeMap, ConcurrentMap
mduigou
parents:
16867
diff
changeset
|
713 |
v = function.apply(k, v); |
6c3c0ff49eb5
8016446: Improve forEach/replaceAll for Map, HashMap, Hashtable, IdentityHashMap, WeakHashMap, TreeMap, ConcurrentMap
mduigou
parents:
16867
diff
changeset
|
714 |
|
6c3c0ff49eb5
8016446: Improve forEach/replaceAll for Map, HashMap, Hashtable, IdentityHashMap, WeakHashMap, TreeMap, ConcurrentMap
mduigou
parents:
16867
diff
changeset
|
715 |
try { |
6c3c0ff49eb5
8016446: Improve forEach/replaceAll for Map, HashMap, Hashtable, IdentityHashMap, WeakHashMap, TreeMap, ConcurrentMap
mduigou
parents:
16867
diff
changeset
|
716 |
entry.setValue(v); |
35396
c58a744d0bb4
8145164: Default implementation of ConcurrentMap::compute can throw NPE
dl
parents:
34682
diff
changeset
|
717 |
} catch (IllegalStateException ise) { |
18280
6c3c0ff49eb5
8016446: Improve forEach/replaceAll for Map, HashMap, Hashtable, IdentityHashMap, WeakHashMap, TreeMap, ConcurrentMap
mduigou
parents:
16867
diff
changeset
|
718 |
// this usually means the entry is no longer in the map. |
6c3c0ff49eb5
8016446: Improve forEach/replaceAll for Map, HashMap, Hashtable, IdentityHashMap, WeakHashMap, TreeMap, ConcurrentMap
mduigou
parents:
16867
diff
changeset
|
719 |
throw new ConcurrentModificationException(ise); |
6c3c0ff49eb5
8016446: Improve forEach/replaceAll for Map, HashMap, Hashtable, IdentityHashMap, WeakHashMap, TreeMap, ConcurrentMap
mduigou
parents:
16867
diff
changeset
|
720 |
} |
16867 | 721 |
} |
722 |
} |
|
723 |
||
724 |
/** |
|
725 |
* If the specified key is not already associated with a value (or is mapped |
|
726 |
* to {@code null}) associates it with the given value and returns |
|
727 |
* {@code null}, else returns the current value. |
|
728 |
* |
|
729 |
* @implSpec |
|
730 |
* The default implementation is equivalent to, for this {@code |
|
731 |
* map}: |
|
732 |
* |
|
733 |
* <pre> {@code |
|
21352
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
734 |
* V v = map.get(key); |
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
735 |
* if (v == null) |
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
736 |
* v = map.put(key, value); |
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
737 |
* |
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
738 |
* return v; |
16867 | 739 |
* }</pre> |
740 |
* |
|
21352
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
741 |
* <p>The default implementation makes no guarantees about synchronization |
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
742 |
* or atomicity properties of this method. Any implementation providing |
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
743 |
* atomicity guarantees must override this method and document its |
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
744 |
* concurrency properties. |
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
745 |
* |
16867 | 746 |
* @param key key with which the specified value is to be associated |
747 |
* @param value value to be associated with the specified key |
|
748 |
* @return the previous value associated with the specified key, or |
|
18532
0bbca0914946
8017088: Map/HashMap.compute() incorrect with key mapping to null value
mduigou
parents:
18280
diff
changeset
|
749 |
* {@code null} if there was no mapping for the key. |
16867 | 750 |
* (A {@code null} return can also indicate that the map |
751 |
* previously associated {@code null} with the key, |
|
752 |
* if the implementation supports null values.) |
|
753 |
* @throws UnsupportedOperationException if the {@code put} operation |
|
754 |
* is not supported by this map |
|
23738 | 755 |
* (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>) |
16867 | 756 |
* @throws ClassCastException if the key or value is of an inappropriate |
757 |
* type for this map |
|
23738 | 758 |
* (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>) |
16867 | 759 |
* @throws NullPointerException if the specified key or value is null, |
760 |
* and this map does not permit null keys or values |
|
23738 | 761 |
* (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>) |
16867 | 762 |
* @throws IllegalArgumentException if some property of the specified key |
763 |
* or value prevents it from being stored in this map |
|
23738 | 764 |
* (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>) |
16867 | 765 |
* @since 1.8 |
766 |
*/ |
|
767 |
default V putIfAbsent(K key, V value) { |
|
768 |
V v = get(key); |
|
769 |
if (v == null) { |
|
21352
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
770 |
v = put(key, value); |
16867 | 771 |
} |
772 |
||
773 |
return v; |
|
774 |
} |
|
775 |
||
776 |
/** |
|
777 |
* Removes the entry for the specified key only if it is currently |
|
778 |
* mapped to the specified value. |
|
779 |
* |
|
780 |
* @implSpec |
|
781 |
* The default implementation is equivalent to, for this {@code map}: |
|
782 |
* |
|
783 |
* <pre> {@code |
|
784 |
* if (map.containsKey(key) && Objects.equals(map.get(key), value)) { |
|
785 |
* map.remove(key); |
|
786 |
* return true; |
|
787 |
* } else |
|
788 |
* return false; |
|
789 |
* }</pre> |
|
790 |
* |
|
21352
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
791 |
* <p>The default implementation makes no guarantees about synchronization |
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
792 |
* or atomicity properties of this method. Any implementation providing |
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
793 |
* atomicity guarantees must override this method and document its |
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
794 |
* concurrency properties. |
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
795 |
* |
16867 | 796 |
* @param key key with which the specified value is associated |
797 |
* @param value value expected to be associated with the specified key |
|
798 |
* @return {@code true} if the value was removed |
|
799 |
* @throws UnsupportedOperationException if the {@code remove} operation |
|
800 |
* is not supported by this map |
|
23738 | 801 |
* (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>) |
16867 | 802 |
* @throws ClassCastException if the key or value is of an inappropriate |
803 |
* type for this map |
|
23738 | 804 |
* (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>) |
16867 | 805 |
* @throws NullPointerException if the specified key or value is null, |
806 |
* and this map does not permit null keys or values |
|
23738 | 807 |
* (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>) |
16867 | 808 |
* @since 1.8 |
809 |
*/ |
|
810 |
default boolean remove(Object key, Object value) { |
|
811 |
Object curValue = get(key); |
|
812 |
if (!Objects.equals(curValue, value) || |
|
813 |
(curValue == null && !containsKey(key))) { |
|
814 |
return false; |
|
815 |
} |
|
816 |
remove(key); |
|
817 |
return true; |
|
818 |
} |
|
819 |
||
820 |
/** |
|
821 |
* Replaces the entry for the specified key only if currently |
|
822 |
* mapped to the specified value. |
|
823 |
* |
|
824 |
* @implSpec |
|
825 |
* The default implementation is equivalent to, for this {@code map}: |
|
826 |
* |
|
827 |
* <pre> {@code |
|
828 |
* if (map.containsKey(key) && Objects.equals(map.get(key), value)) { |
|
829 |
* map.put(key, newValue); |
|
830 |
* return true; |
|
831 |
* } else |
|
832 |
* return false; |
|
833 |
* }</pre> |
|
834 |
* |
|
19855 | 835 |
* The default implementation does not throw NullPointerException |
836 |
* for maps that do not support null values if oldValue is null unless |
|
837 |
* newValue is also null. |
|
838 |
* |
|
21352
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
839 |
* <p>The default implementation makes no guarantees about synchronization |
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
840 |
* or atomicity properties of this method. Any implementation providing |
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
841 |
* atomicity guarantees must override this method and document its |
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
842 |
* concurrency properties. |
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
843 |
* |
16867 | 844 |
* @param key key with which the specified value is associated |
845 |
* @param oldValue value expected to be associated with the specified key |
|
846 |
* @param newValue value to be associated with the specified key |
|
847 |
* @return {@code true} if the value was replaced |
|
848 |
* @throws UnsupportedOperationException if the {@code put} operation |
|
849 |
* is not supported by this map |
|
23738 | 850 |
* (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>) |
16867 | 851 |
* @throws ClassCastException if the class of a specified key or value |
852 |
* prevents it from being stored in this map |
|
19855 | 853 |
* @throws NullPointerException if a specified key or newValue is null, |
16867 | 854 |
* and this map does not permit null keys or values |
19855 | 855 |
* @throws NullPointerException if oldValue is null and this map does not |
856 |
* permit null values |
|
23738 | 857 |
* (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>) |
16867 | 858 |
* @throws IllegalArgumentException if some property of a specified key |
859 |
* or value prevents it from being stored in this map |
|
860 |
* @since 1.8 |
|
861 |
*/ |
|
862 |
default boolean replace(K key, V oldValue, V newValue) { |
|
863 |
Object curValue = get(key); |
|
864 |
if (!Objects.equals(curValue, oldValue) || |
|
865 |
(curValue == null && !containsKey(key))) { |
|
866 |
return false; |
|
867 |
} |
|
868 |
put(key, newValue); |
|
869 |
return true; |
|
870 |
} |
|
871 |
||
872 |
/** |
|
873 |
* Replaces the entry for the specified key only if it is |
|
874 |
* currently mapped to some value. |
|
875 |
* |
|
876 |
* @implSpec |
|
877 |
* The default implementation is equivalent to, for this {@code map}: |
|
878 |
* |
|
879 |
* <pre> {@code |
|
880 |
* if (map.containsKey(key)) { |
|
881 |
* return map.put(key, value); |
|
882 |
* } else |
|
883 |
* return null; |
|
884 |
* }</pre> |
|
885 |
* |
|
21352
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
886 |
* <p>The default implementation makes no guarantees about synchronization |
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
887 |
* or atomicity properties of this method. Any implementation providing |
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
888 |
* atomicity guarantees must override this method and document its |
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
889 |
* concurrency properties. |
35396
c58a744d0bb4
8145164: Default implementation of ConcurrentMap::compute can throw NPE
dl
parents:
34682
diff
changeset
|
890 |
* |
16867 | 891 |
* @param key key with which the specified value is associated |
892 |
* @param value value to be associated with the specified key |
|
893 |
* @return the previous value associated with the specified key, or |
|
894 |
* {@code null} if there was no mapping for the key. |
|
895 |
* (A {@code null} return can also indicate that the map |
|
896 |
* previously associated {@code null} with the key, |
|
897 |
* if the implementation supports null values.) |
|
898 |
* @throws UnsupportedOperationException if the {@code put} operation |
|
899 |
* is not supported by this map |
|
23738 | 900 |
* (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>) |
16867 | 901 |
* @throws ClassCastException if the class of the specified key or value |
902 |
* prevents it from being stored in this map |
|
23738 | 903 |
* (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>) |
16867 | 904 |
* @throws NullPointerException if the specified key or value is null, |
905 |
* and this map does not permit null keys or values |
|
906 |
* @throws IllegalArgumentException if some property of the specified key |
|
907 |
* or value prevents it from being stored in this map |
|
908 |
* @since 1.8 |
|
909 |
*/ |
|
910 |
default V replace(K key, V value) { |
|
21352
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
911 |
V curValue; |
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
912 |
if (((curValue = get(key)) != null) || containsKey(key)) { |
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
913 |
curValue = put(key, value); |
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
914 |
} |
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
915 |
return curValue; |
16867 | 916 |
} |
917 |
||
918 |
/** |
|
21352
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
919 |
* If the specified key is not already associated with a value (or is mapped |
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
920 |
* to {@code null}), attempts to compute its value using the given mapping |
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
921 |
* function and enters it into this map unless {@code null}. |
16867 | 922 |
* |
29743
981893a47bec
8071667: HashMap.computeIfAbsent() adds entry that HashMap.get() does not find.
bchristi
parents:
25859
diff
changeset
|
923 |
* <p>If the mapping function returns {@code null}, no mapping is recorded. |
981893a47bec
8071667: HashMap.computeIfAbsent() adds entry that HashMap.get() does not find.
bchristi
parents:
25859
diff
changeset
|
924 |
* If the mapping function itself throws an (unchecked) exception, the |
16867 | 925 |
* exception is rethrown, and no mapping is recorded. The most |
926 |
* common usage is to construct a new object serving as an initial |
|
927 |
* mapped value or memoized result, as in: |
|
928 |
* |
|
929 |
* <pre> {@code |
|
930 |
* map.computeIfAbsent(key, k -> new Value(f(k))); |
|
931 |
* }</pre> |
|
932 |
* |
|
21352
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
933 |
* <p>Or to implement a multi-value map, {@code Map<K,Collection<V>>}, |
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
934 |
* supporting multiple values per key: |
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
935 |
* |
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
936 |
* <pre> {@code |
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
937 |
* map.computeIfAbsent(key, k -> new HashSet<V>()).add(v); |
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
938 |
* }</pre> |
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
939 |
* |
29743
981893a47bec
8071667: HashMap.computeIfAbsent() adds entry that HashMap.get() does not find.
bchristi
parents:
25859
diff
changeset
|
940 |
* <p>The mapping function should not modify this map during computation. |
21352
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
941 |
* |
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
942 |
* @implSpec |
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
943 |
* The default implementation is equivalent to the following steps for this |
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
944 |
* {@code map}, then returning the current value or {@code null} if now |
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
945 |
* absent: |
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
946 |
* |
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
947 |
* <pre> {@code |
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
948 |
* if (map.get(key) == null) { |
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
949 |
* V newValue = mappingFunction.apply(key); |
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
950 |
* if (newValue != null) |
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
951 |
* map.put(key, newValue); |
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
952 |
* } |
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
953 |
* }</pre> |
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
954 |
* |
29743
981893a47bec
8071667: HashMap.computeIfAbsent() adds entry that HashMap.get() does not find.
bchristi
parents:
25859
diff
changeset
|
955 |
* <p>The default implementation makes no guarantees about detecting if the |
981893a47bec
8071667: HashMap.computeIfAbsent() adds entry that HashMap.get() does not find.
bchristi
parents:
25859
diff
changeset
|
956 |
* mapping function modifies this map during computation and, if |
981893a47bec
8071667: HashMap.computeIfAbsent() adds entry that HashMap.get() does not find.
bchristi
parents:
25859
diff
changeset
|
957 |
* appropriate, reporting an error. Non-concurrent implementations should |
981893a47bec
8071667: HashMap.computeIfAbsent() adds entry that HashMap.get() does not find.
bchristi
parents:
25859
diff
changeset
|
958 |
* override this method and, on a best-effort basis, throw a |
981893a47bec
8071667: HashMap.computeIfAbsent() adds entry that HashMap.get() does not find.
bchristi
parents:
25859
diff
changeset
|
959 |
* {@code ConcurrentModificationException} if it is detected that the |
981893a47bec
8071667: HashMap.computeIfAbsent() adds entry that HashMap.get() does not find.
bchristi
parents:
25859
diff
changeset
|
960 |
* mapping function modifies this map during computation. Concurrent |
981893a47bec
8071667: HashMap.computeIfAbsent() adds entry that HashMap.get() does not find.
bchristi
parents:
25859
diff
changeset
|
961 |
* implementations should override this method and, on a best-effort basis, |
981893a47bec
8071667: HashMap.computeIfAbsent() adds entry that HashMap.get() does not find.
bchristi
parents:
25859
diff
changeset
|
962 |
* throw an {@code IllegalStateException} if it is detected that the |
981893a47bec
8071667: HashMap.computeIfAbsent() adds entry that HashMap.get() does not find.
bchristi
parents:
25859
diff
changeset
|
963 |
* mapping function modifies this map during computation and as a result |
981893a47bec
8071667: HashMap.computeIfAbsent() adds entry that HashMap.get() does not find.
bchristi
parents:
25859
diff
changeset
|
964 |
* computation would never complete. |
981893a47bec
8071667: HashMap.computeIfAbsent() adds entry that HashMap.get() does not find.
bchristi
parents:
25859
diff
changeset
|
965 |
* |
16867 | 966 |
* <p>The default implementation makes no guarantees about synchronization |
967 |
* or atomicity properties of this method. Any implementation providing |
|
968 |
* atomicity guarantees must override this method and document its |
|
969 |
* concurrency properties. In particular, all implementations of |
|
970 |
* subinterface {@link java.util.concurrent.ConcurrentMap} must document |
|
29743
981893a47bec
8071667: HashMap.computeIfAbsent() adds entry that HashMap.get() does not find.
bchristi
parents:
25859
diff
changeset
|
971 |
* whether the mapping function is applied once atomically only if the value |
981893a47bec
8071667: HashMap.computeIfAbsent() adds entry that HashMap.get() does not find.
bchristi
parents:
25859
diff
changeset
|
972 |
* is not present. |
16867 | 973 |
* |
974 |
* @param key key with which the specified value is to be associated |
|
29743
981893a47bec
8071667: HashMap.computeIfAbsent() adds entry that HashMap.get() does not find.
bchristi
parents:
25859
diff
changeset
|
975 |
* @param mappingFunction the mapping function to compute a value |
16867 | 976 |
* @return the current (existing or computed) value associated with |
977 |
* the specified key, or null if the computed value is null |
|
978 |
* @throws NullPointerException if the specified key is null and |
|
21352
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
979 |
* this map does not support null keys, or the mappingFunction |
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
980 |
* is null |
16867 | 981 |
* @throws UnsupportedOperationException if the {@code put} operation |
982 |
* is not supported by this map |
|
23738 | 983 |
* (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>) |
16867 | 984 |
* @throws ClassCastException if the class of the specified key or value |
985 |
* prevents it from being stored in this map |
|
23738 | 986 |
* (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>) |
35396
c58a744d0bb4
8145164: Default implementation of ConcurrentMap::compute can throw NPE
dl
parents:
34682
diff
changeset
|
987 |
* @throws IllegalArgumentException if some property of the specified key |
c58a744d0bb4
8145164: Default implementation of ConcurrentMap::compute can throw NPE
dl
parents:
34682
diff
changeset
|
988 |
* or value prevents it from being stored in this map |
c58a744d0bb4
8145164: Default implementation of ConcurrentMap::compute can throw NPE
dl
parents:
34682
diff
changeset
|
989 |
* (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>) |
16867 | 990 |
* @since 1.8 |
991 |
*/ |
|
992 |
default V computeIfAbsent(K key, |
|
993 |
Function<? super K, ? extends V> mappingFunction) { |
|
20189
1e618f2a82d9
8024331: j.u.Map.computeIfPresent() default/nondefault implementations don't throw NPE if the remappingFunction is null and the key is absent
bpb
parents:
19855
diff
changeset
|
994 |
Objects.requireNonNull(mappingFunction); |
21352
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
995 |
V v; |
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
996 |
if ((v = get(key)) == null) { |
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
997 |
V newValue; |
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
998 |
if ((newValue = mappingFunction.apply(key)) != null) { |
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
999 |
put(key, newValue); |
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
1000 |
return newValue; |
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
1001 |
} |
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
1002 |
} |
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
1003 |
|
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
1004 |
return v; |
16867 | 1005 |
} |
1006 |
||
1007 |
/** |
|
1008 |
* If the value for the specified key is present and non-null, attempts to |
|
1009 |
* compute a new mapping given the key and its current mapped value. |
|
1010 |
* |
|
29743
981893a47bec
8071667: HashMap.computeIfAbsent() adds entry that HashMap.get() does not find.
bchristi
parents:
25859
diff
changeset
|
1011 |
* <p>If the remapping function returns {@code null}, the mapping is removed. |
981893a47bec
8071667: HashMap.computeIfAbsent() adds entry that HashMap.get() does not find.
bchristi
parents:
25859
diff
changeset
|
1012 |
* If the remapping function itself throws an (unchecked) exception, the |
981893a47bec
8071667: HashMap.computeIfAbsent() adds entry that HashMap.get() does not find.
bchristi
parents:
25859
diff
changeset
|
1013 |
* exception is rethrown, and the current mapping is left unchanged. |
981893a47bec
8071667: HashMap.computeIfAbsent() adds entry that HashMap.get() does not find.
bchristi
parents:
25859
diff
changeset
|
1014 |
* |
981893a47bec
8071667: HashMap.computeIfAbsent() adds entry that HashMap.get() does not find.
bchristi
parents:
25859
diff
changeset
|
1015 |
* <p>The remapping function should not modify this map during computation. |
981893a47bec
8071667: HashMap.computeIfAbsent() adds entry that HashMap.get() does not find.
bchristi
parents:
25859
diff
changeset
|
1016 |
* |
21352
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
1017 |
* @implSpec |
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
1018 |
* The default implementation is equivalent to performing the following |
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
1019 |
* steps for this {@code map}, then returning the current value or |
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
1020 |
* {@code null} if now absent: |
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
1021 |
* |
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
1022 |
* <pre> {@code |
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
1023 |
* if (map.get(key) != null) { |
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
1024 |
* V oldValue = map.get(key); |
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
1025 |
* V newValue = remappingFunction.apply(key, oldValue); |
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
1026 |
* if (newValue != null) |
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
1027 |
* map.put(key, newValue); |
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
1028 |
* else |
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
1029 |
* map.remove(key); |
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
1030 |
* } |
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
1031 |
* }</pre> |
16867 | 1032 |
* |
29743
981893a47bec
8071667: HashMap.computeIfAbsent() adds entry that HashMap.get() does not find.
bchristi
parents:
25859
diff
changeset
|
1033 |
* <p>The default implementation makes no guarantees about detecting if the |
981893a47bec
8071667: HashMap.computeIfAbsent() adds entry that HashMap.get() does not find.
bchristi
parents:
25859
diff
changeset
|
1034 |
* remapping function modifies this map during computation and, if |
981893a47bec
8071667: HashMap.computeIfAbsent() adds entry that HashMap.get() does not find.
bchristi
parents:
25859
diff
changeset
|
1035 |
* appropriate, reporting an error. Non-concurrent implementations should |
981893a47bec
8071667: HashMap.computeIfAbsent() adds entry that HashMap.get() does not find.
bchristi
parents:
25859
diff
changeset
|
1036 |
* override this method and, on a best-effort basis, throw a |
981893a47bec
8071667: HashMap.computeIfAbsent() adds entry that HashMap.get() does not find.
bchristi
parents:
25859
diff
changeset
|
1037 |
* {@code ConcurrentModificationException} if it is detected that the |
981893a47bec
8071667: HashMap.computeIfAbsent() adds entry that HashMap.get() does not find.
bchristi
parents:
25859
diff
changeset
|
1038 |
* remapping function modifies this map during computation. Concurrent |
981893a47bec
8071667: HashMap.computeIfAbsent() adds entry that HashMap.get() does not find.
bchristi
parents:
25859
diff
changeset
|
1039 |
* implementations should override this method and, on a best-effort basis, |
981893a47bec
8071667: HashMap.computeIfAbsent() adds entry that HashMap.get() does not find.
bchristi
parents:
25859
diff
changeset
|
1040 |
* throw an {@code IllegalStateException} if it is detected that the |
981893a47bec
8071667: HashMap.computeIfAbsent() adds entry that HashMap.get() does not find.
bchristi
parents:
25859
diff
changeset
|
1041 |
* remapping function modifies this map during computation and as a result |
981893a47bec
8071667: HashMap.computeIfAbsent() adds entry that HashMap.get() does not find.
bchristi
parents:
25859
diff
changeset
|
1042 |
* computation would never complete. |
981893a47bec
8071667: HashMap.computeIfAbsent() adds entry that HashMap.get() does not find.
bchristi
parents:
25859
diff
changeset
|
1043 |
* |
16867 | 1044 |
* <p>The default implementation makes no guarantees about synchronization |
1045 |
* or atomicity properties of this method. Any implementation providing |
|
1046 |
* atomicity guarantees must override this method and document its |
|
1047 |
* concurrency properties. In particular, all implementations of |
|
1048 |
* subinterface {@link java.util.concurrent.ConcurrentMap} must document |
|
29743
981893a47bec
8071667: HashMap.computeIfAbsent() adds entry that HashMap.get() does not find.
bchristi
parents:
25859
diff
changeset
|
1049 |
* whether the remapping function is applied once atomically only if the |
981893a47bec
8071667: HashMap.computeIfAbsent() adds entry that HashMap.get() does not find.
bchristi
parents:
25859
diff
changeset
|
1050 |
* value is not present. |
16867 | 1051 |
* |
1052 |
* @param key key with which the specified value is to be associated |
|
29743
981893a47bec
8071667: HashMap.computeIfAbsent() adds entry that HashMap.get() does not find.
bchristi
parents:
25859
diff
changeset
|
1053 |
* @param remappingFunction the remapping function to compute a value |
16867 | 1054 |
* @return the new value associated with the specified key, or null if none |
1055 |
* @throws NullPointerException if the specified key is null and |
|
1056 |
* this map does not support null keys, or the |
|
1057 |
* remappingFunction is null |
|
1058 |
* @throws UnsupportedOperationException if the {@code put} operation |
|
1059 |
* is not supported by this map |
|
23738 | 1060 |
* (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>) |
16867 | 1061 |
* @throws ClassCastException if the class of the specified key or value |
1062 |
* prevents it from being stored in this map |
|
23738 | 1063 |
* (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>) |
35396
c58a744d0bb4
8145164: Default implementation of ConcurrentMap::compute can throw NPE
dl
parents:
34682
diff
changeset
|
1064 |
* @throws IllegalArgumentException if some property of the specified key |
c58a744d0bb4
8145164: Default implementation of ConcurrentMap::compute can throw NPE
dl
parents:
34682
diff
changeset
|
1065 |
* or value prevents it from being stored in this map |
c58a744d0bb4
8145164: Default implementation of ConcurrentMap::compute can throw NPE
dl
parents:
34682
diff
changeset
|
1066 |
* (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>) |
16867 | 1067 |
* @since 1.8 |
1068 |
*/ |
|
1069 |
default V computeIfPresent(K key, |
|
1070 |
BiFunction<? super K, ? super V, ? extends V> remappingFunction) { |
|
20189
1e618f2a82d9
8024331: j.u.Map.computeIfPresent() default/nondefault implementations don't throw NPE if the remappingFunction is null and the key is absent
bpb
parents:
19855
diff
changeset
|
1071 |
Objects.requireNonNull(remappingFunction); |
16867 | 1072 |
V oldValue; |
21352
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
1073 |
if ((oldValue = get(key)) != null) { |
16867 | 1074 |
V newValue = remappingFunction.apply(key, oldValue); |
1075 |
if (newValue != null) { |
|
21352
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
1076 |
put(key, newValue); |
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
1077 |
return newValue; |
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
1078 |
} else { |
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
1079 |
remove(key); |
16867 | 1080 |
return null; |
21352
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
1081 |
} |
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
1082 |
} else { |
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
1083 |
return null; |
16867 | 1084 |
} |
1085 |
} |
|
1086 |
||
1087 |
/** |
|
21352
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
1088 |
* Attempts to compute a mapping for the specified key and its current |
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
1089 |
* mapped value (or {@code null} if there is no current mapping). For |
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
1090 |
* example, to either create or append a {@code String} msg to a value |
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
1091 |
* mapping: |
16867 | 1092 |
* |
1093 |
* <pre> {@code |
|
1094 |
* map.compute(key, (k, v) -> (v == null) ? msg : v.concat(msg))}</pre> |
|
1095 |
* (Method {@link #merge merge()} is often simpler to use for such purposes.) |
|
1096 |
* |
|
29743
981893a47bec
8071667: HashMap.computeIfAbsent() adds entry that HashMap.get() does not find.
bchristi
parents:
25859
diff
changeset
|
1097 |
* <p>If the remapping function returns {@code null}, the mapping is removed |
981893a47bec
8071667: HashMap.computeIfAbsent() adds entry that HashMap.get() does not find.
bchristi
parents:
25859
diff
changeset
|
1098 |
* (or remains absent if initially absent). If the remapping function |
981893a47bec
8071667: HashMap.computeIfAbsent() adds entry that HashMap.get() does not find.
bchristi
parents:
25859
diff
changeset
|
1099 |
* itself throws an (unchecked) exception, the exception is rethrown, and |
981893a47bec
8071667: HashMap.computeIfAbsent() adds entry that HashMap.get() does not find.
bchristi
parents:
25859
diff
changeset
|
1100 |
* the current mapping is left unchanged. |
981893a47bec
8071667: HashMap.computeIfAbsent() adds entry that HashMap.get() does not find.
bchristi
parents:
25859
diff
changeset
|
1101 |
* |
981893a47bec
8071667: HashMap.computeIfAbsent() adds entry that HashMap.get() does not find.
bchristi
parents:
25859
diff
changeset
|
1102 |
* <p>The remapping function should not modify this map during computation. |
16867 | 1103 |
* |
1104 |
* @implSpec |
|
1105 |
* The default implementation is equivalent to performing the following |
|
1106 |
* steps for this {@code map}, then returning the current value or |
|
1107 |
* {@code null} if absent: |
|
1108 |
* |
|
1109 |
* <pre> {@code |
|
1110 |
* V oldValue = map.get(key); |
|
1111 |
* V newValue = remappingFunction.apply(key, oldValue); |
|
35396
c58a744d0bb4
8145164: Default implementation of ConcurrentMap::compute can throw NPE
dl
parents:
34682
diff
changeset
|
1112 |
* if (oldValue != null) { |
16867 | 1113 |
* if (newValue != null) |
21352
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
1114 |
* map.put(key, newValue); |
16867 | 1115 |
* else |
21352
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
1116 |
* map.remove(key); |
16867 | 1117 |
* } else { |
1118 |
* if (newValue != null) |
|
21352
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
1119 |
* map.put(key, newValue); |
16867 | 1120 |
* else |
1121 |
* return null; |
|
1122 |
* } |
|
1123 |
* }</pre> |
|
1124 |
* |
|
29743
981893a47bec
8071667: HashMap.computeIfAbsent() adds entry that HashMap.get() does not find.
bchristi
parents:
25859
diff
changeset
|
1125 |
* <p>The default implementation makes no guarantees about detecting if the |
981893a47bec
8071667: HashMap.computeIfAbsent() adds entry that HashMap.get() does not find.
bchristi
parents:
25859
diff
changeset
|
1126 |
* remapping function modifies this map during computation and, if |
981893a47bec
8071667: HashMap.computeIfAbsent() adds entry that HashMap.get() does not find.
bchristi
parents:
25859
diff
changeset
|
1127 |
* appropriate, reporting an error. Non-concurrent implementations should |
981893a47bec
8071667: HashMap.computeIfAbsent() adds entry that HashMap.get() does not find.
bchristi
parents:
25859
diff
changeset
|
1128 |
* override this method and, on a best-effort basis, throw a |
981893a47bec
8071667: HashMap.computeIfAbsent() adds entry that HashMap.get() does not find.
bchristi
parents:
25859
diff
changeset
|
1129 |
* {@code ConcurrentModificationException} if it is detected that the |
981893a47bec
8071667: HashMap.computeIfAbsent() adds entry that HashMap.get() does not find.
bchristi
parents:
25859
diff
changeset
|
1130 |
* remapping function modifies this map during computation. Concurrent |
981893a47bec
8071667: HashMap.computeIfAbsent() adds entry that HashMap.get() does not find.
bchristi
parents:
25859
diff
changeset
|
1131 |
* implementations should override this method and, on a best-effort basis, |
981893a47bec
8071667: HashMap.computeIfAbsent() adds entry that HashMap.get() does not find.
bchristi
parents:
25859
diff
changeset
|
1132 |
* throw an {@code IllegalStateException} if it is detected that the |
981893a47bec
8071667: HashMap.computeIfAbsent() adds entry that HashMap.get() does not find.
bchristi
parents:
25859
diff
changeset
|
1133 |
* remapping function modifies this map during computation and as a result |
981893a47bec
8071667: HashMap.computeIfAbsent() adds entry that HashMap.get() does not find.
bchristi
parents:
25859
diff
changeset
|
1134 |
* computation would never complete. |
981893a47bec
8071667: HashMap.computeIfAbsent() adds entry that HashMap.get() does not find.
bchristi
parents:
25859
diff
changeset
|
1135 |
* |
21352
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
1136 |
* <p>The default implementation makes no guarantees about synchronization |
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
1137 |
* or atomicity properties of this method. Any implementation providing |
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
1138 |
* atomicity guarantees must override this method and document its |
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
1139 |
* concurrency properties. In particular, all implementations of |
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
1140 |
* subinterface {@link java.util.concurrent.ConcurrentMap} must document |
29743
981893a47bec
8071667: HashMap.computeIfAbsent() adds entry that HashMap.get() does not find.
bchristi
parents:
25859
diff
changeset
|
1141 |
* whether the remapping function is applied once atomically only if the |
981893a47bec
8071667: HashMap.computeIfAbsent() adds entry that HashMap.get() does not find.
bchristi
parents:
25859
diff
changeset
|
1142 |
* value is not present. |
16867 | 1143 |
* |
1144 |
* @param key key with which the specified value is to be associated |
|
29743
981893a47bec
8071667: HashMap.computeIfAbsent() adds entry that HashMap.get() does not find.
bchristi
parents:
25859
diff
changeset
|
1145 |
* @param remappingFunction the remapping function to compute a value |
16867 | 1146 |
* @return the new value associated with the specified key, or null if none |
1147 |
* @throws NullPointerException if the specified key is null and |
|
1148 |
* this map does not support null keys, or the |
|
1149 |
* remappingFunction is null |
|
1150 |
* @throws UnsupportedOperationException if the {@code put} operation |
|
1151 |
* is not supported by this map |
|
23738 | 1152 |
* (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>) |
16867 | 1153 |
* @throws ClassCastException if the class of the specified key or value |
1154 |
* prevents it from being stored in this map |
|
23738 | 1155 |
* (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>) |
35396
c58a744d0bb4
8145164: Default implementation of ConcurrentMap::compute can throw NPE
dl
parents:
34682
diff
changeset
|
1156 |
* @throws IllegalArgumentException if some property of the specified key |
c58a744d0bb4
8145164: Default implementation of ConcurrentMap::compute can throw NPE
dl
parents:
34682
diff
changeset
|
1157 |
* or value prevents it from being stored in this map |
c58a744d0bb4
8145164: Default implementation of ConcurrentMap::compute can throw NPE
dl
parents:
34682
diff
changeset
|
1158 |
* (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>) |
16867 | 1159 |
* @since 1.8 |
1160 |
*/ |
|
1161 |
default V compute(K key, |
|
1162 |
BiFunction<? super K, ? super V, ? extends V> remappingFunction) { |
|
20189
1e618f2a82d9
8024331: j.u.Map.computeIfPresent() default/nondefault implementations don't throw NPE if the remappingFunction is null and the key is absent
bpb
parents:
19855
diff
changeset
|
1163 |
Objects.requireNonNull(remappingFunction); |
16867 | 1164 |
V oldValue = get(key); |
18532
0bbca0914946
8017088: Map/HashMap.compute() incorrect with key mapping to null value
mduigou
parents:
18280
diff
changeset
|
1165 |
|
21352
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
1166 |
V newValue = remappingFunction.apply(key, oldValue); |
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
1167 |
if (newValue == null) { |
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
1168 |
// delete mapping |
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
1169 |
if (oldValue != null || containsKey(key)) { |
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
1170 |
// something to remove |
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
1171 |
remove(key); |
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
1172 |
return null; |
16867 | 1173 |
} else { |
21352
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
1174 |
// nothing to do. Leave things as they were. |
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
1175 |
return null; |
16867 | 1176 |
} |
21352
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
1177 |
} else { |
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
1178 |
// add or replace old mapping |
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
1179 |
put(key, newValue); |
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
1180 |
return newValue; |
16867 | 1181 |
} |
1182 |
} |
|
1183 |
||
1184 |
/** |
|
1185 |
* If the specified key is not already associated with a value or is |
|
22055
d9836bf9992a
8029055: Map.merge implementations should refuse null value param
mduigou
parents:
21352
diff
changeset
|
1186 |
* associated with null, associates it with the given non-null value. |
d9836bf9992a
8029055: Map.merge implementations should refuse null value param
mduigou
parents:
21352
diff
changeset
|
1187 |
* Otherwise, replaces the associated value with the results of the given |
16867 | 1188 |
* remapping function, or removes if the result is {@code null}. This |
1189 |
* method may be of use when combining multiple mapped values for a key. |
|
1190 |
* For example, to either create or append a {@code String msg} to a |
|
1191 |
* value mapping: |
|
1192 |
* |
|
1193 |
* <pre> {@code |
|
1194 |
* map.merge(key, msg, String::concat) |
|
1195 |
* }</pre> |
|
1196 |
* |
|
29743
981893a47bec
8071667: HashMap.computeIfAbsent() adds entry that HashMap.get() does not find.
bchristi
parents:
25859
diff
changeset
|
1197 |
* <p>If the remapping function returns {@code null}, the mapping is removed. |
981893a47bec
8071667: HashMap.computeIfAbsent() adds entry that HashMap.get() does not find.
bchristi
parents:
25859
diff
changeset
|
1198 |
* If the remapping function itself throws an (unchecked) exception, the |
981893a47bec
8071667: HashMap.computeIfAbsent() adds entry that HashMap.get() does not find.
bchristi
parents:
25859
diff
changeset
|
1199 |
* exception is rethrown, and the current mapping is left unchanged. |
981893a47bec
8071667: HashMap.computeIfAbsent() adds entry that HashMap.get() does not find.
bchristi
parents:
25859
diff
changeset
|
1200 |
* |
981893a47bec
8071667: HashMap.computeIfAbsent() adds entry that HashMap.get() does not find.
bchristi
parents:
25859
diff
changeset
|
1201 |
* <p>The remapping function should not modify this map during computation. |
16867 | 1202 |
* |
1203 |
* @implSpec |
|
22055
d9836bf9992a
8029055: Map.merge implementations should refuse null value param
mduigou
parents:
21352
diff
changeset
|
1204 |
* The default implementation is equivalent to performing the following |
d9836bf9992a
8029055: Map.merge implementations should refuse null value param
mduigou
parents:
21352
diff
changeset
|
1205 |
* steps for this {@code map}, then returning the current value or |
d9836bf9992a
8029055: Map.merge implementations should refuse null value param
mduigou
parents:
21352
diff
changeset
|
1206 |
* {@code null} if absent: |
16867 | 1207 |
* |
1208 |
* <pre> {@code |
|
1209 |
* V oldValue = map.get(key); |
|
1210 |
* V newValue = (oldValue == null) ? value : |
|
1211 |
* remappingFunction.apply(oldValue, value); |
|
1212 |
* if (newValue == null) |
|
21352
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
1213 |
* map.remove(key); |
16867 | 1214 |
* else |
21352
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
1215 |
* map.put(key, newValue); |
16867 | 1216 |
* }</pre> |
1217 |
* |
|
29743
981893a47bec
8071667: HashMap.computeIfAbsent() adds entry that HashMap.get() does not find.
bchristi
parents:
25859
diff
changeset
|
1218 |
* <p>The default implementation makes no guarantees about detecting if the |
981893a47bec
8071667: HashMap.computeIfAbsent() adds entry that HashMap.get() does not find.
bchristi
parents:
25859
diff
changeset
|
1219 |
* remapping function modifies this map during computation and, if |
981893a47bec
8071667: HashMap.computeIfAbsent() adds entry that HashMap.get() does not find.
bchristi
parents:
25859
diff
changeset
|
1220 |
* appropriate, reporting an error. Non-concurrent implementations should |
981893a47bec
8071667: HashMap.computeIfAbsent() adds entry that HashMap.get() does not find.
bchristi
parents:
25859
diff
changeset
|
1221 |
* override this method and, on a best-effort basis, throw a |
981893a47bec
8071667: HashMap.computeIfAbsent() adds entry that HashMap.get() does not find.
bchristi
parents:
25859
diff
changeset
|
1222 |
* {@code ConcurrentModificationException} if it is detected that the |
981893a47bec
8071667: HashMap.computeIfAbsent() adds entry that HashMap.get() does not find.
bchristi
parents:
25859
diff
changeset
|
1223 |
* remapping function modifies this map during computation. Concurrent |
981893a47bec
8071667: HashMap.computeIfAbsent() adds entry that HashMap.get() does not find.
bchristi
parents:
25859
diff
changeset
|
1224 |
* implementations should override this method and, on a best-effort basis, |
981893a47bec
8071667: HashMap.computeIfAbsent() adds entry that HashMap.get() does not find.
bchristi
parents:
25859
diff
changeset
|
1225 |
* throw an {@code IllegalStateException} if it is detected that the |
981893a47bec
8071667: HashMap.computeIfAbsent() adds entry that HashMap.get() does not find.
bchristi
parents:
25859
diff
changeset
|
1226 |
* remapping function modifies this map during computation and as a result |
981893a47bec
8071667: HashMap.computeIfAbsent() adds entry that HashMap.get() does not find.
bchristi
parents:
25859
diff
changeset
|
1227 |
* computation would never complete. |
981893a47bec
8071667: HashMap.computeIfAbsent() adds entry that HashMap.get() does not find.
bchristi
parents:
25859
diff
changeset
|
1228 |
* |
21352
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
1229 |
* <p>The default implementation makes no guarantees about synchronization |
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
1230 |
* or atomicity properties of this method. Any implementation providing |
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
1231 |
* atomicity guarantees must override this method and document its |
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
1232 |
* concurrency properties. In particular, all implementations of |
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
1233 |
* subinterface {@link java.util.concurrent.ConcurrentMap} must document |
29743
981893a47bec
8071667: HashMap.computeIfAbsent() adds entry that HashMap.get() does not find.
bchristi
parents:
25859
diff
changeset
|
1234 |
* whether the remapping function is applied once atomically only if the |
981893a47bec
8071667: HashMap.computeIfAbsent() adds entry that HashMap.get() does not find.
bchristi
parents:
25859
diff
changeset
|
1235 |
* value is not present. |
16867 | 1236 |
* |
22055
d9836bf9992a
8029055: Map.merge implementations should refuse null value param
mduigou
parents:
21352
diff
changeset
|
1237 |
* @param key key with which the resulting value is to be associated |
d9836bf9992a
8029055: Map.merge implementations should refuse null value param
mduigou
parents:
21352
diff
changeset
|
1238 |
* @param value the non-null value to be merged with the existing value |
d9836bf9992a
8029055: Map.merge implementations should refuse null value param
mduigou
parents:
21352
diff
changeset
|
1239 |
* associated with the key or, if no existing value or a null value |
d9836bf9992a
8029055: Map.merge implementations should refuse null value param
mduigou
parents:
21352
diff
changeset
|
1240 |
* is associated with the key, to be associated with the key |
29743
981893a47bec
8071667: HashMap.computeIfAbsent() adds entry that HashMap.get() does not find.
bchristi
parents:
25859
diff
changeset
|
1241 |
* @param remappingFunction the remapping function to recompute a value if |
981893a47bec
8071667: HashMap.computeIfAbsent() adds entry that HashMap.get() does not find.
bchristi
parents:
25859
diff
changeset
|
1242 |
* present |
22055
d9836bf9992a
8029055: Map.merge implementations should refuse null value param
mduigou
parents:
21352
diff
changeset
|
1243 |
* @return the new value associated with the specified key, or null if no |
d9836bf9992a
8029055: Map.merge implementations should refuse null value param
mduigou
parents:
21352
diff
changeset
|
1244 |
* value is associated with the key |
16867 | 1245 |
* @throws UnsupportedOperationException if the {@code put} operation |
1246 |
* is not supported by this map |
|
23738 | 1247 |
* (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>) |
16867 | 1248 |
* @throws ClassCastException if the class of the specified key or value |
1249 |
* prevents it from being stored in this map |
|
23738 | 1250 |
* (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>) |
35396
c58a744d0bb4
8145164: Default implementation of ConcurrentMap::compute can throw NPE
dl
parents:
34682
diff
changeset
|
1251 |
* @throws IllegalArgumentException if some property of the specified key |
c58a744d0bb4
8145164: Default implementation of ConcurrentMap::compute can throw NPE
dl
parents:
34682
diff
changeset
|
1252 |
* or value prevents it from being stored in this map |
c58a744d0bb4
8145164: Default implementation of ConcurrentMap::compute can throw NPE
dl
parents:
34682
diff
changeset
|
1253 |
* (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>) |
22055
d9836bf9992a
8029055: Map.merge implementations should refuse null value param
mduigou
parents:
21352
diff
changeset
|
1254 |
* @throws NullPointerException if the specified key is null and this map |
d9836bf9992a
8029055: Map.merge implementations should refuse null value param
mduigou
parents:
21352
diff
changeset
|
1255 |
* does not support null keys or the value or remappingFunction is |
d9836bf9992a
8029055: Map.merge implementations should refuse null value param
mduigou
parents:
21352
diff
changeset
|
1256 |
* null |
16867 | 1257 |
* @since 1.8 |
1258 |
*/ |
|
1259 |
default V merge(K key, V value, |
|
1260 |
BiFunction<? super V, ? super V, ? extends V> remappingFunction) { |
|
20189
1e618f2a82d9
8024331: j.u.Map.computeIfPresent() default/nondefault implementations don't throw NPE if the remappingFunction is null and the key is absent
bpb
parents:
19855
diff
changeset
|
1261 |
Objects.requireNonNull(remappingFunction); |
22055
d9836bf9992a
8029055: Map.merge implementations should refuse null value param
mduigou
parents:
21352
diff
changeset
|
1262 |
Objects.requireNonNull(value); |
16867 | 1263 |
V oldValue = get(key); |
22055
d9836bf9992a
8029055: Map.merge implementations should refuse null value param
mduigou
parents:
21352
diff
changeset
|
1264 |
V newValue = (oldValue == null) ? value : |
d9836bf9992a
8029055: Map.merge implementations should refuse null value param
mduigou
parents:
21352
diff
changeset
|
1265 |
remappingFunction.apply(oldValue, value); |
35396
c58a744d0bb4
8145164: Default implementation of ConcurrentMap::compute can throw NPE
dl
parents:
34682
diff
changeset
|
1266 |
if (newValue == null) { |
22055
d9836bf9992a
8029055: Map.merge implementations should refuse null value param
mduigou
parents:
21352
diff
changeset
|
1267 |
remove(key); |
21352
0372edc9a995
8024688: further split Map and ConcurrentMap defaults eliminating looping from Map defaults, Map.merge fixes and doc fixes.
mduigou
parents:
21339
diff
changeset
|
1268 |
} else { |
22055
d9836bf9992a
8029055: Map.merge implementations should refuse null value param
mduigou
parents:
21352
diff
changeset
|
1269 |
put(key, newValue); |
16867 | 1270 |
} |
22055
d9836bf9992a
8029055: Map.merge implementations should refuse null value param
mduigou
parents:
21352
diff
changeset
|
1271 |
return newValue; |
16867 | 1272 |
} |
34527
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1273 |
|
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1274 |
/** |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1275 |
* Returns an immutable map containing zero mappings. |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1276 |
* See <a href="#immutable">Immutable Map Static Factory Methods</a> for details. |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1277 |
* |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1278 |
* @param <K> the {@code Map}'s key type |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1279 |
* @param <V> the {@code Map}'s value type |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1280 |
* @return an empty {@code Map} |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1281 |
* |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1282 |
* @since 9 |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1283 |
*/ |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1284 |
static <K, V> Map<K, V> of() { |
37802
91fc9ac7b8b3
8139233: add initial compact immutable collection implementations
smarks
parents:
35396
diff
changeset
|
1285 |
return new ImmutableCollections.Map0<>(); |
34527
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1286 |
} |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1287 |
|
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1288 |
/** |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1289 |
* Returns an immutable map containing a single mapping. |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1290 |
* See <a href="#immutable">Immutable Map Static Factory Methods</a> for details. |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1291 |
* |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1292 |
* @param <K> the {@code Map}'s key type |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1293 |
* @param <V> the {@code Map}'s value type |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1294 |
* @param k1 the mapping's key |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1295 |
* @param v1 the mapping's value |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1296 |
* @return a {@code Map} containing the specified mapping |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1297 |
* @throws NullPointerException if the key or the value is {@code null} |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1298 |
* |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1299 |
* @since 9 |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1300 |
*/ |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1301 |
static <K, V> Map<K, V> of(K k1, V v1) { |
37802
91fc9ac7b8b3
8139233: add initial compact immutable collection implementations
smarks
parents:
35396
diff
changeset
|
1302 |
return new ImmutableCollections.Map1<>(k1, v1); |
34527
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1303 |
} |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1304 |
|
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1305 |
/** |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1306 |
* Returns an immutable map containing two mappings. |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1307 |
* See <a href="#immutable">Immutable Map Static Factory Methods</a> for details. |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1308 |
* |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1309 |
* @param <K> the {@code Map}'s key type |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1310 |
* @param <V> the {@code Map}'s value type |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1311 |
* @param k1 the first mapping's key |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1312 |
* @param v1 the first mapping's value |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1313 |
* @param k2 the second mapping's key |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1314 |
* @param v2 the second mapping's value |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1315 |
* @return a {@code Map} containing the specified mappings |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1316 |
* @throws IllegalArgumentException if the keys are duplicates |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1317 |
* @throws NullPointerException if any key or value is {@code null} |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1318 |
* |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1319 |
* @since 9 |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1320 |
*/ |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1321 |
static <K, V> Map<K, V> of(K k1, V v1, K k2, V v2) { |
37802
91fc9ac7b8b3
8139233: add initial compact immutable collection implementations
smarks
parents:
35396
diff
changeset
|
1322 |
return new ImmutableCollections.MapN<>(k1, v1, k2, v2); |
34527
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1323 |
} |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1324 |
|
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1325 |
/** |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1326 |
* Returns an immutable map containing three mappings. |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1327 |
* See <a href="#immutable">Immutable Map Static Factory Methods</a> for details. |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1328 |
* |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1329 |
* @param <K> the {@code Map}'s key type |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1330 |
* @param <V> the {@code Map}'s value type |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1331 |
* @param k1 the first mapping's key |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1332 |
* @param v1 the first mapping's value |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1333 |
* @param k2 the second mapping's key |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1334 |
* @param v2 the second mapping's value |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1335 |
* @param k3 the third mapping's key |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1336 |
* @param v3 the third mapping's value |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1337 |
* @return a {@code Map} containing the specified mappings |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1338 |
* @throws IllegalArgumentException if there are any duplicate keys |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1339 |
* @throws NullPointerException if any key or value is {@code null} |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1340 |
* |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1341 |
* @since 9 |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1342 |
*/ |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1343 |
static <K, V> Map<K, V> of(K k1, V v1, K k2, V v2, K k3, V v3) { |
37802
91fc9ac7b8b3
8139233: add initial compact immutable collection implementations
smarks
parents:
35396
diff
changeset
|
1344 |
return new ImmutableCollections.MapN<>(k1, v1, k2, v2, k3, v3); |
34527
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1345 |
} |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1346 |
|
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1347 |
/** |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1348 |
* Returns an immutable map containing four mappings. |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1349 |
* See <a href="#immutable">Immutable Map Static Factory Methods</a> for details. |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1350 |
* |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1351 |
* @param <K> the {@code Map}'s key type |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1352 |
* @param <V> the {@code Map}'s value type |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1353 |
* @param k1 the first mapping's key |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1354 |
* @param v1 the first mapping's value |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1355 |
* @param k2 the second mapping's key |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1356 |
* @param v2 the second mapping's value |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1357 |
* @param k3 the third mapping's key |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1358 |
* @param v3 the third mapping's value |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1359 |
* @param k4 the fourth mapping's key |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1360 |
* @param v4 the fourth mapping's value |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1361 |
* @return a {@code Map} containing the specified mappings |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1362 |
* @throws IllegalArgumentException if there are any duplicate keys |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1363 |
* @throws NullPointerException if any key or value is {@code null} |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1364 |
* |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1365 |
* @since 9 |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1366 |
*/ |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1367 |
static <K, V> Map<K, V> of(K k1, V v1, K k2, V v2, K k3, V v3, K k4, V v4) { |
37802
91fc9ac7b8b3
8139233: add initial compact immutable collection implementations
smarks
parents:
35396
diff
changeset
|
1368 |
return new ImmutableCollections.MapN<>(k1, v1, k2, v2, k3, v3, k4, v4); |
34527
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1369 |
} |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1370 |
|
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1371 |
/** |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1372 |
* Returns an immutable map containing five mappings. |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1373 |
* See <a href="#immutable">Immutable Map Static Factory Methods</a> for details. |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1374 |
* |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1375 |
* @param <K> the {@code Map}'s key type |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1376 |
* @param <V> the {@code Map}'s value type |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1377 |
* @param k1 the first mapping's key |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1378 |
* @param v1 the first mapping's value |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1379 |
* @param k2 the second mapping's key |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1380 |
* @param v2 the second mapping's value |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1381 |
* @param k3 the third mapping's key |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1382 |
* @param v3 the third mapping's value |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1383 |
* @param k4 the fourth mapping's key |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1384 |
* @param v4 the fourth mapping's value |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1385 |
* @param k5 the fifth mapping's key |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1386 |
* @param v5 the fifth mapping's value |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1387 |
* @return a {@code Map} containing the specified mappings |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1388 |
* @throws IllegalArgumentException if there are any duplicate keys |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1389 |
* @throws NullPointerException if any key or value is {@code null} |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1390 |
* |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1391 |
* @since 9 |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1392 |
*/ |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1393 |
static <K, V> Map<K, V> of(K k1, V v1, K k2, V v2, K k3, V v3, K k4, V v4, K k5, V v5) { |
37802
91fc9ac7b8b3
8139233: add initial compact immutable collection implementations
smarks
parents:
35396
diff
changeset
|
1394 |
return new ImmutableCollections.MapN<>(k1, v1, k2, v2, k3, v3, k4, v4, k5, v5); |
34527
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1395 |
} |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1396 |
|
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1397 |
/** |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1398 |
* Returns an immutable map containing six mappings. |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1399 |
* See <a href="#immutable">Immutable Map Static Factory Methods</a> for details. |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1400 |
* |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1401 |
* @param <K> the {@code Map}'s key type |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1402 |
* @param <V> the {@code Map}'s value type |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1403 |
* @param k1 the first mapping's key |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1404 |
* @param v1 the first mapping's value |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1405 |
* @param k2 the second mapping's key |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1406 |
* @param v2 the second mapping's value |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1407 |
* @param k3 the third mapping's key |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1408 |
* @param v3 the third mapping's value |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1409 |
* @param k4 the fourth mapping's key |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1410 |
* @param v4 the fourth mapping's value |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1411 |
* @param k5 the fifth mapping's key |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1412 |
* @param v5 the fifth mapping's value |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1413 |
* @param k6 the sixth mapping's key |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1414 |
* @param v6 the sixth mapping's value |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1415 |
* @return a {@code Map} containing the specified mappings |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1416 |
* @throws IllegalArgumentException if there are any duplicate keys |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1417 |
* @throws NullPointerException if any key or value is {@code null} |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1418 |
* |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1419 |
* @since 9 |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1420 |
*/ |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1421 |
static <K, V> Map<K, V> of(K k1, V v1, K k2, V v2, K k3, V v3, K k4, V v4, K k5, V v5, |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1422 |
K k6, V v6) { |
37802
91fc9ac7b8b3
8139233: add initial compact immutable collection implementations
smarks
parents:
35396
diff
changeset
|
1423 |
return new ImmutableCollections.MapN<>(k1, v1, k2, v2, k3, v3, k4, v4, k5, v5, |
91fc9ac7b8b3
8139233: add initial compact immutable collection implementations
smarks
parents:
35396
diff
changeset
|
1424 |
k6, v6); |
34527
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1425 |
} |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1426 |
|
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1427 |
/** |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1428 |
* Returns an immutable map containing seven mappings. |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1429 |
* See <a href="#immutable">Immutable Map Static Factory Methods</a> for details. |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1430 |
* |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1431 |
* @param <K> the {@code Map}'s key type |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1432 |
* @param <V> the {@code Map}'s value type |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1433 |
* @param k1 the first mapping's key |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1434 |
* @param v1 the first mapping's value |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1435 |
* @param k2 the second mapping's key |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1436 |
* @param v2 the second mapping's value |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1437 |
* @param k3 the third mapping's key |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1438 |
* @param v3 the third mapping's value |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1439 |
* @param k4 the fourth mapping's key |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1440 |
* @param v4 the fourth mapping's value |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1441 |
* @param k5 the fifth mapping's key |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1442 |
* @param v5 the fifth mapping's value |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1443 |
* @param k6 the sixth mapping's key |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1444 |
* @param v6 the sixth mapping's value |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1445 |
* @param k7 the seventh mapping's key |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1446 |
* @param v7 the seventh mapping's value |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1447 |
* @return a {@code Map} containing the specified mappings |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1448 |
* @throws IllegalArgumentException if there are any duplicate keys |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1449 |
* @throws NullPointerException if any key or value is {@code null} |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1450 |
* |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1451 |
* @since 9 |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1452 |
*/ |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1453 |
static <K, V> Map<K, V> of(K k1, V v1, K k2, V v2, K k3, V v3, K k4, V v4, K k5, V v5, |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1454 |
K k6, V v6, K k7, V v7) { |
37802
91fc9ac7b8b3
8139233: add initial compact immutable collection implementations
smarks
parents:
35396
diff
changeset
|
1455 |
return new ImmutableCollections.MapN<>(k1, v1, k2, v2, k3, v3, k4, v4, k5, v5, |
91fc9ac7b8b3
8139233: add initial compact immutable collection implementations
smarks
parents:
35396
diff
changeset
|
1456 |
k6, v6, k7, v7); |
34527
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1457 |
} |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1458 |
|
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1459 |
/** |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1460 |
* Returns an immutable map containing eight mappings. |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1461 |
* See <a href="#immutable">Immutable Map Static Factory Methods</a> for details. |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1462 |
* |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1463 |
* @param <K> the {@code Map}'s key type |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1464 |
* @param <V> the {@code Map}'s value type |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1465 |
* @param k1 the first mapping's key |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1466 |
* @param v1 the first mapping's value |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1467 |
* @param k2 the second mapping's key |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1468 |
* @param v2 the second mapping's value |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1469 |
* @param k3 the third mapping's key |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1470 |
* @param v3 the third mapping's value |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1471 |
* @param k4 the fourth mapping's key |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1472 |
* @param v4 the fourth mapping's value |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1473 |
* @param k5 the fifth mapping's key |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1474 |
* @param v5 the fifth mapping's value |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1475 |
* @param k6 the sixth mapping's key |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1476 |
* @param v6 the sixth mapping's value |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1477 |
* @param k7 the seventh mapping's key |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1478 |
* @param v7 the seventh mapping's value |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1479 |
* @param k8 the eighth mapping's key |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1480 |
* @param v8 the eighth mapping's value |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1481 |
* @return a {@code Map} containing the specified mappings |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1482 |
* @throws IllegalArgumentException if there are any duplicate keys |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1483 |
* @throws NullPointerException if any key or value is {@code null} |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1484 |
* |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1485 |
* @since 9 |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1486 |
*/ |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1487 |
static <K, V> Map<K, V> of(K k1, V v1, K k2, V v2, K k3, V v3, K k4, V v4, K k5, V v5, |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1488 |
K k6, V v6, K k7, V v7, K k8, V v8) { |
37802
91fc9ac7b8b3
8139233: add initial compact immutable collection implementations
smarks
parents:
35396
diff
changeset
|
1489 |
return new ImmutableCollections.MapN<>(k1, v1, k2, v2, k3, v3, k4, v4, k5, v5, |
91fc9ac7b8b3
8139233: add initial compact immutable collection implementations
smarks
parents:
35396
diff
changeset
|
1490 |
k6, v6, k7, v7, k8, v8); |
34527
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1491 |
} |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1492 |
|
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1493 |
/** |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1494 |
* Returns an immutable map containing nine mappings. |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1495 |
* See <a href="#immutable">Immutable Map Static Factory Methods</a> for details. |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1496 |
* |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1497 |
* @param <K> the {@code Map}'s key type |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1498 |
* @param <V> the {@code Map}'s value type |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1499 |
* @param k1 the first mapping's key |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1500 |
* @param v1 the first mapping's value |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1501 |
* @param k2 the second mapping's key |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1502 |
* @param v2 the second mapping's value |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1503 |
* @param k3 the third mapping's key |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1504 |
* @param v3 the third mapping's value |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1505 |
* @param k4 the fourth mapping's key |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1506 |
* @param v4 the fourth mapping's value |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1507 |
* @param k5 the fifth mapping's key |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1508 |
* @param v5 the fifth mapping's value |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1509 |
* @param k6 the sixth mapping's key |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1510 |
* @param v6 the sixth mapping's value |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1511 |
* @param k7 the seventh mapping's key |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1512 |
* @param v7 the seventh mapping's value |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1513 |
* @param k8 the eighth mapping's key |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1514 |
* @param v8 the eighth mapping's value |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1515 |
* @param k9 the ninth mapping's key |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1516 |
* @param v9 the ninth mapping's value |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1517 |
* @return a {@code Map} containing the specified mappings |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1518 |
* @throws IllegalArgumentException if there are any duplicate keys |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1519 |
* @throws NullPointerException if any key or value is {@code null} |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1520 |
* |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1521 |
* @since 9 |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1522 |
*/ |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1523 |
static <K, V> Map<K, V> of(K k1, V v1, K k2, V v2, K k3, V v3, K k4, V v4, K k5, V v5, |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1524 |
K k6, V v6, K k7, V v7, K k8, V v8, K k9, V v9) { |
37802
91fc9ac7b8b3
8139233: add initial compact immutable collection implementations
smarks
parents:
35396
diff
changeset
|
1525 |
return new ImmutableCollections.MapN<>(k1, v1, k2, v2, k3, v3, k4, v4, k5, v5, |
91fc9ac7b8b3
8139233: add initial compact immutable collection implementations
smarks
parents:
35396
diff
changeset
|
1526 |
k6, v6, k7, v7, k8, v8, k9, v9); |
34527
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1527 |
} |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1528 |
|
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1529 |
/** |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1530 |
* Returns an immutable map containing ten mappings. |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1531 |
* See <a href="#immutable">Immutable Map Static Factory Methods</a> for details. |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1532 |
* |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1533 |
* @param <K> the {@code Map}'s key type |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1534 |
* @param <V> the {@code Map}'s value type |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1535 |
* @param k1 the first mapping's key |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1536 |
* @param v1 the first mapping's value |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1537 |
* @param k2 the second mapping's key |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1538 |
* @param v2 the second mapping's value |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1539 |
* @param k3 the third mapping's key |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1540 |
* @param v3 the third mapping's value |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1541 |
* @param k4 the fourth mapping's key |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1542 |
* @param v4 the fourth mapping's value |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1543 |
* @param k5 the fifth mapping's key |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1544 |
* @param v5 the fifth mapping's value |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1545 |
* @param k6 the sixth mapping's key |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1546 |
* @param v6 the sixth mapping's value |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1547 |
* @param k7 the seventh mapping's key |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1548 |
* @param v7 the seventh mapping's value |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1549 |
* @param k8 the eighth mapping's key |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1550 |
* @param v8 the eighth mapping's value |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1551 |
* @param k9 the ninth mapping's key |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1552 |
* @param v9 the ninth mapping's value |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1553 |
* @param k10 the tenth mapping's key |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1554 |
* @param v10 the tenth mapping's value |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1555 |
* @return a {@code Map} containing the specified mappings |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1556 |
* @throws IllegalArgumentException if there are any duplicate keys |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1557 |
* @throws NullPointerException if any key or value is {@code null} |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1558 |
* |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1559 |
* @since 9 |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1560 |
*/ |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1561 |
static <K, V> Map<K, V> of(K k1, V v1, K k2, V v2, K k3, V v3, K k4, V v4, K k5, V v5, |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1562 |
K k6, V v6, K k7, V v7, K k8, V v8, K k9, V v9, K k10, V v10) { |
37802
91fc9ac7b8b3
8139233: add initial compact immutable collection implementations
smarks
parents:
35396
diff
changeset
|
1563 |
return new ImmutableCollections.MapN<>(k1, v1, k2, v2, k3, v3, k4, v4, k5, v5, |
91fc9ac7b8b3
8139233: add initial compact immutable collection implementations
smarks
parents:
35396
diff
changeset
|
1564 |
k6, v6, k7, v7, k8, v8, k9, v9, k10, v10); |
34527
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1565 |
} |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1566 |
|
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1567 |
/** |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1568 |
* Returns an immutable map containing keys and values extracted from the given entries. |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1569 |
* The entries themselves are not stored in the map. |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1570 |
* See <a href="#immutable">Immutable Map Static Factory Methods</a> for details. |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1571 |
* |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1572 |
* @apiNote |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1573 |
* It is convenient to create the map entries using the {@link Map#entry Map.entry()} method. |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1574 |
* For example, |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1575 |
* |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1576 |
* <pre>{@code |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1577 |
* import static java.util.Map.entry; |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1578 |
* |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1579 |
* Map<Integer,String> map = Map.ofEntries( |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1580 |
* entry(1, "a"), |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1581 |
* entry(2, "b"), |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1582 |
* entry(3, "c"), |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1583 |
* ... |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1584 |
* entry(26, "z")); |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1585 |
* }</pre> |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1586 |
* |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1587 |
* @param <K> the {@code Map}'s key type |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1588 |
* @param <V> the {@code Map}'s value type |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1589 |
* @param entries {@code Map.Entry}s containing the keys and values from which the map is populated |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1590 |
* @return a {@code Map} containing the specified mappings |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1591 |
* @throws IllegalArgumentException if there are any duplicate keys |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1592 |
* @throws NullPointerException if any entry, key, or value is {@code null}, or if |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1593 |
* the {@code entries} array is {@code null} |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1594 |
* |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1595 |
* @see Map#entry Map.entry() |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1596 |
* @since 9 |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1597 |
*/ |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1598 |
@SafeVarargs |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1599 |
@SuppressWarnings("varargs") |
34682
fbee345d8615
8144952: add wildcards to the Map.ofEntries() method
smarks
parents:
34527
diff
changeset
|
1600 |
static <K, V> Map<K, V> ofEntries(Entry<? extends K, ? extends V>... entries) { |
37802
91fc9ac7b8b3
8139233: add initial compact immutable collection implementations
smarks
parents:
35396
diff
changeset
|
1601 |
Objects.requireNonNull(entries); |
91fc9ac7b8b3
8139233: add initial compact immutable collection implementations
smarks
parents:
35396
diff
changeset
|
1602 |
if (entries.length == 0) { |
91fc9ac7b8b3
8139233: add initial compact immutable collection implementations
smarks
parents:
35396
diff
changeset
|
1603 |
return new ImmutableCollections.Map0<>(); |
91fc9ac7b8b3
8139233: add initial compact immutable collection implementations
smarks
parents:
35396
diff
changeset
|
1604 |
} else if (entries.length == 1) { |
91fc9ac7b8b3
8139233: add initial compact immutable collection implementations
smarks
parents:
35396
diff
changeset
|
1605 |
return new ImmutableCollections.Map1<>(entries[0].getKey(), |
91fc9ac7b8b3
8139233: add initial compact immutable collection implementations
smarks
parents:
35396
diff
changeset
|
1606 |
entries[0].getValue()); |
91fc9ac7b8b3
8139233: add initial compact immutable collection implementations
smarks
parents:
35396
diff
changeset
|
1607 |
} else { |
91fc9ac7b8b3
8139233: add initial compact immutable collection implementations
smarks
parents:
35396
diff
changeset
|
1608 |
Object[] kva = new Object[entries.length << 1]; |
91fc9ac7b8b3
8139233: add initial compact immutable collection implementations
smarks
parents:
35396
diff
changeset
|
1609 |
int a = 0; |
91fc9ac7b8b3
8139233: add initial compact immutable collection implementations
smarks
parents:
35396
diff
changeset
|
1610 |
for (Entry<? extends K, ? extends V> entry : entries) { |
91fc9ac7b8b3
8139233: add initial compact immutable collection implementations
smarks
parents:
35396
diff
changeset
|
1611 |
kva[a++] = entry.getKey(); |
91fc9ac7b8b3
8139233: add initial compact immutable collection implementations
smarks
parents:
35396
diff
changeset
|
1612 |
kva[a++] = entry.getValue(); |
91fc9ac7b8b3
8139233: add initial compact immutable collection implementations
smarks
parents:
35396
diff
changeset
|
1613 |
} |
91fc9ac7b8b3
8139233: add initial compact immutable collection implementations
smarks
parents:
35396
diff
changeset
|
1614 |
return new ImmutableCollections.MapN<>(kva); |
34527
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1615 |
} |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1616 |
} |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1617 |
|
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1618 |
/** |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1619 |
* Returns an immutable {@link Entry} containing the given key and value. |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1620 |
* These entries are suitable for populating {@code Map} instances using the |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1621 |
* {@link Map#ofEntries Map.ofEntries()} method. |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1622 |
* The {@code Entry} instances created by this method have the following characteristics: |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1623 |
* |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1624 |
* <ul> |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1625 |
* <li>They disallow {@code null} keys and values. Attempts to create them using a {@code null} |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1626 |
* key or value result in {@code NullPointerException}. |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1627 |
* <li>They are immutable. Calls to {@link Entry#setValue Entry.setValue()} |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1628 |
* on a returned {@code Entry} result in {@code UnsupportedOperationException}. |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1629 |
* <li>They are not serializable. |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1630 |
* <li>They are <a href="../lang/doc-files/ValueBased.html">value-based</a>. |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1631 |
* Callers should make no assumptions about the identity of the returned instances. |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1632 |
* This method is free to create new instances or reuse existing ones. Therefore, |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1633 |
* identity-sensitive operations on these instances (reference equality ({@code ==}), |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1634 |
* identity hash code, and synchronization) are unreliable and should be avoided. |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1635 |
* </ul> |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1636 |
* |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1637 |
* @apiNote |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1638 |
* For a serializable {@code Entry}, see {@link AbstractMap.SimpleEntry} or |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1639 |
* {@link AbstractMap.SimpleImmutableEntry}. |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1640 |
* |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1641 |
* @param <K> the key's type |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1642 |
* @param <V> the value's type |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1643 |
* @param k the key |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1644 |
* @param v the value |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1645 |
* @return an {@code Entry} containing the specified key and value |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1646 |
* @throws NullPointerException if the key or value is {@code null} |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1647 |
* |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1648 |
* @see Map#ofEntries Map.ofEntries() |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1649 |
* @since 9 |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1650 |
*/ |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1651 |
static <K, V> Entry<K, V> entry(K k, V v) { |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1652 |
// KeyValueHolder checks for nulls |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1653 |
return new KeyValueHolder<>(k, v); |
e3caf3a43d09
8139232: JEP-269 initial API and skeleton implementations
smarks
parents:
32108
diff
changeset
|
1654 |
} |
2 | 1655 |
} |