public class IterableUtils extends Object
Iterable instances.
Note: this util class has been designed for fail-fast argument checking.
NullPointerException if a null Iterable is passed as argument.
Predicate, will result in a NullPointerException. Exception: passing
a null Comparator is equivalent to a Comparator with natural ordering.
| Constructor and Description |
|---|
IterableUtils() |
| Modifier and Type | Method and Description |
|---|---|
static <E> Iterable<E> |
boundedIterable(Iterable<E> iterable,
long maxSize)
Returns a view of the given iterable that contains at most the given number
of elements.
|
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> |
collatedIterable(Comparator<? super E> comparator,
Iterable<? extends E> a,
Iterable<? extends E> b)
Combines the two provided iterables into an ordered iterable using the
provided comparator.
|
static <E> Iterable<E> |
collatedIterable(Iterable<? extends E> a,
Iterable<? extends E> b)
Combines the two provided iterables into an ordered iterable using
natural ordering.
|
static <E> boolean |
contains(Iterable<? extends E> iterable,
E object,
Equator<? super E> equator)
Checks if the object is contained in the given iterable.
|
static <E> boolean |
contains(Iterable<E> iterable,
Object object)
Checks if the object is contained in the given iterable.
|
static <E> long |
countMatches(Iterable<E> input,
Predicate<? super E> predicate)
Counts the number of elements in the input iterable that match the predicate.
|
static <E> Iterable<E> |
emptyIfNull(Iterable<E> iterable)
Returns an immutable empty iterable if the argument is null,
or the argument itself otherwise.
|
static <E> Iterable<E> |
emptyIterable()
Gets an empty iterable.
|
static <E> Iterable<E> |
filteredIterable(Iterable<E> iterable,
Predicate<? super E> predicate)
Returns a view of the given iterable that only contains elements matching
the provided predicate.
|
static <E> E |
find(Iterable<E> iterable,
Predicate<? super E> predicate)
Finds the first element in the given iterable which matches the given predicate.
|
static <T> T |
first(Iterable<T> iterable)
Shortcut for
get(iterator, 0). |
static <E> void |
forEach(Iterable<E> iterable,
Closure<? super E> closure)
Applies the closure to each element of the provided iterable.
|
static <E> E |
forEachButLast(Iterable<E> iterable,
Closure<? super E> closure)
Executes the given closure on each but the last element in the iterable.
|
static <E,T extends E> |
frequency(Iterable<E> iterable,
T obj)
Returns the number of occurrences of the provided object in the iterable.
|
static <T> T |
get(Iterable<T> iterable,
int index)
Returns the
index-th value in the iterable's Iterator, throwing
IndexOutOfBoundsException if there is no such element. |
static <E> int |
indexOf(Iterable<E> iterable,
Predicate<? super E> predicate)
Returns the index of the first element in the specified iterable that
matches the given predicate.
|
static boolean |
isEmpty(Iterable<?> iterable)
Answers true if the provided iterable is empty.
|
static <E> Iterable<E> |
loopingIterable(Iterable<E> iterable)
Returns a view of the given iterable which will cycle infinitely over
its elements.
|
static <E> boolean |
matchesAll(Iterable<E> iterable,
Predicate<? super E> predicate)
Answers true if a predicate is true for every element of an iterable.
|
static <E> boolean |
matchesAny(Iterable<E> iterable,
Predicate<? super E> predicate)
Answers true if a predicate is true for any element of the iterable.
|
static <O,R extends Collection<O>> |
partition(Iterable<? extends O> iterable,
Factory<R> partitionFactory,
Predicate<? super O>... predicates)
Partitions all elements from iterable into separate output collections,
based on the evaluation of the given predicates.
|
static <O> List<List<O>> |
partition(Iterable<? extends O> iterable,
Predicate<? super O>... predicates)
Partitions all elements from iterable into separate output collections,
based on the evaluation of the given predicates.
|
static <O> List<List<O>> |
partition(Iterable<? extends O> iterable,
Predicate<? super O> predicate)
Partitions all elements from iterable into separate output collections,
based on the evaluation of the given predicate.
|
static <E> Iterable<E> |
reversedIterable(Iterable<E> iterable)
Returns a reversed view of the given iterable.
|
static int |
size(Iterable<?> iterable)
Returns the number of elements contained in the given iterator.
|
static <E> Iterable<E> |
skippingIterable(Iterable<E> iterable,
long elementsToSkip)
Returns a view of the given iterable that skips the first N elements.
|
static <E> List<E> |
toList(Iterable<E> iterable)
Gets a new list with the contents of the provided iterable.
|
static <E> String |
toString(Iterable<E> iterable)
Returns a string representation of the elements of the specified iterable.
|
static <E> String |
toString(Iterable<E> iterable,
Transformer<? super E,String> transformer)
Returns a string representation of the elements of the specified iterable.
|
static <E> String |
toString(Iterable<E> iterable,
Transformer<? super E,String> transformer,
String delimiter,
String prefix,
String suffix)
Returns a string representation of the elements of the specified iterable.
|
static <I,O> Iterable<O> |
transformedIterable(Iterable<I> iterable,
Transformer<? super I,? extends O> transformer)
Returns a transformed view of the given iterable where all of its elements
have been transformed by the provided transformer.
|
static <E> Iterable<E> |
uniqueIterable(Iterable<E> iterable)
Returns a unique view of the given iterable.
|
static <E> Iterable<E> |
unmodifiableIterable(Iterable<E> iterable)
Returns an unmodifiable view of the given iterable.
|
static <E> Iterable<E> |
zippingIterable(Iterable<? extends E> first,
Iterable<? extends E>... others)
Interleaves two iterables into a single iterable.
|
static <E> Iterable<E> |
zippingIterable(Iterable<? extends E> a,
Iterable<? extends E> b)
Interleaves two iterables into a single iterable.
|
public IterableUtils()
public static <E> Iterable<E> emptyIterable()
This iterable does not contain any elements.
E - the element typepublic static <E> Iterable<E> chainedIterable(Iterable<? extends E> a, Iterable<? extends E> b)
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.
E - the element typea - the first iterable, may not be nullb - the second iterable, may not be nullNullPointerException - if either a or b is nullpublic static <E> Iterable<E> chainedIterable(Iterable<? extends E> a, Iterable<? extends E> b, Iterable<? extends E> c)
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.
E - the element typea - the first iterable, may not be nullb - the second iterable, may not be nullc - the third iterable, may not be nullNullPointerException - if either of the provided iterables is nullpublic static <E> Iterable<E> chainedIterable(Iterable<? extends E> a, Iterable<? extends E> b, Iterable<? extends E> c, Iterable<? extends E> d)
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.
E - the element typea - the first iterable, may not be nullb - the second iterable, may not be nullc - the third iterable, may not be nulld - the fourth iterable, may not be nullNullPointerException - if either of the provided iterables is nullpublic static <E> Iterable<E> chainedIterable(Iterable<? extends E>... iterables)
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.
E - the element typeiterables - the iterables to combine, may not be nullNullPointerException - if either of the provided iterables is nullpublic static <E> Iterable<E> collatedIterable(Iterable<? extends E> a, Iterable<? extends E> b)
The returned iterable's iterator supports remove() when the
corresponding input iterator supports it.
E - the element typea - the first iterable, may not be nullb - the second iterable, may not be nullNullPointerException - if either of the provided iterables is nullpublic static <E> Iterable<E> collatedIterable(Comparator<? super E> comparator, Iterable<? extends E> a, Iterable<? extends E> b)
The returned iterable's iterator supports remove() when the
corresponding input iterator supports it.
E - the element typecomparator - the comparator defining an ordering over the elements,
may be null, in which case natural ordering will be useda - the first iterable, may not be nullb - the second iterable, may not be nullNullPointerException - if either of the provided iterables is nullpublic static <E> Iterable<E> filteredIterable(Iterable<E> iterable, Predicate<? super E> predicate)
The returned iterable's iterator supports remove() when the
corresponding input iterator supports it.
E - the element typeiterable - the iterable to filter, may not be nullpredicate - the predicate used to filter elements, may not be nullNullPointerException - if either iterable or predicate is nullpublic static <E> Iterable<E> boundedIterable(Iterable<E> iterable, long maxSize)
The returned iterable's iterator supports remove() when the corresponding
input iterator supports it.
E - the element typeiterable - the iterable to limit, may not be nullmaxSize - the maximum number of elements, must not be negativeIllegalArgumentException - if maxSize is negativeNullPointerException - if iterable is nullpublic static <E> Iterable<E> loopingIterable(Iterable<E> iterable)
The returned iterable's iterator supports remove() if
iterable.iterator() does. After remove() is called, subsequent
cycles omit the removed element, which is no longer in iterable. The
iterator's hasNext() method returns true until iterable
is empty.
E - the element typeiterable - the iterable to loop, may not be nullNullPointerException - if iterable is nullpublic static <E> Iterable<E> reversedIterable(Iterable<E> iterable)
In case the provided iterable is a List instance, a
ReverseListIterator will be used to reverse the traversal
order, otherwise an intermediate List needs to be created.
The returned iterable's iterator supports remove() if the
provided iterable is a List instance.
E - the element typeiterable - the iterable to use, may not be nullNullPointerException - if iterable is nullReverseListIteratorpublic static <E> Iterable<E> skippingIterable(Iterable<E> iterable, long elementsToSkip)
The returned iterable's iterator supports remove() when the corresponding
input iterator supports it.
E - the element typeiterable - the iterable to use, may not be nullelementsToSkip - the number of elements to skip from the start, must not be negativeIllegalArgumentException - if elementsToSkip is negativeNullPointerException - if iterable is nullpublic static <I,O> Iterable<O> transformedIterable(Iterable<I> iterable, Transformer<? super I,? extends O> transformer)
The returned iterable's iterator supports remove() when the corresponding
input iterator supports it.
I - the input element typeO - the output element typeiterable - the iterable to transform, may not be nulltransformer - the transformer, must not be nullNullPointerException - if either iterable or transformer is nullpublic static <E> Iterable<E> uniqueIterable(Iterable<E> iterable)
The returned iterable's iterator supports remove() when the
corresponding input iterator supports it. Calling remove()
will only remove a single element from the underlying iterator.
E - the element typeiterable - the iterable to use, may not be nullNullPointerException - if iterable is nullpublic static <E> Iterable<E> unmodifiableIterable(Iterable<E> iterable)
The returned iterable's iterator does not support remove().
E - the element typeiterable - the iterable to use, may not be nullNullPointerException - if iterable is nullpublic static <E> Iterable<E> zippingIterable(Iterable<? extends E> a, Iterable<? extends E> b)
The returned iterable has an iterator that traverses the elements in a
and b in alternating order. The source iterators are not polled until
necessary.
The returned iterable's iterator supports remove() when the corresponding
input iterator supports it.
E - the element typea - the first iterable, may not be nullb - the second iterable, may not be nullNullPointerException - if either a or b is nullpublic static <E> Iterable<E> zippingIterable(Iterable<? extends E> first, Iterable<? extends E>... others)
The returned iterable has an iterator that traverses the elements in a
and b in alternating order. The source iterators are not polled until
necessary.
The returned iterable's iterator supports remove() when the corresponding
input iterator supports it.
E - the element typefirst - the first iterable, may not be nullothers - the array of iterables to interleave, may not be nullNullPointerException - if either of the provided iterables is nullpublic static <E> Iterable<E> emptyIfNull(Iterable<E> iterable)
E - the element typeiterable - the iterable, may be nullpublic static <E> void forEach(Iterable<E> iterable, Closure<? super E> closure)
E - the element typeiterable - the iterator to use, may be nullclosure - the closure to apply to each element, may not be nullNullPointerException - if closure is nullpublic static <E> E forEachButLast(Iterable<E> iterable, Closure<? super E> closure)
If the input iterable is null no change is made.
E - the type of object the Iterable containsiterable - the iterable to get the input from, may be nullclosure - the closure to perform, may not be nullpublic static <E> E find(Iterable<E> iterable, Predicate<? super E> predicate)
A null or empty iterator returns null.
E - the element typeiterable - the iterable to search, may be nullpredicate - the predicate to use, may not be nullNullPointerException - if predicate is nullpublic static <E> int indexOf(Iterable<E> iterable, Predicate<? super E> predicate)
A null or empty iterable returns -1.
E - the element typeiterable - the iterable to search, may be nullpredicate - the predicate to use, may not be nullNullPointerException - if predicate is nullpublic static <E> boolean matchesAll(Iterable<E> iterable, Predicate<? super E> predicate)
A null or empty iterable returns true.
E - the type of object the Iterable containsiterable - the Iterable to use, may be nullpredicate - the predicate to use, may not be nullNullPointerException - if predicate is nullpublic static <E> boolean matchesAny(Iterable<E> iterable, Predicate<? super E> predicate)
A null or empty iterable returns false.
E - the type of object the Iterable containsiterable - the Iterable to use, may be nullpredicate - the predicate to use, may not be nullNullPointerException - if predicate is nullpublic static <E> long countMatches(Iterable<E> input, Predicate<? super E> predicate)
A null iterable matches no elements.
E - the type of object the Iterable containsinput - the Iterable to get the input from, may be nullpredicate - the predicate to use, may not be nullNullPointerException - if predicate is nullpublic static boolean isEmpty(Iterable<?> iterable)
A null iterable returns true.
iterable - the to use, may be nullpublic static <E> boolean contains(Iterable<E> iterable, Object object)
A null or empty iterable returns false.
E - the type of object the Iterable containsiterable - the iterable to check, may be nullobject - the object to checkpublic static <E> boolean contains(Iterable<? extends E> iterable, E object, Equator<? super E> equator)
equator unlike contains(Iterable, Object)
which uses Object.equals(Object).
A null or empty iterable returns false.
A null object will not be passed to the equator, instead a
NullPredicate
will be used.
E - the type of object the Iterable containsiterable - the iterable to check, may be nullobject - the object to checkequator - the equator to use to check, may not be nullNullPointerException - if equator is nullpublic static <E,T extends E> int frequency(Iterable<E> iterable, T obj)
public static <T> T get(Iterable<T> iterable, int index)
index-th value in the iterable's Iterator, throwing
IndexOutOfBoundsException if there is no such element.
If the Iterable is a List, then it will use List.get(int).
T - the type of object in the Iterable.iterable - the Iterable to get a value from, may be nullindex - the index to getIndexOutOfBoundsException - if the index is invalidpublic static <T> T first(Iterable<T> iterable)
get(iterator, 0).
Returns the first value in the iterable's Iterator, throwing
IndexOutOfBoundsException if there is no such element.
If the Iterable is a List, then it will use List.get(int).
T - the type of object in the Iterable.iterable - the Iterable to get a value from, may be nullIndexOutOfBoundsException - if the request is invalidpublic static int size(Iterable<?> iterable)
A null or empty iterator returns 0.
iterable - the iterable to check, may be nullpublic static <O> List<List<O>> partition(Iterable<? extends O> iterable, Predicate<? super O> predicate)
For each predicate, the result will contain a list holding all elements of the input iterable matching the predicate. The last list will hold all elements which didn't match any predicate:
[C1, R] = partition(I, P1) with I = input P1 = first predicate C1 = collection of elements matching P1 R = collection of elements rejected by all predicates
If the input iterable is null, the same is returned as for an
empty iterable.
Example: for an input list [1, 2, 3, 4, 5] calling partition with a predicate [x < 3] will result in the following output: [[1, 2], [3, 4, 5]].
O - the type of object the Iterable containsiterable - the iterable to partition, may be nullpredicate - the predicate to use, may not be nullNullPointerException - if predicate is nullpublic static <O> List<List<O>> partition(Iterable<? extends O> iterable, Predicate<? super O>... predicates)
For each predicate, the result will contain a list holding all elements of the input iterable matching the predicate. The last list will hold all elements which didn't match any predicate:
[C1, C2, R] = partition(I, P1, P2) with I = input P1 = first predicate P2 = second predicate C1 = collection of elements matching P1 C2 = collection of elements matching P2 R = collection of elements rejected by all predicates
Note: elements are only added to the output collection of the first matching predicate, determined by the order of arguments.
If the input iterable is null, the same is returned as for an
empty iterable.
Example: for an input list [1, 2, 3, 4, 5] calling partition with predicates [x < 3] and [x < 5] will result in the following output: [[1, 2], [3, 4], [5]].
O - the type of object the Iterable containsiterable - the collection to get the input from, may be nullpredicates - the predicates to use, may not be nullNullPointerException - if any predicate is nullpublic static <O,R extends Collection<O>> List<R> partition(Iterable<? extends O> iterable, Factory<R> partitionFactory, Predicate<? super O>... predicates)
For each predicate, the returned list will contain a collection holding all elements of the input iterable matching the predicate. The last collection contained in the list will hold all elements which didn't match any predicate:
[C1, C2, R] = partition(I, P1, P2) with I = input P1 = first predicate P2 = second predicate C1 = collection of elements matching P1 C2 = collection of elements matching P2 R = collection of elements rejected by all predicates
Note: elements are only added to the output collection of the first matching predicate, determined by the order of arguments.
If the input iterable is null, the same is returned as for an
empty iterable.
If no predicates have been provided, all elements of the input collection
will be added to the rejected collection.
Example: for an input list [1, 2, 3, 4, 5] calling partition with predicates [x < 3] and [x < 5] will result in the following output: [[1, 2], [3, 4], [5]].
O - the type of object the Iterable containsR - the type of the output Collectioniterable - the collection to get the input from, may be nullpartitionFactory - the factory used to create the output collectionspredicates - the predicates to use, may not be nullNullPointerException - if any predicate is nullpublic static <E> List<E> toList(Iterable<E> iterable)
E - the element typeiterable - the iterable to use, may be nullpublic static <E> String toString(Iterable<E> 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).
E - the element typeiterable - the iterable to convert to a string, may be nulliterablepublic static <E> String toString(Iterable<E> iterable, Transformer<? super E,String> transformer)
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 using the provided transformer.
E - the element typeiterable - the iterable to convert to a string, may be nulltransformer - the transformer used to get a string representation of an elementiterableNullPointerException - if transformer is nullpublic static <E> String toString(Iterable<E> iterable, Transformer<? super E,String> transformer, String delimiter, String prefix, String suffix)
The string representation consists of a list of the iterable's elements,
enclosed by the provided prefix and suffix. Adjacent elements
are separated by the provided delimiter. Elements are converted to
strings as by using the provided transformer.
E - the element typeiterable - the iterable to convert to a string, may be nulltransformer - the transformer used to get a string representation of an elementdelimiter - the string to delimit elementsprefix - the prefix, prepended to the string representationsuffix - the suffix, appended to the string representationiterableNullPointerException - if either transformer, delimiter, prefix or suffix is nullCopyright © 2001–2019 The Apache Software Foundation. All rights reserved.