
CSR

Resolution: Approved

P4

None

source, binary

minimal

Minimal compatibility risk: adding static methods on concrete classes.

Java API

SE
Summary
Add methods to create HashMap, LinkedHashMap, and WeakHashMap instances with the appropriate capacity for a given number of mappings.
Problem
HashMap, LinkedHashMap, and WeakHashMap have constructors that take an int "capacity" argument. These constructors are useful for presizing a map instance so that a certain number of elements can be added without the map having to resize itself.
The name "capacity" is rather misleading. The capacity is actually the internal table length. The number of mappings that can be held in a map is generally 0.75 of its capacity, where 0.75 is the default load factor. The intargument constructors are confusing and lead to a couple different kinds of errors.
One error is mistaking the capacity for the number of mappings to be added. Indeed, there are several locations in the JDK that have this error, and it seems likely that this error occurs frequently in code "in the wild."
A second kind of error is improper computation of the capacity given the expected number of mappings. Generally this is dividing by the load factor (a floatingpoint number). A variety of errors can arise with this computation, including offbyone errors and integer wraparound. Again, the JDK itself uses a variety of different computations, all of which have slightly different problems. See the bug report for a catalog and analysis of these issues.
Solution
Add new static factory methods to HashMap, LinkedHashMap, and WeakHashMap.
Specification
// java.util.HashMap
/**
* 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.
*
* @param numMappings the expected number of mappings
* @param <K> the type of keys maintained by this map
* @param <V> the type of mapped values
* @return the newly created map
* @throws IllegalArgumentException if numMappings is negative
* @since 19
*/
public static <K, V> HashMap<K, V> newHashMap(int numMappings)
// java.util.LinkedHashMap
/**
* Creates a new, empty, insertionordered LinkedHashMap 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.
*
* @param numMappings the expected number of mappings
* @param <K> the type of keys maintained by this map
* @param <V> the type of mapped values
* @return the newly created map
* @throws IllegalArgumentException if numMappings is negative
* @since 19
*/
public static <K, V> LinkedHashMap<K, V> newLinkedHashMap(int numMappings)
// java.util.WeakHashMap
/**
* Creates a new, empty WeakHashMap 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.
*
* @param numMappings the expected number of mappings
* @param <K> the type of keys maintained by this map
* @param <V> the type of mapped values
* @return the newly created map
* @throws IllegalArgumentException if numMappings is negative
* @since 19
*/
public static <K, V> WeakHashMap<K, V> newWeakHashMap(int numMappings)
 csr of

JDK8186958 Need method to create presized HashMap
 Resolved