Class XCollectionUtils


  • public class XCollectionUtils
    extends Object
    Utility class for operations on collections and iterables.
    Since:
    7.0.0
    Author:
    XIMA Media GmbH
    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      static <T> Collector<T,​?,​Stream<IterableUtils.Indexed<T>>> adjoiningIndex()  
      static <T,​R>
      Collector<T,​?,​R>
      adjoiningIndex​(Function<Iterable<IterableUtils.Indexed<T>>,​R> finisher)  
      static <T,​A,​R>
      Collector<T,​?,​R>
      adjoiningIndex​(Collector<IterableUtils.Indexed<T>,​A,​R> downstream)  
      static <T> Collection<T> defaultCollection​(Collection<T> collection)
      Sames as CollectionUtils.emptyIfNull(Collection), but with a more verbose name when using static imports.
      static <T> List<T> defaultList​(List<T> list)
      Sames as ListUtils.emptyIfNull(List), but with a more verbose name when using static imports.
      static <T> Set<T> defaultSet​(Set<T> set)
      Sames as SetUtils.emptyIfNull(Set), but with a more verbose name when using static imports.
      static <T> T firstElement​(Iterable<T> elements)  
      static <T> T firstItem​(List<T> list)  
      static <T> List<T> growToSize​(List<T> list, int targetSize, IntFunction<T> missingValueSupplier)
      Grows a list to at least the given target size, doing nothing if the list's size is already equal to or greater than the target size.
      static boolean isEmptyCollection​(Collection<?> collection)
      Sames as CollectionUtils.isEmpty(Collection), but with a more verbose name when using static imports.
      static boolean isNonEmptyCollection​(Collection<?> collection)
      Sames as CollectionUtils.isNotEmpty(Collection), but with a more verbose name when using static imports.
      static <T> T itemAt​(List<T> list, int index)
      Gets the item at the given index, or null if the index is out of bounds.
      static <T> T lastElement​(Iterable<T> elements)  
      static <T> T lastItem​(List<T> list)  
      static <T> List<T> listOfSize​(int targetSize, T initialValue)  
      static <T> List<T> listOfSizeWith​(int targetSize, IntFunction<T> initialValue)  
      static <K1,​K2,​V>
      Map<K2,​V>
      mapKeys​(Map<? extends K1,​? extends V> map, Function<? super K1,​? extends K2> keyMapper)
      Remaps the keys of a map by applying the given mapping function to all keys, returning a new map.
      static <K1,​K2,​V>
      Map<K2,​V>
      mapKeys​(Map<? extends K1,​? extends V> map, Function<? super K1,​? extends K2> keyMapper, BinaryOperator<V> mergeFunction)
      Remaps the keys of a map by applying the given mapping function to all keys, returning a new map.
      static <K1,​K2,​V>
      Map<K2,​V>
      mapKeysToUnmodifiableMap​(Map<? extends K1,​? extends V> map, Function<? super K1,​? extends K2> keyMapper)
      Remaps the keys of a map by applying the given mapping function to all keys, returning a new unmodifiable map.
      static <K1,​K2,​V>
      Map<K2,​V>
      mapKeysToUnmodifiableMap​(Map<? extends K1,​? extends V> map, Function<? super K1,​? extends K2> keyMapper, BinaryOperator<V> mergeFunction)
      Remaps the keys of a map by applying the given mapping function to all keys, returning a new unmodifiable map.
      static <K1,​V1,​K2,​V2>
      Map<K2,​V2>
      mapMap​(Map<? extends K1,​? extends V1> map, BiFunction<? super K1,​? super V1,​? extends Map.Entry<? extends K2,​? extends V2>> entryMapper)
      Maps the entries of a map by applying the given mapping function, returning a new map.
      static <K1,​V1,​K2,​V2>
      Map<K2,​V2>
      mapMap​(Map<? extends K1,​? extends V1> map, BiFunction<? super K1,​? super V1,​? extends Map.Entry<? extends K2,​? extends V2>> entryMapper, BinaryOperator<V2> mergeFunction)
      Maps the entries of a map by applying the given mapping function, returning a new map.
      static <K1,​V1,​K2,​V2,​M extends Map<K2,​V2>>
      M
      mapMap​(Map<? extends K1,​? extends V1> map, BiFunction<? super K1,​? super V1,​? extends Map.Entry<? extends K2,​? extends V2>> entryMapper, BinaryOperator<V2> mergeFunction, Supplier<M> mapFactory)
      Maps the entries of a map by applying the given mapping function, returning a new map.
      static <T,​S>
      List<S>
      mapToList​(Iterable<T> items, Function<T,​S> mapper)
      Maps the elements of an iterable to new elements via the given mapping function.
      static <T,​S,​C extends Collection<S>>
      C
      mapToList​(Iterable<T> items, Function<T,​S> mapper, Supplier<C> collectionFactory)
      Maps the elements of an iterable to new elements via the given mapping function, putting the result into a collection.
      static <K1,​V1,​K2,​V2>
      Map<K2,​V2>
      mapToUnmodifiableMap​(Map<? extends K1,​? extends V1> map, BiFunction<? super K1,​? super V1,​? extends Map.Entry<? extends K2,​? extends V2>> entryMapper)
      Maps the entries of a map by applying the given mapping function, returning a new unmodifiable map.
      static <K1,​V1,​K2,​V2>
      Map<K2,​V2>
      mapToUnmodifiableMap​(Map<? extends K1,​? extends V1> map, BiFunction<? super K1,​? super V1,​? extends Map.Entry<? extends K2,​? extends V2>> entryMapper, BinaryOperator<V2> mergeFunction)
      Maps the entries of a map by applying the given mapping function, returning a new unmodifiable map.
      static <K,​V1,​V2>
      Map<K,​V2>
      mapValues​(Map<? extends K,​? extends V1> map, Function<? super V1,​? extends V2> valueMapper)
      Remaps the values of a map by applying the given mapping function to all keys, returning a new map.
      static <K,​V1,​V2>
      Map<K,​V2>
      mapValuesToUnmodifiableMap​(Map<? extends K,​? extends V1> map, Function<? super V1,​? extends V2> valueMapper)
      Remaps the values of a map by applying the given mapping function to all keys, returning a new unmodifiable map.
      static <T> List<T> serializableList​(Iterable<T> sequence)
      Takes any Collection or Iterable and converts it to a serializable list that can be transferred via the API.
    • Method Detail

      • firstItem

        public static <T> T firstItem​(List<T> list)
        Type Parameters:
        T - Type of the elements in the list.
        Parameters:
        list - List to process.
        Returns:
        The first item in the list, or null if the list is null or empty, or the first item is null.
      • firstElement

        public static <T> T firstElement​(Iterable<T> elements)
        Type Parameters:
        T - Type of the elements.
        Parameters:
        elements - Elements to process.
        Returns:
        The first element from the elements, or null if the elements are null or empty, or the first item is null.
      • isEmptyCollection

        public static boolean isEmptyCollection​(Collection<?> collection)
        Sames as CollectionUtils.isEmpty(Collection), but with a more verbose name when using static imports.
        Parameters:
        collection - Collection to check.
        Returns:
        true if the collection is null or empty.
      • isNonEmptyCollection

        public static boolean isNonEmptyCollection​(Collection<?> collection)
        Sames as CollectionUtils.isNotEmpty(Collection), but with a more verbose name when using static imports.
        Parameters:
        collection - Collection to check.
        Returns:
        true if the collection is neither null nor empty.
      • defaultCollection

        public static <T> Collection<T> defaultCollection​(Collection<T> collection)
        Sames as CollectionUtils.emptyIfNull(Collection), but with a more verbose name when using static imports.
        Type Parameters:
        T - Type of the items in the collection.
        Parameters:
        collection - Collection to check.
        Returns:
        The given collection, or an empty collection when null is given.
      • defaultList

        public static <T> List<T> defaultList​(List<T> list)
        Sames as ListUtils.emptyIfNull(List), but with a more verbose name when using static imports.
        Type Parameters:
        T - Type of the items in the set.
        Parameters:
        list - List to check.
        Returns:
        The given list, or an empty list when null is given.
      • defaultSet

        public static <T> Set<T> defaultSet​(Set<T> set)
        Sames as SetUtils.emptyIfNull(Set), but with a more verbose name when using static imports.
        Type Parameters:
        T - Type of the items in the set.
        Parameters:
        set - Set to check.
        Returns:
        The given set, or an empty set when null is given.
      • lastElement

        public static <T> T lastElement​(Iterable<T> elements)
        Type Parameters:
        T - Type of the elements.
        Parameters:
        elements - Elements to process.
        Returns:
        The last element from the elements, or null if the elements are null or empty, or the first item is null.
      • growToSize

        public static <T> List<T> growToSize​(List<T> list,
                                             int targetSize,
                                             IntFunction<T> missingValueSupplier)
        Grows a list to at least the given target size, doing nothing if the list's size is already equal to or greater than the target size. When the given list is null, an empty list is created, grown, and returned.
        Type Parameters:
        T - Type of the list items.
        Parameters:
        list - List to mutate.
        targetSize - Target size.
        missingValueSupplier - Supplier for new values when the list needs to be grown. It is given the index of the position at which an element is needed.
        Returns:
        The given list grown to the target size.
        Throws:
        NullPointerException - When the value supplier is null.
      • mapToList

        public static <T,​S> List<S> mapToList​(Iterable<T> items,
                                                    Function<T,​S> mapper)
        Maps the elements of an iterable to new elements via the given mapping function. Functionally the same as
         StreamSupport.stream(items.spliterator(), false).map(mapper).collect(Collectors.toList())
         
        The returned list is serializable and mutable.
        Type Parameters:
        T - Type of the source elements.
        S - Type of the target elements.
        Parameters:
        items - Elements to map. Can be null, which is interpreted as an empty list.
        mapper - Mapping function to apply.
        Returns:
        A new list with the mapped elements.
      • mapToList

        public static <T,​S,​C extends Collection<S>> C mapToList​(Iterable<T> items,
                                                                            Function<T,​S> mapper,
                                                                            Supplier<C> collectionFactory)
        Maps the elements of an iterable to new elements via the given mapping function, putting the result into a collection. Functionally the same as
         StreamSupport.stream(items.spliterator(), false).map(mapper).collect(Collectors.toCollection(() -> listFactory.apply(list.size()))
         
        Type Parameters:
        T - Type of the source elements.
        S - Type of the target elements.
        C - Type of the new collection.
        Parameters:
        items - Elements to map. Can be null, which is interpreted as an empty list.
        mapper - Mapping function to apply.
        collectionFactory - Factory for creating a new collection.
        Returns:
        A collection as obtained from the factory, with the mapped elements added at the end.
      • itemAt

        public static <T> T itemAt​(List<T> list,
                                   int index)
        Gets the item at the given index, or null if the index is out of bounds.
        Type Parameters:
        T - Type of the elements in the list.
        Parameters:
        list - List to process.
        index - Index to access.
        Returns:
        The element at the index, null if there is no such element.
      • lastItem

        public static <T> T lastItem​(List<T> list)
        Type Parameters:
        T - Type of the elements in the list.
        Parameters:
        list - List to process.
        Returns:
        The last item in the list, or null if the list is null or empty, or the last item is null.
      • listOfSize

        public static <T> List<T> listOfSize​(int targetSize,
                                             T initialValue)
        Type Parameters:
        T - Type of the list elements.
        Parameters:
        targetSize - Desired size of the list.
        initialValue - Initial value for each element.
        Returns:
        A list of the given size, with each element set to the given initial value.
      • listOfSizeWith

        public static <T> List<T> listOfSizeWith​(int targetSize,
                                                 IntFunction<T> initialValue)
        Type Parameters:
        T - Type of the list elements.
        Parameters:
        targetSize - Desired size of the list.
        initialValue - Supplier for the initial value for each element.
        Returns:
        A list of the given size, with each element set to the value returned by the given supplier.
      • adjoiningIndex

        public static <T> Collector<T,​?,​Stream<IterableUtils.Indexed<T>>> adjoiningIndex()
        Type Parameters:
        T - Type of the input elements.
        Returns:
        A collector that adds the 0-based index to all elements, and returns a stream of these elements.
      • adjoiningIndex

        public static <T,​R> Collector<T,​?,​R> adjoiningIndex​(Function<Iterable<IterableUtils.Indexed<T>>,​R> finisher)
        Type Parameters:
        T - Type of the input elements.
        R - Type of the output.
        Parameters:
        finisher - Finisher that transform the indexed element to the output type.
        Returns:
        A collector that adds the 0-based index to all elements, and applies the finisher to the list of indexed elements.
      • adjoiningIndex

        public static <T,​A,​R> Collector<T,​?,​R> adjoiningIndex​(Collector<IterableUtils.Indexed<T>,​A,​R> downstream)
        Type Parameters:
        T - Type of the input elements.
        A - Type of the intermediate elements of the downstream collector.
        R - Type of the output.
        Parameters:
        downstream - Downstream that combines all elements into a single value.
        Returns:
        A collector that adds the 0-based index to all elements, and applies the downstream collector to all elements.
      • mapKeys

        public static <K1,​K2,​V> Map<K2,​V> mapKeys​(Map<? extends K1,​? extends V> map,
                                                                    Function<? super K1,​? extends K2> keyMapper)
        Remaps the keys of a map by applying the given mapping function to all keys, returning a new map. If there are multiple mapped entries with the same key, the latter entry will be used.
        Type Parameters:
        K1 - Type of the input map keys.
        K2 - Type of the output map keys.
        V - Type of the map values.
        Parameters:
        map - Map to process.
        keyMapper - Mapping function for the keys.
        Returns:
        The new map.
        Since:
        8.0.0
      • mapKeys

        public static <K1,​K2,​V> Map<K2,​V> mapKeys​(Map<? extends K1,​? extends V> map,
                                                                    Function<? super K1,​? extends K2> keyMapper,
                                                                    BinaryOperator<V> mergeFunction)
        Remaps the keys of a map by applying the given mapping function to all keys, returning a new map.
        Type Parameters:
        K1 - Type of the input map keys.
        K2 - Type of the output map keys.
        V - Type of the map values.
        Parameters:
        map - Map to process.
        keyMapper - Mapping function for the keys.
        mergeFunction - Merge function values that map to the same key.
        Returns:
        The new map.
        Since:
        8.0.0
      • mapKeysToUnmodifiableMap

        public static <K1,​K2,​V> Map<K2,​V> mapKeysToUnmodifiableMap​(Map<? extends K1,​? extends V> map,
                                                                                     Function<? super K1,​? extends K2> keyMapper)
        Remaps the keys of a map by applying the given mapping function to all keys, returning a new unmodifiable map. If there are multiple mapped entries with the same key, the latter entry will be used.
        Type Parameters:
        K1 - Type of the input map keys.
        K2 - Type of the output map keys.
        V - Type of the map values.
        Parameters:
        map - Map to process.
        keyMapper - Mapping function for the keys.
        Returns:
        The new map.
        Since:
        8.0.0
      • mapKeysToUnmodifiableMap

        public static <K1,​K2,​V> Map<K2,​V> mapKeysToUnmodifiableMap​(Map<? extends K1,​? extends V> map,
                                                                                     Function<? super K1,​? extends K2> keyMapper,
                                                                                     BinaryOperator<V> mergeFunction)
        Remaps the keys of a map by applying the given mapping function to all keys, returning a new unmodifiable map.
        Type Parameters:
        K1 - Type of the input map keys.
        K2 - Type of the output map keys.
        V - Type of the map values.
        Parameters:
        map - Map to process.
        keyMapper - Mapping function for the keys.
        mergeFunction - Merge function values that map to the same key.
        Returns:
        The new map.
        Since:
        8.0.0
      • mapMap

        public static <K1,​V1,​K2,​V2> Map<K2,​V2> mapMap​(Map<? extends K1,​? extends V1> map,
                                                                              BiFunction<? super K1,​? super V1,​? extends Map.Entry<? extends K2,​? extends V2>> entryMapper)
        Maps the entries of a map by applying the given mapping function, returning a new map. If there are multiple mapped entries with the same key, the latter entry will be used.
        Type Parameters:
        K1 - Type of the input map keys.
        V1 - Type of the input map values.
        K2 - Type of the output map keys.
        V2 - Type of the output map values.
        Parameters:
        map - Map to process.
        entryMapper - Mapping function for the entries.
        Returns:
        The new map.
        Since:
        8.0.0
      • mapMap

        public static <K1,​V1,​K2,​V2> Map<K2,​V2> mapMap​(Map<? extends K1,​? extends V1> map,
                                                                              BiFunction<? super K1,​? super V1,​? extends Map.Entry<? extends K2,​? extends V2>> entryMapper,
                                                                              BinaryOperator<V2> mergeFunction)
        Maps the entries of a map by applying the given mapping function, returning a new map.
        Type Parameters:
        K1 - Type of the input map keys.
        V1 - Type of the input map values.
        K2 - Type of the output map keys.
        V2 - Type of the output map values.
        Parameters:
        map - Map to process.
        entryMapper - Mapping function for the entries.
        mergeFunction - Merge function for duplicate entries.
        Returns:
        The new map.
        Since:
        8.0.0
      • mapMap

        public static <K1,​V1,​K2,​V2,​M extends Map<K2,​V2>> M mapMap​(Map<? extends K1,​? extends V1> map,
                                                                                                BiFunction<? super K1,​? super V1,​? extends Map.Entry<? extends K2,​? extends V2>> entryMapper,
                                                                                                BinaryOperator<V2> mergeFunction,
                                                                                                Supplier<M> mapFactory)
        Maps the entries of a map by applying the given mapping function, returning a new map.
        Type Parameters:
        K1 - Type of the input map keys.
        V1 - Type of the input map values.
        K2 - Type of the output map keys.
        V2 - Type of the output map values.
        M - Type of the returned map.
        Parameters:
        map - Map to process.
        entryMapper - Mapping function for the entries.
        mergeFunction - Merge function for duplicate entries.
        mapFactory - Factory for the map to build.
        Returns:
        The new map.
        Since:
        8.0.0
      • mapToUnmodifiableMap

        public static <K1,​V1,​K2,​V2> Map<K2,​V2> mapToUnmodifiableMap​(Map<? extends K1,​? extends V1> map,
                                                                                            BiFunction<? super K1,​? super V1,​? extends Map.Entry<? extends K2,​? extends V2>> entryMapper)
        Maps the entries of a map by applying the given mapping function, returning a new unmodifiable map. If there are multiple mapped entries with the same key, the latter entry will be used.
        Type Parameters:
        K1 - Type of the input map keys.
        V1 - Type of the input map values.
        K2 - Type of the output map keys.
        V2 - Type of the output map values.
        Parameters:
        map - Map to process.
        entryMapper - Mapping function for the entries.
        Returns:
        The new map.
        Since:
        8.0.0
      • mapToUnmodifiableMap

        public static <K1,​V1,​K2,​V2> Map<K2,​V2> mapToUnmodifiableMap​(Map<? extends K1,​? extends V1> map,
                                                                                            BiFunction<? super K1,​? super V1,​? extends Map.Entry<? extends K2,​? extends V2>> entryMapper,
                                                                                            BinaryOperator<V2> mergeFunction)
        Maps the entries of a map by applying the given mapping function, returning a new unmodifiable map.
        Type Parameters:
        K1 - Type of the input map keys.
        V1 - Type of the input map values.
        K2 - Type of the output map keys.
        V2 - Type of the output map values.
        Parameters:
        map - Map to process.
        entryMapper - Mapping function for the entries.
        mergeFunction - Merge function values that map to the same key.
        Returns:
        The new map.
        Since:
        8.0.0
      • mapValues

        public static <K,​V1,​V2> Map<K,​V2> mapValues​(Map<? extends K,​? extends V1> map,
                                                                      Function<? super V1,​? extends V2> valueMapper)
        Remaps the values of a map by applying the given mapping function to all keys, returning a new map.
        Type Parameters:
        K - Type of the map keys.
        V1 - Type of the input map values.
        V2 - Type of the output map values.
        Parameters:
        map - Map to process.
        valueMapper - Mapping function for the values.
        Returns:
        The new map.
        Since:
        8.0.0
      • mapValuesToUnmodifiableMap

        public static <K,​V1,​V2> Map<K,​V2> mapValuesToUnmodifiableMap​(Map<? extends K,​? extends V1> map,
                                                                                       Function<? super V1,​? extends V2> valueMapper)
        Remaps the values of a map by applying the given mapping function to all keys, returning a new unmodifiable map.
        Type Parameters:
        K - Type of the map keys.
        V1 - Type of the input map values.
        V2 - Type of the output map values.
        Parameters:
        map - Map to process.
        valueMapper - Mapping function for the values.
        Returns:
        The new map.
        Since:
        8.0.0
      • serializableList

        public static <T> List<T> serializableList​(Iterable<T> sequence)
        Takes any Collection or Iterable and converts it to a serializable list that can be transferred via the API.
        Type Parameters:
        T - Type of the list items.
        Parameters:
        sequence - A sequence of items to put into a list.
        Returns:
        A serializable list with the given items.