Package com.gengoai.collection

Class Iterables

java.lang.Object

com.gengoai.collection.Iterables

public final class Iterables
extends Object

Methods for manipulating iterables

Author:

David B. Bracewell

Method Summary

Modifier and Type	Method	Description
static <T> Iterable<T>	asIterable(@NonNull Iterator<? extends T> iterator)	Wraps an Iterator as an Iterable
static <T> Iterable<T>	asIterable(Object array)	Wraps an array as an Iterable
static <T> Iterable<T>	concat(@NonNull Iterable<? extends T>... iterables)	Concatenates iterables together
static <E> Iterable<E>	filter(@NonNull Iterable<? extends E> iterable, @NonNull SerializablePredicate<? super E> predicate)	Filters elements from the given iterable when the given filter predicate evaluates to false
static <T> Iterable<T>	flatten(@NonNull Iterable<? extends Iterable<? extends T>> iterable)	Flattens an iterable of iterables into a single iterable view.
static <T> Optional<T>	get(@NonNull Iterable<? extends T> iterable, int index)	Gets the element of the iterable at the given index using either get if the iterable is a list or by iterating index times.
static <T> T	get(Iterable<? extends T> iterable, int index, T defaultValue)	Gets the element of the iterable at the given index using either get if the iterable is a list or by iterating index times.
static <T> Optional<T>	getFirst(@NonNull Iterable<? extends T> iterable)	Returns the first item in an iterable.
static <T> T	getFirst(@NonNull Iterable<T> iterable, T defaultValue)	Gets the first element of the iterable.
static <T> Optional<T>	getLast(@NonNull Iterable<? extends T> iterable)	Returns the last item in an iterable.
static <T> T	getLast(@NonNull Iterable<? extends T> iterable, T defaultValue)	Returns the last item in an iterable.
static boolean	isEmpty(@NonNull Iterable<?> iterable)	Determines if the iterable is empty or not.
static int	size(@NonNull Iterable<?> iterable)	Gets the size of the iterable
static <E extends Comparable<? super E>> List<E>	sort(@NonNull Iterable<? extends E> iterable)	Sorts the items of an iterable returning an array of the sorted items.
static <E> List<E>	sort(@NonNull Iterable<? extends E> iterable, @NonNull Comparator<? super E> comparator)	Sorts the items of an iterable returning an array of the sorted items.
static <I,O> Iterable<O>	transform(@NonNull Iterable<? extends I> iterable, @NonNull SerializableFunction<? super I,? extends O> function)	Transforms the elements in the iterable
static <T,U> Iterable<Map.Entry<T,U>>	zip(@NonNull Iterable<? extends T> iterable1, @NonNull Iterable<? extends U> iterable2)	Zips (combines) two iterators together.
static <T> Iterable<Map.Entry<T,Integer>>	zipWithIndex(@NonNull Iterable<? extends T> iterable)	Creates pairs of entries from the given iterable and its index in the iterable (0 based)

Methods inherited from class java.lang.Object

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

Method Detail

asIterable

public static <T> Iterable<T> asIterable(Object array)

Wraps an array as an Iterable

Type Parameters:

T - the component type of the array

Parameters:

array - The array to wrap

Returns:

An Iterable wrapping the iterator.

asIterable

public static <T> Iterable<T> asIterable(@NonNull
                                         @NonNull Iterator<? extends T> iterator)

Wraps an Iterator as an Iterable

Type Parameters:

T - the type parameter

Parameters:

iterator - The iterator to wrap

Returns:

An Iterable wrapping the iterator.

concat

@SafeVarargs
public static <T> Iterable<T> concat(@NonNull
                                     @NonNull Iterable<? extends T>... iterables)

Concatenates iterables together

Type Parameters:

T - the iterables element type parameter

Parameters:

iterables - the iterables to concatenate

Returns:

the concatenated iterable

filter

public static <E> Iterable<E> filter(@NonNull
                                     @NonNull Iterable<? extends E> iterable,
                                     @NonNull
                                     @NonNull SerializablePredicate<? super E> predicate)

Filters elements from the given iterable when the given filter predicate evaluates to false

Type Parameters:

E - the iterable type parameter

Parameters:

iterable - the iterable to filter

predicate - the filter to apply items evaluating to false will be removed from the iterator

Returns:

the filtered iterable

flatten

public static <T> Iterable<T> flatten(@NonNull
                                      @NonNull Iterable<? extends Iterable<? extends T>> iterable)

Flattens an iterable of iterables into a single iterable view.

Type Parameters:

T - the iterable element type parameter

Parameters:

iterable - the iterable to flatten

Returns:

the flattened iterable

get

public static <T> Optional<T> get(@NonNull
                                  @NonNull Iterable<? extends T> iterable,
                                  int index)

Gets the element of the iterable at the given index using either get if the iterable is a list or by iterating index times.

Type Parameters:

T - the iterable element type parameter

Parameters:

iterable - the iterable

index - the index of the element to retrieve

Returns:

Optional of the element or empty when the index is out of bounds

get

public static <T> T get(Iterable<? extends T> iterable,
                        int index,
                        T defaultValue)

Gets the element of the iterable at the given index using either get if the iterable is a list or by iterating index times.

Type Parameters:

T - the iterable element type parameter

Parameters:

iterable - the iterable

index - the index of the element to retrieve

defaultValue - value to return when the element is null or index is out of bounds

Returns:

element value or default value

getFirst

public static <T> Optional<T> getFirst(@NonNull
                                       @NonNull Iterable<? extends T> iterable)

Returns the first item in an iterable.

Type Parameters:

T - the type of element in the iterable

Parameters:

iterable - the iterable

Returns:

An optional containing the first element in the iterable if available

getFirst

public static <T> T getFirst(@NonNull
                             @NonNull Iterable<T> iterable,
                             T defaultValue)

Gets the first element of the iterable.

Type Parameters:

T - the iterable element type parameter

Parameters:

iterable - the iterable

defaultValue - the default value

Returns:

the first element of the iterable or the default value

getLast

public static <T> Optional<T> getLast(@NonNull
                                      @NonNull Iterable<? extends T> iterable)

Returns the last item in an iterable.

Type Parameters:

T - the type of element in the iterable

Parameters:

iterable - the iterable

Returns:

An optional containing the last element in the iterable or null if none

getLast

public static <T> T getLast(@NonNull
                            @NonNull Iterable<? extends T> iterable,
                            T defaultValue)

Returns the last item in an iterable.

Type Parameters:

T - the type of element in the iterable

Parameters:

iterable - the iterable

defaultValue - default value if the list is empty

Returns:

An optional containing the last element in the iterable or null if none

isEmpty

public static boolean isEmpty(@NonNull
                              @NonNull Iterable<?> iterable)

Determines if the iterable is empty or not.

Parameters:

iterable - the iterable to check

Returns:

True if the iterable is empty, False otherwise

size

public static int size(@NonNull
                       @NonNull Iterable<?> iterable)

Gets the size of the iterable

Parameters:

iterable - the iterable

Returns:

the number of items in the iterable

sort

public static <E extends Comparable<? super E>> List<E> sort(@NonNull
                                                             @NonNull Iterable<? extends E> iterable)

Sorts the items of an iterable returning an array of the sorted items.

Type Parameters:

E - The component type of the iterable which implements the Comparable interface.

Parameters:

iterable - The iterable instance to sort

Returns:

A list of the items in the given iterable sorted using the items natural comparator.

sort

public static <E> List<E> sort(@NonNull
                               @NonNull Iterable<? extends E> iterable,
                               @NonNull
                               @NonNull Comparator<? super E> comparator)

Sorts the items of an iterable returning an array of the sorted items.

Type Parameters:

E - The component type of the iterable.

Parameters:

iterable - The iterable instance to sort

comparator - The comparator to use for sorting

Returns:

A list of the items in the given iterable sorted using the given comparator.

transform

public static <I,O> Iterable<O> transform(@NonNull
                                                @NonNull Iterable<? extends I> iterable,
                                                @NonNull
                                                @NonNull SerializableFunction<? super I,? extends O> function)

Transforms the elements in the iterable

Type Parameters:

I - the iterable element type parameter

O - the transformed element type parameter

Parameters:

iterable - the iterable to transform

function - the function to perform transform

Returns:

the transformed iterable

zip

public static <T,U> Iterable<Map.Entry<T,U>> zip(@NonNull
                                                             @NonNull Iterable<? extends T> iterable1,
                                                             @NonNull
                                                             @NonNull Iterable<? extends U> iterable2)

Zips (combines) two iterators together. For example, if iterable 1 contained [1,2,3] and iterable 2 contained [4,5,6] the result would be [(1,4), (2,5), (3,6)]. Note that the length of the resulting stream will be the minimum of the two iterables.

Type Parameters:

T - the component type of the first iterator

U - the component type of the second iterator

Parameters:

iterable1 - the iterator making up the key in the resulting entries

iterable2 - the iterator making up the value in the resulting entries

Returns:

A stream of entries whose keys are taken from iterable1 and values are taken from iterable2

zipWithIndex

public static <T> Iterable<Map.Entry<T,Integer>> zipWithIndex(@NonNull
                                                                    @NonNull Iterable<? extends T> iterable)

Creates pairs of entries from the given iterable and its index in the iterable (0 based)

Type Parameters:

T - the iterator type parameter

Parameters:

iterable - the iterator

Returns:

the iterable with index values