Class CollectionUtil


  • public final class CollectionUtil
    extends Object
    Generic collection-related utility functions for java.util types.
    Author:
    Brian Remedios, Clément Fournier
    • Method Summary

      All Methods Static Methods Concrete Methods 
      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 <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.
    • 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)
      • makeUnmodifiableAndNonNull

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