CKTIS / Java
Map.containsKey and Map.put: key presence versus a null value
Check whether a map contains a key even when its value is `null`. Learn how `put` inserts or replaces a mapping and how that differs from conditional insertion.
Version: Java SE 21
Syntax
java.util.Map<K, V> — instance method signatures:
boolean containsKey(Object key)
V put(K key, V value)Map.containsKey(Object key) returns true if the map has an entry for the key, without changing the map. The Map contract defines a match using Objects.equals(key, k), where k is the stored key. In a HashMap, a new, logically equal key matches the existing entry. IdentityHashMap deliberately compares references with == instead.
In a map that allows null values, such as HashMap, get(key) == null alone cannot distinguish a missing entry from an entry with a null value. Use containsKey to tell them apart. A containsKey query may throw ClassCastException for an unsuitable key type or NullPointerException for a disallowed null key.
Map.put(K key, V value) creates an entry for a missing key or replaces the value of an existing entry. It returns the previous value, not the new one. A null result can mean either no previous entry or a previous null value. put is optional: if a map does not support it, a call that would change the map must throw UnsupportedOperationException. If the call would have no effect on the map, the implementation may throw that exception but is not required to. Key and value restrictions depend on the implementation.
To insert only when the key is missing and preserve an existing null value, use if (!map.containsKey(key)) map.put(key, value);. In contrast, putIfAbsent can replace an existing null value. The separate check and write do not form an atomic operation with respect to other threads.
Examples
import java.util.HashMap;
import java.util.Map;
public class MapContainsKeyDemo {
public static void main(String[] args) {
Map<String, String> map = new HashMap<>();
String storedKey = new String("task");
String equalKey = new String("task");
String missingKey = "other";
map.put(storedKey, null);
System.out.println("Same reference: " + (storedKey == equalKey));
System.out.println("Equal key: contains=" + map.containsKey(equalKey)
+ ", get=" + map.get(equalKey));
System.out.println("Missing key: contains=" + map.containsKey(missingKey)
+ ", get=" + map.get(missingKey));
if (!map.containsKey(equalKey)) {
map.put(equalKey, "default");
}
System.out.println("After guarded insert: " + map.get(equalKey));
System.out.println("Previous value: " + map.put(equalKey, "ready"));
System.out.println("Current value: " + map.get(storedKey));
System.out.println("Size: " + map.size());
}
}Result
Same reference: false Equal key: contains=true, get=null Missing key: contains=false, get=null After guarded insert: null Previous value: null Current value: ready Size: 1
The two `String` objects containing `task` are equal but are distinct references. Both the present and missing keys give `null` from `get`, but only the present one gives `true` from `containsKey`. The guard skips the default insertion. The unconditional `put` returns the previous `null` value and stores `ready` without increasing the map size.
Related lessons
- Java · Lesson 17 · Advanced · Version: 2
- Java · Lesson 18 · Advanced · Version: 2
- Java · Lesson 39 · Intermediate · Version: 2