Serguey Asael Shinder: new HashMap<>(n) resizes before it holds n entries; newHashMap(n) does not
A common way to "presize" a map looks like this:
List<User> users = loadUsers(); // say, 1,000 of them
Map<Long, User> byId = new HashMap<>(users.size());
for (User u : users) byId.put(u.id(), u);It reads as "a map for 1,000 entries", and it is not one. The class documentation of HashMap defines the argument: "The capacity is the number of buckets in the hash table, and the initial capacity is simply the capacity at the time the hash table is created." And then the rule that matters: "When the number of entries in the hash table exceeds the product of the load factor and the current capacity, the hash table is rehashed (that is, internal data structures are rebuilt) so that the hash table has approximately twice the number of buckets."
The default load factor is 0.75. The implementation rounds the requested capacity up to a power of two, so new HashMap<>(1000) starts with 1,024 buckets and a threshold of 768. Entry 769 triggers a full rehash into 2,048 buckets, which is exactly the work the presizing was meant to avoid. For an exact power of two the waste is starkest: new HashMap<>(1024) is also 1,024 buckets and also rehashes at 769.
The old workaround was arithmetic, new HashMap<>((int) (n / 0.75f) + 1), which everyone got slightly wrong at least once. Java 19 added a factory that takes the number you actually have. The javadoc of HashMap.newHashMap(int numMappings): "Creates a new, empty HashMap suitable for the expected number of mappings. The returned map uses the default load factor of 0.75, and its initial capacity is generally large enough so that the expected number of mappings can be added without resizing the map." The constructors now carry an API note pointing to it: "To create a HashMap with an initial capacity that accommodates an expected number of mappings, use newHashMap."
Map<Long, User> byId = HashMap.newHashMap(users.size());LinkedHashMap.newLinkedHashMap, HashSet.newHashSet and LinkedHashSet.newLinkedHashSet follow the same convention.
None of this changes behaviour, only cost, and for small maps the cost is noise. It matters on hot paths that build large maps repeatedly, and it matters for reading code: a constructor argument that looks like a size and is not one is the kind of thing a reviewer passes without a second look.
Source: java.util.HashMap javadoc, Java SE 25 — https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/util/HashMap.html