Class XIterableUtils

java.lang.Object
de.xima.fc.utils.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 Details

    • XIterableUtils

      public XIterableUtils()

  • Method Details

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

    • filteredMappedIterable

      public static <I,O> Iterable<O> filteredMappedIterable(Iterable<? extends I> iterable, Function<? super I, ? extends O> mapper, Predicate<? super O> test)
      Combines mappedIterable and filteredIterable into a single method for convenience.

      Applies the mapper to each element of the given iterable, then removes all elements that do not match the test predicate. The returned iterable will contain only the elements that match the predicate.

      Compared with filteredIterable and mappedIterable 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:
      I - Type of the provided input elements.
      O - Type of the mapped 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.
      test - Test predicate to apply to each input element. null is treated as a predicate that returns false for all inputs.
      Returns:
      An iterable with the mapped and 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.

    • flatMappedIterable

      public static <In,Out> Iterable<Out> flatMappedIterable(Iterable<? extends In> iterable, Function<? super In, ? extends Iterable<? extends Out>> mapper)
      Maps all elements of the given iterable using the given mapper function. The returned iterable will contain the mapped elements. Each output of the given mapper is an Iterable, this method iterates over these elements.
      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.

    • flatMappedIterator

      public static <In,Out> Iterator<Out> flatMappedIterator(Iterator<? extends In> iterator, Function<? super In, ? extends Iterator<? extends Out>> mapper)
      Maps all elements of the given iterator using the given mapper function. The returned iterator will contain the mapped elements. Each output of the given mapper is an Iterator, this method iterates over these elements.
      Type Parameters:
      In - Type of the input elements.
      Out - Type of the output elements.
      Parameters:
      iterator - Iterator to map. Null is treated as an empty iterator.
      mapper - Mapper function to apply to each element. null is treated as a function that returns null for all inputs.
      Returns:
      An iterator with the mapped elements.

    • iterableAsCollection

      public static <T> Collection<T> iterableAsCollection(Iterable<T> iterable)
      Similar to iterableToCollection(Iterable), but returns the given iterable unchanged if already a collection. iterableToCollection(Iterable) always returns a new collection.
      Type Parameters:
      T - Type of the items.
      Parameters:
      iterable - Iterable to convert.
      Returns:
      A collection with the given elements.

    • iterableAsList

      public static <T> List<T> iterableAsList(Iterable<T> iterable)
      Similar to iterableToList(Iterable), but returns the given iterable unchanged if already a list. iterableToList(Iterable) always returns a new list.
      Type Parameters:
      T - Type of the items.
      Parameters:
      iterable - Iterable to convert.
      Returns:
      A list with the given elements.

    • iterableAsSet

      public static <T> Set<T> iterableAsSet(Iterable<T> iterable)
      Similar to iterableToSet(Iterable), but returns the given iterable unchanged if already a set. iterableToSet(Iterable) always returns a new set.
      Type Parameters:
      T - Type of the items.
      Parameters:
      iterable - Iterable to convert.
      Returns:
      A set with the given elements.

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

    • mappedFilteredIterable

      public static <I,O> Iterable<O> mappedFilteredIterable(Iterable<? extends I> iterable, Predicate<? super I> test, Function<? super I, ? extends O> mapper)
      Combines filteredIterable and mappedIterable into a single method for convenience.

      Removes all elements of the given iterable that do not match the given test predicate, then apply the mapper function. The returned iterable will contain only the elements that match the predicate.

      Compared with filteredIterable and mappedIterable 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:
      I - Type of the input elements.
      O - Type of the output elements.
      Parameters:
      iterable - Iterable to map. Null is treated as an empty iterable.
      test - Test predicate to apply to each mapped element. null is treated as a predicate that returns false for all inputs.
      mapper - Mapper function to apply to each input element. null is treated as a function that returns null for all inputs.
      Returns:
      An iterable with the filtered and mapped 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.

    • mappedIterator

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

      Compared with transformedIterator from Apache Commons and Iterators.transform from Guava, this method (a) returns an iterator that does not allow the elements to be modified; (b) allows the iterator 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:
      iterator - Iterator to map. Null is treated as an empty iterator.
      mapper - Mapper function to apply to each element. null is treated as a function that returns null for all inputs.
      Returns:
      An iterator 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.