Package de.xima.fc.utils

Class XIterableUtils

  • public final class XIterableUtils
extends Object
    Additional utilities for Iterables not found in other libraries.
    Since:
    8.2.0
    Author:
    XIMA MEDIA GmbH

    • Constructor Detail

      • XIterableUtils

        public XIterableUtils()

    • Method Detail

      • allMatch

        public static <T> boolean allMatch​(Iterable<? extends T> items,
                                   Predicate<? super T> predicate)
        Similar to the matchesAll method from Apache Commons, but does not throw on null predicates. Returns true if all items match the given predicate. Returns true if the iterable is null or empty. A null predicate is treated as a predicate that always returns false.
        Type Parameters:
        T - Type of the items in the iterable.
        Parameters:
        items - Items to check.
        predicate - Predicate to check.
        Returns:
        true if no item exists which does not match the predicate.

      • anyMatch

        public static <T> boolean anyMatch​(Iterable<? extends T> items,
                                   Predicate<? super T> predicate)
        Similar to the matchesAny method from Apache Commons, but does not throw on null predicates. Returns true if at least one item exists which matches the predicate. Returns false if the iterable is null or empty. A null predicate is treated as a predicate that always returns false.
        Type Parameters:
        T - Type of the items in the iterable.
        Parameters:
        items - Items to check.
        predicate - Predicate to check.
        Returns:
        true if at least one item exists which matches the predicate.

      • collectIterable

        public static <T,​A,​C> C collectIterable​(Iterable<? extends T> iterable,
                                                    Collector<? super T,​A,​? extends C> collector)
        Collects the elements of an iterable using a collector. This behaves the sames as 
             streamIterable(emptyIterableIfNull(iterable)).collect(collector);
        but is more concise to write.
        Type Parameters:
        T - Type of the items.
        A - Type of the accumulator.
        C - Type of the resulting container.
        Parameters:
        iterable - Iterable to collect.
        collector - Collector to use.
        Returns:
        The result of the collection.

      • filteredIterable

        public static <T> Iterable<T> filteredIterable​(Iterable<? extends T> iterable,
                                               Predicate<? super T> test)
        Removes all elements of the given iterable that do not match the given mapper predicate. The returned iterable will contain only the elements that match the predicate.

        Compared with filteredIterable from Apache Commons and Iterables.filter from Guava, this method (a) returns an iterable that does not allow the elements to be modified; (b) allows the iterable to be null; (c) uses the standard java.util.function.Predicate interface instead of the custom interfaces from the other libraries.

        Type Parameters:
        T - Type of the input elements.
        Parameters:
        iterable - Iterable to map. Null is treated as an empty iterable.
        test - Test predicate to apply to each element. null is treated as a predicate that returns false for all inputs.
        Returns:
        An iterable with the filtered elements.

      • firstOrNull

        public static <T> T firstOrNull​(Iterable<T> iterable)
        Similar to the first method from Apache Commons, but returns null instead of throwing if the iterable is empty.
        Type Parameters:
        T - Type of the items in the iterable.
        Parameters:
        iterable - Iterable to process.
        Returns:
        The first item in the iterable, or null if either the iterable is null or it contains no items.

      • iterableToCollection

        public static <T,​S extends Collection<T>> S iterableToCollection​(Iterable<? extends T> iterable,
                                                                       com.google.common.base.Supplier<? extends S> collectionSupplier)
        Type Parameters:
        T - Type of the items.
        S - Type of the collection.
        Parameters:
        iterable - Iterable to convert.
        collectionSupplier - Supplier for the type of collection implementation to use.
        Returns:
        A collection with the given elements.

      • iterableToCollection

        public static <T> Collection<T> iterableToCollection​(Iterable<? extends T> iterable)
        Collects the elements of an iterable into a collection. No guarantees are made regarding the type of the collection. Use one of the other methods if you need a specific type.
        Type Parameters:
        T - Type of the items.
        Parameters:
        iterable - Iterable to convert.
        Returns:
        A collection with the given elements.

      • iterableToCollection

        public static <T,​L extends Collection<T>> L iterableToCollection​(Iterable<? extends T> iterable,
                                                                       Collector<? super T,​?,​? extends L> collectionCollector)
        Collects the elements of an iterable into a collection.
        Type Parameters:
        T - Type of the items.
        L - Type of the collection.
        Parameters:
        iterable - Iterable to convert.
        collectionCollector - Collector for the collection implementation to use.
        Returns:
        A collection with the given elements.

      • iterableToList

        public static <T> List<T> iterableToList​(Iterable<? extends T> iterable)
        Collects the elements of an iterable into a list. No guarantees are made regarding the type of the list. Use one of the other methods if you need a specific type.
        Type Parameters:
        T - Type of the items.
        Parameters:
        iterable - Iterable to convert.
        Returns:
        A list with the given elements.

      • iterableToList

        public static <T,​L extends List<T>> L iterableToList​(Iterable<? extends T> iterable,
                                                           Collector<? super T,​?,​? extends L> listCollector)
        Collects the elements of an iterable into a list.
        Type Parameters:
        T - Type of the items.
        L - Type of the list.
        Parameters:
        iterable - Iterable to convert.
        listCollector - Collector for the list implementation to use.
        Returns:
        A list with the given elements.

      • iterableToList

        public static <T,​S extends List<T>> S iterableToList​(Iterable<? extends T> iterable,
                                                           com.google.common.base.Supplier<? extends S> listSupplier)
        Type Parameters:
        T - Type of the items.
        S - Type of the list.
        Parameters:
        iterable - Iterable to convert.
        listSupplier - Supplier for the type of list implementation to use.
        Returns:
        A list with the given elements.

      • iterableToSet

        public static <T> Set<T> iterableToSet​(Iterable<? extends T> iterable)
        Collects the elements of an iterable into a set. No guarantees are made regarding the type of the list. Use one of the other methods if you need a specific type.
        Type Parameters:
        T - Type of the items.
        Parameters:
        iterable - Iterable to convert.
        Returns:
        A set with the given elements.

      • iterableToSet

        public static <T,​S extends Set<T>> S iterableToSet​(Iterable<? extends T> iterable,
                                                         Collector<? super T,​?,​? extends S> setCollector)
        Type Parameters:
        T - Type of the items.
        S - Type of the set.
        Parameters:
        iterable - Iterable to convert.
        setCollector - Collector for the type of set implementation to use.
        Returns:
        A set with the given elements.

      • iterableToSet

        public static <T,​S extends Set<T>> S iterableToSet​(Iterable<? extends T> iterable,
                                                         com.google.common.base.Supplier<? extends S> setSupplier)
        Type Parameters:
        T - Type of the items.
        S - Type of the set.
        Parameters:
        iterable - Iterable to convert.
        setSupplier - Supplier for the type of set implementation to use.
        Returns:
        A set with the given elements.

      • mappedIterable

        public static <In,​Out> Iterable<Out> mappedIterable​(Iterable<? extends In> iterable,
                                                          Function<? super In,​? extends Out> mapper)
        Maps all elements of the given iterable using the given mapper function. The returned iterable will contain the mapped elements.

        Compared with transformedIterable from Apache Commons and Iterables.transform from Guava, this method (a) returns an iterable that does not allow the elements to be modified; (b) allows the iterable to be null; (c) uses the standard java.util.function.Function interface instead of the custom interfaces from the other libraries.

        Type Parameters:
        In - Type of the input elements.
        Out - Type of the output elements.
        Parameters:
        iterable - Iterable to map. Null is treated as an empty iterable.
        mapper - Mapper function to apply to each element. null is treated as a function that returns null for all inputs.
        Returns:
        An iterable with the mapped elements.

      • noneMatch

        public static <T> boolean noneMatch​(Iterable<? extends T> items,
                                    Predicate<? super T> predicate)
        Similar to the matchesNone method from Apache Commons, but does not throw on null predicates. Returns true if no item matches the given predicate. Returns true if the iterable is null or empty. A null predicate is treated as a predicate that always returns false.
        Type Parameters:
        T - Type of the items in the iterable.
        Parameters:
        items - Items to check.
        predicate - Predicate to check.
        Returns:
        true if no item exists which does not match the predicate.

      • retainWhile

        public static <T> Iterable<T> retainWhile​(Iterable<? extends T> iterable,
                                          Predicate<? super T> test)
        Applies the given test predicate to the elements of the iterable. Once the test predicate returns false, excludes all elements from that point on. The returned iterable will contain only the initial elements at the beginning that match the test predicate.
        Type Parameters:
        T - Type of the items.
        Parameters:
        iterable - Iterable to process. Null is treated as an empty iterable.
        test - Test predicate to apply on the elements. Null is treated as a predicate that always returns false.
        Returns:
        An iterable with all elements from the given iterable, but excluding all elements after the first element that does not match the test predicate.

      • toSet

        @Deprecated
public static <T> Set<T> toSet​(Iterable<? extends T> iterable)
        Deprecated.
        Use iterableToSet(Iterable) instead.
        Collects the elements of an iterable into a set. No guarantees are made regarding the type of the list. Use one of the other methods if you need a specific type.
        Type Parameters:
        T - Type of the items.
        Parameters:
        iterable - Iterable to convert.
        Returns:
        A set with the given elements.

      • toSet

        @Deprecated
public static <T,​S extends Set<T>> S toSet​(Iterable<? extends T> iterable,
                                                 Collector<? super T,​?,​? extends S> setCollector)
        Deprecated.
        Use iterableToSet(Iterable, Collector) instead.
        Type Parameters:
        T - Type of the items.
        S - Type of the set.
        Parameters:
        iterable - Iterable to convert.
        setCollector - Collector for the type of set implementation to use.
        Returns:
        A set with the given elements.

      • toSet

        @Deprecated
public static <T,​S extends Set<T>> S toSet​(Iterable<? extends T> iterable,
                                                 com.google.common.base.Supplier<? extends S> setSupplier)
        Deprecated.
        Use iterableToList(Iterable, Supplier) instead.
        Type Parameters:
        T - Type of the items.
        S - Type of the set.
        Parameters:
        iterable - Iterable to convert.
        setSupplier - Supplier for the type of set implementation to use.
        Returns:
        A set with the given elements.

      • withIndex

        public static <T> Iterable<XIterableUtils.Indexed<T>> withIndex​(Iterable<T> iterable)
        Wraps an iterable and adds the index to each element.
        Type Parameters:
        T - Type of the elements in the iterable.
        Parameters:
        iterable - Iterable to wrap.
        Returns:
        An iterable that iterates over the same elements, but with a 0-based index added to each element.

      • withIndexStreamed

        public static <T> Stream<XIterableUtils.Indexed<T>> withIndexStreamed​(Iterable<T> iterable)
        Wraps an iterable and adds the index to each element.
        Type Parameters:
        T - Type of the elements in the iterable.
        Parameters:
        iterable - Iterable to wrap.
        Returns:
        A stream that iterates over the same elements, but with a 0-based index added to each element.