Package com.landawn.abacus.util

Class ListMultimap<K,E>

java.lang.Object

com.landawn.abacus.util.Multimap<K,E,List<E>>

com.landawn.abacus.util.ListMultimap<K,E>

Type Parameters:

K - the key type

E -

All Implemented Interfaces:

Iterable<Map.Entry<K,List<E>>>

public final class ListMultimap<K,E>
extends Multimap<K,E,List<E>>

See Also:

• CommonUtil.newListMultimap()
• CommonUtil.newListMultimap(Class, Class)
• CommonUtil.newListMultimap(Supplier, Supplier)

Method Summary

Modifier and Type	Method	Description
static <K, E> ListMultimap<K,E>	concat(Collection<? extends Map<? extends K,? extends E>> c)	Creates a new instance of ListMultimap by concatenating the key-value pairs from a collection of maps.
static <K, E> ListMultimap<K,E>	concat(Map<? extends K,? extends E> a, Map<? extends K,? extends E> b)	Creates a new instance of ListMultimap by concatenating the key-value pairs from two specified maps.
static <K, E> ListMultimap<K,E>	concat(Map<? extends K,? extends E> a, Map<? extends K,? extends E> b, Map<? extends K,? extends E> c)	Creates a new instance of ListMultimap by concatenating the key-value pairs from three specified maps.
ListMultimap<K,E>	copy()	Returns a new ListMultimap and copies all key-value pairs from this ListMultimap to the new one.
static <T, K> ListMultimap<K,T>	create(Collection<? extends T> c, Function<? super T,? extends K> keyMapper)	Creates a new instance of ListMultimap from a given collection and a key mapper function.
static <T, K, E> ListMultimap<K,E>	create(Collection<? extends T> c, Function<? super T,? extends K> keyMapper, Function<? super T,? extends E> valueExtractor)	Creates a new instance of ListMultimap from a given collection, a key mapper function, and a value extractor function.
static <K, E> ListMultimap<K,E>	create(Map<? extends K,? extends E> map)	Creates a new instance of ListMultimap with the key-value pairs from the specified map.
ListMultimap<K,E>	filter(BiPredicate<? super K,? super List<E>> filter)	Filters the ListMultimap based on the provided key-value pair filter.
ListMultimap<K,E>	filterByKey(Predicate<? super K> filter)	Filters the ListMultimap based on the provided key filter.
ListMultimap<K,E>	filterByValue(Predicate<? super List<E>> filter)	Filters the ListMultimap based on the provided value filter.
E	getFirst(K key)	Return the first value for the given key, or null if no value is found.
E	getFirstOrDefault(K key, E defaultValue)	Return the first value for the given key, or defaultValue if no value is found.
ListMultimap<E,K>	inverse()	Inverts the ListMultimap, swapping keys with values.
static <K, E> ListMultimap<K,E>	of(K k1, E v1)	Creates a new instance of ListMultimap with one key-value pair.
static <K, E> ListMultimap<K,E>	of(K k1, E v1, K k2, E v2)	Creates a new instance of ListMultimap with two key-value pairs.
static <K, E> ListMultimap<K,E>	of(K k1, E v1, K k2, E v2, K k3, E v3)	Creates a new instance of ListMultimap with three key-value pairs.
static <K, E> ListMultimap<K,E>	of(K k1, E v1, K k2, E v2, K k3, E v3, K k4, E v4)	Creates a new instance of ListMultimap with four key-value pairs.
static <K, E> ListMultimap<K,E>	of(K k1, E v1, K k2, E v2, K k3, E v3, K k4, E v4, K k5, E v5)	Creates a new instance of ListMultimap with five key-value pairs.
static <K, E> ListMultimap<K,E>	of(K k1, E v1, K k2, E v2, K k3, E v3, K k4, E v4, K k5, E v5, K k6, E v6)	Creates a new instance of ListMultimap with six key-value pairs.
static <K, E> ListMultimap<K,E>	of(K k1, E v1, K k2, E v2, K k3, E v3, K k4, E v4, K k5, E v5, K k6, E v6, K k7, E v7)	Creates a new instance of ListMultimap with seven key-value pairs.
ImmutableMap<K,ImmutableList<E>>	toImmutableMap()	Converts the current ListMultimap into an ImmutableMap.
ImmutableMap<K,ImmutableList<E>>	toImmutableMap(IntFunction<? extends Map<K,ImmutableList<E>>> mapSupplier)	Converts the current ListMultimap into an ImmutableMap using a provided map supplier.
static <K, E, V extends List<E>> ListMultimap<K,E>	wrap(Map<K,V> map)	Wraps the provided map into a ListMultimap.
static <K, E, V extends List<E>> ListMultimap<K,E>	wrap(Map<K,V> map, Supplier<? extends V> valueSupplier)	Wraps the provided map into a ListMultimap with a custom list supplier.

Methods inherited from class com.landawn.abacus.util.Multimap

accept, acceptIfNotEmpty, apply, applyIfNotEmpty, clear, compute, computeIfAbsent, computeIfPresent, contains, containsAll, containsKey, containsValue, entrySet, entryStream, equals, flatForEach, flatForEachValue, flatValues, flatValues, forEach, forEachKey, forEachValue, get, getOrDefault, hashCode, inverse, isEmpty, iterator, keySet, merge, merge, put, put, putIfAbsent, putIfKeyAbsent, putMany, putMany, putMany, putManyIfKeyAbsent, removeAll, removeAllIf, removeAllIf, removeMany, removeMany, removeMany, removeManyIf, removeManyIf, removeOne, removeOne, removeOneIf, removeOneIf, replaceAll, replaceAllWithOne, replaceAllWithOneIf, replaceAllWithOneIf, replaceManyWithOne, replaceManyWithOneIf, replaceManyWithOneIf, replaceOne, replaceOneIf, replaceOneIf, size, stream, toMap, toMap, toMultiset, toString, totalCountOfValues, values

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.lang.Iterable

forEach, spliterator

Method Details

of

public static <K,
E> ListMultimap<K,E> of(K k1,
 E v1)

Creates a new instance of ListMultimap with one key-value pair.

Type Parameters:

K - the type of the key

E - the type of the value

Parameters:

k1 - the key of the key-value pair

v1 - the value of the key-value pair

Returns:

a new instance of ListMultimap with the specified key-value pair

of

public static <K,
E> ListMultimap<K,E> of(K k1,
 E v1,
 K k2,
 E v2)

Creates a new instance of ListMultimap with two key-value pairs.

Type Parameters:

K - the type of the keys

E - the type of the values

Parameters:

k1 - the first key of the key-value pairs

v1 - the first value of the key-value pairs

k2 - the second key of the key-value pairs

v2 - the second value of the key-value pairs

Returns:

a new instance of ListMultimap with the specified key-value pairs

of

public static <K,
E> ListMultimap<K,E> of(K k1,
 E v1,
 K k2,
 E v2,
 K k3,
 E v3)

Creates a new instance of ListMultimap with three key-value pairs.

Type Parameters:

K - the type of the keys

E - the type of the values

Parameters:

k1 - the first key of the key-value pairs

v1 - the first value of the key-value pairs

k2 - the second key of the key-value pairs

v2 - the second value of the key-value pairs

k3 - the third key of the key-value pairs

v3 - the third value of the key-value pairs

Returns:

a new instance of ListMultimap with the specified key-value pairs

of

public static <K,
E> ListMultimap<K,E> of(K k1,
 E v1,
 K k2,
 E v2,
 K k3,
 E v3,
 K k4,
 E v4)

Creates a new instance of ListMultimap with four key-value pairs.

Type Parameters:

K - the type of the keys

E - the type of the values

Parameters:

k1 - the first key of the key-value pairs

v1 - the first value of the key-value pairs

k2 - the second key of the key-value pairs

v2 - the second value of the key-value pairs

k3 - the third key of the key-value pairs

v3 - the third value of the key-value pairs

k4 - the fourth key of the key-value pairs

v4 - the fourth value of the key-value pairs

Returns:

a new instance of ListMultimap with the specified key-value pairs

of

public static <K,
E> ListMultimap<K,E> of(K k1,
 E v1,
 K k2,
 E v2,
 K k3,
 E v3,
 K k4,
 E v4,
 K k5,
 E v5)

Creates a new instance of ListMultimap with five key-value pairs.

Type Parameters:

K - the type of the keys

E - the type of the values

Parameters:

k1 - the first key of the key-value pairs

v1 - the first value of the key-value pairs

k2 - the second key of the key-value pairs

v2 - the second value of the key-value pairs

k3 - the third key of the key-value pairs

v3 - the third value of the key-value pairs

k4 - the fourth key of the key-value pairs

v4 - the fourth value of the key-value pairs

k5 - the fifth key of the key-value pairs

v5 - the fifth value of the key-value pairs

Returns:

a new instance of ListMultimap with the specified key-value pairs

of

public static <K,
E> ListMultimap<K,E> of(K k1,
 E v1,
 K k2,
 E v2,
 K k3,
 E v3,
 K k4,
 E v4,
 K k5,
 E v5,
 K k6,
 E v6)

Creates a new instance of ListMultimap with six key-value pairs.

Type Parameters:

K - the type of the keys

E - the type of the values

Parameters:

k1 - the first key of the key-value pairs

v1 - the first value of the key-value pairs

k2 - the second key of the key-value pairs

v2 - the second value of the key-value pairs

k3 - the third key of the key-value pairs

v3 - the third value of the key-value pairs

k4 - the fourth key of the key-value pairs

v4 - the fourth value of the key-value pairs

k5 - the fifth key of the key-value pairs

v5 - the fifth value of the key-value pairs

k6 - the sixth key of the key-value pairs

v6 - the sixth value of the key-value pairs

Returns:

a new instance of ListMultimap with the specified key-value pairs

of

public static <K,
E> ListMultimap<K,E> of(K k1,
 E v1,
 K k2,
 E v2,
 K k3,
 E v3,
 K k4,
 E v4,
 K k5,
 E v5,
 K k6,
 E v6,
 K k7,
 E v7)

Creates a new instance of ListMultimap with seven key-value pairs.

Type Parameters:

K - the type of the keys

E - the type of the values

Parameters:

k1 - the first key of the key-value pairs

v1 - the first value of the key-value pairs

k2 - the second key of the key-value pairs

v2 - the second value of the key-value pairs

k3 - the third key of the key-value pairs

v3 - the third value of the key-value pairs

k4 - the fourth key of the key-value pairs

v4 - the fourth value of the key-value pairs

k5 - the fifth key of the key-value pairs

v5 - the fifth value of the key-value pairs

k6 - the sixth key of the key-value pairs

v6 - the sixth value of the key-value pairs

k7 - the seventh key of the key-value pairs

v7 - the seventh value of the key-value pairs

Returns:

a new instance of ListMultimap with the specified key-value pairs

create

public static <K,
E> ListMultimap<K,E> create(Map<? extends K,? extends E> map)

Creates a new instance of ListMultimap with the key-value pairs from the specified map.

Type Parameters:

K - the type of the keys

E - the type of the values

Parameters:

map - the map containing the key-value pairs to be added to the new ListMultimap

Returns:

a new instance of ListMultimap with the key-value pairs from the specified map

create

public static <T,
K> ListMultimap<K,T> create(Collection<? extends T> c,
 Function<? super T,? extends K> keyMapper)
                                       throws IllegalArgumentException

Creates a new instance of ListMultimap from a given collection and a key mapper function.

Type Parameters:

T - the type of the elements in the collection

K - the type of the keys in the ListMultimap

Parameters:

c - the collection of elements to be added to the ListMultimap

keyMapper - the function to generate keys for the ListMultimap

Returns:

a new instance of ListMultimap with keys and values from the specified collection

Throws:

IllegalArgumentException - if the keyMapper is null

create

public static <T,
K,
E> ListMultimap<K,E> create(Collection<? extends T> c,
 Function<? super T,? extends K> keyMapper,
 Function<? super T,? extends E> valueExtractor)
                                          throws IllegalArgumentException

Creates a new instance of ListMultimap from a given collection, a key mapper function, and a value extractor function.

Type Parameters:

T - the type of the elements in the collection

K - the type of the keys in the ListMultimap

E - the type of the values in the ListMultimap

Parameters:

c - the collection of elements to be added to the ListMultimap

keyMapper - the function to generate keys for the ListMultimap

valueExtractor - the function to extract values for the ListMultimap

Returns:

a new instance of ListMultimap with keys and values from the specified collection

Throws:

IllegalArgumentException - if the keyMapper or valueExtractor is null

concat

public static <K,
E> ListMultimap<K,E> concat(Map<? extends K,? extends E> a,
 Map<? extends K,? extends E> b)

Creates a new instance of ListMultimap by concatenating the key-value pairs from two specified maps.

Type Parameters:

K - the type of the keys

E - the type of the values

Parameters:

a - the first map containing the key-value pairs to be added to the new ListMultimap

b - the second map containing the key-value pairs to be added to the new ListMultimap

Returns:

a new instance of ListMultimap with the key-value pairs from the specified maps

concat

public static <K,
E> ListMultimap<K,E> concat(Map<? extends K,? extends E> a,
 Map<? extends K,? extends E> b,
 Map<? extends K,? extends E> c)

Creates a new instance of ListMultimap by concatenating the key-value pairs from three specified maps.

Type Parameters:

K - the type of the keys

E - the type of the values

Parameters:

a - the first map containing the key-value pairs to be added to the new ListMultimap

b - the second map containing the key-value pairs to be added to the new ListMultimap

c - the third map containing the key-value pairs to be added to the new ListMultimap

Returns:

a new instance of ListMultimap with the key-value pairs from the specified maps

concat

public static <K,
E> ListMultimap<K,E> concat(Collection<? extends Map<? extends K,? extends E>> c)

Creates a new instance of ListMultimap by concatenating the key-value pairs from a collection of maps.

Type Parameters:

K - the type of the keys

E - the type of the values

Parameters:

c - the collection of maps containing the key-value pairs to be added to the new ListMultimap

Returns:

a new instance of ListMultimap with the key-value pairs from the specified collection of maps

wrap

@Beta
public static <K,
E,
V extends List<E>>
ListMultimap<K,E> wrap(Map<K,V> map)
                throws IllegalArgumentException

Wraps the provided map into a ListMultimap. Changes to the specified map will be reflected in the ListMultimap and vice versa.

Type Parameters:

K - the type of the keys in the map

E - the type of the elements in the list

V - the type of the list

Parameters:

map - the map to be wrapped into a ListMultimap

Returns:

a new instance of ListMultimap backed by the provided map.

Throws:

IllegalArgumentException - if the provided map is null

wrap

@Beta
public static <K,
E,
V extends List<E>>
ListMultimap<K,E> wrap(Map<K,V> map,
 Supplier<? extends V> valueSupplier)
                throws IllegalArgumentException

Wraps the provided map into a ListMultimap with a custom list supplier. Changes to the specified map will be reflected in the ListMultimap and vice versa.

Type Parameters:

K - the type of the keys in the map

E - the type of the elements in the list

V - the type of the list

Parameters:

map - the map to be wrapped into a ListMultimap

valueSupplier - the supplier that provides the list to be used as the value collection

Returns:

a new instance of ListMultimap backed by the provided map.

Throws:

IllegalArgumentException - if the provided map or valueSupplier is null

getFirst

public E getFirst(K key)

Return the first value for the given key, or null if no value is found.

Overrides:

getFirst in class Multimap<K,E,List<E>>

Parameters:

key - The key whose associated value is to be returned.

Returns:

The first value associated with the specified key, or null if the key has no associated values.

getFirstOrDefault

public E getFirstOrDefault(K key,
 E defaultValue)

Return the first value for the given key, or defaultValue if no value is found.

Overrides:

getFirstOrDefault in class Multimap<K,E,List<E>>

Parameters:

key - The key whose associated value is to be returned.

defaultValue - The default value to return if no value is associated with the key.

Returns:

The first value associated with the specified key, or the default value if the key has no associated values.

inverse

public ListMultimap<E,K> inverse()

Inverts the ListMultimap, swapping keys with values.

Returns:

a new instance of ListMultimap where the original keys are now values and the original values are now keys

copy

public ListMultimap<K,E> copy()

Returns a new ListMultimap and copies all key-value pairs from this ListMultimap to the new one. The new ListMultimap has the same structural and hash characteristics as this one.

Overrides:

copy in class Multimap<K,E,List<E>>

Returns:

A new ListMultimap containing all the key-value pairs of this ListMultimap.

See Also:

• Multimap.putMany(Multimap)

filterByKey

public ListMultimap<K,E> filterByKey(Predicate<? super K> filter)

Filters the ListMultimap based on the provided key filter. This method creates a new ListMultimap and adds all key-value pairs from the current ListMultimap that satisfy the provided key filter. The new ListMultimap has the same structural and hash characteristics as the current one.

Overrides:

filterByKey in class Multimap<K,E,List<E>>

Parameters:

filter - The predicate to be applied to each key in the ListMultimap. If the predicate returns true, the key-value pair is included in the new ListMultimap.

Returns:

A new ListMultimap containing all the key-value pairs of the current ListMultimap that satisfy the provided key filter.

filterByValue

public ListMultimap<K,E> filterByValue(Predicate<? super List<E>> filter)

Filters the ListMultimap based on the provided value filter. This method creates a new ListMultimap and adds all key-value pairs from the current ListMultimap that satisfy the provided value filter. The new ListMultimap has the same structural and hash characteristics as the current one.

Overrides:

filterByValue in class Multimap<K,E,List<E>>

Parameters:

filter - The predicate to be applied to each value in the ListMultimap. If the predicate returns true, the key-value pair is included in the new ListMultimap.

Returns:

A new ListMultimap containing all the key-value pairs of the current ListMultimap that satisfy the provided value filter.

filter

public ListMultimap<K,E> filter(BiPredicate<? super K,? super List<E>> filter)

Filters the ListMultimap based on the provided key-value pair filter. This method creates a new ListMultimap and adds all key-value pairs from the current ListMultimap that satisfy the provided key-value pair filter. The new ListMultimap has the same structural and hash characteristics as the current one.

Overrides:

filter in class Multimap<K,E,List<E>>

Parameters:

filter - The predicate to be applied to each key-value pair in the ListMultimap. If the predicate returns true, the key-value pair is included in the new ListMultimap.

Returns:

A new ListMultimap containing all the key-value pairs of the current ListMultimap that satisfy the provided key-value pair filter.

toImmutableMap

public ImmutableMap<K,ImmutableList<E>> toImmutableMap()

Converts the current ListMultimap into an ImmutableMap. Each key-value pair in the ListMultimap is transformed into a key-ImmutableList pair in the ImmutableMap. The ImmutableList contains all the values that were associated with the key in the ListMultimap.

Returns:

an ImmutableMap where each key is associated with an ImmutableList of values from the original ListMultimap

toImmutableMap

public ImmutableMap<K,ImmutableList<E>> toImmutableMap(IntFunction<? extends Map<K,ImmutableList<E>>> mapSupplier)

Converts the current ListMultimap into an ImmutableMap using a provided map supplier. Each key-value pair in the ListMultimap is transformed into a key-ImmutableList pair in the ImmutableMap. The ImmutableList contains all the values that were associated with the key in the ListMultimap.

Parameters:

mapSupplier - The supplier function that provides a Map instance. The function takes an integer argument which is the initial size of the map.

Returns:

an ImmutableMap where each key is associated with an ImmutableList of values from the original ListMultimap