# Class: com.pnfsoftware.jeb.util.collect.Maps

Utility methods for [maps](Map).

## Constructor: Maps


## Static Method: addMulti
- parameter: `map`, type: `java.util.Map<K,java.util.List<V>>`
- parameter: `key`, type: `K`
- return type: `java.util.List<V>`

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<K,C>`
- return type: `java.util.Collection<V>`

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<K,V>`
- parameter: `ascending`, type: `boolean`
- return type: `java.util.LinkedHashMap<K,V>`

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<K,V>`
- 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<K,V>`
- 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<K,V>`
- return type: `java.util.List<java.util.Map.Entry<K,V>>`

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<K,V>`
- parameter: `descending`, type: `boolean`
- return type: `java.util.List<java.util.Map.Entry<K,V>>`

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<K,V>`
- parameter: `ascending`, type: `boolean`
- return type: `java.util.List<V>`

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<K,V>`
- return type: `java.util.List<V>`

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<K,java.util.List<V>>`
- parameter: `key`, type: `K`
- parameter: `value`, type: `V`
- return type: `java.util.List<V>`

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<K,java.util.List<V>>`
- parameter: `key`, type: `K`
- parameter: `values`, type: `java.util.Collection<V>`
- return type: `java.util.List<V>`

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<K,C>`
- parameter: `key`, type: `K`
- parameter: `value`, type: `V`
- parameter: `supplier`, type: `java.util.function.Supplier<C>`
- 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<java.lang.String,V>`
- 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<K,?>`
- parameter: `keys`, type: `java.util.Collection<? extends K>`
- 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<K,V>`
- 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<K,C>`
- 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<K,?>`
- parameter: `keys`, type: `java.util.Collection<? extends K>`
- 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<K,V>`

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<K,V>`

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<K,V>`

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<? extends java.util.Map>`
- return type: `java.util.Map<K,V>`

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

