Add a notice about HashMap keys changing hashCode
Closes #33384
Similar to a notice in the doc for `HashSet` where it is also unsafe to
change `hashCode` while an object is in the collection.
R=lrn@google.com
Change-Id: I0e609656fccd563ecf71d4be5ecadafc1a6da891
CoreLibraryReviewExempt: Doc changes only.
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/310774
Commit-Queue: Nate Bosch <nbosch@google.com>
Reviewed-by: Lasse Nielsen <lrn@google.com>
diff --git a/sdk/lib/collection/hash_map.dart b/sdk/lib/collection/hash_map.dart
index c2283ff..c105708 100644
--- a/sdk/lib/collection/hash_map.dart
+++ b/sdk/lib/collection/hash_map.dart
@@ -38,6 +38,10 @@
/// called during a [forEach] or [putIfAbsent] call,
/// or while iterating the map ([keys], [values] or [entries]).
///
+/// Do not modify keys in any way which changes their equality (and thus their
+/// hash code) while they are in the map. If a map key's [Object.hashCode]
+/// changes, it may cause future lookups for that key to fail.
+///
/// Example:
/// ```dart
/// final Map<int, String> planets = HashMap(); // Is a HashMap
