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 pre-sizing 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 int-argument 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 floating-point number). A variety of errors can arise with this computation, including off-by-one 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, insertion-ordered 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)