Package org.apache.jackrabbit.oak.commons.collections

Class IterableUtils

java.lang.Object
org.apache.jackrabbit.oak.commons.collections.IterableUtils
public class IterableUtils extends Object
Utility methods for Iterable conversions.

  • Method Details

    • chainedIterable

      public static <E> Iterable<E> chainedIterable(Iterable<? extends E> a, Iterable<? extends E> b)
      Combines two iterables into a single iterable.

      The returned iterable has an iterator that traverses the elements in a, followed by the elements in b. The source iterators are not polled until necessary.

      The returned iterable's iterator supports remove() when the corresponding input iterator supports it.

      Type Parameters:
      E - the element type
      Parameters:
      a - the first iterable, may not be null
      b - the second iterable, may not be null
      Returns:
      a new iterable, combining the provided iterables
      Throws:
      NullPointerException - if either of the provided iterables is null

    • chainedIterable

      public static <E> Iterable<E> chainedIterable(Iterable<? extends E> a, Iterable<? extends E> b, Iterable<? extends E> c)
      Combines three iterables into a single iterable.

      The returned iterable has an iterator that traverses the elements in a, followed by the elements in b and c. The source iterators are not polled until necessary.

      The returned iterable's iterator supports remove() when the corresponding input iterator supports it.

      Type Parameters:
      E - the element type
      Parameters:
      a - the first iterable, may not be null
      b - the second iterable, may not be null
      c - the third iterable, may not be null
      Returns:
      a new iterable, combining the provided iterables
      Throws:
      NullPointerException - if either of the provided iterables is null

    • chainedIterable

      public static <E> Iterable<E> chainedIterable(Iterable<? extends E> a, Iterable<? extends E> b, Iterable<? extends E> c, Iterable<? extends E> d)
      Combines four iterables into a single iterable.

      The returned iterable has an iterator that traverses the elements in a, followed by the elements in b, c and d. The source iterators are not polled until necessary.

      The returned iterable's iterator supports remove() when the corresponding input iterator supports it.

      Type Parameters:
      E - the element type
      Parameters:
      a - the first iterable, may not be null
      b - the second iterable, may not be null
      c - the third iterable, may not be null
      d - the fourth iterable, may not be null
      Returns:
      a new iterable, combining the provided iterables
      Throws:
      NullPointerException - if either of the provided iterables is null

    • chainedIterable

      @SafeVarargs public static <E> Iterable<E> chainedIterable(Iterable<? extends E>... iterables)
      Combines the provided iterables into a single iterable.

      The returned iterable has an iterator that traverses the elements in the order of the arguments, i.e. iterables[0], iterables[1], .... The source iterators are not polled until necessary.

      The returned iterable's iterator supports remove() when the corresponding input iterator supports it.

      Type Parameters:
      E - the element type
      Parameters:
      iterables - the iterables to combine, may not be null
      Returns:
      a new iterable, combining the provided iterables
      Throws:
      NullPointerException - if either of the provided iterables is null

    • chainedIterable

      public static <E> Iterable<E> chainedIterable(Iterable<? extends Iterable<? extends E>> iterables)
      Creates an Iterable that chains multiple Iterable instances into a single Iterable.

      The returned Iterable will iterate over all elements of the first Iterable, then all elements of the second, and so on.

      Type Parameters:
      E - the type of elements returned by the iterator
      Parameters:
      iterables - an Iterable of Iterable instances to be chained
      Returns:
      an Iterable that provides a single view of all elements in the input Iterable instances
      Throws:
      NullPointerException - if the input Iterable or any of its elements are null

    • contains

      public static <E> boolean contains(Iterable<E> iterable, Object object)
      Checks if the specified object is present in the given iterable.
      Type Parameters:
      E - the type of elements in the iterable
      Parameters:
      iterable - the iterable to search, may not be null
      object - the object to find, may be null
      Returns:
      true if the iterable contains the object, false otherwise
      Throws:
      NullPointerException - if the iterable is null

    • size

      public static int size(Iterable<?> itr)
      Returns the number of elements in the specified iterable.
      Parameters:
      itr - the iterable to count elements in, may not be null
      Returns:
      the number of elements in the iterable
      Throws:
      NullPointerException - if the iterable is null

    • matchesAll

      public static <E> boolean matchesAll(Iterable<E> itr, Predicate<? super E> predicate)
      Checks if all elements in the specified iterable match the given predicate.
      Type Parameters:
      E - the type of elements in the iterable
      Parameters:
      itr - the iterable to check, may not be null
      predicate - the predicate to apply to elements, may not be null
      Returns:
      true if all elements match the predicate, false otherwise
      Throws:
      NullPointerException - if the iterable or predicate is null

    • isEmpty

      public static boolean isEmpty(Iterable<?> itr)
      Checks if the specified iterable is empty.
      Parameters:
      itr - the iterable to check, may be null
      Returns:
      true if the iterable is empty or null, false otherwise

    • toArray

      @NotNull public static <T> @NotNull T[] toArray(Iterable<T> itr, Class<T> type)
      Converts an Iterable to an array of the specified type.
      Type Parameters:
      T - the type of elements in the itr
      Parameters:
      itr - the itr to convert, may be null
      type - the class of the type of elements in the array, may not be null
      Returns:
      an array containing the elements of the itr
      Throws:
      NullPointerException - if the itr or type is null

    • partition

      public static <T> Iterable<List<T>> partition(Iterable<T> itr, int size)
      Splits an Iterable into an Iterator of sub-iterators, each of the specified size.
      Type Parameters:
      T - the type of elements in the itr
      Parameters:
      itr - the itr to split, may not be null
      size - the size of each sub-iterator, must be greater than 0
      Returns:
      an iterator of sub-iterators, each of the specified size
      Throws:
      NullPointerException - if the itr is null
      IllegalArgumentException - if size is less than or equal to 0

    • filter

      public static <E> Iterable<E> filter(Iterable<E> itr, Predicate<? super E> predicate)
      Filters an Iterable based on a given predicate.
      Type Parameters:
      E - the type of elements in the iterable
      Parameters:
      itr - the iterable to filter, may not be null
      predicate - the predicate to apply to elements, may not be null
      Returns:
      an iterable containing only the elements that match the predicate
      Throws:
      NullPointerException - if the iterable or predicate is null

    • filter

      public static <E> Iterable<E> filter(Iterable<?> itr, Class<E> type)
      Filters an Iterable to include only elements of the specified class type.
      Type Parameters:
      E - the type of elements to include
      Parameters:
      itr - the iterable to filter, may not be null
      type - the class type to filter by, may not be null
      Returns:
      an iterable containing only the elements of the specified class type
      Throws:
      NullPointerException - if the iterable or class type is null

    • transform

      public static <I, O> Iterable<O> transform(Iterable<I> iterable, Function<? super I,? extends O> function)
      Transforms an Iterable by applying a given function to each element.
      Type Parameters:
      I - the type of input elements
      O - the type of output elements
      Parameters:
      iterable - the iterable to transform, must not be null
      function - the function to apply to each element, must not be null
      Returns:
      an iterable containing the transformed elements
      Throws:
      NullPointerException - if the iterable or function is null

    • mergeSorted

      public static <T> Iterable<T> mergeSorted(Iterable<? extends Iterable<? extends T>> iterables, Comparator<? super T> c)
      Merges multiple sorted iterables into a single sorted iterable.
      Type Parameters:
      T - the type of elements returned by this iterable
      Parameters:
      iterables - the iterables to merge, must not be null
      c - the c to determine the order of elements, must not be null
      Returns:
      an iterable that merges the input iterables in sorted order
      Throws:
      NullPointerException - if the iterables or c are null

    • elementsEqual

      public static boolean elementsEqual(Iterable<?> itr1, Iterable<?> itr2)
      Checks if two iterables have the same elements in the same order.

      This method iterates through both iterables and compares each corresponding pair of elements using Objects.equals(Object, Object).

      Note that both iterables will be fully traversed during the comparison.

      Parameters:
      itr1 - the first iterable to compare, may be null
      itr2 - the second iterable to compare, may be null
      Returns:
      true if both iterables contain the same elements in the same order, false otherwise. Returns true if both iterables are null and false if only one is null.
      See Also:

    • limit

      public static <T> Iterable<T> limit(Iterable<T> iterable, int limitSize)
      Creates an iterable limited to the specified number of elements.

      The returned iterable's iterator will stop returning elements after the specified limit has been reached or when the source iterable's iterator is exhausted, whichever comes first.

      The returned iterable's iterator supports remove() if the original iterator supports it.

      Type Parameters:
      T - the type of elements in the iterable
      Parameters:
      iterable - the iterable to limit, may be null
      limitSize - the maximum number of elements to return
      Returns:
      a limited iterable
      Throws:
      IllegalArgumentException - if limitSize is negative

    • toString

      public static String toString(Iterable<?> iterable)
      Returns a string representation of the elements of the specified iterable.

      The string representation consists of a list of the iterable's elements, enclosed in square brackets ("[]"). Adjacent elements are separated by the characters ", " (a comma followed by a space). Elements are converted to strings as by String.valueOf(Object).

      Parameters:
      iterable - the iterable to convert to a string, may be null
      Returns:
      a string representation of iterable

    • getFirst

      public static <T> T getFirst(Iterable<T> iterable, T defaultValue)
      Returns the first element of the specified iterable, or the default value if the iterable is empty.

      The iterable is only traversed enough to get the first element. If the iterable is empty, the default value is returned instead.

      Type Parameters:
      T - the type of elements in the iterable
      Parameters:
      iterable - the iterable to get the first element from, may be null
      defaultValue - the value to return if the iterable is empty
      Returns:
      the first element in the iterable or the default value if the iterable is empty
      Throws:
      NullPointerException - if the iterable is null

    • get

      public static <T> T get(Iterable<T> iterable, int index)
      Returns the element at the specified index in the specified iterable.

      The iterable is traversed until the specified index is reached. If the position is greater than the number of elements in the iterable, an IndexOutOfBoundsException is thrown.

      Type Parameters:
      T - the type of elements in the iterable
      Parameters:
      iterable - the iterable to get the element from, must not be null
      index - the index of the element to retrieve, must be non-negative
      Returns:
      the element at the specified index
      Throws:
      NullPointerException - if the iterable is null
      IndexOutOfBoundsException - if the position is negative or greater than the number of elements in the iterable

    • find

      public static <T> T find(Iterable<T> iterable, Predicate<? super T> predicate)
      Returns the first element in the specified iterable that matches the given predicate.

      The iterable is traversed until an element is found that satisfies the predicate. If no element satisfies the predicate, null is returned.

      Type Parameters:
      T - the type of elements in the iterable
      Parameters:
      iterable - the iterable to search, must not be null
      predicate - the predicate to apply, must not be null
      Returns:
      the first element that satisfies the predicate, or null if no such element exists
      Throws:
      NullPointerException - if either the iterable or predicate is null

    • getLast

      public static <T> T getLast(Iterable<T> iterable)
      Returns the last element of the specified iterable, or null if the iterable is empty.

      The iterable must be fully traversed to find the last element.

      Type Parameters:
      T - the type of elements in the iterable
      Parameters:
      iterable - the iterable to get the last element from, must not be null
      Returns:
      the last element in the iterable or null if the iterable is empty