Lines Matching defs:Map
33 // Android-changed: removed docs for removed OpenJDK 9 Immutable Map static methods
36 * An object that maps keys to values. A map cannot contain duplicate keys;
37 * each key can map to at most one value.
42 * <p>The {@code Map} interface provides three <i>collection views</i>, which
43 * allow a map's contents to be viewed as a set of keys, collection of values,
44 * or set of key-value mappings. The <i>order</i> of a map is defined as
45 * the order in which the iterators on the map's collection views return their
46 * elements. Some map implementations, like the {@code TreeMap} class, make
50 * <p>Note: great care must be exercised if mutable objects are used as map
51 * keys. The behavior of a map is not specified if the value of an object is
53 * object is a key in the map. A special case of this prohibition is that it
54 * is not permissible for a map to contain itself as a key. While it is
55 * permissible for a map to contain itself as a value, extreme caution is
57 * well defined on such a map.
59 * <p>All general-purpose map implementation classes should provide two
61 * empty map, and a constructor with a single argument of type {@code Map},
62 * which creates a new map with the same key-value mappings as its argument.
63 * In effect, the latter constructor allows the user to copy any map,
64 * producing an equivalent map of the desired class. There is no way to
66 * all of the general-purpose map implementations in the JDK comply.
69 * methods that modify the map on which they operate, are specified to throw
70 * {@code UnsupportedOperationException} if this map does not support the
73 * have no effect on the map. For example, invoking the {@link #putAll(Map)}
74 * method on an unmodifiable map may, but is not required to, throw the
75 * exception if the map whose mappings are to be "superimposed" is empty.
77 * <p>Some map implementations have restrictions on the keys and values they
86 * would not result in the insertion of an ineligible element into the map may
95 * only if this map contains a mapping for a key {@code k} such that
97 * <i>not</i> be construed to imply that invoking {@code Map.containsKey}
108 * <p>Some map operations which perform recursive traversal of the map may fail
109 * with an exception for self-referential instances where the map directly or
115 * @param <K> the type of keys maintained by this map
128 public interface Map<K, V> {
132 * Returns the number of key-value mappings in this map. If the
133 * map contains more than {@code Integer.MAX_VALUE} elements, returns
136 * @return the number of key-value mappings in this map
141 * Returns {@code true} if this map contains no key-value mappings.
143 * @return {@code true} if this map contains no key-value mappings
148 * Returns {@code true} if this map contains a mapping for the specified
150 * this map contains a mapping for a key {@code k} such that
154 * @param key key whose presence in this map is to be tested
155 * @return {@code true} if this map contains a mapping for the specified
158 * this map
160 * @throws NullPointerException if the specified key is null and this map
167 * Returns {@code true} if this map maps one or more keys to the
169 * this map contains at least one mapping to a value {@code v} such that
171 * will probably require time linear in the map size for most
172 * implementations of the {@code Map} interface.
174 * @param value value whose presence in this map is to be tested
175 * @return {@code true} if this map maps one or more keys to the
178 * this map
181 * map does not permit null values
188 * or {@code null} if this map contains no mapping for the key.
190 * <p>More formally, if this map contains a mapping from a key
196 * <p>If this map permits null values, then a return value of
197 * {@code null} does not <i>necessarily</i> indicate that the map
198 * contains no mapping for the key; it's also possible that the map
204 * {@code null} if this map contains no mapping for the key
206 * this map
208 * @throws NullPointerException if the specified key is null and this map
217 * Associates the specified value with the specified key in this map
218 * (optional operation). If the map previously contained a mapping for
219 * the key, the old value is replaced by the specified value. (A map
228 * (A {@code null} return can also indicate that the map
232 * is not supported by this map
234 * prevents it from being stored in this map
236 * and this map does not permit null keys or values
238 * or value prevents it from being stored in this map
243 * Removes the mapping for a key from this map if it is present
244 * (optional operation). More formally, if this map contains a mapping
247 * is removed. (The map can contain at most one such mapping.)
249 * <p>Returns the value to which this map previously associated the key,
250 * or {@code null} if the map contained no mapping for the key.
252 * <p>If this map permits null values, then a return value of
253 * {@code null} does not <i>necessarily</i> indicate that the map
254 * contained no mapping for the key; it's also possible that the map
257 * <p>The map will not contain a mapping for the specified key once the
260 * @param key key whose mapping is to be removed from the map
264 * is not supported by this map
266 * this map
269 * map does not permit null keys
278 * Copies all of the mappings from the specified map to this map
280 * of calling {@link #put(Object,Object) put(k, v)} on this map once
282 * specified map. The behavior of this operation is undefined if the
283 * specified map is modified while the operation is in progress.
285 * @param m mappings to be stored in this map
287 * is not supported by this map
289 * specified map prevents it from being stored in this map
290 * @throws NullPointerException if the specified map is null, or if
291 * this map does not permit null keys or values, and the
292 * specified map contains null keys or values
294 * the specified map prevents it from being stored in this map
296 void putAll(Map<? extends K, ? extends V> m);
299 * Removes all of the mappings from this map (optional operation).
300 * The map will be empty after this call returns.
303 * is not supported by this map
311 * Returns a {@link Set} view of the keys contained in this map.
312 * The set is backed by the map, so changes to the map are
313 * reflected in the set, and vice-versa. If the map is modified
317 * which removes the corresponding mapping from the map, via the
323 * @return a set view of the keys contained in this map
328 * Returns a {@link Collection} view of the values contained in this map.
329 * The collection is backed by the map, so changes to the map are
330 * reflected in the collection, and vice-versa. If the map is
335 * mapping from the map, via the {@code Iterator.remove},
340 * @return a collection view of the values contained in this map
345 * Returns a {@link Set} view of the mappings contained in this map.
346 * The set is backed by the map, so changes to the map are
347 * reflected in the set, and vice-versa. If the map is modified
350 * {@code setValue} operation on a map entry returned by the
353 * mapping from the map, via the {@code Iterator.remove},
358 * @return a set view of the mappings contained in this map
360 Set<Map.Entry<K, V>> entrySet();
363 * A map entry (key-value pair). The {@code Map.entrySet} method returns
364 * a collection-view of the map, whose elements are of this class. The
365 * <i>only</i> way to obtain a reference to a map entry is from the
366 * iterator of this collection-view. These {@code Map.Entry} objects are
368 * the behavior of a map entry is undefined if the backing map has been
370 * the {@code setValue} operation on the map entry.
372 * @see Map#entrySet()
382 * removed from the backing map.
388 * has been removed from the backing map (by the iterator's
394 * removed from the backing map.
400 * value (optional operation). (Writes through to the map.) The
402 * removed from the map (by the iterator's {@code remove} operation).
407 * is not supported by the backing map
409 * prevents it from being stored in the backing map
410 * @throws NullPointerException if the backing map does not permit
413 * prevents it from being stored in the backing map
416 * removed from the backing map.
422 * Returns {@code true} if the given object is also a map entry and
432 * different implementations of the {@code Map.Entry} interface.
434 * @param o object to be compared for equality with this map entry
435 * @return {@code true} if the specified object is equal to this map
441 * Returns the hash code value for this map entry. The hash code
442 * of a map entry {@code e} is defined to be: <pre>
451 * @return the hash code value for this map entry
459 * Returns a comparator that compares {@link Map.Entry} in natural order on key.
464 * @param <K> the {@link Comparable} type of then map keys
465 * @param <V> the type of the map values
466 * @return a comparator that compares {@link Map.Entry} in natural order on key.
470 public static <K extends Comparable<? super K>, V> Comparator<Map.Entry<K, V>> comparingByKey() {
471 return (Comparator<Map.Entry<K, V>> & Serializable)
476 * Returns a comparator that compares {@link Map.Entry} in natural order on value.
481 * @param <K> the type of the map keys
482 * @param <V> the {@link Comparable} type of the map values
483 * @return a comparator that compares {@link Map.Entry} in natural order on value.
487 public static <K, V extends Comparable<? super V>> Comparator<Map.Entry<K, V>> comparingByValue() {
488 return (Comparator<Map.Entry<K, V>> & Serializable)
493 * Returns a comparator that compares {@link Map.Entry} by key using the given
499 * @param <K> the type of the map keys
500 * @param <V> the type of the map values
502 * @return a comparator that compares {@link Map.Entry} by the key.
505 public static <K, V> Comparator<Map.Entry<K, V>> comparingByKey(Comparator<? super K> cmp) {
507 return (Comparator<Map.Entry<K, V>> & Serializable)
512 * Returns a comparator that compares {@link Map.Entry} by value using the given
518 * @param <K> the type of the map keys
519 * @param <V> the type of the map values
521 * @return a comparator that compares {@link Map.Entry} by the value.
524 public static <K, V> Comparator<Map.Entry<K, V>> comparingByValue(Comparator<? super V> cmp) {
526 return (Comparator<Map.Entry<K, V>> & Serializable)
534 * Compares the specified object with this map for equality. Returns
535 * {@code true} if the given object is also a map and the two maps
540 * of the {@code Map} interface.
542 * @param o object to be compared for equality with this map
543 * @return {@code true} if the specified object is equal to this map
548 * Returns the hash code value for this map. The hash code of a map is
549 * defined to be the sum of the hash codes of each entry in the map's
555 * @return the hash code value for this map
556 * @see Map.Entry#hashCode()
566 * {@code defaultValue} if this map contains no mapping for the key.
577 * {@code defaultValue} if this map contains no mapping for the key
579 * this map
581 * @throws NullPointerException if the specified key is null and this map
594 * Performs the given action for each entry in this map until all entries
601 * The default implementation is equivalent to, for this {@code map}:
603 * for (Map.Entry<K, V> entry : map.entrySet())
620 for (Map.Entry<K, V> entry : entrySet()) {
627 // this usually means the entry is no longer in the map.
641 * <p>The default implementation is equivalent to, for this {@code map}:
643 * for (Map.Entry<K, V> entry : map.entrySet())
654 * is not supported by this map's entry set iterator.
656 * prevents it from being stored in this map
658 * specified replacement value is null, and this map does not permit null
661 * type for this map
664 * and this map does not permit null keys or values
667 * prevents it from being stored in this map
675 for (Map.Entry<K, V> entry : entrySet()) {
682 // this usually means the entry is no longer in the map.
692 // this usually means the entry is no longer in the map.
705 * map}:
708 * V v = map.get(key);
710 * v = map.put(key, value);
724 * (A {@code null} return can also indicate that the map
728 * is not supported by this map
731 * type for this map
734 * and this map does not permit null keys or values
737 * or value prevents it from being stored in this map
755 * The default implementation is equivalent to, for this {@code map}:
758 * if (map.containsKey(key) && Objects.equals(map.get(key), value)) {
759 * map.remove(key);
774 * is not supported by this map
777 * type for this map
780 * and this map does not permit null keys or values
799 * The default implementation is equivalent to, for this {@code map}:
802 * if (map.containsKey(key) && Objects.equals(map.get(key), value)) {
803 * map.put(key, newValue);
823 * is not supported by this map
826 * prevents it from being stored in this map
828 * and this map does not permit null keys or values
829 * @throws NullPointerException if oldValue is null and this map does not
833 * or value prevents it from being stored in this map
851 * The default implementation is equivalent to, for this {@code map}:
854 * if (map.containsKey(key)) {
855 * return map.put(key, value);
869 * (A {@code null} return can also indicate that the map
873 * is not supported by this map
876 * prevents it from being stored in this map
879 * and this map does not permit null keys or values
881 * or value prevents it from being stored in this map
895 * function and enters it into this map unless {@code null}.
904 * map.computeIfAbsent(key, k -> new Value(f(k)));
907 * <p>Or to implement a multi-value map, {@code Map<K,Collection<V>>},
911 * map.computeIfAbsent(key, k -> new HashSet<V>()).add(v);
914 * <p>The mapping function should not modify this map during computation.
918 * {@code map}, then returning the current value or {@code null} if now
922 * if (map.get(key) == null) {
925 * map.put(key, newValue);
930 * mapping function modifies this map during computation and, if
934 * mapping function modifies this map during computation. Concurrent
937 * mapping function modifies this map during computation and as a result
953 * this map does not support null keys, or the mappingFunction
956 * is not supported by this map
959 * prevents it from being stored in this map
962 * or value prevents it from being stored in this map
989 * <p>The remapping function should not modify this map during computation.
993 * steps for this {@code map}, then returning the current value or
997 * if (map.get(key) != null) {
998 * V oldValue = map.get(key);
1001 * map.put(key, newValue);
1003 * map.remove(key);
1008 * remapping function modifies this map during computation and, if
1012 * remapping function modifies this map during computation. Concurrent
1015 * remapping function modifies this map during computation and as a result
1030 * this map does not support null keys, or the
1033 * is not supported by this map
1036 * prevents it from being stored in this map
1039 * or value prevents it from being stored in this map
1068 map.compute(key, (k, v) -> (v == null) ? msg : v.concat(msg))}</pre>
1076 * <p>The remapping function should not modify this map during computation.
1080 * steps for this {@code map}, then returning the current value or
1084 * V oldValue = map.get(key);
1088 * map.put(key, newValue);
1090 * map.remove(key);
1093 * map.put(key, newValue);
1100 * remapping function modifies this map during computation and, if
1104 * remapping function modifies this map during computation. Concurrent
1107 * remapping function modifies this map during computation and as a result
1122 * this map does not support null keys, or the
1125 * is not supported by this map
1128 * prevents it from being stored in this map
1131 * or value prevents it from being stored in this map
1168 * map.merge(key, msg, String::concat)
1175 * <p>The remapping function should not modify this map during computation.
1179 * steps for this {@code map}, then returning the current value or
1183 * V oldValue = map.get(key);
1187 * map.remove(key);
1189 * map.put(key, newValue);
1193 * remapping function modifies this map during computation and, if
1197 * remapping function modifies this map during computation. Concurrent
1200 * remapping function modifies this map during computation and as a result
1220 * is not supported by this map
1223 * prevents it from being stored in this map
1226 * or value prevents it from being stored in this map
1228 * @throws NullPointerException if the specified key is null and this map
1248 // Android-removed: OpenJDK 9 Immutable Map static methods
