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 Summary

Modifier and Type	Method	Description
static <E> Iterable<E>	chainedIterable(Iterable<? extends E>... iterables)	Combines the provided iterables into a single iterable.
static <E> Iterable<E>	chainedIterable(Iterable<? extends E> a, Iterable<? extends E> b)	Combines two iterables into a single iterable.
static <E> Iterable<E>	chainedIterable(Iterable<? extends E> a, Iterable<? extends E> b, Iterable<? extends E> c)	Combines three iterables into a single iterable.
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.
static <E> Iterable<E>	chainedIterable(Iterable<? extends Iterable<? extends E>> iterables)	Creates an Iterable that chains multiple Iterable instances into a single Iterable.
static <E> boolean	contains(Iterable<E> iterable, Object object)	Checks if the specified object is present in the given iterable.
static boolean	elementsEqual(Iterable<?> itr1, Iterable<?> itr2)	Checks if two iterables have the same elements in the same order.
static <E> Iterable<E>	filter(Iterable<?> itr, Class<E> type)	Filters an Iterable to include only elements of the specified class type.
static <E> Iterable<E>	filter(Iterable<E> itr, Predicate<? super E> predicate)	Filters an Iterable based on a given predicate.
static <T> T	find(Iterable<T> iterable, Predicate<? super T> predicate)	Returns the first element in the specified iterable that matches the given predicate.
static <T> T	get(Iterable<T> iterable, int index)	Returns the element at the specified index in the specified iterable.
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.
static <T> T	getLast(Iterable<T> iterable)	Returns the last element of the specified iterable, or null if the iterable is empty.
static boolean	isEmpty(Iterable<?> itr)	Checks if the specified iterable is empty.
static <T> Iterable<T>	limit(Iterable<T> iterable, int limitSize)	Creates an iterable limited to the specified number of elements.
static <E> boolean	matchesAll(Iterable<E> itr, Predicate<? super E> predicate)	Checks if all elements in the specified iterable match the given predicate.
static <T> Iterable<T>	mergeSorted(Iterable<? extends Iterable<? extends T>> iterables, Comparator<? super T> c)	Merges multiple sorted iterables into a single sorted iterable.
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.
static int	size(Iterable<?> itr)	Returns the number of elements in the specified iterable.
static <T> @NotNull T[]	toArray(Iterable<T> itr, Class<T> type)	Converts an Iterable to an array of the specified type.
static String	toString(Iterable<?> iterable)	Returns a string representation of the elements of the specified iterable.
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.

Methods inherited from class java.lang.Object

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

Method Detail

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:

IteratorUtils.elementsEqual(Iterator, Iterator)

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