Package eu.bandm.tools.util.java

Class Iterables

java.lang.Object
eu.bandm.tools.util.java.Iterables
public final class Iterables extends Object
Library of constants and operations for working with iterable objects.

The stream framework covers most needs for high-level operations on sequences of values. The methods of this class may be a useful light-weight alternative where streams would introduce too much notational or computational complexity.

See Also:

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static interface 
    Iterables.Cached<A>
    A list that is populated lazily on demand.

  • Method Summary

    Modifier and Type
    Method
    Description
    static <A, B> boolean
    allZip(BiPredicate<? super A,? super B> rel, Iterable<? extends A> left, Iterable<? extends B> right)
    Checks whether all corresponding pairs of elements are in a given relation.
    static <E> Optional<E>
    anyOf(Iterable<E> things)
    Returns an arbitrary element, if available.
    static <A, B> boolean
    anyZip(BiPredicate<? super A,? super B> rel, Iterable<? extends A> left, Iterable<? extends B> right)
    Checks whether any corresponding pairs of elements are in a given relation.
    static <A> Iterables.Cached<A>
    cache(Iterable<A> things)
    Returns a view on an iterable that stores iterated values in a list.
    static <A> Iterable<A>
    concat(Iterable<? extends A> first, Iterable<? extends A> second)
    Returns a view on two iterables that contains both their elements in order.
    static <A> Iterable<A>
    cons(A first, Iterable<A> rest)
    Returns a view on an iterable that contains one more element at the start.
    static <A> Iterable<A>
    drop(int offset, Iterable<A> things)
    Returns a view on an iterable that has the same elements, except the first ones.
    static <A> Iterable<A>
    dropTake(int offset, int length, Iterable<A> things)
    Combines the effects of drop and take.
    static <A> Iterable<A>
    empty()
    Returns an empty iterable.
    static <A> Iterable<A>
    filter(Predicate<? super A> pred, Iterable<A> things)
    Returns a view on an iterable that contains only those elements that match a given predicate.
    static <A, B> Iterable<A>
    filterWithConstraint(BiPredicate<? super A,? super B> rel, Iterable<A> things, Iterable<B> constraints)
    Returns a view on an iterable that contains only those elements that match with a corresponding constraint.
    static <E> Optional<E>
    firstOf(Iterable<E> things)
    Returns the first element, if available.
    static <A, B> Iterable<B>
    flatMap(Function<? super A,? extends Iterable<? extends B>> fun, Iterable<A> items)
    Returns a concatenation of subsequences computed with a function.
    static <A> Iterable<A>
    flatten(Iterable<? extends Iterable<? extends A>> items)
    Returns a view on an iterable of iterables that contains all of their elements.
    static <T> void
    forEachPair(Iterable<T> data, @Opt Consumer<T> first, BiConsumer<T,T> pairwise, @Opt Consumer<T> last)
    Performs the given action for all remaining pairs of adjacent elements delivered by the iterator, as well as for the first and last singleton, in order.
    static <T> void
    forEachPair(Iterable<T> data, BiConsumer<T,T> pairwise)
    Performs the given action for all remaining pairs of adjacent elements delivered by the iterator, in order.
    static <T> void
    forEachTriple(Iterable<T> data, TriConsumer<@Opt T,@Opt T,@Opt T> consumer)
    Performs the given action for all remaining triples of adjacent elements delivered by the iterator, including partial ones, in order.
    static <A, B> Iterable<B>
    map(Function<? super A,? extends B> fun, Iterable<? extends A> things)
    Returns a view on an iterable that has all elements transformed by a given function.
    static <A> Iterable<A>
    merge(Comparator<? super A> order, boolean removeDuplicates, Iterable<? extends A> left, Iterable<? extends A> right)
    Returns the merged combination of two ordered sequences.
    static <A> Iterable<A>
    next(Iterable<A> things)
    Returns a view on an iterable that contains the same elements, except the first one.
    static <E> Iterable<E>
    of(E... things)
    Returns an iterable view containing exactly the given elements.
    static <A> Iterable<A>
    singleton(A item)
    Returns an iterable that contains exactly one element.
    static <A> Iterable<A>
    take(int length, Iterable<A> things)
    Returns a view on an iterable that has the same elements, up to a given length.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Method Details

    • empty

      public static <A> Iterable<A> empty()
      Returns an empty iterable.
      Type Parameters:
      A - the element type
      Returns:
      an iterable that has no elements

    • map

      public static <A, B> Iterable<B> map(Function<? super A,? extends B> fun, Iterable<? extends A> things)
      Returns a view on an iterable that has all elements transformed by a given function.

      Changes to the underlying iterable are reflected in the result.

      Type Parameters:
      A - the source element type
      B - the target element type
      Parameters:
      fun - a transformer function
      things - some elements
      Returns:
      an iterable where each element is computed on the fly by applying fun to the corresponding element of things
      Throws:
      NullPointerException - if fun or things is null

    • singleton

      public static <A> Iterable<A> singleton(A item)
      Returns an iterable that contains exactly one element.
      Type Parameters:
      A - the element type
      Parameters:
      item - the element
      Returns:
      an iterable that contains just the given element

    • of

      @SafeVarargs public static <E> Iterable<E> of(E... things)
      Returns an iterable view containing exactly the given elements.

      Changes to the underlying array are reflected in the result.

      This method differs from Arrays.asList(T...) by not disclosing the number of available elements.

      Type Parameters:
      E - the element type
      Parameters:
      things - an array of elements
      Returns:
      an iterable containing exactly the given elements in order
      See Also:

    • flatten

      public static <A> Iterable<A> flatten(Iterable<? extends Iterable<? extends A>> items)
      Returns a view on an iterable of iterables that contains all of their elements.

      Changes to the underlying iterable(s) are reflected by the resulting view.

      Type Parameters:
      A - the type of elements
      Parameters:
      items - an iterable of iterables of elements
      Returns:
      an unmodifiable iterable that contains all elements that are contained in an iterable contained in items

    • flatMap

      public static <A, B> Iterable<B> flatMap(Function<? super A,? extends Iterable<? extends B>> fun, Iterable<A> items)
      Returns a concatenation of subsequences computed with a function.
      Type Parameters:
      A - the source element type
      B - the target element type
      Parameters:
      fun - a function that computes a subsequence of target elements from a single source element
      items - the source elements
      Returns:
      the concatenation of the subsequences obtained by applying fun to all source elements in order

    • cons

      public static <A> Iterable<A> cons(A first, Iterable<A> rest)
      Returns a view on an iterable that contains one more element at the start.

      Changes to the underlying iterable are reflected in the result.

      Type Parameters:
      A - the element type
      Parameters:
      first - the new first element
      rest - the other elements
      Returns:
      an iterable that, upon iteration, produces the first followed by the other elements
      Throws:
      NullPointerException - if rest is null

    • concat

      public static <A> Iterable<A> concat(Iterable<? extends A> first, Iterable<? extends A> second)
      Returns a view on two iterables that contains both their elements in order.

      Changes to the underlying iterables are reflected in the result.

      Type Parameters:
      A - the element type
      Parameters:
      first - the first part of elements
      second - the second part of elements
      Returns:
      an iterables that contains all elements of first followed by all elements of second
      Throws:
      NullPointerException - if first or second is null

    • filter

      public static <A> Iterable<A> filter(Predicate<? super A> pred, Iterable<A> things)
      Returns a view on an iterable that contains only those elements that match a given predicate.

      Changes to the underlying iterable are reflected in the result.

      Type Parameters:
      A - the element type
      Parameters:
      pred - a predicate specifying which elements to retain
      things - some elements
      Returns:
      an iterable that contains all elements of things for which pred returns true, in order
      Throws:
      NullPointerException - if pred or things is null

    • cache

      public static <A> Iterables.Cached<A> cache(Iterable<A> things)
      Returns a view on an iterable that stores iterated values in a list.

      This is useful if the underlying iterable computes elements expensively on the demand.

      Behavior is unspecified if the underlying iterable is mutable.

      The resulting list call for elements on demand. Iteration over the list requires elements one at a time. Some other list operations, such as calculating the size or comparison with another list, require all elements at once.

      Type Parameters:
      A - the element type
      Parameters:
      things - an iterable (that computes elements on demand)
      Returns:
      a list that is populated with elements on demand

    • next

      public static <A> Iterable<A> next(Iterable<A> things)
      Returns a view on an iterable that contains the same elements, except the first one.

      Changes to the underlying iterable are reflected in the result.

      When Iterable.iterator() is called on the result and the underlying iterable is empty, a NoSuchElementException is thrown.

      Type Parameters:
      A - the element type
      Parameters:
      things - some elements
      Returns:
      an iterable that contains all given elements except the first one

    • allZip

      public static <A, B> boolean allZip(BiPredicate<? super A,? super B> rel, Iterable<? extends A> left, Iterable<? extends B> right)
      Checks whether all corresponding pairs of elements are in a given relation.

      There must be as many left elements as right elements to relate.

      Type Parameters:
      A - the left element type
      B - the right element type
      Parameters:
      rel - the relation on pairs of a left and a right element
      left - the left elements
      right - the right elements
      Returns:
      true if rel returns true for all pairs of the i-th left and the i-th right element
      Throws:
      IllegalArgumentException - if there are differently many left and right elements, and the result has not been determined up to that point
      NullPointerException - if rel, left or right is null

    • anyZip

      public static <A, B> boolean anyZip(BiPredicate<? super A,? super B> rel, Iterable<? extends A> left, Iterable<? extends B> right)
      Checks whether any corresponding pairs of elements are in a given relation.

      There must be as many left elements as right elements to relate.

      Type Parameters:
      A - the left element type
      B - the right element type
      Parameters:
      rel - the relation on pairs of a left and a right element
      left - the left elements
      right - the right elements
      Returns:
      true if rel returns true for at least one pair of the i-th left and the i-th right element
      Throws:
      IllegalArgumentException - if there are differently many left and right elements, and the result has not been determined up to that point
      NullPointerException - if rel, left or right is null

    • merge

      public static <A> Iterable<A> merge(Comparator<? super A> order, boolean removeDuplicates, Iterable<? extends A> left, Iterable<? extends A> right)
      Returns the merged combination of two ordered sequences.

      Each input sequence is iterated over exactly once.

      Type Parameters:
      A - the element type
      Parameters:
      order - the ordering of both inputs and the result
      removeDuplicates - duplicates are removed if true, or retained if false
      left - the first ordered sequence of elements
      right - the second ordered sequence of elements
      Returns:
      an ordered sequence that contains the elements of both inputs, possibly without duplicates
      Throws:
      NullPointerException - if order, left or right is null

    • filterWithConstraint

      public static <A, B> Iterable<A> filterWithConstraint(BiPredicate<? super A,? super B> rel, Iterable<A> things, Iterable<B> constraints)
      Returns a view on an iterable that contains only those elements that match with a corresponding constraint.

      Changes to the underlying iterables are reflected in the result.

      Type Parameters:
      A - the element type
      B - the constraint type
      Parameters:
      rel - a binary predicate on elements and constraints specifying which elements to retain
      things - some elements
      constraints - some constraints
      Returns:
      an iterable that contains, for all i, the i-th element of things for which rel returns true when paired with the i-th constraint, in order
      Throws:
      IllegalArgumentException - if there are fewer constraints than elements
      NullPointerException - if pred or things is null

    • drop

      public static <A> Iterable<A> drop(int offset, Iterable<A> things)
      Returns a view on an iterable that has the same elements, except the first ones.

      Changes to the underlying iterable are reflected in the result.

      If more elements were to be dropped than available, the result is simply empty.

      Type Parameters:
      A - the element type
      Parameters:
      offset - the number of elements to discard from the start of each iteration
      things - some elements
      Returns:
      an iterable that has the same elements as things, except for offset many that are discarded at the start of iteration
      Throws:
      IllegalArgumentException - if offset is negative
      NullPointerException - if things is null
      See Also:

    • take

      public static <A> Iterable<A> take(int length, Iterable<A> things)
      Returns a view on an iterable that has the same elements, up to a given length.

      Changes to the underlying iterable are reflected in the result.

      If more elements were to be retained than available, the result is simply equivalent to the input.

      Type Parameters:
      A - the element type
      Parameters:
      length - the number of elements to retain from each iteration
      things - some elements
      Returns:
      an iterable that has the same first elements as things, but ends after length
      Throws:
      IllegalArgumentException - if length is negative
      NullPointerException - if things is null
      See Also:

    • dropTake

      public static <A> Iterable<A> dropTake(int offset, int length, Iterable<A> things)
      Combines the effects of drop and take.
      Type Parameters:
      A - the element type
      Parameters:
      offset - the number of elements to discard from the start of each iteration
      length - the number of elements to retain from each iteration
      things - some elements
      Returns:
      an iterable that has the same elements as things, except for offset many that are discarded at the start of iteration, but ends after length
      Throws:
      IllegalArgumentException - if offset or length is negative
      NullPointerException - if things is null
      See Also:

    • anyOf

      public static <E> Optional<E> anyOf(Iterable<E> things)
      Returns an arbitrary element, if available. If the iterables is meta-stable, then the returned element will be the same until a change of content.
      Type Parameters:
      E - the element type
      Parameters:
      things - some elements
      Returns:
      an optional value that contains an arbitrarily chosen element if there is one, or the empty optional value if there are no elements

    • firstOf

      public static <E> Optional<E> firstOf(Iterable<E> things)
      Returns the first element, if available.
      Type Parameters:
      E - the element type
      Parameters:
      things - some elements
      Returns:
      an optional value that contains the first (by iteration order) element if there is one, or the empty optional value if there are no elements

    • forEachPair

      public static <T> void forEachPair(Iterable<T> data, BiConsumer<T,T> pairwise)
      Performs the given action for all remaining pairs of adjacent elements delivered by the iterator, in order.
      Type Parameters:
      T - the element type
      Parameters:
      data - some elements
      pairwise - the action to perform
      See Also:

    • forEachPair

      public static <T> void forEachPair(Iterable<T> data, @Opt @Opt Consumer<T> first, BiConsumer<T,T> pairwise, @Opt @Opt Consumer<T> last)
      Performs the given action for all remaining pairs of adjacent elements delivered by the iterator, as well as for the first and last singleton, in order.
      Type Parameters:
      T - the element type
      Parameters:
      data - some elements
      first - the action to perform for the first singleton, or null for no action
      pairwise - the action to perform for pairs
      last - the action to perform for the last singleton, or null for no action
      See Also:

    • forEachTriple

      public static <T> void forEachTriple(Iterable<T> data, TriConsumer<@Opt T,@Opt T,@Opt T> consumer)
      Performs the given action for all remaining triples of adjacent elements delivered by the iterator, including partial ones, in order.

      If the data is completely empty, no action is performed. Otherwise the schema for binding the parameters of the code e.g. from a four element list is as follows: 

            null null #0
      null #0   #1
      #0   #1   #2
      #1   #2   #3
      #2   #3   null
      #3   null null
      Type Parameters:
      T - the element type
      Parameters:
      data - some elements
      consumer - the action to perform