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, U> Map<K,U>
    mapView(Map<K,V> map, Function<? super V,? extends U> valueMapper)
    Returns a view over the given map, where values are mapped using the given function.
    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 Details

    • 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

    • mapView

      public static <K, V, U> Map<K,U> mapView(Map<K,V> map, Function<? super V,? extends U> valueMapper)
      Returns a view over the given map, where values are mapped using the given function.
      Since:
      7.14.0

    • 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)