Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-8284377

Need method to create pre-sized HashMap

    XMLWordPrintable

Details

    • CSR
    • Status: Closed
    • P4
    • Resolution: Approved
    • 19
    • core-libs
    • None
    • source, binary
    • minimal
    • Minimal compatibility risk: adding static methods on concrete classes.
    • Java API
    • SE

    Description

      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)

      Attachments

        Issue Links

          Activity

            People

              smarks Stuart Marks
              igerasim Ivan Gerasimov
              Chris Hegarty, Roger Riggs
              Votes:
              0 Vote for this issue
              Watchers:
              2 Start watching this issue

              Dates

                Created:
                Updated:
                Resolved: