# Class: com.pnfsoftware.jeb.util.collect.Maps Utility methods for [maps](Map). ## Constructor: Maps ## Static Method: addMulti - parameter: `map`, type: `java.util.Map>` - parameter: `key`, type: `K` - return type: `java.util.List` Description: Add a list bucket for the key in the provided multi\-map. If no list of values exists for the key, a new `ArrayList` is created with an initial capacity of one. parameter: K: key type parameter: V: value type parameter: map: multi\-map to update parameter: key: key whose bucket should be created or retrieved return: the list for the provided key ## Static Method: collectMulti - parameter: `map`, type: `java.util.Map` - return type: `java.util.Collection` Description: Collect the values of a multi\-map. parameter: K: key type parameter: V: value type stored in the collection values parameter: C: collection type, mapped by the keys parameter: map: a map of key\-collections return: the collection of values stored in the multi\-map ## Static Method: createSortedMapByValue - parameter: `map`, type: `java.util.Map` - parameter: `ascending`, type: `boolean` - return type: `java.util.LinkedHashMap` Description: Sort a map by its values. The values must be [Comparable](Comparable) objects. parameter: map: a map; it must not contain null values parameter: ascending: true to sort by ascending order, false to sort by descending order return: a map ordered by its values; this map can be modified without impacting the original map's structure ## Static Method: get - parameter: `map`, type: `java.util.Map` - parameter: `key`, type: `K` - return type: `V` Description: Get a value from a potentially null map. parameter: map: optional map parameter: key: key return: the value, null if the map is null or contains a key pointing to a null value ## Static Method: get - parameter: `map`, type: `java.util.Map` - parameter: `key`, type: `K` - parameter: `safeValue`, type: `V` - return type: `V` Description: Get a value from a potentially null map. parameter: map: optional map parameter: key: key parameter: safeValue: value returned if the map is null or does not contain the provided key return: the value \- note: the returned value can be null if the key is present, but points to a null value ## Static Method: getSortedEntriesByValue - parameter: `map`, type: `java.util.Map` - return type: `java.util.List>` Description: Retrieve a list of sorted \(key,value\) pairs from the provided map, sorted by ascending values. parameter: K: key type parameter: V: value type, which must implement [Comparable](Comparable) parameter: map: the input map \(preferably not containing null values\) return: a list of sorted entries \(the entries are backed the provided map: modifying them will modify the map\); entries mapping to null values will be last in the list ## Static Method: getSortedEntriesByValue - parameter: `map`, type: `java.util.Map` - parameter: `descending`, type: `boolean` - return type: `java.util.List>` Description: Retrieve a list of sorted \(key,value\) pairs from the provided map, sorted by values. parameter: K: key type parameter: V: value type, which must implement [Comparable](Comparable) parameter: map: the input map \(should not contain null values\) parameter: descending: if true, the list is sorted by descending values instead of ascending values return: a list of sorted entries \(the entries are backed the provided map: modifying them will modify the map\); entries mapping to null values will be last in the list ## Static Method: getSortedValues - parameter: `map`, type: `java.util.Map` - parameter: `ascending`, type: `boolean` - return type: `java.util.List` Description: Retrieve the values of a map, sorted by natural ascending or descending order. The values must be [Comparable](Comparable) objects. parameter: map: a map; it must not contain null values parameter: ascending: true to sort by ascending order, false to sort by descending order return: a list of sorted values; the list can be modified without impacting the map's structure ## Static Method: getSortedValues - parameter: `map`, type: `java.util.Map` - return type: `java.util.List` Description: Retrieve the values of a map, sorted by natural ascending. The values must be [Comparable](Comparable) objects. parameter: map: a map; it must not contain null values return: a list of sorted values; the list can be modified without impacting the map's structure ## Static Method: putMulti - parameter: `map`, type: `java.util.Map>` - parameter: `key`, type: `K` - parameter: `value`, type: `V` - return type: `java.util.List` Description: Add a key\-value entry to the provided multi\-map. If no list of values exists for the key, a new `ArrayList` is created with an initial capacity of one \(to accommodate the addition of the value\). Equivalent to [#putMulti(Map, Object, Object, Supplier)](#putMulti(Map, Object, Object, Supplier)) with supplier being `ArrayList::new`. parameter: K: key type parameter: V: value type parameter: map: multi\-map to update parameter: key: key parameter: value: value to add return: the list for the provided key ## Static Method: putMulti - parameter: `map`, type: `java.util.Map>` - parameter: `key`, type: `K` - parameter: `values`, type: `java.util.Collection` - return type: `java.util.List` Description: Add a collection of key\-value entries to the provided multi\-map. If no list of values exists for the key, a new `ArrayList` is created. parameter: K: key type parameter: V: value type parameter: map: multi\-map to update parameter: key: key parameter: values: values to add return: the list for the provided key ## Static Method: putMulti - parameter: `map`, type: `java.util.Map` - parameter: `key`, type: `K` - parameter: `value`, type: `V` - parameter: `supplier`, type: `java.util.function.Supplier` - return type: `boolean` Description: Add a key\-value entry to the provided multi\-map. If no list of values exists for the key, a new list is created using the provided listFactory parameter. parameter: K: key type parameter: V: value type parameter: C: collection\-of\-value type parameter: map: the map parameter: key: the key parameter: value: value to be added to the collection mapped for key parameter: supplier: collection factory if no collection exists and is mapped for the provided key return: true if the collection to which the value was added changed \(i.e., same semantic as [Collection#add(Object)](Collection#add(Object))\) ## Static Method: putNoOverwrite - parameter: `map`, type: `java.util.Map` - parameter: `preferredKey`, type: `java.lang.String` - parameter: `value`, type: `V` - return type: `java.lang.String` Description: Insert a value to a string\-key'ed map with guarantee that no existing key\-value pair will be overwritten. parameter: map: target map parameter: preferredKey: the preferred key for insertion parameter: value: value to insert return: the actual key that was generated for insertion \(may be different than the Preferred if using the preferred would lead to an existing mapping to be overwritten\) ## Static Method: removeAll - parameter: `map`, type: `java.util.Map` - parameter: `keys`, type: `java.util.Collection` - return type: `boolean` Description: Remove all entries whose keys are in the provided collection. parameter: K: key type parameter: map: map to modify parameter: keys: keys to remove return: true if the map was modified ## Static Method: removeForValue - parameter: `map`, type: `java.util.Map` - parameter: `v`, type: `V` - parameter: `useReferenceEquality`, type: `boolean` - return type: `int` Description: Remove entries that map to the provided value. parameter: K: key type parameter: V: value type parameter: map: map parameter: v: a non\-null value parameter: useReferenceEquality: if true, values are compared using ==; else, they are compared using equals\(\) return: the number of entries removed ## Static Method: removeMulti - parameter: `map`, type: `java.util.Map` - parameter: `key`, type: `K` - parameter: `value`, type: `V` - return type: `boolean` Description: Remove a key\-value stored in a multi\-map. parameter: K: key type parameter: V: value type parameter: C: collection\-of\-value type parameter: map: a map of key\-collections parameter: key: key parameter: value: value to remove return: true if a key\-value was removed, false otherwise ## Static Method: retainAll - parameter: `map`, type: `java.util.Map` - parameter: `keys`, type: `java.util.Collection` - return type: `boolean` Description: Retain only entries whose keys are in the provided collection. parameter: K: key type parameter: map: map to modify parameter: keys: keys to retain return: true if the map was modified ## Static Method: toMap - parameter: `key`, type: `K` - parameter: `value`, type: `V` - return type: `java.util.HashMap` Description: Build a [HashMap](HashMap) containing 1 element \(key, value\). parameter: key: key parameter: value: value associated to key return: a new hash map ## Static Method: toMap - parameter: `key`, type: `K` - parameter: `value`, type: `V` - parameter: `key2`, type: `K` - parameter: `value2`, type: `V` - return type: `java.util.HashMap` Description: Build a [HashMap](HashMap) containing 2 elements \(key, value\). parameter: key: key parameter: value: value associated to key parameter: key2: 2nd key parameter: value2: value associated to 2nd key return: a new hash map ## Static Method: toMap - parameter: `key`, type: `K` - parameter: `value`, type: `V` - parameter: `key2`, type: `K` - parameter: `value2`, type: `V` - parameter: `key3`, type: `K` - parameter: `value3`, type: `V` - return type: `java.util.HashMap` Description: Build a [HashMap](HashMap) containing 3 elements \(key, value\). parameter: key: key parameter: value: value associated to key parameter: key2: 2nd key parameter: value2: value associated to 2nd key parameter: key3: 3rd key parameter: value3: value associated to 3rd key return: a new hash map ## Static Method: toMap - parameter: `key`, type: `K` - parameter: `value`, type: `V` - parameter: `c`, type: `java.lang.Class` - return type: `java.util.Map` Description: Build a map containing 1 element \(key, value\). parameter: key: key parameter: value: value associated to key parameter: c: optional requested map type; use null to obtain a [HashMap](HashMap) return: a new map