Document and test how ImmutableMap.toImmutableMap behaves when the mergeFunction returns null.

cpovirk · Google Java Core Libraries · commit 1916f618fa93 · 2023-11-08T14:09:05.000-08:00
(The test is Google-internal for now because we're in the process of reshuffling our `Collector` tests to make them run under Android as part of #6567. Also, we skip the test under GWT+J2CL because of a bug in their implementation of `Collectors.toMap`.) This addresses the main part of #6824, but I'm keeping the bug open as a prompt to recognize our nullness annotations in the future. RELNOTES=n/a PiperOrigin-RevId: 580635720
diff --git a/guava/src/com/google/common/collect/ImmutableMap.java b/guava/src/com/google/common/collect/ImmutableMap.java
@@ -96,8 +96,11 @@ public abstract class ImmutableMap<K, V> implements Map<K, V>, Serializable {
    * and values are the result of applying the provided mapping functions to the input elements.
    *
    * <p>If the mapped keys contain duplicates (according to {@link Object#equals(Object)}), the
-   * values are merged using the specified merging function. Entries will appear in the encounter
-   * order of the first occurrence of the key.
+   * values are merged using the specified merging function. If the merging function returns {@code
+   * null}, then the collector removes the value that has been computed for the key thus far (though
+   * future occurrences of the key would reinsert it).
+   *
+   * <p>Entries will appear in the encounter order of the first occurrence of the key.
    *
    * @since 21.0
    */

Original file line number	Diff line number	Diff line change
`@@ -96,8 +96,11 @@ public abstract class ImmutableMap<K, V> implements Map<K, V>, Serializable {`
`96`	`96`	`* and values are the result of applying the provided mapping functions to the input elements.`
`97`	`97`	`*`
`98`	`98`	`* <p>If the mapped keys contain duplicates (according to {@link Object#equals(Object)}), the`
`99`		`- * values are merged using the specified merging function. Entries will appear in the encounter`
`100`		`- * order of the first occurrence of the key.`
	`99`	`+ * values are merged using the specified merging function. If the merging function returns {@code`
	`100`	`+ * null}, then the collector removes the value that has been computed for the key thus far (though`
	`101`	`+ * future occurrences of the key would reinsert it).`
	`102`	`+ *`
	`103`	`+ * <p>Entries will appear in the encounter order of the first occurrence of the key.`
`101`	`104`	`*`
`102`	`105`	`* @since 21.0`
`103`	`106`	`*/`