الخرائط (Maps)

Written Explanation

What a map promises

A Map<K, V> associates keys of type K with values of type V. The Java documentation says a map "cannot contain duplicate keys; each key can map to at most one value". Values may repeat freely: two products can cost the same.

Declare by interface, create by class, as always:

Map<String, Integer> stock = new HashMap<>();

Read it as "a map from String to Integer". Both type arguments must be reference types (Lesson 1).

The core methods

Two points deserve attention. put on an existing key replaces the value; it does not add a second entry. And get returns null for a missing key, which is a convenient signal but also the source of the most common map bug, below.

Choosing the implementation

The HashMap documentation says it "makes no guarantees as to the order of the map", and that get and put take constant time if the hash function spreads the keys well. A TreeMap guarantees log(n) time for containsKey, get, put, and remove, and keeps keys in ascending order using compareTo or a comparator. The pattern is the same as for sets: start with HashMap; reach for LinkedHashMap when you need insertion order and TreeMap when you need sorted keys.

The keys follow the rules of sets. In a HashMap or LinkedHashMap, two keys are the same when equals says so and their hashCode values agree, so key classes need both methods (BEG-026). In a TreeMap, two keys are the same when the comparison returns 0.

Looping over a map

A map is not a Collection, so it is not directly usable in a for-each. It gives you three views that are collections:

• keySet() gives the keys.
• values() gives the values.
• entrySet() gives the key-value pairs, each as a Map.Entry<K, V> with getKey() and getValue().

for (Map.Entry<String, Integer> e : stock.entrySet()) {
    System.out.println(e.getKey() + "=" + e.getValue());
}

Use entrySet() when you need both key and value. Looping over keySet() and calling get(k) inside the loop works, but does an extra lookup each time and is more to write.

The missing-key trap

get returns null when the key is absent. With a Map<String, Integer>, the returned type is Integer, a reference. If you then use it where an int is needed, Java unboxes it automatically, and unboxing null throws a NullPointerException:

int n = stock.get("cap");   // "cap" was never added

The real message on JDK 21 is Cannot invoke "java.lang.Integer.intValue()" because the return value of "java.util.Map.get(Object)" is null. It looks mysterious until you remember what get returns for a missing key. The fixes:

• stock.getOrDefault("cap", 0) when a default is natural.
• containsKey first when absence needs different handling.
• Store the result in an Integer variable and compare with null.

Counting with a map

Counting is the classic map job: the key is the thing, the value is the count.

counts.put(w, counts.getOrDefault(w, 0) + 1);

If w is new, getOrDefault gives 0 and we store 1; otherwise it gives the old count and we store one more. A shorter form is counts.merge(w, 1, Integer::sum). The documentation says merge stores the given value if the key is absent, otherwise it combines the old and new values with the function you pass. The Integer::sum part is a method reference, a way to pass a function that BEG-035 teaches properly; for now read it as "add the old count and the new 1". You may use either form. Lesson 8 builds a full word-frequency program on this idea.

Values can be collections

A value can itself be a collection, which gives "one key, many values":

Map<String, List<String>> byInitial = new TreeMap<>();

Each key leads to a list. You create the list the first time you see the key, then add to it. Note that the nested angle brackets are exactly as they read.