Package io.microsphere.collection

Class MapUtils

  • All Implemented Interfaces:
    Utils
    public abstract class MapUtils
extends java.lang.Object
implements Utils
    The utilities class for Java Map
    Since:
    1.0.0
    Author:
    Mercy
    See Also:
    Map

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static float FIXED_LOAD_FACTOR
      The fixed load factor for HashMap or Hashtable = 1.00
      static float MIN_LOAD_FACTOR
      The min load factor for HashMap or Hashtable

    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      static java.util.Map<java.lang.String,​java.lang.Object> flattenMap​(java.util.Map<java.lang.String,​java.lang.Object> map)
      Flattens a nested map of properties into a single-level map.
      static <K,​V>
      java.util.Map.Entry<K,​V>      		 immutableEntry​(K key, V value)
      Creates an immutable Map.Entry with the specified key and value.
      static boolean isEmpty​(java.util.Map<?,​?> map)
      Checks if the specified map is either null or empty.
      static boolean isMap​(java.lang.Class<?> type)
      Checks if the specified class type is an implementation of Map.
      static boolean isMap​(java.lang.Object instance)
      Checks if the specified object is an instance of Map.
      static boolean isNotEmpty​(java.util.Map<?,​?> map)
      Checks if the specified map is not empty and not null.
      static java.util.Map<java.lang.String,​java.lang.Object> nestedMap​(java.util.Map<java.lang.String,​java.lang.Object> map)
      Converts a flat map with dot-separated keys into a nested map structure.
      static <K,​V>
      java.util.concurrent.ConcurrentHashMap<K,​V>      		 newConcurrentHashMap()
      Creates a new empty ConcurrentHashMap with the default initial capacity (16) and the default load factor (0.75), using the default concurrency level.
      static <K,​V>
      java.util.concurrent.ConcurrentHashMap<K,​V>      		 newConcurrentHashMap​(int initialCapacity)
      Creates a new ConcurrentHashMap with the specified initial capacity and the default load factor (0.75), using the default concurrency level.
      static <K,​V>
      java.util.concurrent.ConcurrentHashMap<K,​V>      		 newConcurrentHashMap​(int initialCapacity, float loadFactor)
      Creates a new ConcurrentHashMap with the specified initial capacity and load factor.
      static <K,​V>
      java.util.concurrent.ConcurrentHashMap<K,​V>      		 newConcurrentHashMap​(java.util.Map<? extends K,​? extends V> map)
      Creates a new ConcurrentHashMap with the same mappings as the specified map.
      static <K,​V>
      java.util.Map<K,​V>      		 newFixedHashMap​(int size)
      Creates a new empty HashMap with the specified initial capacity and a fixed load factor.
      static <K,​V>
      java.util.Map<K,​V>      		 newFixedLinkedHashMap​(int size)
      Creates a new empty LinkedHashMap with the specified initial capacity and a fixed load factor.
      static <K,​V>
      java.util.HashMap<K,​V>      		 newHashMap()
      Creates a new empty HashMap with the default initial capacity (16) and the default load factor (0.75).
      static <K,​V>
      java.util.HashMap<K,​V>      		 newHashMap​(int initialCapacity)
      Creates a new HashMap with the specified initial capacity and the default load factor (0.75).
      static <K,​V>
      java.util.HashMap<K,​V>      		 newHashMap​(int initialCapacity, float loadFactor)
      Creates a new HashMap with the specified initial capacity and load factor.
      static <K,​V>
      java.util.HashMap<K,​V>      		 newHashMap​(java.util.Map<? extends K,​? extends V> map)
      Creates a new HashMap with the same mappings as the specified map.
      static <K,​V>
      java.util.LinkedHashMap<K,​V>      		 newLinkedHashMap()
      Creates a new empty LinkedHashMap with the default initial capacity (16) and the default load factor (0.75).
      static <K,​V>
      java.util.LinkedHashMap<K,​V>      		 newLinkedHashMap​(int initialCapacity)
      Creates a new LinkedHashMap with the specified initial capacity and the default load factor (0.75).
      static <K,​V>
      java.util.LinkedHashMap<K,​V>      		 newLinkedHashMap​(int initialCapacity, float loadFactor)
      Creates a new LinkedHashMap with the specified initial capacity and load factor.
      static <K,​V>
      java.util.LinkedHashMap<K,​V>      		 newLinkedHashMap​(int initialCapacity, float loadFactor, boolean accessOrder)
      Creates a new LinkedHashMap with the specified initial capacity, load factor, and ordering mode.
      static <K,​V>
      java.util.LinkedHashMap<K,​V>      		 newLinkedHashMap​(java.util.Map<? extends K,​? extends V> map)
      Creates a new LinkedHashMap with the same mappings as the specified map.
      static <K,​V>
      java.util.TreeMap<K,​V>      		 newTreeMap()
      Creates a new empty TreeMap using natural ordering for the keys.
      static <K,​V>
      java.util.TreeMap<K,​V>      		 newTreeMap​(java.util.Comparator<? super K> comparator)
      Creates a new empty TreeMap with the specified comparator to order the keys.
      static <K,​V>
      java.util.TreeMap<K,​V>      		 newTreeMap​(java.util.Map<? extends K,​? extends V> map)
      Creates a new TreeMap with the same mappings as the specified map.
      static <K,​V>
      java.util.TreeMap<K,​V>      		 newTreeMap​(java.util.SortedMap<K,​? extends V> map)
      Creates a new TreeMap with the same mappings as the specified sorted map.
      static java.util.Map of​(java.lang.Object... values)
      Creates an immutable map from a varargs array of key-value pairs.
      static <K,​V>
      java.util.Map<K,​V>      		 of​(java.util.Map.Entry<? extends K,​? extends V>... entries)
      Creates an immutable map from the provided array of Map.Entry objects.
      static <K,​V>
      java.util.Map<K,​V>      		 of​(K key, V value)
      Creates an immutable map containing a single key-value pair.
      static <K,​V>
      java.util.Map<K,​V>      		 of​(K key1, V value1, K key2, V value2)
      Creates an immutable map containing two key-value pairs.
      static <K,​V>
      java.util.Map<K,​V>      		 of​(K key1, V value1, K key2, V value2, K key3, V value3)
      Creates an immutable map containing three key-value pairs.
      static <K,​V>
      java.util.Map<K,​V>      		 of​(K key1, V value1, K key2, V value2, K key3, V value3, K key4, V value4)
      Creates an immutable map containing four key-value pairs.
      static <K,​V>
      java.util.Map<K,​V>      		 of​(K key1, V value1, K key2, V value2, K key3, V value3, K key4, V value4, K key5, V value5)
      Creates an immutable map containing five key-value pairs.
      static <K,​V>
      java.util.Map.Entry<K,​V>      		 ofEntry​(K key, V value)
      Creates an immutable Map.Entry with the specified key and value.
      static java.util.Map ofMap​(java.lang.Object... keyValuePairs)
      Creates an immutable map from a varargs array of key-value pairs.
      static <K,​V>
      java.util.Map<K,​V>      		 ofMap​(K key, V value)
      Creates an immutable map containing a single key-value pair.
      static <K,​V>
      java.util.Map<K,​V>      		 shallowCloneMap​(java.util.Map<K,​V> source)
      Performs a shallow clone of the provided map, creating a new map instance with the same key-value mappings.
      static int size​(java.util.Map<?,​?> map)
      Returns the size of the specified map, or 0 if the map is null.
      static <K,​V,​E>
      java.util.Map<K,​V>      		 toFixedMap​(java.util.Collection<E> values, java.util.function.Function<E,​java.util.Map.Entry<K,​V>> entryMapper)
      Converts a collection of elements into an immutable map using the provided function to extract key-value pairs.

      • Methods inherited from class java.lang.Object

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

    • Field Detail

      • MIN_LOAD_FACTOR

        public static final float MIN_LOAD_FACTOR
        The min load factor for HashMap or Hashtable
        See Also:
        Constant Field Values

      • FIXED_LOAD_FACTOR

        public static final float FIXED_LOAD_FACTOR
        The fixed load factor for HashMap or Hashtable = 1.00
        See Also:
        Constant Field Values

    • Method Detail

      • isMap

        public static boolean isMap​(java.lang.Object instance)
        Checks if the specified object is an instance of Map.

        This method provides a convenient way to determine whether a given object is a map. It returns true if the object is an instance of Map, otherwise false.

        Example Usage

        
 System.out.println(MapUtils.isMap(new HashMap<>())); // true
 System.out.println(MapUtils.isMap(new ArrayList<>())); // false
 System.out.println(MapUtils.isMap(null)); // false
        Parameters:
        instance - the object to check, may be null
        Returns:
        true if the object is an instance of Map, otherwise false

      • isMap

        public static boolean isMap​(java.lang.Class<?> type)
        Checks if the specified class type is an implementation of Map.

        This method provides a convenient way to determine whether a given class implements the Map interface. It returns true if the class is assignable from Map, indicating that it is a map type.

        Example Usage

        
 System.out.println(MapUtils.isMap(HashMap.class)); // true
 System.out.println(MapUtils.isMap(List.class));    // false
 System.out.println(MapUtils.isMap(null));         // false
        Parameters:
        type - the class type to check, may be null
        Returns:
        true if the type is a Map implementation, otherwise false

      • isEmpty

        public static boolean isEmpty​(java.util.Map<?,​?> map)
        Checks if the specified map is either null or empty.

        A map is considered empty if it contains no key-value mappings. This method provides a null-safe way to check for emptiness.

        Example Usage

        
 Map<String, Integer> map1 = new HashMap<>();
 System.out.println(isEmpty(map1)); // true

 map1.put("one", 1);
 System.out.println(isEmpty(map1)); // false

 Map<String, Integer> map2 = null;
 System.out.println(isEmpty(map2)); // true
        Parameters:
        map - the map to check, may be null
        Returns:
        true if the map is null or empty, otherwise false

      • isNotEmpty

        public static boolean isNotEmpty​(java.util.Map<?,​?> map)
        Checks if the specified map is not empty and not null.

        This method provides a null-safe way to determine if a map contains one or more key-value mappings.

        Example Usage

        
 Map<String, Integer> map1 = new HashMap<>();
 System.out.println(isNotEmpty(map1)); // false

 map1.put("one", 1);
 System.out.println(isNotEmpty(map1)); // true

 Map<String, Integer> map2 = null;
 System.out.println(isNotEmpty(map2)); // false
        Parameters:
        map - the map to check, may be null
        Returns:
        true if the map is neither null nor empty, otherwise false

      • size

        public static int size​(java.util.Map<?,​?> map)
        Returns the size of the specified map, or 0 if the map is null.

        This method provides a null-safe way to obtain the size of a map. It avoids NullPointerException by returning zero when the input map is null.

        Example Usage

        
 Map<String, Integer> map1 = new HashMap<>();
 map1.put("one", 1);
 map1.put("two", 2);
 System.out.println(size(map1)); // Output: 2

 Map<String, Integer> map2 = null;
 System.out.println(size(map2)); // Output: 0

 Map<String, Integer> map3 = new HashMap<>();
 System.out.println(size(map3)); // Output: 0
        Parameters:
        map - the map whose size is to be returned, may be null
        Returns:
        the size of the map, or 0 if the map is null

      • of

        @Nonnull
@Immutable
public static <K,​V> java.util.Map<K,​V> of​(K key,
                                                      V value)
        Creates an immutable map containing a single key-value pair.

        This method provides a convenient way to create a small, read-only map with one entry. The resulting map is thread-safe and cannot be modified after creation.

        Example Usage

        
 Map<String, Integer> map = MapUtils.of("one", 1);
 System.out.println(map.get("one")); // Output: 1
        Type Parameters:
        K - the type of the key
        V - the type of the value
        Parameters:
        key - the key to be placed in the map
        value - the value to be associated with the key
        Returns:
        a new immutable map containing the specified key-value pair

      • of

        @Nonnull
@Immutable
public static <K,​V> java.util.Map<K,​V> of​(K key1,
                                                      V value1,
                                                      K key2,
                                                      V value2)
        Creates an immutable map containing two key-value pairs.

        This method provides a convenient way to create a small, read-only map with two entries. The resulting map is thread-safe and cannot be modified after creation.

        Example Usage

        
 Map<String, Integer> map = MapUtils.of("one", 1, "two", 2);
 System.out.println(map.get("one")); // Output: 1
 System.out.println(map.get("two")); // Output: 2
        Type Parameters:
        K - the type of the keys
        V - the type of the values
        Parameters:
        key1 - the first key to be placed in the map
        value1 - the value to be associated with the first key
        key2 - the second key to be placed in the map
        value2 - the value to be associated with the second key
        Returns:
        a new immutable map containing the specified key-value pairs

      • of

        @Nonnull
@Immutable
public static <K,​V> java.util.Map<K,​V> of​(K key1,
                                                      V value1,
                                                      K key2,
                                                      V value2,
                                                      K key3,
                                                      V value3)
        Creates an immutable map containing three key-value pairs.

        This method provides a convenient way to create a small, read-only map with three entries. The resulting map is thread-safe and cannot be modified after creation.

        Example Usage

        
 Map<String, Integer> map = MapUtils.of("one", 1, "two", 2, "three", 3);
 System.out.println(map.get("one"));   // Output: 1
 System.out.println(map.get("two"));   // Output: 2
 System.out.println(map.get("three")); // Output: 3
        Type Parameters:
        K - the type of the keys
        V - the type of the values
        Parameters:
        key1 - the first key to be placed in the map
        value1 - the value to be associated with the first key
        key2 - the second key to be placed in the map
        value2 - the value to be associated with the second key
        key3 - the third key to be placed in the map
        value3 - the value to be associated with the third key
        Returns:
        a new immutable map containing the specified key-value pairs

      • of

        @Nonnull
@Immutable
public static <K,​V> java.util.Map<K,​V> of​(K key1,
                                                      V value1,
                                                      K key2,
                                                      V value2,
                                                      K key3,
                                                      V value3,
                                                      K key4,
                                                      V value4)
        Creates an immutable map containing four key-value pairs.

        This method provides a convenient way to create a small, read-only map with four entries. The resulting map is thread-safe and cannot be modified after creation.

        Example Usage

        
 Map<String, Integer> map = MapUtils.of("one", 1, "two", 2, "three", 3, "four", 4);
 System.out.println(map.get("one"));   // Output: 1
 System.out.println(map.get("two"));   // Output: 2
 System.out.println(map.get("three")); // Output: 3
 System.out.println(map.get("four"));  // Output: 4
        Type Parameters:
        K - the type of the keys
        V - the type of the values
        Parameters:
        key1 - the first key to be placed in the map
        value1 - the value to be associated with the first key
        key2 - the second key to be placed in the map
        value2 - the value to be associated with the second key
        key3 - the third key to be placed in the map
        value3 - the value to be associated with the third key
        key4 - the fourth key to be placed in the map
        value4 - the value to be associated with the fourth key
        Returns:
        a new immutable map containing the specified key-value pairs

      • of

        @Nonnull
@Immutable
public static <K,​V> java.util.Map<K,​V> of​(K key1,
                                                      V value1,
                                                      K key2,
                                                      V value2,
                                                      K key3,
                                                      V value3,
                                                      K key4,
                                                      V value4,
                                                      K key5,
                                                      V value5)
        Creates an immutable map containing five key-value pairs.

        This method provides a convenient way to create a small, read-only map with five entries. The resulting map is thread-safe and cannot be modified after creation.

        Example Usage

        
 Map<String, Integer> map = MapUtils.of("one", 1, "two", 2, "three", 3, "four", 4, "five", 5);
 System.out.println(map.get("one"));   // Output: 1
 System.out.println(map.get("two"));   // Output: 2
 System.out.println(map.get("three")); // Output: 3
 System.out.println(map.get("four"));  // Output: 4
 System.out.println(map.get("five"));  // Output: 5
        Type Parameters:
        K - the type of the keys
        V - the type of the values
        Parameters:
        key1 - the first key to be placed in the map
        value1 - the value to be associated with the first key
        key2 - the second key to be placed in the map
        value2 - the value to be associated with the second key
        key3 - the third key to be placed in the map
        value3 - the value to be associated with the third key
        key4 - the fourth key to be placed in the map
        value4 - the value to be associated with the fourth key
        key5 - the fifth key to be placed in the map
        value5 - the value to be associated with the fifth key
        Returns:
        a new immutable map containing the specified key-value pairs

      • of

        @Nonnull
@Immutable
public static java.util.Map of​(java.lang.Object... values)
        Creates an immutable map from a varargs array of key-value pairs.

        This method provides a convenient way to create a small, read-only map with multiple entries. The arguments must be provided in consecutive key-value pairs. For example: MapUtils.of("key1", "value1", "key2", "value2"). The resulting map is thread-safe and cannot be modified after creation.

        Example Usage

        
 Map<String, Integer> map = MapUtils.of("one", 1, "two", 2);
 System.out.println(map.get("one")); // Output: 1
 System.out.println(map.get("two")); // Output: 2

 Map<String, String> emptyMap = MapUtils.of(); // returns an empty map
        Parameters:
        values - a varargs array of objects representing key-value pairs
        Returns:
        a new immutable map containing the specified key-value pairs
        Throws:
        java.lang.IllegalArgumentException - if the number of arguments is not even (indicating incomplete key-value pairs)

      • of

        @Nonnull
@Immutable
public static <K,​V> java.util.Map<K,​V> of​(java.util.Map.Entry<? extends K,​? extends V>... entries)
        Creates an immutable map from the provided array of Map.Entry objects.

        This method offers a convenient way to construct a small, read-only map using pre-defined entries. The resulting map is thread-safe and cannot be modified after creation.

        Example Usage

        
 Map<String, Integer> entry1 = new AbstractMap.SimpleEntry<>("one", 1);
 Map<String, Integer> entry2 = new AbstractMap.SimpleEntry<>("two", 2);
 Map<String, Integer> map = MapUtils.of(entry1, entry2);

 System.out.println(map.get("one")); // Output: 1
 System.out.println(map.get("two")); // Output: 2
        Type Parameters:
        K - the type of the keys
        V - the type of the values
        Parameters:
        entries - a varargs array of Map.Entry objects representing key-value pairs
        Returns:
        a new immutable map containing the specified entries
        Throws:
        java.lang.NullPointerException - if the entries array is null

      • ofMap

        @Nonnull
@Immutable
public static <K,​V> java.util.Map<K,​V> ofMap​(K key,
                                                         V value)
        Creates an immutable map containing a single key-value pair.

        This method provides a convenient way to create a small, read-only map with one entry. The resulting map is thread-safe and cannot be modified after creation.

        Example Usage

        
 Map<String, Integer> map = MapUtils.ofMap("one", 1);
 System.out.println(map.get("one")); // Output: 1
        Type Parameters:
        K - the type of the key
        V - the type of the value
        Parameters:
        key - the key to be placed in the map
        value - the value to be associated with the key
        Returns:
        a new immutable map containing the specified key-value pair

      • ofMap

        @Nonnull
@Immutable
public static java.util.Map ofMap​(java.lang.Object... keyValuePairs)
        Creates an immutable map from a varargs array of key-value pairs.

        This method provides a convenient way to create a small, read-only map with multiple entries. The arguments must be provided in consecutive key-value pairs. For example: MapUtils.ofMap("key1", "value1", "key2", "value2"). The resulting map is thread-safe and cannot be modified after creation.

        Example Usage

        
 Map<String, Integer> map = MapUtils.ofMap("one", 1, "two", 2);
 System.out.println(map.get("one")); // Output: 1
 System.out.println(map.get("two")); // Output: 2

 Map<String, String> emptyMap = MapUtils.ofMap(); // returns an empty map
        Parameters:
        keyValuePairs - a varargs array of objects representing key-value pairs
        Returns:
        a new immutable map containing the specified key-value pairs
        Throws:
        java.lang.IllegalArgumentException - if the number of arguments is not even (indicating incomplete key-value pairs)

      • newHashMap

        @Nonnull
public static <K,​V> java.util.HashMap<K,​V> newHashMap()
        Creates a new empty HashMap with the default initial capacity (16) and the default load factor (0.75).

        Example Usage

        
  HashMap<String, Integer> map = MapUtils.newHashMap();
  map.put("one", 1);
  System.out.println(map.get("one")); // Output: 1
        Type Parameters:
        K - the type of keys maintained by the returned map
        V - the type of mapped values
        Returns:
        a new empty HashMap instance
        See Also:
        HashMap()

      • newHashMap

        @Nonnull
public static <K,​V> java.util.HashMap<K,​V> newHashMap​(int initialCapacity)
        Creates a new HashMap with the specified initial capacity and the default load factor (0.75).

        Example Usage

        
 HashMap<String, Integer> map = MapUtils.newHashMap(10);
 map.put("one", 1);
 System.out.println(map.get("one")); // Output: 1
        Type Parameters:
        K - The type of keys maintained by the returned map.
        V - The type of mapped values.
        Parameters:
        initialCapacity - The initial capacity of the returned HashMap.
        Returns:
        A new HashMap instance with the specified initial capacity.
        See Also:
        HashMap(int)

      • newHashMap

        @Nonnull
public static <K,​V> java.util.HashMap<K,​V> newHashMap​(int initialCapacity,
                                                                  float loadFactor)
        Creates a new HashMap with the specified initial capacity and load factor.

        The initial capacity refers to the number of buckets in the hash table, while the load factor determines how full the hash table can get before its capacity is automatically increased.

        Example Usage

        
 HashMap<String, Integer> map = MapUtils.newHashMap(10, 0.75f);
 map.put("one", 1);
 System.out.println(map.get("one")); // Output: 1
        Type Parameters:
        K - The type of keys maintained by the returned map.
        V - The type of mapped values.
        Parameters:
        initialCapacity - The initial capacity of the returned HashMap.
        loadFactor - The load factor of the returned HashMap.
        Returns:
        A new HashMap instance with the specified initial capacity and load factor.
        See Also:
        HashMap(int, float)

      • newHashMap

        @Nonnull
public static <K,​V> java.util.HashMap<K,​V> newHashMap​(java.util.Map<? extends K,​? extends V> map)
        Creates a new HashMap with the same mappings as the specified map.

        This method provides a convenient way to create a new HashMap instance that contains all the key-value pairs from an existing map. The order of the entries in the resulting HashMap is not guaranteed, as HashMap does not maintain any specific order.

        Example Usage

        
 Map<String, Integer> originalMap = new HashMap<>();
 originalMap.put("one", 1);
 originalMap.put("two", 2);

 HashMap<String, Integer> copiedMap = MapUtils.newHashMap(originalMap);
 System.out.println(copiedMap.get("one")); // Output: 1
 System.out.println(copiedMap.get("two")); // Output: 2
        Type Parameters:
        K - The type of keys maintained by the returned map.
        V - The type of mapped values.
        Parameters:
        map - The initial map whose entries are to be copied into the new HashMap.
        Returns:
        A new HashMap instance initialized with the entries from the provided map.
        See Also:
        HashMap(Map)

      • newLinkedHashMap

        @Nonnull
public static <K,​V> java.util.LinkedHashMap<K,​V> newLinkedHashMap()
        Creates a new empty LinkedHashMap with the default initial capacity (16) and the default load factor (0.75).

        Example Usage

        
 LinkedHashMap<String, Integer> map = MapUtils.newLinkedHashMap();
 map.put("one", 1);
 System.out.println(map.get("one")); // Output: 1
        Type Parameters:
        K - the type of keys maintained by the returned map
        V - the type of mapped values
        Returns:
        a new empty LinkedHashMap instance
        See Also:
        LinkedHashMap()

      • newLinkedHashMap

        @Nonnull
public static <K,​V> java.util.LinkedHashMap<K,​V> newLinkedHashMap​(int initialCapacity)
        Creates a new LinkedHashMap with the specified initial capacity and the default load factor (0.75).

        Example Usage

        
 LinkedHashMap<String, Integer> map = MapUtils.newLinkedHashMap(10);
 map.put("one", 1);
 System.out.println(map.get("one")); // Output: 1
        Type Parameters:
        K - The type of keys maintained by the returned map.
        V - The type of mapped values.
        Parameters:
        initialCapacity - The initial capacity of the returned LinkedHashMap.
        Returns:
        A new LinkedHashMap instance with the specified initial capacity.
        See Also:
        LinkedHashMap(int)

      • newLinkedHashMap

        @Nonnull
public static <K,​V> java.util.LinkedHashMap<K,​V> newLinkedHashMap​(int initialCapacity,
                                                                              float loadFactor)
        Creates a new LinkedHashMap with the specified initial capacity and load factor.

        The initial capacity refers to the number of buckets in the hash table, while the load factor determines how full the hash table can get before its capacity is automatically increased.

        Example Usage

        
 LinkedHashMap<String, Integer> map = MapUtils.newLinkedHashMap(10, 0.75f);
 map.put("one", 1);
 System.out.println(map.get("one")); // Output: 1
        Type Parameters:
        K - The type of keys maintained by the returned map.
        V - The type of mapped values.
        Parameters:
        initialCapacity - The initial capacity of the returned LinkedHashMap.
        loadFactor - The load factor of the returned LinkedHashMap.
        Returns:
        A new LinkedHashMap instance with the specified initial capacity and load factor.
        See Also:
        LinkedHashMap(int, float)

      • newLinkedHashMap

        @Nonnull
public static <K,​V> java.util.LinkedHashMap<K,​V> newLinkedHashMap​(int initialCapacity,
                                                                              float loadFactor,
                                                                              boolean accessOrder)
        Creates a new LinkedHashMap with the specified initial capacity, load factor, and ordering mode.

        The initial capacity refers to the number of buckets in the hash table, while the load factor determines how full the hash table can get before its capacity is automatically increased. The accessOrder parameter determines the iteration ordering of the map:

        • If set to true, the map will be ordered by the access order (least recently accessed elements come first).
        • If set to false, the map will be ordered by insertion order.

        Example Usage

        
 LinkedHashMap<String, Integer> map = MapUtils.newLinkedHashMap(10, 0.75f, true);
 map.put("one", 1);
 map.put("two", 2);
 map.get("one"); // Accessing "one" may reorder the map depending on accessOrder
        Type Parameters:
        K - The type of keys maintained by the returned map.
        V - The type of mapped values.
        Parameters:
        initialCapacity - The initial capacity of the returned LinkedHashMap.
        loadFactor - The load factor of the returned LinkedHashMap.
        accessOrder - If true, the map will use access order for iteration; if false, insertion order.
        Returns:
        A new LinkedHashMap instance with the specified initial capacity, load factor, and ordering mode.
        See Also:
        LinkedHashMap(int, float, boolean)

      • newLinkedHashMap

        @Nonnull
public static <K,​V> java.util.LinkedHashMap<K,​V> newLinkedHashMap​(java.util.Map<? extends K,​? extends V> map)
        Creates a new LinkedHashMap with the same mappings as the specified map.

        This method provides a convenient way to create a new LinkedHashMap instance that contains all the key-value pairs from an existing map. The iteration order of the resulting map is based on insertion order unless the original map was an instance of LinkedHashMap with access order enabled.

        Example Usage

        
 Map<String, Integer> originalMap = new HashMap<>();
 originalMap.put("one", 1);
 originalMap.put("two", 2);

 LinkedHashMap<String, Integer> linkedMap = MapUtils.newLinkedHashMap(originalMap);
 System.out.println(linkedMap.get("one")); // Output: 1
 System.out.println(linkedMap.get("two")); // Output: 2
        Type Parameters:
        K - The type of keys maintained by the returned map.
        V - The type of mapped values.
        Parameters:
        map - The initial map whose entries are to be copied into the new LinkedHashMap.
        Returns:
        A new LinkedHashMap instance initialized with the entries from the provided map.
        See Also:
        LinkedHashMap(Map)

      • newConcurrentHashMap

        @Nonnull
public static <K,​V> java.util.concurrent.ConcurrentHashMap<K,​V> newConcurrentHashMap()
        Creates a new empty ConcurrentHashMap with the default initial capacity (16) and the default load factor (0.75), using the default concurrency level.

        Example Usage

        
  ConcurrentHashMap<String, Integer> map = MapUtils.newConcurrentHashMap();
  map.put("one", 1);
  System.out.println(map.get("one")); // Output: 1
        Type Parameters:
        K - the type of keys maintained by the returned map
        V - the type of mapped values
        Returns:
        a new empty ConcurrentHashMap instance
        See Also:
        ConcurrentHashMap()

      • newConcurrentHashMap

        @Nonnull
public static <K,​V> java.util.concurrent.ConcurrentHashMap<K,​V> newConcurrentHashMap​(int initialCapacity)
        Creates a new ConcurrentHashMap with the specified initial capacity and the default load factor (0.75), using the default concurrency level.

        This method provides a convenient way to initialize a ConcurrentHashMap with a known initial size, which can help reduce the frequency of rehash operations as elements are added.

        Example Usage

        
  ConcurrentHashMap<String, Integer> map = MapUtils.newConcurrentHashMap(10);
  map.put("one", 1);
  System.out.println(map.get("one")); // Output: 1
        Type Parameters:
        K - The type of keys maintained by the returned map.
        V - The type of mapped values.
        Parameters:
        initialCapacity - The initial capacity of the returned ConcurrentHashMap.
        Returns:
        A new ConcurrentHashMap instance with the specified initial capacity.
        See Also:
        ConcurrentHashMap(int)

      • newConcurrentHashMap

        @Nonnull
public static <K,​V> java.util.concurrent.ConcurrentHashMap<K,​V> newConcurrentHashMap​(int initialCapacity,
                                                                                                 float loadFactor)
        Creates a new ConcurrentHashMap with the specified initial capacity and load factor.

        The initial capacity refers to the number of buckets in the hash table, while the load factor determines how full the hash table can get before its capacity is automatically increased.

        Example Usage

        
  ConcurrentHashMap<String, Integer> map = MapUtils.newConcurrentHashMap(10, 0.75f);
  map.put("one", 1);
  System.out.println(map.get("one")); // Output: 1
        Type Parameters:
        K - The type of keys maintained by the returned map.
        V - The type of mapped values.
        Parameters:
        initialCapacity - The initial capacity of the returned ConcurrentHashMap.
        loadFactor - The load factor of the returned ConcurrentHashMap.
        Returns:
        A new ConcurrentHashMap instance with the specified initial capacity and load factor.
        See Also:
        ConcurrentHashMap(int, float)

      • newConcurrentHashMap

        @Nonnull
public static <K,​V> java.util.concurrent.ConcurrentHashMap<K,​V> newConcurrentHashMap​(java.util.Map<? extends K,​? extends V> map)
        Creates a new ConcurrentHashMap with the same mappings as the specified map.

        This method provides a convenient way to create a new ConcurrentHashMap instance that contains all the key-value pairs from an existing map. The returned map is thread-safe and suitable for concurrent access scenarios.

        Example Usage

        
 Map<String, Integer> originalMap = new HashMap<>();
 originalMap.put("one", 1);
 originalMap.put("two", 2);

 ConcurrentHashMap<String, Integer> concurrentMap = MapUtils.newConcurrentHashMap(originalMap);
 System.out.println(concurrentMap.get("one")); // Output: 1
 System.out.println(concurrentMap.get("two")); // Output: 2
        Type Parameters:
        K - The type of keys maintained by the returned map.
        V - The type of mapped values.
        Parameters:
        map - The initial map whose entries are to be copied into the new ConcurrentHashMap.
        Returns:
        A new ConcurrentHashMap instance initialized with the entries from the provided map.
        See Also:
        ConcurrentHashMap(Map)

      • newTreeMap

        @Nonnull
public static <K,​V> java.util.TreeMap<K,​V> newTreeMap()
        Creates a new empty TreeMap using natural ordering for the keys.

        This method provides a convenient way to create a TreeMap with default settings, ensuring that the keys will be sorted according to their natural ordering.

        Example Usage

        
 TreeMap<String, Integer> treeMap = MapUtils.newTreeMap();
 treeMap.put("banana", 2);
 treeMap.put("apple", 1);

 // Output will be ordered by keys: apple=1, banana=2
 for (Map.Entry<String, Integer> entry : treeMap.entrySet()) {
     System.out.println(entry.getKey() + "=" + entry.getValue());
 }
        Type Parameters:
        K - the type of keys maintained by the returned map
        V - the type of mapped values
        Returns:
        a new empty TreeMap instance with natural key ordering
        See Also:
        TreeMap()

      • newTreeMap

        @Nonnull
public static <K,​V> java.util.TreeMap<K,​V> newTreeMap​(java.util.Comparator<? super K> comparator)
        Creates a new empty TreeMap with the specified comparator to order the keys.

        This method provides a convenient way to create a TreeMap with a custom ordering strategy, allowing for flexible sorting based on the provided comparator.

        Example Usage

        
 Comparator<String> descendingOrder = Collections.reverseOrder();
 TreeMap<String, Integer> treeMap = MapUtils.newTreeMap(descendingOrder);
 treeMap.put("banana", 2);
 treeMap.put("apple", 1);

 // Output will be ordered by keys in descending order: banana=2, apple=1
 for (Map.Entry<String, Integer> entry : treeMap.entrySet()) {
     System.out.println(entry.getKey() + "=" + entry.getValue());
 }
        Type Parameters:
        K - The type of keys maintained by the returned map.
        V - The type of mapped values.
        Parameters:
        comparator - The comparator to use for ordering the keys in this map.
        Returns:
        A new empty TreeMap instance with the specified comparator.
        See Also:
        TreeMap(Comparator)

      • newTreeMap

        @Nonnull
public static <K,​V> java.util.TreeMap<K,​V> newTreeMap​(java.util.Map<? extends K,​? extends V> map)
        Creates a new TreeMap with the same mappings as the specified map.

        This method provides a convenient way to create a new TreeMap instance that contains all the key-value pairs from an existing map. The keys in the resulting TreeMap will be sorted according to their natural ordering, or by the comparator used by the provided map if it is a sorted map.

        Example Usage

        
 Map<String, Integer> originalMap = new HashMap<>();
 originalMap.put("banana", 2);
 originalMap.put("apple", 1);

 TreeMap<String, Integer> treeMap = MapUtils.newTreeMap(originalMap);

 // Output will be ordered by keys: apple=1, banana=2
 for (Map.Entry<String, Integer> entry : treeMap.entrySet()) {
     System.out.println(entry.getKey() + "=" + entry.getValue());
 }
        Type Parameters:
        K - The type of keys maintained by the returned map.
        V - The type of mapped values.
        Parameters:
        map - The initial map whose entries are to be copied into the new TreeMap.
        Returns:
        A new TreeMap instance initialized with the entries from the provided map.
        See Also:
        TreeMap(Map)

      • newTreeMap

        @Nonnull
public static <K,​V> java.util.TreeMap<K,​V> newTreeMap​(java.util.SortedMap<K,​? extends V> map)
        Creates a new TreeMap with the same mappings as the specified sorted map.

        This method provides a convenient way to create a new TreeMap instance that contains all the key-value pairs from an existing SortedMap. The keys in the resulting TreeMap will be sorted according to the comparator used by the provided map, or by natural ordering if the map uses natural ordering.

        Example Usage

        
 SortedMap<String, Integer> originalSortedMap = new TreeMap<>();
 originalSortedMap.put("banana", 2);
 originalSortedMap.put("apple", 1);

 TreeMap<String, Integer> treeMap = MapUtils.newTreeMap(originalSortedMap);

 // Output will be ordered by keys: apple=1, banana=2
 for (Map.Entry<String, Integer> entry : treeMap.entrySet()) {
     System.out.println(entry.getKey() + "=" + entry.getValue());
 }
        Type Parameters:
        K - The type of keys maintained by the returned map.
        V - The type of mapped values.
        Parameters:
        map - The initial sorted map whose entries are to be copied into the new TreeMap.
        Returns:
        A new TreeMap instance initialized with the entries from the provided sorted map.
        See Also:
        TreeMap(SortedMap)

      • shallowCloneMap

        @Nonnull
public static <K,​V> java.util.Map<K,​V> shallowCloneMap​(@Nonnull
                                                                   java.util.Map<K,​V> source)
        Performs a shallow clone of the provided map, creating a new map instance with the same key-value mappings.

        This method returns a new map of the most appropriate type based on the source map's implementation:

        • LinkedHashMap for insertion-ordered maps
        • ConcurrentSkipListMap for concurrent navigable maps
        • TreeMap for sorted maps
        • ConcurrentHashMap for concurrent maps
        • IdentityHashMap for identity-based maps
        • HashMap as the default fallback

        Example Usage

        
 Map<String, Integer> original = new HashMap<>();
 original.put("one", 1);
 original.put("two", 2);

 Map<String, Integer> cloned = MapUtils.shallowCloneMap(original);
 System.out.println(cloned.get("one")); // Output: 1
 System.out.println(cloned.get("two")); // Output: 2

 // The cloned map is independent from the original
 original.put("three", 3);
 System.out.println(cloned.containsKey("three")); // false
        Type Parameters:
        K - the type of keys maintained by the map
        V - the type of mapped values
        Parameters:
        source - the map to be shallow cloned, must not be null
        Returns:
        a new map containing the same key-value pairs as the source map
        Throws:
        java.lang.NullPointerException - if the source map is null

      • newFixedHashMap

        @Nonnull
public static <K,​V> java.util.Map<K,​V> newFixedHashMap​(int size)
        Creates a new empty HashMap with the specified initial capacity and a fixed load factor.

        This method is useful when you want to create a HashMap with a known initial size and use the predefined fixed load factor (1.0f), which helps in minimizing resizing operations.

        Example Usage

        
 Map<String, Integer> map = MapUtils.newFixedHashMap(10);
 map.put("one", 1);
 System.out.println(map.get("one")); // Output: 1
        Type Parameters:
        K - The type of keys maintained by the returned map.
        V - The type of mapped values.
        Parameters:
        size - The initial capacity of the returned HashMap.
        Returns:
        A new HashMap instance with the specified initial capacity and fixed load factor.
        See Also:
        HashMap(int, float)

      • newFixedLinkedHashMap

        @Nonnull
public static <K,​V> java.util.Map<K,​V> newFixedLinkedHashMap​(int size)
        Creates a new empty LinkedHashMap with the specified initial capacity and a fixed load factor.

        This method is useful when you want to create a LinkedHashMap with a known initial size and use the predefined fixed load factor (1.0f), which helps in minimizing resizing operations.

        Example Usage

        
 Map<String, Integer> map = MapUtils.newFixedLinkedHashMap(10);
 map.put("one", 1);
 System.out.println(map.get("one")); // Output: 1
        Type Parameters:
        K - The type of keys maintained by the returned map.
        V - The type of mapped values.
        Parameters:
        size - The initial capacity of the returned LinkedHashMap.
        Returns:
        A new LinkedHashMap instance with the specified initial capacity and fixed load factor.
        See Also:
        LinkedHashMap(int, float)

      • toFixedMap

        @Nonnull
@Immutable
public static <K,​V,​E> java.util.Map<K,​V> toFixedMap​(java.util.Collection<E> values,
                                                                      java.util.function.Function<E,​java.util.Map.Entry<K,​V>> entryMapper)
        Converts a collection of elements into an immutable map using the provided function to extract key-value pairs.

        This method creates a fixed-size, immutable map from the given collection by applying the entryMapper function to each element to obtain key-value mappings. The resulting map is thread-safe and cannot be modified.

        Example Usage

        
 List<User> users = Arrays.asList(new User("1", "Alice"), new User("2", "Bob"));

 Map<String, String> userMap = MapUtils.toFixedMap(users, user ->
     MapUtils.ofEntry(user.getId(), user.getName()));

 System.out.println(userMap.get("1")); // Output: Alice
 System.out.println(userMap.get("2")); // Output: Bob
        Type Parameters:
        K - the type of keys maintained by the returned map
        V - the type of mapped values
        E - the type of elements in the input collection
        Parameters:
        values - the collection of elements to convert into a map, must not be null
        entryMapper - the function that maps each element to a key-value pair (Map.Entry), must not be null
        Returns:
        a new immutable map containing the key-value pairs derived from the input collection
        Throws:
        java.lang.NullPointerException - if values or entryMapper is null

      • ofEntry

        @Nonnull
public static <K,​V> java.util.Map.Entry<K,​V> ofEntry​(K key,
                                                                 V value)
        Creates an immutable Map.Entry with the specified key and value.

        This method returns a fixed entry implementation that does not allow modification of its contents. The returned entry is suitable for use in read-only contexts, such as populating immutable maps.

        Example Usage

        
 Map.Entry<String, Integer> entry = MapUtils.ofEntry("one", 1);
 System.out.println(entry.getKey());   // Output: one
 System.out.println(entry.getValue()); // Output: 1

 // Using in combination with other utilities to build a map:
 Map<String, Integer> map = MapUtils.of(
     MapUtils.ofEntry("apple", 3),
     MapUtils.ofEntry("banana", 5)
 );
 System.out.println(map.get("apple"));  // Output: 3
 System.out.println(map.get("banana")); // Output: 5
        Type Parameters:
        K - the type of the key
        V - the type of the value
        Parameters:
        key - the key to be stored in the entry
        value - the value to be associated with the key
        Returns:
        a new immutable map entry containing the specified key and value
        See Also:
        DefaultEntry

      • immutableEntry

        @Nonnull
@Immutable
public static <K,​V> java.util.Map.Entry<K,​V> immutableEntry​(K key,
                                                                        V value)
        Creates an immutable Map.Entry with the specified key and value.

        This method returns a read-only entry implementation that does not allow modification of its contents. It is suitable for use in read-only contexts, such as populating immutable maps.

        Example Usage

        
 Map.Entry<String, Integer> entry = MapUtils.immutableEntry("one", 1);
 System.out.println(entry.getKey());   // Output: one
 System.out.println(entry.getValue()); // Output: 1

 // Attempting to modify the entry will throw an exception:
 // entry.setValue(2); // throws UnsupportedOperationException
        Type Parameters:
        K - the type of the key
        V - the type of the value
        Parameters:
        key - the key to be stored in the entry
        value - the value to be associated with the key
        Returns:
        a new immutable map entry containing the specified key and value
        See Also:
        ImmutableEntry

      • flattenMap

        @Nonnull
@Immutable
public static java.util.Map<java.lang.String,​java.lang.Object> flattenMap​(java.util.Map<java.lang.String,​java.lang.Object> map)
        Flattens a nested map of properties into a single-level map.

        If the input map is empty or null, the same map instance is returned.

        For example, given the following input: 

        
 {
   "a": "1",
   "b": {
     "c": "2",
     "d": {
       "e": "3"
     }
   }
 }
        The resulting flattened map would be: 
        
 {
   "a": "1",
   "b.c": "2",
   "b.d.e": "3"
 }
        Parameters:
        map - The map containing potentially nested properties to be flattened.
        Returns:
        A new unmodifiable map with all properties flattened to a single level.

      • nestedMap

        @Nonnull
@Immutable
public static java.util.Map<java.lang.String,​java.lang.Object> nestedMap​(java.util.Map<java.lang.String,​java.lang.Object> map)
        Converts a flat map with dot-separated keys into a nested map structure.

        This method takes a map where keys represent hierarchical paths (e.g., "a.b.c") and transforms it into a nested map structure where each level of the hierarchy becomes a separate map. This is particularly useful for configuration properties or data that needs to be organized in a tree-like structure.

        Example Usage

        
 Map<String, Object> flatMap = new LinkedHashMap<>();
 flatMap.put("a.b.1", "value1");
 flatMap.put("a.b.2", "value2");
 flatMap.put("a.c", "value3");
 flatMap.put("d", "value4");

 Map<String, Object> nested = MapUtils.nestedMap(flatMap);
 // Result:
 // {
 //   "a": {
 //     "b": {
 //       "1": "value1",
 //       "2": "value2"
 //     },
 //     "c": "value3"
 //   },
 //   "d": "value4"
 // }
        Parameters:
        map - the flat map to be converted into a nested structure, may be null
        Returns:
        a new map with nested structure, or an empty map if input is null or empty