Class CollectionUtils


  • public abstract class CollectionUtils
    extends Object
    Since:
    4.0
    Author:
    Nick Smith, Neil Mc Erlean
    • Constructor Detail

      • CollectionUtils

        public CollectionUtils()
    • Method Detail

      • isEmpty

        public static boolean isEmpty​(Map<?,​?> map)
      • isEmpty

        public static boolean isEmpty​(Collection<?> items)
      • nullSafeMerge

        public static <T> Set<T> nullSafeMerge​(Set<T> first,
                                               Set<T> second)
        This method merges two sets returning the union of both sets.
        Parameters:
        first - first set. can be null.
        second - second set. can be null.
        Returns:
        the union of both sets. will not be null
      • nullSafeMerge

        public static <T> Set<T> nullSafeMerge​(Set<T> first,
                                               Set<T> second,
                                               boolean emptyResultIsNull)
        This method merges two sets returning the union of both sets.
        Parameters:
        first - first set. can be null.
        second - second set. can be null.
        emptyResultIsNull - if the result is empty, should we return null?
        Returns:
        the union of both sets or null.
      • nullSafeMerge

        public static <K,​V> Map<K,​V> nullSafeMerge​(Map<K,​V> first,
                                                               Map<K,​V> second)
        This method merges two maps returning the union of both maps.
        Parameters:
        first - first map. can be null.
        second - second map. can be null.
        Returns:
        the union of both maps. will not be null
      • nullSafeMerge

        public static <K,​V> Map<K,​V> nullSafeMerge​(Map<K,​V> first,
                                                               Map<K,​V> second,
                                                               boolean emptyResultIsNull)
        This method merges two maps returning the union of both maps.
        Parameters:
        first - first map. can be null.
        second - second map. can be null.
        emptyResultIsNull - if the result is empty, should we return null?
        Returns:
        the union of both maps, or null.
      • nullSafeAppend

        public static <T> List<T> nullSafeAppend​(List<T> first,
                                                 List<T> second)
        This method joins two lists returning the a single list consisting of the first followed by the second.
        Parameters:
        first - first list. can be null.
        second - second list. can be null.
        Returns:
        the concatenation of both lists. will not be null
      • nullSafeAppend

        public static <T> List<T> nullSafeAppend​(List<T> first,
                                                 List<T> second,
                                                 boolean emptyResultIsNull)
        This method joins two lists returning the a single list consisting of the first followed by the second.
        Parameters:
        first - first list. can be null.
        second - second list. can be null.
        emptyResultIsNull - if the result is empty, should we return null?
        Returns:
        the concatenation of both lists or null
      • transform

        public static <F,​T> List<T> transform​(Collection<F> values,
                                                    Function<? super F,​? extends T> transformer)
        Converts a Collection of values of type F to a Serializable List of values of type T. Filters out all values converted to null.
        Type Parameters:
        F - From type
        T - To type
        Parameters:
        values - the values to convert.
        transformer - Used to convert values.
        Returns:
        List
      • transformKeys

        public static <F,​T,​V> Map<T,​V> transformKeys​(Map<F,​V> map,
                                                                       Function<? super F,​? extends T> transformer)
        Converts a Map having keys of type F to a new Map instance having keys of type T. The object references in the value set are copied to the transformed map, thus reusing the same objects.
        Type Parameters:
        F - From type
        T - To type
        V - The value type of the before and after maps.
        Parameters:
        map - the map to convert.
        transformer - Used to convert keys.
        Returns:
        a new Map instance with transformed keys and unchanged values. These values will be the same object references.
      • transform

        public static <F,​T> List<T> transform​(Function<? super F,​? extends T> transformer,
                                                    F... values)
        Converts a Collection of values of type F to a Serializable List of values of type T. Filters out all values converted to null.
        Type Parameters:
        F - From type
        T - To type
        Parameters:
        values - the values to convert.
        transformer - Used to convert values.
        Returns:
        List
      • asSet

        public static <T> Set<T> asSet​(T... objects)
        This utility method converts a vararg of Objects into a Set.
        Parameters:
        objects - the objects to be added to the set
        Returns:
        a Set of objects (any equal objects will of course not be duplicated)
        Throws:
        ClassCastException - if any of the supplied objects are not of type T.
      • asSet

        public static <T> Set<T> asSet​(Class<T> clazz,
                                       Object... objects)
        This utility method converts a vararg of Objects into a Set.
        Parameters:
        clazz - the Set type to return.
        objects - the objects to be added to the set
        Returns:
        a Set of objects (any equal objects will of course not be duplicated)
        Throws:
        ClassCastException - if any of the supplied objects are not of type T.
      • filter

        public static <T> List<T> filter​(Collection<T> values,
                                         Function<? super T,​Boolean> filter)
        Returns a filtered List of values. Only values for which filter.apply(T) returns true are included in the List or returned values.
        Type Parameters:
        T - The type of the Collection
        Parameters:
        values - the Collection to be filtered.
        filter - the Function used to filter the Collection.
        Returns:
        the filtered List of values.
      • flatten

        public static <T> List<T> flatten​(Collection<? extends Collection<? extends T>> values)
        This method flattens the provided collection of collections of values into a single List object containing each of the elements from the provided sub-collections.

        For example, flatten( [1, 2], [3], [], [4, 5, 6] ) would produce a List like [1, 2, 3, 4, 5, 6]. Here, "[]" represents any Java collection.

        Type Parameters:
        T - the element type of the collections. Note that this must be the same for all collections.
        Parameters:
        values - a collection of collections of elements to be flattened.
        Returns:
        a List containing the flattened elements.
      • flatten

        @SafeVarargs
        public static <T> List<T> flatten​(Collection<? extends T>... collections)
        Parameters:
        collections - a vararg of Collection objects to be flattened into a list.
        Returns:
        A flat List containing the elements of the provided collections.
        Since:
        5.0
      • transformFlat

        public static <F,​T> List<T> transformFlat​(Collection<F> values,
                                                        Function<? super F,​? extends Collection<? extends T>> transformer)
      • findFirst

        public static <T> T findFirst​(Collection<T> values,
                                      Function<? super T,​Boolean> acceptor)
        Finds the first value for which acceptor returns true.
        Type Parameters:
        T - T
        Parameters:
        values - Collection
        acceptor - Function
        Returns:
        returns accepted value or null.
      • unmodifiableSet

        public static <T> Set<T> unmodifiableSet​(T... values)
        Returns an immutable Serializable Set containing the values.
        Type Parameters:
        T - T
        Parameters:
        values - T...
        Returns:
        Set
      • unmodifiableSet

        public static <T> Set<T> unmodifiableSet​(Collection<T> values)
        Returns an immutable Serializable Set containing the values.
        Type Parameters:
        T - T
        Parameters:
        values - Collection
        Returns:
        Set
      • transformToMap

        public static <F,​T> Map<F,​T> transformToMap​(Collection<F> values,
                                                                Function<F,​T> transformer)
        Parameters:
        values - Collection
        transformer - Function
        Returns:
        Map
      • filterKeys

        public static <K,​V> Map<K,​V> filterKeys​(Map<K,​V> map,
                                                            Function<? super K,​? extends Boolean> filter)
        This method can be used to filter a Map. Any keys in the supplied map, for which the supplied filter function returns true, will be included in the resultant Map, else they will not.
        Parameters:
        map - the map whose entries are to be filtered.
        filter - the filter function which is applied to the key.
        Returns:
        a filtered map.
      • transform

        public static <FK,​FV,​TK,​TV> Map<TK,​TV> transform​(Map<FK,​FV> map,
                                                                                 Function<Map.Entry<FK,​FV>,​Pair<TK,​TV>> transformer)
      • containsFilter

        public static <T> Filter<T> containsFilter​(Collection<T> values)
      • intersect

        public static <T> List<T> intersect​(List<? extends T> list1,
                                            List<? extends T> list2)
        This method returns a new ArrayList which is the intersection of the two List parameters, based on equality of their elements. The intersection list will contain elements in the order they have in list1 and any references in the resultant list will be to elements within list1 also.
        Returns:
        a new ArrayList whose values represent the intersection of the two Lists.
      • intersect

        public static <K,​V> Map<K,​V> intersect​(Map<K,​V> map1,
                                                           Map<K,​V> map2)
        This method returns a new HashMap which is the intersection of the two Map parameters, based on equality of their entries. Any references in the resultant map will be to elements within map1.
        Returns:
        a new HashMap whose values represent the intersection of the two Maps.
      • intersect

        public static <T> Set<T> intersect​(Set<? extends T> set1,
                                           Set<? extends T> set2)
        This method returns a new HashSet which is the intersection of the two Set parameters, based on equality of their elements. Any references in the resultant set will be to elements within set1.
        Returns:
        a new HashSet whose values represent the intersection of the two Sets.
      • sortMapByValue

        public static <K,​V> Map<K,​V> sortMapByValue​(Map<K,​V> map,
                                                                Comparator<Map.Entry<K,​V>> valueComparator)
        Creates a new sorted map, based on the values from the given map and Comparator.
        Parameters:
        map - the map which needs to be sorted
        valueComparator - the Comparator
        Returns:
        a new sorted map
      • toEntryComparator

        public static <K,​V> Comparator<Map.Entry<K,​V>> toEntryComparator​(Comparator<V> valueComparator)
        This method offers convenient conversion from value-based comparators to entry-based comparators for use with sortMapByValue(Map, Comparator) above.

        Call it like so: CollectionUtils.<String, Integer>toEntryComparator(valueComparator);

        Parameters:
        valueComparator - a comparator which compares the value types from a Map.
        Returns:
        a comparator which takes Map.Entry objects from that Map and compares their values.
      • moveLeft

        public static <T> List<T> moveLeft​(int offset,
                                           T element,
                                           List<T> list)
        This method returns a new List instance containing the same element objects as the provided list, but with the specified element having been moved left by the specified offset.

        If the offset would mean that the element would move beyond the start or end of the list, it will move only to the end.

        Parameters:
        offset - the number of places over which to move the specified element.
        element - the element to be moved.
        list - the list to be reordered.
        Returns:
        a new List instance containing the ordered elements.
        Throws:
        NoSuchElementException - if the list does not contain an element equal to the one specified.
      • moveRight

        public static <T> List<T> moveRight​(int offset,
                                            T element,
                                            List<T> list)
        This method does the same as moveLeft(int, Object, List) but it moves the specified element to the right instead of the left.