CKTIS / Java
Map.put — insert or replace a value
Store a value under a key and get back the previous value. Learn when a `null` result means the key was absent and when it means the key already mapped to `null`.
Version: Java SE 21
Syntax
V put(K key, V value)
V previous = map.put(key, value);Map.put is an instance method of java.util.Map<K, V> in Java SE 21. Map.put() is shorthand for the same method, not a no-argument call. Call map.put(key, value) with a key of type K and a value of type V. It adds an entry if the key is absent or replaces the value if the key is present. In a HashMap, distinct key objects that compare equal by equals and have matching hashCode values address the same entry.
The method returns the previous value, not the new one. A null return means either there was no entry or the previous value was null, if the map permits it. Check containsKey(key) before writing to tell those cases apart, provided the map does not change between the two operations. Storing null as a value does not remove the entry.
put is optional. A map created by Map.of throws UnsupportedOperationException. A map can reject a disallowed null with NullPointerException, an unsuitable type with ClassCastException, or a disallowed property of a key or value with IllegalArgumentException. Writing through a modifiable NavigableMap.subMap view updates the backing map; an out-of-range key throws IllegalArgumentException and is not inserted.
HashMap and WeakHashMap allow a null key and null values. A WeakHashMap entry can also disappear when the garbage collector discards its weakly reachable key. After put inserts a new entry into a LinkedHashMap, the map calls removeEldestEntry automatically. An override can return true to evict the eldest entry. Merely replacing a value does not trigger that hook.
If a cache should store only valid results, skip put when, for example, a negative result signals an error. Map<Class<?>, Object> does not enforce that a value matches the type represented by its key; use type.cast(value) to check before storing it. If a Lock guards a shared map, use the same lock for all accesses: call lock.lock() before try, write inside try, and call lock.unlock() in finally.
Examples
import java.util.HashMap;
import java.util.Map;
public class Main {
public static void main(String[] args) {
Map<String, String> statuses = new HashMap<>();
String key = "job";
String equalKey = new String(key);
System.out.println(statuses.containsKey(key));
System.out.println(statuses.put(key, "ready"));
System.out.println(statuses.put(equalKey, null));
System.out.println(statuses.containsKey(key));
System.out.println(statuses.put(key, "done"));
System.out.println(statuses.get(key));
System.out.println(statuses.size());
}
}Result
false null ready true null done 1
The first `null` returned by `put` means the key was absent. The equal key replaces `ready` with `null` without removing the entry. The second `null` returned by `put` is the previous value, and the map still has only one entry.
Related lessons
- Java · Lesson 13 · Advanced · Version: 2
- Java · Lesson 17 · Advanced · Version: 2
- Java · Lesson 18 · Advanced · Version: 2
- Java · Lesson 20 · Advanced · Version: 2
- Java · Lesson 36 · Advanced · Version: 2
- Java · Lesson 35 · Basic · Version: 2
- Java · Lesson 42 · Basic · Version: 2
- Java · Lesson 57 · Basic · Version: 2
- Java · Lesson 58 · Basic · Version: 2
- Java · Lesson 40 · Intermediate · Version: 2
Sources
- Map — put (Java SE 21 & JDK 21)
- HashMap (Java SE 21 & JDK 21)
- WeakHashMap (Java SE 21 & JDK 21)
- NavigableMap — subMap (Java SE 21 & JDK 21)
- LinkedHashMap — removeEldestEntry (Java SE 21 & JDK 21)
- Class — cast (Java SE 21 & JDK 21)
- Lock (Java SE 21 & JDK 21)
- The java Command — Using Source-File Mode (JDK 21)