Package org.apache.commons.collections4

Class MapUtils

java.lang.Object
org.apache.commons.collections4.MapUtils
public class MapUtils extends Object
Provides utility methods and decorators for Map and SortedMap instances.

It contains various type safe methods as well as other useful features like deep copying.

It also provides the following decorators:

Since:
1.0

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final SortedMap
    EMPTY_SORTED_MAP
    An empty unmodifiable sorted map.

  • Method Summary

    Modifier and Type
    Method
    Description
    static void
    debugPrint(PrintStream out, Object label, Map<?,?> map)
    Prints the given map with nice line breaks.
    static <K, V> Map<K,V>
    emptyIfNull(Map<K,V> map)
    Returns an immutable empty map if the argument is null, or the argument itself otherwise.
    static <K, V> IterableMap<K,V>
    fixedSizeMap(Map<K,V> map)
    Returns a fixed-sized map backed by the given map.
    static <K, V> SortedMap<K,V>
    fixedSizeSortedMap(SortedMap<K,V> map)
    Returns a fixed-sized sorted map backed by the given sorted map.
    static <K> Boolean
    getBoolean(Map<? super K,?> map, K key)
    Gets a Boolean from a Map in a null-safe manner.
    static <K> Boolean
    getBoolean(Map<? super K,?> map, K key, Boolean defaultValue)
    Looks up the given key in the given map, converting the result into a boolean, using the default value if the conversion fails.
    static <K> Boolean
    getBoolean(Map<? super K,?> map, K key, Function<K,Boolean> defaultFunction)
    Looks up the given key in the given map, converting the result into a boolean, using the defaultFunction to produce the default value if the conversion fails.
    static <K> boolean
    getBooleanValue(Map<? super K,?> map, K key)
    Gets a boolean from a Map in a null-safe manner.
    static <K> boolean
    getBooleanValue(Map<? super K,?> map, K key, boolean defaultValue)
    Gets a boolean from a Map in a null-safe manner, using the default value if the conversion fails.
    static <K> boolean
    getBooleanValue(Map<? super K,?> map, K key, Function<K,Boolean> defaultFunction)
    Gets a boolean from a Map in a null-safe manner, using the default value produced by the defaultFunction if the conversion fails.
    static <K> Byte
    getByte(Map<? super K,?> map, K key)
    Gets a Byte from a Map in a null-safe manner.
    static <K> Byte
    getByte(Map<? super K,?> map, K key, Byte defaultValue)
    Looks up the given key in the given map, converting the result into a byte, using the default value if the conversion fails.
    static <K> Byte
    getByte(Map<? super K,?> map, K key, Function<K,Byte> defaultFunction)
    Looks up the given key in the given map, converting the result into a byte, using the defaultFunction to produce the default value if the conversion fails.
    static <K> byte
    getByteValue(Map<? super K,?> map, K key)
    Gets a byte from a Map in a null-safe manner.
    static <K> byte
    getByteValue(Map<? super K,?> map, K key, byte defaultValue)
    Gets a byte from a Map in a null-safe manner, using the default value if the conversion fails.
    static <K> byte
    getByteValue(Map<? super K,?> map, K key, Function<K,Byte> defaultFunction)
    Gets a byte from a Map in a null-safe manner, using the default value produced by the defaultFunction if the conversion fails.
    static <K> Double
    getDouble(Map<? super K,?> map, K key)
    Gets a Double from a Map in a null-safe manner.
    static <K> Double
    getDouble(Map<? super K,?> map, K key, Double defaultValue)
    Looks up the given key in the given map, converting the result into a double, using the default value if the conversion fails.
    static <K> Double
    getDouble(Map<? super K,?> map, K key, Function<K,Double> defaultFunction)
    Looks up the given key in the given map, converting the result into a double, using the defaultFunction to produce the default value if the conversion fails.
    static <K> double
    getDoubleValue(Map<? super K,?> map, K key)
    Gets a double from a Map in a null-safe manner.
    static <K> double
    getDoubleValue(Map<? super K,?> map, K key, double defaultValue)
    Gets a double from a Map in a null-safe manner, using the default value if the conversion fails.
    static <K> double
    getDoubleValue(Map<? super K,?> map, K key, Function<K,Double> defaultFunction)
    Gets a double from a Map in a null-safe manner, using the default value produced by the defaultFunction if the conversion fails.
    static <K> Float
    getFloat(Map<? super K,?> map, K key)
    Gets a Float from a Map in a null-safe manner.
    static <K> Float
    getFloat(Map<? super K,?> map, K key, Float defaultValue)
    Looks up the given key in the given map, converting the result into a float, using the default value if the conversion fails.
    static <K> Float
    getFloat(Map<? super K,?> map, K key, Function<K,Float> defaultFunction)
    Looks up the given key in the given map, converting the result into a float, using the defaultFunction to produce the default value if the conversion fails.
    static <K> float
    getFloatValue(Map<? super K,?> map, K key)
    Gets a float from a Map in a null-safe manner.
    static <K> float
    getFloatValue(Map<? super K,?> map, K key, float defaultValue)
    Gets a float from a Map in a null-safe manner, using the default value if the conversion fails.
    static <K> float
    getFloatValue(Map<? super K,?> map, K key, Function<K,Float> defaultFunction)
    Gets a float from a Map in a null-safe manner, using the default value produced by the defaultFunction if the conversion fails.
    static <K> Integer
    getInteger(Map<? super K,?> map, K key)
    Gets an Integer from a Map in a null-safe manner.
    static <K> Integer
    getInteger(Map<? super K,?> map, K key, Integer defaultValue)
    Looks up the given key in the given map, converting the result into an integer, using the default value if the conversion fails.
    static <K> Integer
    getInteger(Map<? super K,?> map, K key, Function<K,Integer> defaultFunction)
    Looks up the given key in the given map, converting the result into an integer, using the defaultFunction to produce the default value if the conversion fails.
    static <K> int
    getIntValue(Map<? super K,?> map, K key)
    Gets an int from a Map in a null-safe manner.
    static <K> int
    getIntValue(Map<? super K,?> map, K key, int defaultValue)
    Gets an int from a Map in a null-safe manner, using the default value if the conversion fails.
    static <K> int
    getIntValue(Map<? super K,?> map, K key, Function<K,Integer> defaultFunction)
    Gets an int from a Map in a null-safe manner, using the default value produced by the defaultFunction if the conversion fails.
    static <K> Long
    getLong(Map<? super K,?> map, K key)
    Gets a Long from a Map in a null-safe manner.
    static <K> Long
    getLong(Map<? super K,?> map, K key, Long defaultValue)
    Looks up the given key in the given map, converting the result into a long, using the default value if the conversion fails.
    static <K> Long
    getLong(Map<? super K,?> map, K key, Function<K,Long> defaultFunction)
    Looks up the given key in the given map, converting the result into a Long, using the defaultFunction to produce the default value if the conversion fails.
    static <K> long
    getLongValue(Map<? super K,?> map, K key)
    Gets a long from a Map in a null-safe manner.
    static <K> long
    getLongValue(Map<? super K,?> map, K key, long defaultValue)
    Gets a long from a Map in a null-safe manner, using the default value if the conversion fails.
    static <K> long
    getLongValue(Map<? super K,?> map, K key, Function<K,Long> defaultFunction)
    Gets a long from a Map in a null-safe manner, using the default value produced by the defaultFunction if the conversion fails.
    static <K> Map<?,?>
    getMap(Map<? super K,?> map, K key)
    Gets a Map from a Map in a null-safe manner.
    static <K> Map<?,?>
    getMap(Map<? super K,?> map, K key, Function<K,Map<?,?>> defaultFunction)
    Looks up the given key in the given map, converting the result into a map, using the defaultFunction to produce the default value if the conversion fails.
    static <K> Map<?,?>
    getMap(Map<? super K,?> map, K key, Map<?,?> defaultValue)
    Looks up the given key in the given map, converting the result into a map, using the default value if the conversion fails.
    static <K> Number
    getNumber(Map<? super K,?> map, K key)
    Gets a Number from a Map in a null-safe manner.
    static <K> Number
    getNumber(Map<? super K,?> map, K key, Number defaultValue)
    Looks up the given key in the given map, converting the result into a number, using the default value if the conversion fails.
    static <K> Number
    getNumber(Map<? super K,?> map, K key, Function<K,Number> defaultFunction)
    Looks up the given key in the given map, converting the result into a number, using the defaultFunction to produce the default value if the conversion fails.
    static <K, V> V
    getObject(Map<? super K,V> map, K key)
    Gets from a Map in a null-safe manner.
    static <K, V> V
    getObject(Map<K,V> map, K key, V defaultValue)
    Looks up the given key in the given map, converting null into the given default value.
    static <K> Short
    getShort(Map<? super K,?> map, K key)
    Gets a Short from a Map in a null-safe manner.
    static <K> Short
    getShort(Map<? super K,?> map, K key, Short defaultValue)
    Looks up the given key in the given map, converting the result into a short, using the default value if the conversion fails.
    static <K> Short
    getShort(Map<? super K,?> map, K key, Function<K,Short> defaultFunction)
    Looks up the given key in the given map, converting the result into a short, using the defaultFunction to produce the default value if the conversion fails.
    static <K> short
    getShortValue(Map<? super K,?> map, K key)
    Gets a short from a Map in a null-safe manner.
    static <K> short
    getShortValue(Map<? super K,?> map, K key, short defaultValue)
    Gets a short from a Map in a null-safe manner, using the default value if the conversion fails.
    static <K> short
    getShortValue(Map<? super K,?> map, K key, Function<K,Short> defaultFunction)
    Gets a short from a Map in a null-safe manner, using the default value produced by the defaultFunction if the conversion fails.
    static <K> String
    getString(Map<? super K,?> map, K key)
    Gets a String from a Map in a null-safe manner.
    static <K> String
    getString(Map<? super K,?> map, K key, String defaultValue)
    Looks up the given key in the given map, converting the result into a string, using the default value if the conversion fails.
    static <K> String
    getString(Map<? super K,?> map, K key, Function<K,String> defaultFunction)
    Looks up the given key in the given map, converting the result into a string, using the defaultFunction to produce the default value if the conversion fails.
    static <K, V> Map<V,K>
    invertMap(Map<K,V> map)
    Inverts the supplied map returning a new HashMap such that the keys of the input are swapped with the values.
    static boolean
    isEmpty(Map<?,?> map)
    Null-safe check if the specified map is empty.
    static boolean
    isNotEmpty(Map<?,?> map)
    Null-safe check if the specified map is not empty.
    static <K, V> IterableMap<K,V>
    iterableMap(Map<K,V> map)
    Gets the specified Map as an IterableMap.
    static <K, V> IterableSortedMap<K,V>
    iterableSortedMap(SortedMap<K,V> sortedMap)
    Gets the specified SortedMap as an IterableSortedMap.
    static <K, V> IterableMap<K,V>
    lazyMap(Map<K,V> map, Factory<? extends V> factory)
    Returns a "lazy" map whose values will be created on demand.
    static <K, V> IterableMap<K,V>
    lazyMap(Map<K,V> map, Transformer<? super K,? extends V> transformerFactory)
    Returns a "lazy" map whose values will be created on demand.
    static <K, V> SortedMap<K,V>
    lazySortedMap(SortedMap<K,V> map, Factory<? extends V> factory)
    Returns a "lazy" sorted map whose values will be created on demand.
    static <K, V> SortedMap<K,V>
    lazySortedMap(SortedMap<K,V> map, Transformer<? super K,? extends V> transformerFactory)
    Returns a "lazy" sorted map whose values will be created on demand.
    static <K, V> MultiValueMap<K,V>
    multiValueMap(Map<K,? super Collection<V>> map)
    Deprecated.
    since 4.1, use MultiValuedMap instead
    static <K, V, C extends Collection<V>>
    MultiValueMap<K,V>
    multiValueMap(Map<K,C> map, Class<C> collectionClass)
    Deprecated.
    since 4.1, use MultiValuedMap instead
    static <K, V, C extends Collection<V>>
    MultiValueMap<K,V>
    multiValueMap(Map<K,C> map, Factory<C> collectionFactory)
    Deprecated.
    since 4.1, use MultiValuedMap instead
    static <K, V> OrderedMap<K,V>
    orderedMap(Map<K,V> map)
    Returns a map that maintains the order of keys that are added backed by the given map.
    static <K, V, E> void
    populateMap(Map<K,V> map, Iterable<? extends E> elements, Transformer<E,K> keyTransformer, Transformer<E,V> valueTransformer)
    Populates a Map using the supplied Transformers to transform the elements into keys and values.
    static <K, V> void
    populateMap(Map<K,V> map, Iterable<? extends V> elements, Transformer<V,K> keyTransformer)
    Populates a Map using the supplied Transformer to transform the elements into keys, using the unaltered element as the value in the Map.
    static <K, V, E> void
    populateMap(MultiMap<K,V> map, Iterable<? extends E> elements, Transformer<E,K> keyTransformer, Transformer<E,V> valueTransformer)
    Populates a MultiMap using the supplied Transformers to transform the elements into keys and values.
    static <K, V> void
    populateMap(MultiMap<K,V> map, Iterable<? extends V> elements, Transformer<V,K> keyTransformer)
    Populates a MultiMap using the supplied Transformer to transform the elements into keys, using the unaltered element as the value in the MultiMap.
    static <K, V> IterableMap<K,V>
    predicatedMap(Map<K,V> map, Predicate<? super K> keyPred, Predicate<? super V> valuePred)
    Returns a predicated (validating) map backed by the given map.
    static <K, V> SortedMap<K,V>
    predicatedSortedMap(SortedMap<K,V> map, Predicate<? super K> keyPred, Predicate<? super V> valuePred)
    Returns a predicated (validating) sorted map backed by the given map.
    static <K, V> Map<K,V>
    putAll(Map<K,V> map, Object[] array)
    Puts all the keys and values from the specified array into the map.
    static <K> void
    safeAddToMap(Map<? super K,Object> map, K key, Object value)
    Protects against adding null values to a map.
    static int
    size(Map<?,?> map)
    Gets the given map size or 0 if the map is null
    static <K, V> Map<K,V>
    synchronizedMap(Map<K,V> map)
    Returns a synchronized map backed by the given map.
    static <K, V> SortedMap<K,V>
    synchronizedSortedMap(SortedMap<K,V> map)
    Returns a synchronized sorted map backed by the given sorted map.
    static Map<String,Object>
    toMap(ResourceBundle resourceBundle)
    Creates a new HashMap using data copied from a ResourceBundle.
    static <K, V> Properties
    toProperties(Map<K,V> map)
    Gets a new Properties object initialized with the values from a Map.
    static <K, V> IterableMap<K,V>
    transformedMap(Map<K,V> map, Transformer<? super K,? extends K> keyTransformer, Transformer<? super V,? extends V> valueTransformer)
    Returns a transformed map backed by the given map.
    static <K, V> SortedMap<K,V>
    transformedSortedMap(SortedMap<K,V> map, Transformer<? super K,? extends K> keyTransformer, Transformer<? super V,? extends V> valueTransformer)
    Returns a transformed sorted map backed by the given map.
    static <K, V> Map<K,V>
    unmodifiableMap(Map<? extends K,? extends V> map)
    Returns an unmodifiable map backed by the given map.
    static <K, V> SortedMap<K,V>
    unmodifiableSortedMap(SortedMap<K,? extends V> map)
    Returns an unmodifiable sorted map backed by the given sorted map.
    static void
    verbosePrint(PrintStream out, Object label, Map<?,?> map)
    Prints the given map with nice line breaks.

    Methods inherited from class java.lang.Object

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

  • Field Details

    • EMPTY_SORTED_MAP

      public static final SortedMap EMPTY_SORTED_MAP
      An empty unmodifiable sorted map. This is not provided in the JDK.

  • Method Details

    • debugPrint

      public static void debugPrint(PrintStream out, Object label, Map<?,?> map)
      Prints the given map with nice line breaks.

      This method prints a nicely formatted String describing the Map. Each map entry will be printed with key, value and value class name. When the value is a Map, recursive behavior occurs.

      This method is NOT thread-safe in any special way. You must manually synchronize on either this class or the stream as required.

      Parameters:
      out - the stream to print to, must not be null
      label - The label to be used, may be null. If null, the label is not output. It typically represents the name of the property in a bean or similar.
      map - The map to print, may be null. If null, the text 'null' is output.
      Throws:
      NullPointerException - if the stream is null

    • emptyIfNull

      public static <K, V> Map<K,V> emptyIfNull(Map<K,V> map)
      Returns an immutable empty map if the argument is null, or the argument itself otherwise.
      Type Parameters:
      K - the key type
      V - the value type
      Parameters:
      map - the map, possibly null
      Returns:
      an empty map if the argument is null

    • fixedSizeMap

      public static <K, V> IterableMap<K,V> fixedSizeMap(Map<K,V> map)
      Returns a fixed-sized map backed by the given map. Elements may not be added or removed from the returned map, but existing elements can be changed (for instance, via the Map.put(Object,Object) method).
      Type Parameters:
      K - the key type
      V - the value type
      Parameters:
      map - the map whose size to fix, must not be null
      Returns:
      a fixed-size map backed by that map
      Throws:
      NullPointerException - if the Map is null

    • fixedSizeSortedMap

      public static <K, V> SortedMap<K,V> fixedSizeSortedMap(SortedMap<K,V> map)
      Returns a fixed-sized sorted map backed by the given sorted map. Elements may not be added or removed from the returned map, but existing elements can be changed (for instance, via the Map.put(Object,Object) method).
      Type Parameters:
      K - the key type
      V - the value type
      Parameters:
      map - the map whose size to fix, must not be null
      Returns:
      a fixed-size map backed by that map
      Throws:
      NullPointerException - if the SortedMap is null

    • getBoolean

      public static <K> Boolean getBoolean(Map<? super K,?> map, K key)
      Gets a Boolean from a Map in a null-safe manner.

      If the value is a Boolean it is returned directly. If the value is a String and it equals 'true' ignoring case then true is returned, otherwise false. If the value is a Number an integer zero value returns false and non-zero returns true. Otherwise, null is returned.

      Type Parameters:
      K - the key type
      Parameters:
      map - the map to use
      key - the key to look up
      Returns:
      the value in the Map as a Boolean, null if null map input

    • getBoolean

      public static <K> Boolean getBoolean(Map<? super K,?> map, K key, Boolean defaultValue)
      Looks up the given key in the given map, converting the result into a boolean, using the default value if the conversion fails.
      Type Parameters:
      K - the key type
      Parameters:
      map - the map whose value to look up
      key - the key of the value to look up in that map
      defaultValue - what to return if the value is null or if the conversion fails
      Returns:
      the value in the map as a boolean, or defaultValue if the original value is null, the map is null or the boolean conversion fails

    • getBoolean

      public static <K> Boolean getBoolean(Map<? super K,?> map, K key, Function<K,Boolean> defaultFunction)
      Looks up the given key in the given map, converting the result into a boolean, using the defaultFunction to produce the default value if the conversion fails.
      Type Parameters:
      K - the key type
      Parameters:
      map - the map whose value to look up
      key - the key of the value to look up in that map
      defaultFunction - what to produce the default value if the value is null or if the conversion fails
      Returns:
      the value in the map as a boolean, or defaultValue produced by the defaultFunction if the original value is null, the map is null or the boolean conversion fails
      Since:
      4.5

    • getBooleanValue

      public static <K> boolean getBooleanValue(Map<? super K,?> map, K key)
      Gets a boolean from a Map in a null-safe manner.

      If the value is a Boolean its value is returned. If the value is a String and it equals 'true' ignoring case then true is returned, otherwise false. If the value is a Number an integer zero value returns false and non-zero returns true. Otherwise, false is returned.

      Type Parameters:
      K - the key type
      Parameters:
      map - the map to use
      key - the key to look up
      Returns:
      the value in the Map as a Boolean, false if null map input

    • getBooleanValue

      public static <K> boolean getBooleanValue(Map<? super K,?> map, K key, boolean defaultValue)
      Gets a boolean from a Map in a null-safe manner, using the default value if the conversion fails.

      If the value is a Boolean its value is returned. If the value is a String and it equals 'true' ignoring case then true is returned, otherwise false. If the value is a Number an integer zero value returns false and non-zero returns true. Otherwise, defaultValue is returned.

      Type Parameters:
      K - the key type
      Parameters:
      map - the map to use
      key - the key to look up
      defaultValue - return if the value is null or if the conversion fails
      Returns:
      the value in the Map as a Boolean, defaultValue if null map input

    • getBooleanValue

      public static <K> boolean getBooleanValue(Map<? super K,?> map, K key, Function<K,Boolean> defaultFunction)
      Gets a boolean from a Map in a null-safe manner, using the default value produced by the defaultFunction if the conversion fails.

      If the value is a Boolean its value is returned. If the value is a String and it equals 'true' ignoring case then true is returned, otherwise false. If the value is a Number an integer zero value returns false and non-zero returns true. Otherwise, defaultValue produced by the defaultFunction is returned.

      Type Parameters:
      K - the key type
      Parameters:
      map - the map to use
      key - the key to look up
      defaultFunction - produce the default value to return if the value is null or if the conversion fails
      Returns:
      the value in the Map as a Boolean, default value produced by the defaultFunction if null map input
      Since:
      4.5

    • getByte

      public static <K> Byte getByte(Map<? super K,?> map, K key)
      Gets a Byte from a Map in a null-safe manner.

      The Byte is obtained from the results of getNumber(Map,Object).

      Type Parameters:
      K - the key type
      Parameters:
      map - the map to use
      key - the key to look up
      Returns:
      the value in the Map as a Byte, null if null map input

    • getByte

      public static <K> Byte getByte(Map<? super K,?> map, K key, Byte defaultValue)
      Looks up the given key in the given map, converting the result into a byte, using the default value if the conversion fails.
      Type Parameters:
      K - the key type
      Parameters:
      map - the map whose value to look up
      key - the key of the value to look up in that map
      defaultValue - what to return if the value is null or if the conversion fails
      Returns:
      the value in the map as a number, or defaultValue if the original value is null, the map is null or the number conversion fails

    • getByte

      public static <K> Byte getByte(Map<? super K,?> map, K key, Function<K,Byte> defaultFunction)
      Looks up the given key in the given map, converting the result into a byte, using the defaultFunction to produce the default value if the conversion fails.
      Type Parameters:
      K - the key type
      Parameters:
      map - the map whose value to look up
      key - the key of the value to look up in that map
      defaultFunction - what to produce the default value if the value is null or if the conversion fails
      Returns:
      the value in the map as a number, or defaultValue produced by the defaultFunction if the original value is null, the map is null or the number conversion fails
      Since:
      4.5

    • getByteValue

      public static <K> byte getByteValue(Map<? super K,?> map, K key)
      Gets a byte from a Map in a null-safe manner.

      The byte is obtained from the results of getNumber(Map,Object).

      Type Parameters:
      K - the key type
      Parameters:
      map - the map to use
      key - the key to look up
      Returns:
      the value in the Map as a byte, 0 if null map input

    • getByteValue

      public static <K> byte getByteValue(Map<? super K,?> map, K key, byte defaultValue)
      Gets a byte from a Map in a null-safe manner, using the default value if the conversion fails.

      The byte is obtained from the results of getNumber(Map,Object).

      Type Parameters:
      K - the key type
      Parameters:
      map - the map to use
      key - the key to look up
      defaultValue - return if the value is null or if the conversion fails
      Returns:
      the value in the Map as a byte, defaultValue if null map input

    • getByteValue

      public static <K> byte getByteValue(Map<? super K,?> map, K key, Function<K,Byte> defaultFunction)
      Gets a byte from a Map in a null-safe manner, using the default value produced by the defaultFunction if the conversion fails.

      The byte is obtained from the results of getNumber(Map,Object).

      Type Parameters:
      K - the key type
      Parameters:
      map - the map to use
      key - the key to look up
      defaultFunction - produce the default value to return if the value is null or if the conversion fails
      Returns:
      the value in the Map as a byte, default value produced by the defaultFunction if null map input
      Since:
      4.5

    • getDouble

      public static <K> Double getDouble(Map<? super K,?> map, K key)
      Gets a Double from a Map in a null-safe manner.

      The Double is obtained from the results of getNumber(Map,Object).

      Type Parameters:
      K - the key type
      Parameters:
      map - the map to use
      key - the key to look up
      Returns:
      the value in the Map as a Double, null if null map input

    • getDouble

      public static <K> Double getDouble(Map<? super K,?> map, K key, Double defaultValue)
      Looks up the given key in the given map, converting the result into a double, using the default value if the conversion fails.
      Type Parameters:
      K - the key type
      Parameters:
      map - the map whose value to look up
      key - the key of the value to look up in that map
      defaultValue - what to return if the value is null or if the conversion fails
      Returns:
      the value in the map as a number, or defaultValue if the original value is null, the map is null or the number conversion fails

    • getDouble

      public static <K> Double getDouble(Map<? super K,?> map, K key, Function<K,Double> defaultFunction)
      Looks up the given key in the given map, converting the result into a double, using the defaultFunction to produce the default value if the conversion fails.
      Type Parameters:
      K - the key type
      Parameters:
      map - the map whose value to look up
      key - the key of the value to look up in that map
      defaultFunction - what to produce the default value if the value is null or if the conversion fails
      Returns:
      the value in the map as a number, or defaultValue produced by the defaultFunction if the original value is null, the map is null or the number conversion fails
      Since:
      4.5

    • getDoubleValue

      public static <K> double getDoubleValue(Map<? super K,?> map, K key)
      Gets a double from a Map in a null-safe manner.

      The double is obtained from the results of getNumber(Map,Object).

      Type Parameters:
      K - the key type
      Parameters:
      map - the map to use
      key - the key to look up
      Returns:
      the value in the Map as a double, 0.0 if null map input

    • getDoubleValue

      public static <K> double getDoubleValue(Map<? super K,?> map, K key, double defaultValue)
      Gets a double from a Map in a null-safe manner, using the default value if the conversion fails.

      The double is obtained from the results of getNumber(Map,Object).

      Type Parameters:
      K - the key type
      Parameters:
      map - the map to use
      key - the key to look up
      defaultValue - return if the value is null or if the conversion fails
      Returns:
      the value in the Map as a double, defaultValue if null map input

    • getDoubleValue

      public static <K> double getDoubleValue(Map<? super K,?> map, K key, Function<K,Double> defaultFunction)
      Gets a double from a Map in a null-safe manner, using the default value produced by the defaultFunction if the conversion fails.

      The double is obtained from the results of getNumber(Map,Object).

      Type Parameters:
      K - the key type
      Parameters:
      map - the map to use
      key - the key to look up
      defaultFunction - produce the default value to return if the value is null or if the conversion fails
      Returns:
      the value in the Map as a double, default value produced by the defaultFunction if null map input
      Since:
      4.5

    • getFloat

      public static <K> Float getFloat(Map<? super K,?> map, K key)
      Gets a Float from a Map in a null-safe manner.

      The Float is obtained from the results of getNumber(Map,Object).

      Type Parameters:
      K - the key type
      Parameters:
      map - the map to use
      key - the key to look up
      Returns:
      the value in the Map as a Float, null if null map input

    • getFloat

      public static <K> Float getFloat(Map<? super K,?> map, K key, Float defaultValue)
      Looks up the given key in the given map, converting the result into a float, using the default value if the conversion fails.
      Type Parameters:
      K - the key type
      Parameters:
      map - the map whose value to look up
      key - the key of the value to look up in that map
      defaultValue - what to return if the value is null or if the conversion fails
      Returns:
      the value in the map as a number, or defaultValue if the original value is null, the map is null or the number conversion fails

    • getFloat

      public static <K> Float getFloat(Map<? super K,?> map, K key, Function<K,Float> defaultFunction)
      Looks up the given key in the given map, converting the result into a float, using the defaultFunction to produce the default value if the conversion fails.
      Type Parameters:
      K - the key type
      Parameters:
      map - the map whose value to look up
      key - the key of the value to look up in that map
      defaultFunction - what to produce the default value if the value is null or if the conversion fails
      Returns:
      the value in the map as a number, or defaultValue produced by the defaultFunction if the original value is null, the map is null or the number conversion fails
      Since:
      4.5

    • getFloatValue

      public static <K> float getFloatValue(Map<? super K,?> map, K key)
      Gets a float from a Map in a null-safe manner.

      The float is obtained from the results of getNumber(Map,Object).

      Type Parameters:
      K - the key type
      Parameters:
      map - the map to use
      key - the key to look up
      Returns:
      the value in the Map as a float, 0.0F if null map input

    • getFloatValue

      public static <K> float getFloatValue(Map<? super K,?> map, K key, float defaultValue)
      Gets a float from a Map in a null-safe manner, using the default value if the conversion fails.

      The float is obtained from the results of getNumber(Map,Object).

      Type Parameters:
      K - the key type
      Parameters:
      map - the map to use
      key - the key to look up
      defaultValue - return if the value is null or if the conversion fails
      Returns:
      the value in the Map as a float, defaultValue if null map input

    • getFloatValue

      public static <K> float getFloatValue(Map<? super K,?> map, K key, Function<K,Float> defaultFunction)
      Gets a float from a Map in a null-safe manner, using the default value produced by the defaultFunction if the conversion fails.

      The float is obtained from the results of getNumber(Map,Object).

      Type Parameters:
      K - the key type
      Parameters:
      map - the map to use
      key - the key to look up
      defaultFunction - produce the default value to return if the value is null or if the conversion fails
      Returns:
      the value in the Map as a float, default value produced by the defaultFunction if null map input
      Since:
      4.5

    • getInteger

      public static <K> Integer getInteger(Map<? super K,?> map, K key)
      Gets an Integer from a Map in a null-safe manner.

      The Integer is obtained from the results of getNumber(Map,Object).

      Type Parameters:
      K - the key type
      Parameters:
      map - the map to use
      key - the key to look up
      Returns:
      the value in the Map as an Integer, null if null map input

    • getInteger

      public static <K> Integer getInteger(Map<? super K,?> map, K key, Function<K,Integer> defaultFunction)
      Looks up the given key in the given map, converting the result into an integer, using the defaultFunction to produce the default value if the conversion fails.
      Type Parameters:
      K - the key type
      Parameters:
      map - the map whose value to look up
      key - the key of the value to look up in that map
      defaultFunction - what to produce the default value if the value is null or if the conversion fails
      Returns:
      the value in the map as a number, or defaultValue produced by the defaultFunction if the original value is null, the map is null or the number conversion fails
      Since:
      4.5

    • getInteger

      public static <K> Integer getInteger(Map<? super K,?> map, K key, Integer defaultValue)
      Looks up the given key in the given map, converting the result into an integer, using the default value if the conversion fails.
      Type Parameters:
      K - the key type
      Parameters:
      map - the map whose value to look up
      key - the key of the value to look up in that map
      defaultValue - what to return if the value is null or if the conversion fails
      Returns:
      the value in the map as a number, or defaultValue if the original value is null, the map is null or the number conversion fails

    • getIntValue

      public static <K> int getIntValue(Map<? super K,?> map, K key)
      Gets an int from a Map in a null-safe manner.

      The int is obtained from the results of getNumber(Map,Object).

      Type Parameters:
      K - the key type
      Parameters:
      map - the map to use
      key - the key to look up
      Returns:
      the value in the Map as an int, 0 if null map input

    • getIntValue

      public static <K> int getIntValue(Map<? super K,?> map, K key, Function<K,Integer> defaultFunction)
      Gets an int from a Map in a null-safe manner, using the default value produced by the defaultFunction if the conversion fails.

      The int is obtained from the results of getNumber(Map,Object).

      Type Parameters:
      K - the key type
      Parameters:
      map - the map to use
      key - the key to look up
      defaultFunction - produce the default value to return if the value is null or if the conversion fails
      Returns:
      the value in the Map as an int, default value produced by the defaultFunction if null map input
      Since:
      4.5

    • getIntValue

      public static <K> int getIntValue(Map<? super K,?> map, K key, int defaultValue)
      Gets an int from a Map in a null-safe manner, using the default value if the conversion fails.

      The int is obtained from the results of getNumber(Map,Object).

      Type Parameters:
      K - the key type
      Parameters:
      map - the map to use
      key - the key to look up
      defaultValue - return if the value is null or if the conversion fails
      Returns:
      the value in the Map as an int, defaultValue if null map input

    • getLong

      public static <K> Long getLong(Map<? super K,?> map, K key)
      Gets a Long from a Map in a null-safe manner.

      The Long is obtained from the results of getNumber(Map,Object).

      Type Parameters:
      K - the key type
      Parameters:
      map - the map to use
      key - the key to look up
      Returns:
      the value in the Map as a Long, null if null map input

    • getLong

      public static <K> Long getLong(Map<? super K,?> map, K key, Function<K,Long> defaultFunction)
      Looks up the given key in the given map, converting the result into a Long, using the defaultFunction to produce the default value if the conversion fails.
      Type Parameters:
      K - the key type
      Parameters:
      map - the map whose value to look up
      key - the key of the value to look up in that map
      defaultFunction - what to produce the default value if the value is null or if the conversion fails
      Returns:
      the value in the map as a number, or defaultValue produced by the defaultFunction if the original value is null, the map is null or the number conversion fails
      Since:
      4.5

    • getLong

      public static <K> Long getLong(Map<? super K,?> map, K key, Long defaultValue)
      Looks up the given key in the given map, converting the result into a long, using the default value if the conversion fails.
      Type Parameters:
      K - the key type
      Parameters:
      map - the map whose value to look up
      key - the key of the value to look up in that map
      defaultValue - what to return if the value is null or if the conversion fails
      Returns:
      the value in the map as a number, or defaultValue if the original value is null, the map is null or the number conversion fails

    • getLongValue

      public static <K> long getLongValue(Map<? super K,?> map, K key)
      Gets a long from a Map in a null-safe manner.

      The long is obtained from the results of getNumber(Map,Object).

      Type Parameters:
      K - the key type
      Parameters:
      map - the map to use
      key - the key to look up
      Returns:
      the value in the Map as a long, 0L if null map input

    • getLongValue

      public static <K> long getLongValue(Map<? super K,?> map, K key, Function<K,Long> defaultFunction)
      Gets a long from a Map in a null-safe manner, using the default value produced by the defaultFunction if the conversion fails.

      The long is obtained from the results of getNumber(Map,Object).

      Type Parameters:
      K - the key type
      Parameters:
      map - the map to use
      key - the key to look up
      defaultFunction - produce the default value to return if the value is null or if the conversion fails
      Returns:
      the value in the Map as a long, default value produced by the defaultFunction if null map input
      Since:
      4.5

    • getLongValue

      public static <K> long getLongValue(Map<? super K,?> map, K key, long defaultValue)
      Gets a long from a Map in a null-safe manner, using the default value if the conversion fails.

      The long is obtained from the results of getNumber(Map,Object).

      Type Parameters:
      K - the key type
      Parameters:
      map - the map to use
      key - the key to look up
      defaultValue - return if the value is null or if the conversion fails
      Returns:
      the value in the Map as a long, defaultValue if null map input

    • getMap

      public static <K> Map<?,?> getMap(Map<? super K,?> map, K key)
      Gets a Map from a Map in a null-safe manner.

      If the value returned from the specified map is not a Map then null is returned.

      Type Parameters:
      K - the key type
      Parameters:
      map - the map to use
      key - the key to look up
      Returns:
      the value in the Map as a Map, null if null map input

    • getMap

      public static <K> Map<?,?> getMap(Map<? super K,?> map, K key, Function<K,Map<?,?>> defaultFunction)
      Looks up the given key in the given map, converting the result into a map, using the defaultFunction to produce the default value if the conversion fails.
      Type Parameters:
      K - the key type
      Parameters:
      map - the map whose value to look up
      key - the key of the value to look up in that map
      defaultFunction - what to produce the default value if the value is null or if the conversion fails
      Returns:
      the value in the map as a number, or defaultValue produced by the defaultFunction if the original value is null, the map is null or the map conversion fails
      Since:
      4.5

    • getMap

      public static <K> Map<?,?> getMap(Map<? super K,?> map, K key, Map<?,?> defaultValue)
      Looks up the given key in the given map, converting the result into a map, using the default value if the conversion fails.
      Type Parameters:
      K - the key type
      Parameters:
      map - the map whose value to look up
      key - the key of the value to look up in that map
      defaultValue - what to return if the value is null or if the conversion fails
      Returns:
      the value in the map as a number, or defaultValue if the original value is null, the map is null or the map conversion fails

    • getNumber

      public static <K> Number getNumber(Map<? super K,?> map, K key)
      Gets a Number from a Map in a null-safe manner.

      If the value is a Number it is returned directly. If the value is a String it is converted using NumberFormat.parse(String) on the system default formatter returning null if the conversion fails. Otherwise, null is returned.

      Type Parameters:
      K - the key type
      Parameters:
      map - the map to use
      key - the key to look up
      Returns:
      the value in the Map as a Number, null if null map input

    • getNumber

      public static <K> Number getNumber(Map<? super K,?> map, K key, Function<K,Number> defaultFunction)
      Looks up the given key in the given map, converting the result into a number, using the defaultFunction to produce the default value if the conversion fails.
      Type Parameters:
      K - the key type
      Parameters:
      map - the map whose value to look up
      key - the key of the value to look up in that map
      defaultFunction - what to produce the default value if the value is null or if the conversion fails
      Returns:
      the value in the map as a number, or defaultValue produced by the defaultFunction if the original value is null, the map is null or the number conversion fails
      Since:
      4.5

    • getNumber

      public static <K> Number getNumber(Map<? super K,?> map, K key, Number defaultValue)
      Looks up the given key in the given map, converting the result into a number, using the default value if the conversion fails.
      Type Parameters:
      K - the key type
      Parameters:
      map - the map whose value to look up
      key - the key of the value to look up in that map
      defaultValue - what to return if the value is null or if the conversion fails
      Returns:
      the value in the map as a number, or defaultValue if the original value is null, the map is null or the number conversion fails

    • getObject

      public static <K, V> V getObject(Map<? super K,V> map, K key)
      Gets from a Map in a null-safe manner.
      Type Parameters:
      K - the key type
      V - the value type
      Parameters:
      map - the map to use
      key - the key to look up
      Returns:
      the value in the Map, null if null map input

    • getObject

      public static <K, V> V getObject(Map<K,V> map, K key, V defaultValue)
      Looks up the given key in the given map, converting null into the given default value.
      Type Parameters:
      K - the key type
      V - the value type
      Parameters:
      map - the map whose value to look up
      key - the key of the value to look up in that map
      defaultValue - what to return if the value is null
      Returns:
      the value in the map, or defaultValue if the original value is null or the map is null

    • getShort

      public static <K> Short getShort(Map<? super K,?> map, K key)
      Gets a Short from a Map in a null-safe manner.

      The Short is obtained from the results of getNumber(Map,Object).

      Type Parameters:
      K - the key type
      Parameters:
      map - the map to use
      key - the key to look up
      Returns:
      the value in the Map as a Short, null if null map input

    • getShort

      public static <K> Short getShort(Map<? super K,?> map, K key, Function<K,Short> defaultFunction)
      Looks up the given key in the given map, converting the result into a short, using the defaultFunction to produce the default value if the conversion fails.
      Type Parameters:
      K - the key type
      Parameters:
      map - the map whose value to look up
      key - the key of the value to look up in that map
      defaultFunction - what to produce the default value if the value is null or if the conversion fails
      Returns:
      the value in the map as a number, or defaultValue produced by the defaultFunction if the original value is null, the map is null or the number conversion fails
      Since:
      4.5

    • getShort

      public static <K> Short getShort(Map<? super K,?> map, K key, Short defaultValue)
      Looks up the given key in the given map, converting the result into a short, using the default value if the conversion fails.
      Type Parameters:
      K - the key type
      Parameters:
      map - the map whose value to look up
      key - the key of the value to look up in that map
      defaultValue - what to return if the value is null or if the conversion fails
      Returns:
      the value in the map as a number, or defaultValue if the original value is null, the map is null or the number conversion fails

    • getShortValue

      public static <K> short getShortValue(Map<? super K,?> map, K key)
      Gets a short from a Map in a null-safe manner.

      The short is obtained from the results of getNumber(Map,Object).

      Type Parameters:
      K - the key type
      Parameters:
      map - the map to use
      key - the key to look up
      Returns:
      the value in the Map as a short, 0 if null map input

    • getShortValue

      public static <K> short getShortValue(Map<? super K,?> map, K key, Function<K,Short> defaultFunction)
      Gets a short from a Map in a null-safe manner, using the default value produced by the defaultFunction if the conversion fails.

      The short is obtained from the results of getNumber(Map,Object).

      Type Parameters:
      K - the key type
      Parameters:
      map - the map to use
      key - the key to look up
      defaultFunction - produce the default value to return if the value is null or if the conversion fails
      Returns:
      the value in the Map as a short, default value produced by the defaultFunction if null map input
      Since:
      4.5

    • getShortValue

      public static <K> short getShortValue(Map<? super K,?> map, K key, short defaultValue)
      Gets a short from a Map in a null-safe manner, using the default value if the conversion fails.

      The short is obtained from the results of getNumber(Map,Object).

      Type Parameters:
      K - the key type
      Parameters:
      map - the map to use
      key - the key to look up
      defaultValue - return if the value is null or if the conversion fails
      Returns:
      the value in the Map as a short, defaultValue if null map input

    • getString

      public static <K> String getString(Map<? super K,?> map, K key)
      Gets a String from a Map in a null-safe manner.

      The String is obtained via toString.

      Type Parameters:
      K - the key type
      Parameters:
      map - the map to use
      key - the key to look up
      Returns:
      the value in the Map as a String, null if null map input

    • getString

      public static <K> String getString(Map<? super K,?> map, K key, Function<K,String> defaultFunction)
      Looks up the given key in the given map, converting the result into a string, using the defaultFunction to produce the default value if the conversion fails.
      Type Parameters:
      K - the key type
      Parameters:
      map - the map whose value to look up
      key - the key of the value to look up in that map
      defaultFunction - what to produce the default value if the value is null or if the conversion fails
      Returns:
      the value in the map as a string, or defaultValue produced by the defaultFunction if the original value is null, the map is null or the string conversion fails
      Since:
      4.5

    • getString

      public static <K> String getString(Map<? super K,?> map, K key, String defaultValue)
      Looks up the given key in the given map, converting the result into a string, using the default value if the conversion fails.
      Type Parameters:
      K - the key type
      Parameters:
      map - the map whose value to look up
      key - the key of the value to look up in that map
      defaultValue - what to return if the value is null or if the conversion fails
      Returns:
      the value in the map as a string, or defaultValue if the original value is null, the map is null or the string conversion fails

    • invertMap

      public static <K, V> Map<V,K> invertMap(Map<K,V> map)
      Inverts the supplied map returning a new HashMap such that the keys of the input are swapped with the values.

      This operation assumes that the inverse mapping is well defined. If the input map had multiple entries with the same value mapped to different keys, the returned map will map one of those keys to the value, but the exact key which will be mapped is undefined.

      Type Parameters:
      K - the key type
      V - the value type
      Parameters:
      map - the map to invert, must not be null
      Returns:
      a new HashMap containing the inverted data
      Throws:
      NullPointerException - if the map is null

    • isEmpty

      public static boolean isEmpty(Map<?,?> map)
      Null-safe check if the specified map is empty.

      Null returns true.

      Parameters:
      map - the map to check, may be null
      Returns:
      true if empty or null
      Since:
      3.2

    • isNotEmpty

      public static boolean isNotEmpty(Map<?,?> map)
      Null-safe check if the specified map is not empty.

      Null returns false.

      Parameters:
      map - the map to check, may be null
      Returns:
      true if non-null and non-empty
      Since:
      3.2

    • iterableMap

      public static <K, V> IterableMap<K,V> iterableMap(Map<K,V> map)
      Gets the specified Map as an IterableMap.
      Type Parameters:
      K - the key type
      V - the value type
      Parameters:
      map - to wrap if necessary.
      Returns:
      IterableMap<K, V>
      Throws:
      NullPointerException - if map is null
      Since:
      4.0

    • iterableSortedMap

      public static <K, V> IterableSortedMap<K,V> iterableSortedMap(SortedMap<K,V> sortedMap)
      Gets the specified SortedMap as an IterableSortedMap.
      Type Parameters:
      K - the key type
      V - the value type
      Parameters:
      sortedMap - to wrap if necessary
      Returns:
      IterableSortedMap<K, V>
      Throws:
      NullPointerException - if sortedMap is null
      Since:
      4.0

    • lazyMap

      public static <K, V> IterableMap<K,V> lazyMap(Map<K,V> map, Factory<? extends V> factory)
      Returns a "lazy" map whose values will be created on demand.

      When the key passed to the returned map's Map.get(Object) method is not present in the map, then the factory will be used to create a new object and that object will become the value associated with that key.

      For instance: 

       Factory factory = new Factory() {
     public Object create() {
         return new Date();
     }
 }
 Map lazyMap = MapUtils.lazyMap(new HashMap(), factory);
 Object obj = lazyMap.get("test");

      After the above code is executed, obj will contain a new Date instance. Furthermore, that Date instance is the value for the "test" key in the map.

      Type Parameters:
      K - the key type
      V - the value type
      Parameters:
      map - the map to make lazy, must not be null
      factory - the factory for creating new objects, must not be null
      Returns:
      a lazy map backed by the given map
      Throws:
      NullPointerException - if the Map or Factory is null

    • lazyMap

      public static <K, V> IterableMap<K,V> lazyMap(Map<K,V> map, Transformer<? super K,? extends V> transformerFactory)
      Returns a "lazy" map whose values will be created on demand.

      When the key passed to the returned map's Map.get(Object) method is not present in the map, then the factory will be used to create a new object and that object will become the value associated with that key. The factory is a Transformer that will be passed the key which it must transform into the value.

      For instance: 

       Transformer factory = new Transformer() {
     public Object transform(Object mapKey) {
         return new File(mapKey);
     }
 }
 Map lazyMap = MapUtils.lazyMap(new HashMap(), factory);
 Object obj = lazyMap.get("C:/dev");

      After the above code is executed, obj will contain a new File instance for the C drive dev directory. Furthermore, that File instance is the value for the "C:/dev" key in the map.

      If a lazy map is wrapped by a synchronized map, the result is a simple synchronized cache. When an object is not is the cache, the cache itself calls back to the factory Transformer to populate itself, all within the same synchronized block.

      Type Parameters:
      K - the key type
      V - the value type
      Parameters:
      map - the map to make lazy, must not be null
      transformerFactory - the factory for creating new objects, must not be null
      Returns:
      a lazy map backed by the given map
      Throws:
      NullPointerException - if the Map or Transformer is null

    • lazySortedMap

      public static <K, V> SortedMap<K,V> lazySortedMap(SortedMap<K,V> map, Factory<? extends V> factory)
      Returns a "lazy" sorted map whose values will be created on demand.

      When the key passed to the returned map's Map.get(Object) method is not present in the map, then the factory will be used to create a new object and that object will become the value associated with that key.

      For instance: 

       Factory factory = new Factory() {
     public Object create() {
         return new Date();
     }
 }
 SortedMap lazy = MapUtils.lazySortedMap(new TreeMap(), factory);
 Object obj = lazy.get("test");

      After the above code is executed, obj will contain a new Date instance. Furthermore, that Date instance is the value for the "test" key.

      Type Parameters:
      K - the key type
      V - the value type
      Parameters:
      map - the map to make lazy, must not be null
      factory - the factory for creating new objects, must not be null
      Returns:
      a lazy map backed by the given map
      Throws:
      NullPointerException - if the SortedMap or Factory is null

    • lazySortedMap

      public static <K, V> SortedMap<K,V> lazySortedMap(SortedMap<K,V> map, Transformer<? super K,? extends V> transformerFactory)
      Returns a "lazy" sorted map whose values will be created on demand.

      When the key passed to the returned map's Map.get(Object) method is not present in the map, then the factory will be used to create a new object and that object will become the value associated with that key. The factory is a Transformer that will be passed the key which it must transform into the value.

      For instance: 

       Transformer factory = new Transformer() {
     public Object transform(Object mapKey) {
         return new File(mapKey);
     }
 }
 SortedMap lazy = MapUtils.lazySortedMap(new TreeMap(), factory);
 Object obj = lazy.get("C:/dev");

      After the above code is executed, obj will contain a new File instance for the C drive dev directory. Furthermore, that File instance is the value for the "C:/dev" key in the map.

      If a lazy map is wrapped by a synchronized map, the result is a simple synchronized cache. When an object is not is the cache, the cache itself calls back to the factory Transformer to populate itself, all within the same synchronized block.

      Type Parameters:
      K - the key type
      V - the value type
      Parameters:
      map - the map to make lazy, must not be null
      transformerFactory - the factory for creating new objects, must not be null
      Returns:
      a lazy map backed by the given map
      Throws:
      NullPointerException - if the Map or Transformer is null

    • multiValueMap

      @Deprecated public static <K, V> MultiValueMap<K,V> multiValueMap(Map<K,? super Collection<V>> map)
      Deprecated.
      since 4.1, use MultiValuedMap instead
      Creates a multi-value map backed by the given map which returns collections of type ArrayList.
      Type Parameters:
      K - the key type
      V - the value type
      Parameters:
      map - the map to decorate
      Returns:
      a multi-value map backed by the given map which returns ArrayLists of values.
      Since:
      3.2
      See Also:

    • multiValueMap

      @Deprecated public static <K, V, C extends Collection<V>> MultiValueMap<K,V> multiValueMap(Map<K,C> map, Class<C> collectionClass)
      Deprecated.
      since 4.1, use MultiValuedMap instead
      Creates a multi-value map backed by the given map which returns collections of the specified type.
      Type Parameters:
      K - the key type
      V - the value type
      C - the collection class type
      Parameters:
      map - the map to decorate
      collectionClass - the type of collections to return from the map (must contain public no-arg constructor and extend Collection)
      Returns:
      a multi-value map backed by the given map which returns collections of the specified type
      Since:
      3.2
      See Also:

    • multiValueMap

      @Deprecated public static <K, V, C extends Collection<V>> MultiValueMap<K,V> multiValueMap(Map<K,C> map, Factory<C> collectionFactory)
      Deprecated.
      since 4.1, use MultiValuedMap instead
      Creates a multi-value map backed by the given map which returns collections created by the specified collection factory.
      Type Parameters:
      K - the key type
      V - the value type
      C - the collection class type
      Parameters:
      map - the map to decorate
      collectionFactory - a factor which creates collection objects
      Returns:
      a multi-value map backed by the given map which returns collections created by the specified collection factory
      Since:
      3.2
      See Also:

    • orderedMap

      public static <K, V> OrderedMap<K,V> orderedMap(Map<K,V> map)
      Returns a map that maintains the order of keys that are added backed by the given map.

      If a key is added twice, the order is determined by the first add. The order is observed through the keySet, values and entrySet.

      Type Parameters:
      K - the key type
      V - the value type
      Parameters:
      map - the map to order, must not be null
      Returns:
      an ordered map backed by the given map
      Throws:
      NullPointerException - if the Map is null

    • populateMap

      public static <K, V, E> void populateMap(Map<K,V> map, Iterable<? extends E> elements, Transformer<E,K> keyTransformer, Transformer<E,V> valueTransformer)
      Populates a Map using the supplied Transformers to transform the elements into keys and values.
      Type Parameters:
      K - the key type
      V - the value type
      E - the type of object contained in the Iterable
      Parameters:
      map - the Map to populate.
      elements - the Iterable containing the input values for the map.
      keyTransformer - the Transformer used to transform the element into a key value
      valueTransformer - the Transformer used to transform the element into a value
      Throws:
      NullPointerException - if the map, elements or transformers are null

    • populateMap

      public static <K, V> void populateMap(Map<K,V> map, Iterable<? extends V> elements, Transformer<V,K> keyTransformer)
      Populates a Map using the supplied Transformer to transform the elements into keys, using the unaltered element as the value in the Map.
      Type Parameters:
      K - the key type
      V - the value type
      Parameters:
      map - the Map to populate.
      elements - the Iterable containing the input values for the map.
      keyTransformer - the Transformer used to transform the element into a key value
      Throws:
      NullPointerException - if the map, elements or transformer are null

    • populateMap

      public static <K, V, E> void populateMap(MultiMap<K,V> map, Iterable<? extends E> elements, Transformer<E,K> keyTransformer, Transformer<E,V> valueTransformer)
      Populates a MultiMap using the supplied Transformers to transform the elements into keys and values.
      Type Parameters:
      K - the key type
      V - the value type
      E - the type of object contained in the Iterable
      Parameters:
      map - the MultiMap to populate.
      elements - the Iterable containing the input values for the map.
      keyTransformer - the Transformer used to transform the element into a key value
      valueTransformer - the Transformer used to transform the element into a value
      Throws:
      NullPointerException - if the map, collection or transformers are null

    • populateMap

      public static <K, V> void populateMap(MultiMap<K,V> map, Iterable<? extends V> elements, Transformer<V,K> keyTransformer)
      Populates a MultiMap using the supplied Transformer to transform the elements into keys, using the unaltered element as the value in the MultiMap.
      Type Parameters:
      K - the key type
      V - the value type
      Parameters:
      map - the MultiMap to populate.
      elements - the Iterable to use as input values for the map.
      keyTransformer - the Transformer used to transform the element into a key value
      Throws:
      NullPointerException - if the map, elements or transformer are null

    • predicatedMap

      public static <K, V> IterableMap<K,V> predicatedMap(Map<K,V> map, Predicate<? super K> keyPred, Predicate<? super V> valuePred)
      Returns a predicated (validating) map backed by the given map.

      Only objects that pass the tests in the given predicates can be added to the map. Trying to add an invalid object results in an IllegalArgumentException. Keys must pass the key predicate, values must pass the value predicate. It is important not to use the original map after invoking this method, as it is a backdoor for adding invalid objects.

      Type Parameters:
      K - the key type
      V - the value type
      Parameters:
      map - the map to predicate, must not be null
      keyPred - the predicate for keys, null means no check
      valuePred - the predicate for values, null means no check
      Returns:
      a predicated map backed by the given map
      Throws:
      NullPointerException - if the Map is null

    • predicatedSortedMap

      public static <K, V> SortedMap<K,V> predicatedSortedMap(SortedMap<K,V> map, Predicate<? super K> keyPred, Predicate<? super V> valuePred)
      Returns a predicated (validating) sorted map backed by the given map.

      Only objects that pass the tests in the given predicates can be added to the map. Trying to add an invalid object results in an IllegalArgumentException. Keys must pass the key predicate, values must pass the value predicate. It is important not to use the original map after invoking this method, as it is a backdoor for adding invalid objects.

      Type Parameters:
      K - the key type
      V - the value type
      Parameters:
      map - the map to predicate, must not be null
      keyPred - the predicate for keys, null means no check
      valuePred - the predicate for values, null means no check
      Returns:
      a predicated map backed by the given map
      Throws:
      NullPointerException - if the SortedMap is null

    • putAll

      public static <K, V> Map<K,V> putAll(Map<K,V> map, Object[] array)
      Puts all the keys and values from the specified array into the map.

      This method is an alternative to the Map.putAll(java.util.Map) method and constructors. It allows you to build a map from an object array of various possible styles.

      If the first entry in the object array implements Map.Entry or KeyValue then the key and value are added from that object. If the first entry in the object array is an object array itself, then it is assumed that index 0 in the sub-array is the key and index 1 is the value. Otherwise, the array is treated as keys and values in alternate indices.

      For example, to create a color map: 

       Map colorMap = MapUtils.putAll(new HashMap(),
         new String[][] { { "RED", "#FF0000" }, { "GREEN", "#00FF00" }, { "BLUE", "#0000FF" } });

      or: 

       Map colorMap = MapUtils.putAll(new HashMap(),
         new String[] { "RED", "#FF0000", "GREEN", "#00FF00", "BLUE", "#0000FF" });

      or: 

       Map colorMap = MapUtils.putAll(new HashMap(), new Map.Entry[] { new DefaultMapEntry("RED", "#FF0000"),
         new DefaultMapEntry("GREEN", "#00FF00"), new DefaultMapEntry("BLUE", "#0000FF") });
      Type Parameters:
      K - the key type
      V - the value type
      Parameters:
      map - the map to populate, must not be null
      array - an array to populate from, null ignored
      Returns:
      the input map
      Throws:
      NullPointerException - if map is null
      IllegalArgumentException - if sub-array or entry matching used and an entry is invalid
      ClassCastException - if the array contents is mixed
      Since:
      3.2

    • safeAddToMap

      public static <K> void safeAddToMap(Map<? super K,Object> map, K key, Object value) throws NullPointerException
      Protects against adding null values to a map.

      This method checks the value being added to the map, and if it is null it is replaced by an empty string.

      This could be useful if the map does not accept null values, or for receiving data from a source that may provide null or empty string which should be held in the same way in the map.

      Keys are not validated. Note that this method can be used to circumvent the map's value type at runtime.

      Type Parameters:
      K - the key type
      Parameters:
      map - the map to add to, must not be null
      key - the key
      value - the value, null converted to ""
      Throws:
      NullPointerException - if the map is null

    • size

      public static int size(Map<?,?> map)
      Gets the given map size or 0 if the map is null
      Parameters:
      map - a Map or null
      Returns:
      the given map size or 0 if the map is null

    • synchronizedMap

      public static <K, V> Map<K,V> synchronizedMap(Map<K,V> map)
      Returns a synchronized map backed by the given map.

      You must manually synchronize on the returned buffer's iterator to avoid non-deterministic behavior: 

       Map m = MapUtils.synchronizedMap(myMap);
 Sets s = m.keySet(); // outside synchronized block
 synchronized (m) { // synchronized on MAP!
     Iterator i = s.iterator();
     while (i.hasNext()) {
         process(i.next());
     }
 }

      This method uses the implementation in Collections.

      Type Parameters:
      K - the key type
      V - the value type
      Parameters:
      map - the map to synchronize, must not be null
      Returns:
      a synchronized map backed by the given map

    • synchronizedSortedMap

      public static <K, V> SortedMap<K,V> synchronizedSortedMap(SortedMap<K,V> map)
      Returns a synchronized sorted map backed by the given sorted map.

      You must manually synchronize on the returned buffer's iterator to avoid non-deterministic behavior: 

       Map m = MapUtils.synchronizedSortedMap(myMap);
 Sets s = m.keySet(); // outside synchronized block
 synchronized (m) { // synchronized on MAP!
     Iterator i = s.iterator();
     while (i.hasNext()) {
         process(i.next());
     }
 }

      This method uses the implementation in Collections.

      Type Parameters:
      K - the key type
      V - the value type
      Parameters:
      map - the map to synchronize, must not be null
      Returns:
      a synchronized map backed by the given map
      Throws:
      NullPointerException - if the map is null

    • toMap

      public static Map<String,Object> toMap(ResourceBundle resourceBundle)
      Creates a new HashMap using data copied from a ResourceBundle.
      Parameters:
      resourceBundle - the resource bundle to convert, must not be null
      Returns:
      the HashMap containing the data
      Throws:
      NullPointerException - if the bundle is null

    • toProperties

      public static <K, V> Properties toProperties(Map<K,V> map)
      Gets a new Properties object initialized with the values from a Map. A null input will return an empty properties object.

      A Properties object may only store non-null keys and values, thus if the provided map contains either a key or value which is null, a NullPointerException will be thrown.

      Type Parameters:
      K - the key type
      V - the value type
      Parameters:
      map - the map to convert to a Properties object
      Returns:
      the properties object
      Throws:
      NullPointerException - if a key or value in the provided map is null

    • transformedMap

      public static <K, V> IterableMap<K,V> transformedMap(Map<K,V> map, Transformer<? super K,? extends K> keyTransformer, Transformer<? super V,? extends V> valueTransformer)
      Returns a transformed map backed by the given map.

      This method returns a new map (decorating the specified map) that will transform any new entries added to it. Existing entries in the specified map will not be transformed. If you want that behavior, see TransformedMap.transformedMap(java.util.Map<K, V>, org.apache.commons.collections4.Transformer<? super K, ? extends K>, org.apache.commons.collections4.Transformer<? super V, ? extends V>).

      Each object is passed through the transformers as it is added to the Map. It is important not to use the original map after invoking this method, as it is a backdoor for adding untransformed objects.

      If there are any elements already in the map being decorated, they are NOT transformed.

      Type Parameters:
      K - the key type
      V - the value type
      Parameters:
      map - the map to transform, must not be null, typically empty
      keyTransformer - the transformer for the map keys, null means no transformation
      valueTransformer - the transformer for the map values, null means no transformation
      Returns:
      a transformed map backed by the given map
      Throws:
      NullPointerException - if the Map is null

    • transformedSortedMap

      public static <K, V> SortedMap<K,V> transformedSortedMap(SortedMap<K,V> map, Transformer<? super K,? extends K> keyTransformer, Transformer<? super V,? extends V> valueTransformer)
      Returns a transformed sorted map backed by the given map.

      This method returns a new sorted map (decorating the specified map) that will transform any new entries added to it. Existing entries in the specified map will not be transformed. If you want that behavior, see TransformedSortedMap.transformedSortedMap(java.util.SortedMap<K, V>, org.apache.commons.collections4.Transformer<? super K, ? extends K>, org.apache.commons.collections4.Transformer<? super V, ? extends V>).

      Each object is passed through the transformers as it is added to the Map. It is important not to use the original map after invoking this method, as it is a backdoor for adding untransformed objects.

      If there are any elements already in the map being decorated, they are NOT transformed.

      Type Parameters:
      K - the key type
      V - the value type
      Parameters:
      map - the map to transform, must not be null, typically empty
      keyTransformer - the transformer for the map keys, null means no transformation
      valueTransformer - the transformer for the map values, null means no transformation
      Returns:
      a transformed map backed by the given map
      Throws:
      NullPointerException - if the SortedMap is null

    • unmodifiableMap

      public static <K, V> Map<K,V> unmodifiableMap(Map<? extends K,? extends V> map)
      Returns an unmodifiable map backed by the given map.

      This method uses the implementation in the decorators subpackage.

      Type Parameters:
      K - the key type
      V - the value type
      Parameters:
      map - the map to make unmodifiable, must not be null
      Returns:
      an unmodifiable map backed by the given map
      Throws:
      NullPointerException - if the map is null

    • unmodifiableSortedMap

      public static <K, V> SortedMap<K,V> unmodifiableSortedMap(SortedMap<K,? extends V> map)
      Returns an unmodifiable sorted map backed by the given sorted map.

      This method uses the implementation in the decorators subpackage.

      Type Parameters:
      K - the key type
      V - the value type
      Parameters:
      map - the sorted map to make unmodifiable, must not be null
      Returns:
      an unmodifiable map backed by the given map
      Throws:
      NullPointerException - if the map is null

    • verbosePrint

      public static void verbosePrint(PrintStream out, Object label, Map<?,?> map)
      Prints the given map with nice line breaks.

      This method prints a nicely formatted String describing the Map. Each map entry will be printed with key and value. When the value is a Map, recursive behavior occurs.

      This method is NOT thread-safe in any special way. You must manually synchronize on either this class or the stream as required.

      Parameters:
      out - the stream to print to, must not be null
      label - The label to be used, may be null. If null, the label is not output. It typically represents the name of the property in a bean or similar.
      map - The map to print, may be null. If null, the text 'null' is output.
      Throws:
      NullPointerException - if the stream is null