Package net.sourceforge.pmd.util

Class CollectionUtil

java.lang.Object

net.sourceforge.pmd.util.CollectionUtil

public final class CollectionUtil
extends Object

Generic collection-related utility functions for java.util types.

Author:

Brian Remedios, Clément Fournier

Method Summary

Modifier and Type	Method	Description
static <N> boolean	all(@Nullable Iterable<? extends N> list, Predicate<? super N> predicate)	Returns true if all elements of the iterable match the predicate.
static <N> boolean	any(@Nullable Iterable<? extends N> list, Predicate<? super N> predicate)	Returns true if any element of the iterable matches the predicate.
static <@NonNull T> @Nullable T	asSingle(Set<@NonNull T> set)	If the set has a single element, returns it, otherwise returns null.
static <K,V> Map<K,V>	associateBy(Collection<? extends @NonNull V> values, Function<? super V,? extends K> keyMapper)
static <K,V> Map<K,V>	associateByTo(Map<K,V> collector, Collection<? extends @NonNull V> values, Function<? super V,? extends K> keyMapper)
static <K,V> Map<K,V>	associateWith(Collection<? extends @NonNull K> keys, Function<? super K,? extends V> mapper)
static <K,V> Map<K,V>	associateWithTo(Map<K,V> collector, Collection<? extends @NonNull K> keys, Function<? super K,? extends V> mapper)
static <K,V> Map<K,V>	buildMap(Consumer<Map<K,V>> effect)
static <K,V> Map<K,V>	buildMap(Map<K,V> initialMap, Consumer<Map<K,V>> effect)
static <T> List<T>	concatView(List<? extends T> head, List<? extends T> tail)	Returns a list view that pretends it is the concatenation of both lists.
static <T> List<T>	defensiveUnmodifiableCopy(List<? extends T> list)	Returns an unmodifiable copy of the list.
static <T> Set<T>	defensiveUnmodifiableCopyToSet(Collection<? extends T> list)
static <T> Set<T>	diff(Collection<? extends T> c1, Collection<? extends T> c2, Collection<? extends T>... rest)	Returns the set difference of the first collection with the other collections.
static <T> List<T>	drop(List<T> list, int n)
static <V> List<V>	emptyList()	Returns the empty list.
static <V,A,C> C	finish(Collector<? super V,A,? extends C> collector, A acc)	Finish the accumulated value of the collector.
static <@NonNull K,V> @Nullable K	getKeyOfValue(Map<@NonNull K,V> m, V v)	Returns the key that corresponds to the given value in the map, or null if it is not contained in the map.
static <T extends Enum<T>> Set<T>	immutableEnumSet(T first, T... rest)	Returns an unmodifiable set containing the given elements.
static <T> Set<T>	immutableSetOf(T first, T... rest)	Returns an unmodifiable set containing the given elements.
static <T> Set<T>	intersect(Collection<? extends T> c1, Collection<? extends T> c2, Collection<? extends T>... rest)	Returns the set intersection of the given collections.
static @NonNull StringBuilder	joinCharsIntoStringBuilder(List<Chars> lines, String delimiter)
static <T> StringBuilder	joinOn(StringBuilder sb, Iterable<? extends T> iterable, BiConsumer<? super StringBuilder,? super T> appendItem, String delimiter)	Like String.join(CharSequence, Iterable), except it appends on a preexisting StringBuilder.
static <T> List<T>	listOf(T first, T... rest)
static <T> List<T>	listOfNotNull(T t)
static <T> @NonNull List<T>	makeUnmodifiableAndNonNull(@Nullable List<? extends T> list)
static <T,R> List<R>	map(Iterable<? extends T> from, Function<? super T,? extends R> f)	Map each element of the given iterable with the given function, and accumulates it into an unmodifiable list.
static <T,R> List<R>	map(Collection<? extends T> from, Function<? super T,? extends R> f)	Map each element of the given collection with the given function, and accumulates it into an unmodifiable list.
static <T,R> List<R>	map(Iterator<? extends T> from, Function<? super T,? extends R> f)	Map each element of the given iterator with the given function, and accumulates it into an unmodifiable list.
static <T,U,A,C> C	map(Collector<? super U,A,? extends C> collector, Iterable<? extends T> from, Function<? super T,? extends U> f)	Map each element of the given iterable with the given function, and accumulates it into the collector.
static <T,U,A,C> C	map(Collector<? super U,A,? extends C> collector, Iterator<? extends T> from, Function<? super T,? extends U> f)	Map each element of the given iterator with the given function, and accumulates it into the collector.
static <T,R> List<R>	map(T[] from, Function<? super T,? extends R> f)	Map each element of the given array with the given function, and accumulates it into an unmodifiable list.
static <T,R> List<@NonNull R>	mapNotNull(Iterable<? extends T> from, Function<? super T,? extends @Nullable R> f)
static <K,V> Map<K,V>	mapOf(K k0, V v0)
static <K,V> Map<K,V>	mapOf(K k1, V v1, K k2, V v2)
static <K,V> void	mergeMaps(Map<K,V> result, Map<K,V> other, BinaryOperator<V> mergeFun)	Merge the second map into the first.
static <N> boolean	none(@Nullable Iterable<? extends N> list, Predicate<? super N> predicate)	Returns true if no element of the iterable matches the predicate.
static <V> List<V>	plus(List<V> list, V v)	Produce a new list with the elements of the first, and one additional item.
static <K,V> Map<K,V>	plus(Map<K,V> m, K k, V v)	Produce a new map with the mappings of the first, and one additional mapping.
static <T> Set<T>	setOf(T first, T... rest)	Returns a set containing the given elements.
static <V> Set<V>	setUnion(Collection<? extends V> set, V first, V... newElements)	Returns an unmodifiable set containing the set union of the collection, and the new elements.
static <T> List<T>	take(List<T> list, int n)
static <T> Collector<T,?,List<T>>	toMutableList()	A collector that returns a mutable list.
static <T> Collector<T,?,Set<T>>	toMutableSet()	A collector that returns a mutable set.
static <T> Collector<T,?,org.pcollections.PSet<T>>	toPersistentSet()	A collectors that accumulates into a persistent set.
static <T> Collector<T,?,List<T>>	toUnmodifiableList()	A collector that returns an unmodifiable list.
static <T> Collector<T,?,Set<T>>	toUnmodifiableSet()	A collector that returns an unmodifiable set.
static <T> Set<T>	union(Collection<? extends T> c1, Collection<? extends T> c2, Collection<? extends T>... rest)	Returns the set union of the given collections.
static <V> org.pcollections.PSet<V>	union(org.pcollections.PSet<V> as, org.pcollections.PSet<V> bs)	Union of two PSets, which avoids creating a new pset if possible.
static <K,V> Map<K,V>	zip(List<? extends @NonNull K> from, List<? extends @NonNull V> to)	Returns a map associating each key in the first list to its corresponding value in the second.

Methods inherited from class java.lang.Object

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

Method Detail

concatView

public static <T> List<T> concatView(List<? extends T> head,
                                     List<? extends T> tail)

Returns a list view that pretends it is the concatenation of both lists. The returned view is unmodifiable. The implementation is pretty stupid and not optimized for repeated concatenation, but should be ok for smallish chains of random-access lists.

Type Parameters:

T - Type of elements in both lists

Parameters:

head - Head elements (to the left)

tail - Tail elements (to the right)

Returns:

A concatenated view

union

@SafeVarargs
public static <T> Set<T> union(Collection<? extends T> c1,
                               Collection<? extends T> c2,
                               Collection<? extends T>... rest)

Returns the set union of the given collections.

Parameters:

c1 - First collection

c2 - Second collection

Returns:

Union of both arguments

intersect

@SafeVarargs
public static <T> Set<T> intersect(Collection<? extends T> c1,
                                   Collection<? extends T> c2,
                                   Collection<? extends T>... rest)

Returns the set intersection of the given collections.

Parameters:

c1 - First collection

c2 - Second collection

Returns:

Intersection of both arguments

diff

@SafeVarargs
public static <T> Set<T> diff(Collection<? extends T> c1,
                              Collection<? extends T> c2,
                              Collection<? extends T>... rest)

Returns the set difference of the first collection with the other collections.

Parameters:

c1 - First collection

c2 - Second collection

Returns:

Difference of arguments

setOf

@SafeVarargs
public static <T> Set<T> setOf(T first,
                               T... rest)

Returns a set containing the given elements. No guarantee is made about mutability.

Parameters:

first - First element

rest - Following elements

immutableSetOf

@SafeVarargs
public static <T> Set<T> immutableSetOf(T first,
                                        T... rest)

Returns an unmodifiable set containing the given elements.

Parameters:

first - First element

rest - Following elements

immutableEnumSet

@SafeVarargs
public static <T extends Enum<T>> Set<T> immutableEnumSet(T first,
                                                          T... rest)

Returns an unmodifiable set containing the given elements.

Parameters:

first - First element

rest - Following elements

listOf

@SafeVarargs
public static <T> List<T> listOf(T first,
                                 T... rest)

mapOf

public static <K,V> Map<K,V> mapOf(K k0,
                                               V v0)

mapOf

public static <K,V> Map<K,V> mapOf(K k1,
                                               V v1,
                                               K k2,
                                               V v2)

buildMap

public static <K,V> Map<K,V> buildMap(Consumer<Map<K,V>> effect)

buildMap

public static <K,V> Map<K,V> buildMap(Map<K,V> initialMap,
                                                  Consumer<Map<K,V>> effect)

mapNotNull

public static <T,R> List<@NonNull R> mapNotNull(Iterable<? extends T> from,
                                                      Function<? super T,? extends @Nullable R> f)

plus

public static <K,V> Map<K,V> plus(Map<K,V> m,
                                              K k,
                                              V v)

Produce a new map with the mappings of the first, and one additional mapping. The returned map may be unmodifiable.

plus

public static <V> List<V> plus(List<V> list,
                               V v)

Produce a new list with the elements of the first, and one additional item. The returned list is immutable.

emptyList

public static <V> List<V> emptyList()

Returns the empty list.

setUnion

@SafeVarargs
public static <V> Set<V> setUnion(Collection<? extends V> set,
                                  V first,
                                  V... newElements)

Returns an unmodifiable set containing the set union of the collection, and the new elements.

getKeyOfValue

public static <@NonNull K,V> @Nullable K getKeyOfValue(Map<@NonNull K,V> m,
                                                             V v)

Returns the key that corresponds to the given value in the map, or null if it is not contained in the map.

Type Parameters:

K - Type of keys

V - Type of values

Parameters:

m - Map

v - Value

Throws:

NullPointerException - If the entry is found, but the key is null

NullPointerException - If the map is null

zip

public static <K,V> Map<K,V> zip(List<? extends @NonNull K> from,
                                             List<? extends @NonNull V> to)

Returns a map associating each key in the first list to its corresponding value in the second.

Throws:

IllegalArgumentException - If the list size are mismatched

NullPointerException - If either of the parameter is null, or any of the keys or values are null

associateWith

public static <K,V> Map<K,V> associateWith(Collection<? extends @NonNull K> keys,
                                                       Function<? super K,? extends V> mapper)

associateWithTo

public static <K,V> Map<K,V> associateWithTo(Map<K,V> collector,
                                                         Collection<? extends @NonNull K> keys,
                                                         Function<? super K,? extends V> mapper)

associateBy

public static <K,V> Map<K,V> associateBy(Collection<? extends @NonNull V> values,
                                                     Function<? super V,? extends K> keyMapper)

associateByTo

public static <K,V> Map<K,V> associateByTo(Map<K,V> collector,
                                                       Collection<? extends @NonNull V> values,
                                                       Function<? super V,? extends K> keyMapper)

map

public static <T,R> List<R> map(Collection<? extends T> from,
                                      Function<? super T,? extends R> f)

Map each element of the given collection with the given function, and accumulates it into an unmodifiable list.

map

public static <T,R> List<R> map(Iterable<? extends T> from,
                                      Function<? super T,? extends R> f)

Map each element of the given iterable with the given function, and accumulates it into an unmodifiable list.

map

public static <T,R> List<R> map(T[] from,
                                      Function<? super T,? extends R> f)

Map each element of the given array with the given function, and accumulates it into an unmodifiable list.

map

public static <T,R> List<R> map(Iterator<? extends T> from,
                                      Function<? super T,? extends R> f)

Map each element of the given iterator with the given function, and accumulates it into an unmodifiable list.

map

public static <T,U,A,C> C map(Collector<? super U,A,? extends C> collector,
                                                Iterable<? extends T> from,
                                                Function<? super T,? extends U> f)

Map each element of the given iterable with the given function, and accumulates it into the collector.

map

public static <T,U,A,C> C map(Collector<? super U,A,? extends C> collector,
                                                Iterator<? extends T> from,
                                                Function<? super T,? extends U> f)

Map each element of the given iterator with the given function, and accumulates it into the collector.

toMutableList

public static <T> Collector<T,?,List<T>> toMutableList()

A collector that returns a mutable list. This contrasts with Collectors.toList(), which makes no guarantee about the mutability of the list.

Type Parameters:

T - Type of accumulated values

toMutableSet

public static <T> Collector<T,?,Set<T>> toMutableSet()

A collector that returns a mutable set. This contrasts with Collectors.toSet(), which makes no guarantee about the mutability of the set. The set preserves insertion order.

Type Parameters:

T - Type of accumulated values

toUnmodifiableList

public static <T> Collector<T,?,List<T>> toUnmodifiableList()

A collector that returns an unmodifiable list. This contrasts with Collectors.toList(), which makes no guarantee about the mutability of the list. Collectors::toUnmodifiableList was only added in JDK 9.

Type Parameters:

T - Type of accumulated values

toUnmodifiableSet

public static <T> Collector<T,?,Set<T>> toUnmodifiableSet()

A collector that returns an unmodifiable set. This contrasts with Collectors.toSet(), which makes no guarantee about the mutability of the set. Collectors::toUnmodifiableSet was only added in JDK 9. The set preserves insertion order.

Type Parameters:

T - Type of accumulated values

toPersistentSet

public static <T> Collector<T,?,org.pcollections.PSet<T>> toPersistentSet()

A collectors that accumulates into a persistent set.

Type Parameters:

T - Type of accumulated values

finish

public static <V,A,C> C finish(Collector<? super V,A,? extends C> collector,
                                           A acc)

Finish the accumulated value of the collector.

drop

public static <T> List<T> drop(List<T> list,
                               int n)

take

public static <T> List<T> take(List<T> list,
                               int n)

listOfNotNull

public static <T> List<T> listOfNotNull(T t)

any

public static <N> boolean any(@Nullable Iterable<? extends N> list,
                              Predicate<? super N> predicate)

Returns true if any element of the iterable matches the predicate. Return false if the list is null or empty.

all

public static <N> boolean all(@Nullable Iterable<? extends N> list,
                              Predicate<? super N> predicate)

Returns true if all elements of the iterable match the predicate. Return true if the list is null or empty.

none

public static <N> boolean none(@Nullable Iterable<? extends N> list,
                               Predicate<? super N> predicate)

Returns true if no element of the iterable matches the predicate. Return true if the list is null or empty.

asSingle

public static <@NonNull T> @Nullable T asSingle(Set<@NonNull T> set)

If the set has a single element, returns it, otherwise returns null. Obviously the set should not contain null elements.

defensiveUnmodifiableCopy

public static <T> List<T> defensiveUnmodifiableCopy(List<? extends T> list)

Returns an unmodifiable copy of the list. This is to be preferred to Collections.unmodifiableList(List) if you don't trust the source of the list, because no one holds a reference to the buffer except the returned unmodifiable list.

Type Parameters:

T - Type of items

Parameters:

list - A list

defensiveUnmodifiableCopyToSet

public static <T> Set<T> defensiveUnmodifiableCopyToSet(Collection<? extends T> list)

joinOn

public static <T> StringBuilder joinOn(StringBuilder sb,
                                       Iterable<? extends T> iterable,
                                       BiConsumer<? super StringBuilder,? super T> appendItem,
                                       String delimiter)

Like String.join(CharSequence, Iterable), except it appends on a preexisting StringBuilder. The result value is that StringBuilder.

joinCharsIntoStringBuilder

public static @NonNull StringBuilder joinCharsIntoStringBuilder(List<Chars> lines,
                                                                String delimiter)

mergeMaps

public static <K,V> void mergeMaps(Map<K,V> result,
                                         Map<K,V> other,
                                         BinaryOperator<V> mergeFun)

Merge the second map into the first. If some keys are in common, merge them using the merge function, like Map.merge(Object, Object, BiFunction).

union

public static <V> org.pcollections.PSet<V> union(org.pcollections.PSet<V> as,
                                                 org.pcollections.PSet<V> bs)

Union of two PSets, which avoids creating a new pset if possible.

makeUnmodifiableAndNonNull

public static <T> @NonNull List<T> makeUnmodifiableAndNonNull(@Nullable List<? extends T> list)