Package org.plumelib.util

Class MapsP

java.lang.Object
org.plumelib.util.MapsP
public final class MapsP extends Object
Utility functions for Map. For collections, see CollectionsPlume.

  • Method Summary

    Modifier and Type
    Method
    Description
    static <K, V, M extends @Nullable Map<K, V>>
    @PolyNull M
    cloneElements(@PolyNull M orig)
    Returns a copy of orig, where each key and value in the result is a clone of the corresponding element of orig.
    static <K, V, M extends @Nullable Map<K, V>>
    @PolyNull M
    cloneValues(@PolyNull M orig)
    Returns a copy of orig, where each value of the result is a clone of the corresponding value of orig, but the keys are the same objects.
    static <K, V> Map<K,V>
    createLruCache(@org.checkerframework.checker.index.qual.Positive int size)
    Creates a LRU cache.
    static <K extends @Nullable DeepCopyable<K>, V extends @Nullable DeepCopyable<V>, M extends @Nullable Map<K, V>>
    @PolyNull M
    deepCopy(@PolyNull M orig)
    Returns a copy of orig, where each key and value in the result is a deep copy (according to the DeepCopyable interface) of the corresponding element of orig.
    static <K, V extends @Nullable DeepCopyable<V>, M extends @Nullable Map<K, V>>
    @PolyNull M
    deepCopyValues(@PolyNull M orig)
    Returns a copy of orig, where each value of the result is a deep copy (according to the DeepCopyable interface) of the corresponding value of orig, but the keys are the same objects.
    static <K extends @NonNull Object>
    @Nullable Integer
    incrementMap(Map<K,Integer> m, K key)
    Increments the Integer which is indexed by key in the Map.
    static <K extends @NonNull Object>
    @Nullable Integer
    incrementMap(Map<K,Integer> m, K key, int count)
    Increments the Integer which is indexed by key in the Map.
    static int
    mapCapacity(int numElements)
    Given an expected number of elements, returns the capacity that should be passed to a HashMap or HashSet constructor, so that the set or map will not resize.
    static int
    mapCapacity(Collection<?> c)
    Given a collection, returns the capacity that should be passed to a HashMap or HashSet constructor, so that the set or map will not resize.
    static int
    mapCapacity(Map<?,?> m)
    Given a map, returns the capacity that should be passed to a HashMap or HashSet constructor, so that the set or map will not resize.
    static <T> int
    mapCapacity(T[] a)
    Given an array, returns the capacity that should be passed to a HashMap or HashSet constructor, so that the set or map will not resize.
    static <K extends @Signed @Nullable Object, V extends @Signed @Nullable Object>
    void
    mapToString(Appendable sb, Map<K,V> m, String linePrefix)
    Deprecated.
    use mapToStringMultiLine(Appendable, Map, String)
    static <K extends @Signed @Nullable Object, V extends @Signed @Nullable Object>
    String
    mapToString(Map<K,V> m)
    Deprecated.
    use mapToStringMultiLine(Map)
    static <K extends @Signed @Nullable Object, V extends @Signed @Nullable Object>
    String
    mapToStringAndClassMultiLine(Map<K,V> m)
    Convert a map to a multi-line string representation, which includes the runtime class of keys and values.
    static <K extends @Signed @Nullable Object, V extends @Signed @Nullable Object>
    String
    mapToStringAndClassMultiLine(Map<K,V> m, String linePrefix)
    Convert a map to a multi-line string representation, which includes the runtime class of keys and values.
    static <K extends @Signed @Nullable Object, V extends @Signed @Nullable Object>
    void
    mapToStringMultiLine(Appendable sb, Map<K,V> m, String linePrefix)
    Write a multi-line representation of the map into the given Appendable (e.g., a StringBuilder), including a final line separator (unless the map is empty).
    static <K extends @Signed @Nullable Object, V extends @Signed @Nullable Object>
    String
    mapToStringMultiLine(Map<K,V> m)
    Returns a multi-line string representation of a map.
    static <K extends @Signed @Nullable Object, V extends @Signed @Nullable Object>
    String
    mapToStringMultiLine(Map<K,V> m, String linePrefix)
    Returns a multi-line string representation of a map.
    static <K extends Comparable<? super K>, V>
    Collection<@KeyFor("#1") K>
    sortedKeySet(Map<K,V> m)
    Returns a sorted version of m.keySet().
    static <K, V> Collection<@KeyFor("#1") K>
    sortedKeySet(Map<K,V> m, Comparator<K> comparator)
    Returns a sorted version of m.keySet().

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Method Details

    • incrementMap

      public static <K extends @NonNull Object> @Nullable Integer incrementMap(Map<K,Integer> m, K key)
      Increments the Integer which is indexed by key in the Map. Sets the value to 1 if not currently mapped.
      Type Parameters:
      K - type of keys in the map
      Parameters:
      m - map from K to Integer
      key - the key whose value will be incremented
      Returns:
      the old value, before it was incremented; this might be null
      Throws:
      Error - if the key is in the Map but maps to a non-Integer

    • incrementMap

      public static <K extends @NonNull Object> @Nullable Integer incrementMap(Map<K,Integer> m, K key, int count)
      Increments the Integer which is indexed by key in the Map. Sets the value to count if not currently mapped.
      Type Parameters:
      K - type of keys in the map
      Parameters:
      m - map from K to Integer
      key - the key whose value will be incremented
      count - how much to increment the value by
      Returns:
      the old value, before it was incremented; this might be null
      Throws:
      Error - if the key is in the Map but maps to a non-Integer

    • sortedKeySet

      public static <K extends Comparable<? super K>, V> Collection<@KeyFor("#1") K> sortedKeySet(Map<K,V> m)
      Returns a sorted version of m.keySet().
      Type Parameters:
      K - type of the map keys
      V - type of the map values
      Parameters:
      m - a map whose keyset will be sorted
      Returns:
      a sorted version of m.keySet()

    • sortedKeySet

      public static <K, V> Collection<@KeyFor("#1") K> sortedKeySet(Map<K,V> m, Comparator<K> comparator)
      Returns a sorted version of m.keySet().
      Type Parameters:
      K - type of the map keys
      V - type of the map values
      Parameters:
      m - a map whose keyset will be sorted
      comparator - the Comparator to use for sorting
      Returns:
      a sorted version of m.keySet()

    • mapCapacity

      public static int mapCapacity(int numElements)
      Given an expected number of elements, returns the capacity that should be passed to a HashMap or HashSet constructor, so that the set or map will not resize.
      Parameters:
      numElements - the maximum expected number of elements in the map or set
      Returns:
      the initial capacity to pass to a HashMap or HashSet constructor

    • mapCapacity

      public static <T> int mapCapacity(T[] a)
      Given an array, returns the capacity that should be passed to a HashMap or HashSet constructor, so that the set or map will not resize.
      Type Parameters:
      T - the type of elements of the array
      Parameters:
      a - an array whose length is the maximum expected number of elements in the map or set
      Returns:
      the initial capacity to pass to a HashMap or HashSet constructor

    • mapCapacity

      public static int mapCapacity(Collection<?> c)
      Given a collection, returns the capacity that should be passed to a HashMap or HashSet constructor, so that the set or map will not resize.
      Parameters:
      c - a collection whose size is the maximum expected number of elements in the map or set
      Returns:
      the initial capacity to pass to a HashMap or HashSet constructor

    • mapCapacity

      public static int mapCapacity(Map<?,?> m)
      Given a map, returns the capacity that should be passed to a HashMap or HashSet constructor, so that the set or map will not resize.
      Parameters:
      m - a map whose size is the maximum expected number of elements in the map or set
      Returns:
      the initial capacity to pass to a HashMap or HashSet constructor

    • deepCopy

      public static <K extends @Nullable DeepCopyable<K>, V extends @Nullable DeepCopyable<V>, M extends @Nullable Map<K, V>> @PolyNull M deepCopy(@PolyNull M orig)
      Returns a copy of orig, where each key and value in the result is a deep copy (according to the DeepCopyable interface) of the corresponding element of orig.
      Type Parameters:
      K - the type of keys of the map
      V - the type of values of the map
      M - the type of the map
      Parameters:
      orig - a map
      Returns:
      a copy of orig, as described above

    • deepCopyValues

      public static <K, V extends @Nullable DeepCopyable<V>, M extends @Nullable Map<K, V>> @PolyNull M deepCopyValues(@PolyNull M orig)
      Returns a copy of orig, where each value of the result is a deep copy (according to the DeepCopyable interface) of the corresponding value of orig, but the keys are the same objects.
      Type Parameters:
      K - the type of keys of the map
      V - the type of values of the map
      M - the type of the map
      Parameters:
      orig - a map
      Returns:
      a copy of orig, as described above

    • createLruCache

      public static <K, V> Map<K,V> createLruCache(@org.checkerframework.checker.index.qual.Positive int size)
      Creates a LRU cache.

      You might want to consider using a WeakHashMap or WeakIdentityHashMap instead

      Type Parameters:
      K - the type of keys
      V - the type of values
      Parameters:
      size - size of the cache
      Returns:
      a new cache with the provided size

    • cloneElements

      public static <K, V, M extends @Nullable Map<K, V>> @PolyNull M cloneElements(@PolyNull M orig)
      Returns a copy of orig, where each key and value in the result is a clone of the corresponding element of orig.
      Type Parameters:
      K - the type of keys of the map
      V - the type of values of the map
      M - the type of the map
      Parameters:
      orig - a map
      Returns:
      a copy of orig, as described above

    • cloneValues

      public static <K, V, M extends @Nullable Map<K, V>> @PolyNull M cloneValues(@PolyNull M orig)
      Returns a copy of orig, where each value of the result is a clone of the corresponding value of orig, but the keys are the same objects.
      Type Parameters:
      K - the type of keys of the map
      V - the type of values of the map
      M - the type of the map
      Parameters:
      orig - a map
      Returns:
      a copy of orig, as described above

    • mapToString

      @Deprecated public static <K extends @Signed @Nullable Object, V extends @Signed @Nullable Object> void mapToString(Appendable sb, Map<K,V> m, String linePrefix)
      Deprecated.
      use mapToStringMultiLine(Appendable, Map, String)
      Write a multi-line representation of the map into the given Appendable (e.g., a StringBuilder), including a final line separator (unless the map is empty).

      Each line has the form "{linePrefix}{key} => {value}"

      This is less expensive than sb.append(mapToStringMultiLine(m)).

      Type Parameters:
      K - type of map keys
      V - type of map values
      Parameters:
      sb - an Appendable (such as StringBuilder) to which to write a multi-line string representation of m
      m - map to be converted to a string
      linePrefix - a prefix to put at the beginning of each line

    • mapToStringMultiLine

      public static <K extends @Signed @Nullable Object, V extends @Signed @Nullable Object> void mapToStringMultiLine(Appendable sb, Map<K,V> m, String linePrefix)
      Write a multi-line representation of the map into the given Appendable (e.g., a StringBuilder), including a final line separator (unless the map is empty).

      Each line has the form "{linePrefix}{key} => {value}".

      This is less expensive than sb.append(mapToStringMultiLine(m)).

      Type Parameters:
      K - type of map keys
      V - type of map values
      Parameters:
      sb - an Appendable (such as StringBuilder) to which to write a multi-line string representation of m
      m - map to be converted to a string
      linePrefix - a prefix to put at the beginning of each line

    • mapToString

      @Deprecated @SideEffectFree public static <K extends @Signed @Nullable Object, V extends @Signed @Nullable Object> String mapToString(Map<K,V> m)
      Deprecated.
      use mapToStringMultiLine(Map)
      Returns a multi-line string representation of a map. Each key-value pair appears on its own line, with no indentation. The last line does not end with a line separator.

      Each line has the form "{linePrefix}{key} => {value}".

      Type Parameters:
      K - type of map keys
      V - type of map values
      Parameters:
      m - map to be converted to a string
      Returns:
      a multi-line string representation of m

    • mapToStringMultiLine

      @SideEffectFree public static <K extends @Signed @Nullable Object, V extends @Signed @Nullable Object> String mapToStringMultiLine(Map<K,V> m)
      Returns a multi-line string representation of a map. Each key-value pair appears on its own line, with no indentation. The last line does not end with a line separator.

      Each line has the form "{key} => {value}".

      Type Parameters:
      K - type of map keys
      V - type of map values
      Parameters:
      m - map to be converted to a string
      Returns:
      a multi-line string representation of the map

    • mapToStringMultiLine

      @SideEffectFree public static <K extends @Signed @Nullable Object, V extends @Signed @Nullable Object> String mapToStringMultiLine(Map<K,V> m, String linePrefix)
      Returns a multi-line string representation of a map. Each key-value pair appears on its own line, with no indentation. The last line does not end with a line separator.

      Each line has the form "{linePrefix}{key} => {value}".

      Type Parameters:
      K - type of map keys
      V - type of map values
      Parameters:
      m - map to be converted to a string
      linePrefix - a prefix to put at the beginning of each line
      Returns:
      a multi-line string representation of the map

    • mapToStringAndClassMultiLine

      @SideEffectFree public static <K extends @Signed @Nullable Object, V extends @Signed @Nullable Object> String mapToStringAndClassMultiLine(Map<K,V> m)
      Convert a map to a multi-line string representation, which includes the runtime class of keys and values. The last line does not end with a line separator.

      Each line has the form "{key} [{key.getClass()}] => {value} [{value.getClass()}]", where the "{}" characters indicate interpolation and the "[]" characters are literally present.

      Type Parameters:
      K - type of map keys
      V - type of map values
      Parameters:
      m - a map
      Returns:
      a string representation of the map

    • mapToStringAndClassMultiLine

      @SideEffectFree public static <K extends @Signed @Nullable Object, V extends @Signed @Nullable Object> String mapToStringAndClassMultiLine(Map<K,V> m, String linePrefix)
      Convert a map to a multi-line string representation, which includes the runtime class of keys and values. The last line does not end with a line separator.

      Each line has the form "{linePrefix}{key} [{key.getClass()}] => {value} [{value.getClass()}]", where the "{}" characters indicate interpolation and the "[]" characters are literally present.

      Type Parameters:
      K - type of map keys
      V - type of map values
      Parameters:
      m - a map
      linePrefix - a prefix to put at the beginning of each line
      Returns:
      a string representation of the map