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