org.eclipse.xtext.xbase.lib

Class IteratorExtensions

java.lang.Object

org.eclipse.xtext.xbase.lib.IteratorExtensions

@GwtCompatible
public class IteratorExtensions
extends java.lang.Object

This is an extension library for iterators.

Constructor Summary

Constructors

Constructor and Description
IteratorExtensions()

Method Summary

Modifier and Type	Method and Description
static <T> java.util.Iterator<T>	drop(java.util.Iterator<T> iterator, int count) Returns a view on this iterator that provides all elements except the first count entries.
static <T> java.util.Iterator<T>	dropWhile(java.util.Iterator<? extends T> iterator, Functions.Function1<? super T,java.lang.Boolean> predicate) Returns an Iterator containing all elements starting from the first element for which the drop-predicate returned false.
static boolean	elementsEqual(java.util.Iterator<?> iterator, java.lang.Iterable<?> iterable) Determines whether two iterators contain equal elements in the same order.
static boolean	elementsEqual(java.util.Iterator<?> iterator, java.util.Iterator<?> other) Determines whether two iterators contain equal elements in the same order.
static <T> boolean	exists(java.util.Iterator<T> iterator, Functions.Function1<? super T,java.lang.Boolean> predicate) Returns true if one or more elements in iterator satisfy the predicate.
static <T> java.util.Iterator<T>	filter(java.util.Iterator<?> unfiltered, java.lang.Class<T> type) Returns all instances of class type in unfiltered.
static <T> java.util.Iterator<T>	filter(java.util.Iterator<T> unfiltered, Functions.Function1<? super T,java.lang.Boolean> predicate) Returns the elements of unfiltered that satisfy a predicate.
static <T> java.util.Iterator<T>	filterNull(java.util.Iterator<T> unfiltered) Returns a new iterator filtering any null references.
static <T> T	findFirst(java.util.Iterator<T> iterator, Functions.Function1<? super T,java.lang.Boolean> predicate) Finds the first element in the given iterator that fulfills the predicate.
static <T> T	findLast(java.util.Iterator<T> iterator, Functions.Function1<? super T,java.lang.Boolean> predicate) Finds the last element in the given iterator that fulfills the predicate.
static <T,R> java.util.Iterator<R>	flatMap(java.util.Iterator<T> original, Functions.Function1<? super T,? extends java.util.Iterator<R>> transformation) Returns an iterable that performs the given transformation for each element of original when requested.
static <T> java.util.Iterator<T>	flatten(java.util.Iterator<? extends java.util.Iterator<? extends T>> inputs) Combines multiple iterators into a single iterator.
static <T,R> R	fold(java.util.Iterator<T> iterator, R seed, Functions.Function2<? super R,? super T,? extends R> function) Applies the combinator function to all elements of the iterator in turn and uses seed as the start value.
static <T> boolean	forall(java.util.Iterator<T> iterator, Functions.Function1<? super T,java.lang.Boolean> predicate) Returns true if every element in iterator satisfies the predicate.
static <T> void	forEach(java.util.Iterator<T> iterator, Procedures.Procedure1<? super T> procedure) Applies procedure for each element of the given iterator.
static <T> void	forEach(java.util.Iterator<T> iterator, Procedures.Procedure2<? super T,? super java.lang.Integer> procedure) Applies procedure for each element of the given iterator.
static <K,V> java.util.Map<K,java.util.List<V>>	groupBy(java.util.Iterator<? extends V> values, Functions.Function1<? super V,? extends K> computeKeys) Returns a map for which the Map.values() is a collection of lists, where the elements in the list will appear in the order as they appeared in the iterator.
static <T> T	head(java.util.Iterator<T> iterator) Returns the first element in the given iterator or null if empty.
static <A> java.util.Iterator<Pair<java.lang.Integer,A>>	indexed(java.util.Iterator<? extends A> iterator) Returns an Iterator of Pairs where the nth pair is created by taking the nth element of the source as the value and its 0-based index as the key.
static boolean	isEmpty(java.util.Iterator<?> iterator) Determines if the given iterator contains no elements.
static boolean	isNullOrEmpty(java.util.Iterator<?> iterator) Determines if the given iterator is null or contains no elements.
static java.lang.String	join(java.util.Iterator<?> iterator) Returns the concatenated string representation of the elements in the given iterator.
static java.lang.String	join(java.util.Iterator<?> iterator, java.lang.CharSequence separator) Returns the concatenated string representation of the elements in the given iterator.
static <T> java.lang.String	join(java.util.Iterator<T> iterator, java.lang.CharSequence before, java.lang.CharSequence separator, java.lang.CharSequence after, Functions.Function1<? super T,? extends java.lang.CharSequence> function) Returns the concatenated string representation of the elements in the given iterator.
static <T> java.lang.String	join(java.util.Iterator<T> iterator, java.lang.CharSequence separator, Functions.Function1<? super T,? extends java.lang.CharSequence> function) Returns the concatenated string representation of the elements in the given iterator.
static <T> T	last(java.util.Iterator<T> iterator) Returns the last element in the given iterator or null if empty.
static <T,R> java.util.Iterator<R>	map(java.util.Iterator<T> original, Functions.Function1<? super T,? extends R> transformation) Returns an iterator that performs the given transformation for each element of original when requested.
static <T extends java.lang.Comparable<? super T>> T	max(java.util.Iterator<T> iterator) Finds the maximum of the elements according to their natural ordering.
static <T> T	max(java.util.Iterator<T> iterator, java.util.Comparator<? super T> comparator) Finds the maximum element according to comparator.
static <T,C extends java.lang.Comparable<? super C>> T	maxBy(java.util.Iterator<T> iterator, Functions.Function1<? super T,C> compareBy) Finds the element that yields the maximum value when passed to compareBy If there are several maxima, the first one will be returned.
static <T extends java.lang.Comparable<? super T>> T	min(java.util.Iterator<T> iterator) Finds the minimum of the given elements according to their natural ordering.
static <T> T	min(java.util.Iterator<T> iterator, java.util.Comparator<? super T> comparator) Finds the mininmum element according to comparator.
static <T,C extends java.lang.Comparable<? super C>> T	minBy(java.util.Iterator<T> iterator, Functions.Function1<? super T,C> compareBy) Finds the element that yields the minimum value when passed to compareBy.
static <T> java.util.Iterator<T>	operator_plus(java.util.Iterator<? extends T> a, java.util.Iterator<? extends T> b) Concatenates two iterators into a single iterator.
static <T> T	reduce(java.util.Iterator<? extends T> iterator, Functions.Function2<? super T,? super T,? extends T> function) Applies the combinator function to all elements of the iterator in turn.
static <T> java.util.Iterator<T>	reject(java.util.Iterator<T> unfiltered, Functions.Function1<? super T,java.lang.Boolean> predicate) Returns the elements of unfiltered that do not satisfy a predicate.
static int	size(java.util.Iterator<?> iterator) Returns the number of elements in iterator.
static <T> java.util.Iterator<T>	tail(java.util.Iterator<T> iterator) Returns a view on this iterator that contains all the elements except the first.
static <T> java.util.Iterator<T>	take(java.util.Iterator<T> iterator, int count) Returns a view on this iterator that provides at most the first count entries.
static <T> java.util.Iterator<T>	takeWhile(java.util.Iterator<? extends T> iterator, Functions.Function1<? super T,java.lang.Boolean> predicate) Returns an Iterator containing all elements starting from the head of the source up to and excluding the first element that violates the predicate.
static <K,V> java.util.Map<K,V>	toInvertedMap(java.util.Iterator<? extends K> keys, Functions.Function1<? super K,V> computeValues) Returns a map for which the Map.values() are computed by the given function, and each key is an element in the given keys.
static <T> java.lang.Iterable<T>	toIterable(java.util.Iterator<T> iterator) Wraps an Iterator in an Iterable.
static <T> java.util.List<T>	toList(java.util.Iterator<? extends T> iterator) Returns a list that contains all the entries of the given iterator in the same order.
static <T,K,V> java.util.Map<K,V>	toMap(java.util.Iterator<? extends T> inputs, Functions.Function1<? super T,K> computeKeys, Functions.Function1<? super T,V> computeValues) Returns a map for which the Map.values() are the product of invoking supplied function computeValues on input iterable elements, and each key is the product of invoking a supplied function computeKeys on same elements.
static <K,V> java.util.Map<K,V>	toMap(java.util.Iterator<? extends V> values, Functions.Function1<? super V,K> computeKeys) Returns a map for which the Map.values() are the given elements in the given order, and each key is the product of invoking a supplied function computeKeys on its corresponding value.
static <T> java.util.Set<T>	toSet(java.util.Iterator<? extends T> iterator) Returns a set that contains all the unique entries of the given iterator in the order of their appearance.

Methods inherited from class java.lang.Object

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

Constructor Detail

IteratorExtensions

public IteratorExtensions()

Method Detail

toIterable

@Pure
public static <T> java.lang.Iterable<T> toIterable(java.util.Iterator<T> iterator)

Wraps an Iterator in an Iterable. WARNING: The resulting Iterable may be used (e.g. calling IterableExtensions.isEmpty(Iterable)) / iterated (e.g. in a for loop) only once. If you want to create a reusable Iterable call IterableExtensions.toList(Iterable) or IterableExtensions.toSet(Iterable) on the result and reuse the resulting List / Set

Parameters:

iterator - the Iterator to wrap in an Iterable. May not be null.

Returns:

an Iterable providing the given Iterator. Never null.

operator_plus

@Pure
public static <T> java.util.Iterator<T> operator_plus(java.util.Iterator<? extends T> a,
                                                            java.util.Iterator<? extends T> b)

Concatenates two iterators into a single iterator. The returned iterator traverses the elements in a, followed by the elements in b. The resulting iterator is effectivly a view on the source iterators. That is, the source iterators are not polled until necessary and the result will reflect changes in the sources.

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

Parameters:

a - the first iterator. May not be null.

b - the second iterator. May not be null.

Returns:

a combined iterator. Never null.

findFirst

public static <T> T findFirst(java.util.Iterator<T> iterator,
                              Functions.Function1<? super T,java.lang.Boolean> predicate)

Finds the first element in the given iterator that fulfills the predicate. If none is found or the iterator is empty, null is returned.

Parameters:

iterator - the iterator. May not be null.

predicate - the predicate. May not be null.

Returns:

the first element in the iterator for which the given predicate returns true, returns null if no element matches the predicate or the iterator is empty.

findLast

public static <T> T findLast(java.util.Iterator<T> iterator,
                             Functions.Function1<? super T,java.lang.Boolean> predicate)

Finds the last element in the given iterator that fulfills the predicate. If none is found or the iterator is empty, null is returned.

Parameters:

iterator - the iterator. May not be null.

predicate - the predicate. May not be null.

Returns:

the last element in the iterator for which the given predicate returns true, returns null if no element matches the predicate or the iterator is empty.

head

public static <T> T head(java.util.Iterator<T> iterator)

Returns the first element in the given iterator or null if empty.

Parameters:

iterator - the iterator. May not be null.

Returns:

the first element in the iterator or null.

tail

public static <T> java.util.Iterator<T> tail(java.util.Iterator<T> iterator)

Returns a view on this iterator that contains all the elements except the first.

Parameters:

iterator - the iterator. May not be null.

Returns:

an iterator with all elements except the first. Never null.

See Also:

drop(Iterator, int)

last

public static <T> T last(java.util.Iterator<T> iterator)

Returns the last element in the given iterator or null if empty.

Parameters:

iterator - the iterator. May not be null.

Returns:

the last element in the iterator or null.

take

@Pure
public static <T> java.util.Iterator<T> take(java.util.Iterator<T> iterator,
                                                   int count)

Returns a view on this iterator that provides at most the first count entries.

Parameters:

iterator - the iterator. May not be null.

count - the number of elements that should be returned at most.

Returns:

an iterator with count elements. Never null.

Throws:

java.lang.IllegalArgumentException - if count is negative.

drop

public static <T> java.util.Iterator<T> drop(java.util.Iterator<T> iterator,
                                             int count)

Returns a view on this iterator that provides all elements except the first count entries.

Parameters:

iterator - the iterator. May not be null.

count - the number of elements that should be dropped.

Returns:

an iterator without the first count elements. Never null.

Throws:

java.lang.IllegalArgumentException - if count is negative.

exists

public static <T> boolean exists(java.util.Iterator<T> iterator,
                                 Functions.Function1<? super T,java.lang.Boolean> predicate)

Returns true if one or more elements in iterator satisfy the predicate.

Parameters:

iterator - the iterator. May not be null.

predicate - the predicate. May not be null.

Returns:

true if one or more elements in iterator satisfy the predicate.

forall

public static <T> boolean forall(java.util.Iterator<T> iterator,
                                 Functions.Function1<? super T,java.lang.Boolean> predicate)

Returns true if every element in iterator satisfies the predicate. If iterator is empty, true is returned. In other words, false is returned if at least one element fails to fulfill the predicate.

Parameters:

iterator - the iterator. May not be null.

predicate - the predicate. May not be null.

Returns:

true if every element in iterator satisfies the predicate and also if there is no element.

filter

@Pure
public static <T> java.util.Iterator<T> filter(java.util.Iterator<T> unfiltered,
                                                     Functions.Function1<? super T,java.lang.Boolean> predicate)

Returns the elements of unfiltered that satisfy a predicate. The resulting iterator does not support remove(). The returned iterator is a view on the original elements. Changes in the unfiltered original are reflected in the view.

Parameters:

unfiltered - the unfiltered iterator. May not be null.

predicate - the predicate. May not be null.

Returns:

an iterator that contains only the elements that fulfill the predicate. Never null.

reject

@Pure
public static <T> java.util.Iterator<T> reject(java.util.Iterator<T> unfiltered,
                                                     Functions.Function1<? super T,java.lang.Boolean> predicate)

Returns the elements of unfiltered that do not satisfy a predicate. The resulting iterator does not support remove(). The returned iterator is a view on the original elements. Changes in the unfiltered original are reflected in the view.

Parameters:

unfiltered - the unfiltered iterator. May not be null.

predicate - the predicate. May not be null.

Returns:

an iterator that contains only the elements that do not fulfill the predicate. Never null.

filter

@Pure
 @GwtIncompatible(value="Class.isInstance")
public static <T> java.util.Iterator<T> filter(java.util.Iterator<?> unfiltered,
                                                                                                 java.lang.Class<T> type)

Returns all instances of class type in unfiltered. The returned iterator has elements whose class is type or a subclass of type. The returned iterator does not support remove(). The returned iterator is a view on the original elements. Changes in the unfiltered original are reflected in the view.

Parameters:

unfiltered - the unfiltered iterator. May not be null.

type - the type of elements desired

Returns:

an unmodifiable iterator containing all elements of the original iterator that were of the requested type. Never null.

filterNull

@Pure
public static <T> java.util.Iterator<T> filterNull(java.util.Iterator<T> unfiltered)

Returns a new iterator filtering any null references.

Parameters:

unfiltered - the unfiltered iterator. May not be null.

Returns:

an unmodifiable iterator containing all elements of the original iterator without any null references. Never null.

map

@Pure
public static <T,R> java.util.Iterator<R> map(java.util.Iterator<T> original,
                                                    Functions.Function1<? super T,? extends R> transformation)

Returns an iterator that performs the given transformation for each element of original when requested. The mapping is done lazily. The returned iterator's iterator supports remove() if the provided iterator does. After a successful remove() call, original no longer contains the corresponding element.

Parameters:

original - the original iterator. May not be null.

transformation - the transformation. May not be null.

Returns:

an iterator that provides the result of the transformation. Never null.

flatMap

@Pure
public static <T,R> java.util.Iterator<R> flatMap(java.util.Iterator<T> original,
                                                        Functions.Function1<? super T,? extends java.util.Iterator<R>> transformation)

Returns an iterable that performs the given transformation for each element of original when requested. The mapping is done lazily. That is, subsequent iterations of the elements in the iterable will repeatedly apply the transformation.

The transformation maps each element to an iterable, and all resulting iterables are combined to a single iterable. Effectively a combination of map(Iterator, Functions.Function1) and flatten(Iterator) is performed.

The returned iterable's iterator does not support remove() in contrast to map(Iterator, Functions.Function1).

Parameters:

original - the original iterable. May not be null.

transformation - the transformation. May not be null and must not yield null.

Returns:

an iterable that provides the result of the transformation. Never null.

Since:

2.13

flatten

public static <T> java.util.Iterator<T> flatten(java.util.Iterator<? extends java.util.Iterator<? extends T>> inputs)

Combines multiple iterators into a single iterator. The returned iterator traverses the elements of each iterator in inputs. The input iterators are not polled until necessary.

Parameters:

inputs - the to be flattened iterators. May not be null.

Returns:

an iterator that provides the concatenated values of the input elements. Never null.

Since:

2.13

forEach

public static <T> void forEach(java.util.Iterator<T> iterator,
                               Procedures.Procedure1<? super T> procedure)

Applies procedure for each element of the given iterator.

Parameters:

iterator - the iterator. May not be null.

procedure - the procedure. May not be null.

forEach

public static <T> void forEach(java.util.Iterator<T> iterator,
                               Procedures.Procedure2<? super T,? super java.lang.Integer> procedure)

Applies procedure for each element of the given iterator. The procedure takes the element and a loop counter. If the counter would overflow, Integer.MAX_VALUE is returned for all subsequent elements. The first element is at index zero.

Parameters:

iterator - the iterator. May not be null.

procedure - the procedure. May not be null.

join

public static java.lang.String join(java.util.Iterator<?> iterator)

Returns the concatenated string representation of the elements in the given iterator. No delimiter is used. The given iterator is left exhausted.

Parameters:

iterator - the iterator. May not be null.

Returns:

the string representation of the iterator's elements. Never null.

See Also:

join(Iterator, CharSequence, org.eclipse.xtext.xbase.lib.Functions.Function1)

join

public static java.lang.String join(java.util.Iterator<?> iterator,
                                    java.lang.CharSequence separator)

Returns the concatenated string representation of the elements in the given iterator. The separator is used to between each pair of entries in the input. The string null is used for null entries in the input. The given iterator is left exhausted.

Parameters:

iterator - the iterator. May not be null.

separator - the separator. May not be null.

Returns:

the string representation of the iterator's elements. Never null.

See Also:

join(Iterator, CharSequence, org.eclipse.xtext.xbase.lib.Functions.Function1)

join

public static <T> java.lang.String join(java.util.Iterator<T> iterator,
                                        java.lang.CharSequence separator,
                                        Functions.Function1<? super T,? extends java.lang.CharSequence> function)

Returns the concatenated string representation of the elements in the given iterator. The function is used to compute the string for each element. The separator is used to between each pair of entries in the input. The string null is used if the function yields null as the string representation for an entry. The given iterator is left exhausted.

Parameters:

iterator - the iterator. May not be null.

separator - the separator. May not be null.

function - the function that is used to compute the string representation of a single element. May not be null.

Returns:

the string representation of the iterator's elements. Never null.

join

public static <T> java.lang.String join(java.util.Iterator<T> iterator,
                                        java.lang.CharSequence before,
                                        java.lang.CharSequence separator,
                                        java.lang.CharSequence after,
                                        Functions.Function1<? super T,? extends java.lang.CharSequence> function)

Returns the concatenated string representation of the elements in the given iterator. The function is used to compute the string for each element. The separator is used to between each pair of entries in the input. The string null is used if the function yields null as the string representation for an entry. The given iterator is left exhausted.

Parameters:

iterator - the iterator. May not be null.

before - prepends the resulting string if the iterator contains at least one element. May be null which is equivalent to passing an empty string.

separator - the separator. May be null which is equivalent to passing an empty string.

after - appended to the resulting string if the iterator contain at least one element. May be null which is equivalent to passing an empty string.

function - the function that is used to compute the string representation of a single element. May not be null.

Returns:

the string representation of the iterator's elements. Never null.

elementsEqual

public static boolean elementsEqual(java.util.Iterator<?> iterator,
                                    java.util.Iterator<?> other)

Determines whether two iterators contain equal elements in the same order. More specifically, this method returns true if iterator and other contain the same number of elements and every element of iterator is equal to the corresponding element of other.

Parameters:

iterator - an iterator. May not be null.

other - an iterator. May not be null.

Returns:

true if the two iterators contain equal elements in the same order.

elementsEqual

public static boolean elementsEqual(java.util.Iterator<?> iterator,
                                    java.lang.Iterable<?> iterable)

Determines whether two iterators contain equal elements in the same order. More specifically, this method returns true if iterator and iterable contain the same number of elements and every element of iterator is equal to the corresponding element of iterable.

Parameters:

iterator - an iterator. May not be null.

iterable - an iterable. May not be null.

Returns:

true if the two iterators contain equal elements in the same order.

isNullOrEmpty

public static boolean isNullOrEmpty(java.util.Iterator<?> iterator)

Determines if the given iterator is null or contains no elements.

Parameters:

iterator - the to-be-queried iterator. May be null.

Returns:

true if the iterator is null or contains no elements

isEmpty

public static boolean isEmpty(java.util.Iterator<?> iterator)

Determines if the given iterator contains no elements.

Parameters:

iterator - the to-be-queried iterator. May not be null.

Returns:

true if the iterator contains no elements

See Also:

isNullOrEmpty(Iterator)

size

public static int size(java.util.Iterator<?> iterator)

Returns the number of elements in iterator. The given iterator is left exhausted.

Parameters:

iterator - the iterator. May not be null.

Returns:

the number of elements in iterator.

reduce

public static <T> T reduce(java.util.Iterator<? extends T> iterator,
                           Functions.Function2<? super T,? super T,? extends T> function)

Applies the combinator function to all elements of the iterator in turn.

One of the function parameters is an element of the iterator, and the other is the result of previous application of the function. The seed of the operation is the first element in the iterator. The second value is computed by applying the function to the seed together with the second element of the iterator. The third value is computed from the previous result together with the third element and so on. In other words, the previous result of each step is taken and passed together with the next element to the combinator function.

If the iterator is empty, null is returned.

More formally, given an iterator [a, b, c, d] and a function f, the result of reduce is f(f(f(a, b), c), d)

Parameters:

iterator - the to-be-reduced iterator. May not be null.

function - the combinator function. May not be null.

Returns:

the last result of the applied combinator function or null for the empty input.

fold

public static <T,R> R fold(java.util.Iterator<T> iterator,
                           R seed,
                           Functions.Function2<? super R,? super T,? extends R> function)

Applies the combinator function to all elements of the iterator in turn and uses seed as the start value.

One of the function parameters is an element of the iterator, and the other is the result of previous application of the function. The seed of the operation is explicitly passed to fold. The first computed value is the result of the applied function for seed and the first element of the iterator. This intermediate result together with the second element of the iterator produced the next result and so on.

fold is similar to reduce but allows a seed value and the combinator function may be asymmetric. It takes T and R and returns R.

If the iterator is empty, seed is returned.

More formally, given an iterator [a, b, c, d], a seed initial and a function f, the result of fold is f(f(f(f(initial, a), b), c), d)

Parameters:

iterator - the to-be-folded iterator. May not be null.

seed - the initial value. May be null.

function - the combinator function. May not be null.

Returns:

the last result of the applied combinator function or seed for the empty input.

toList

public static <T> java.util.List<T> toList(java.util.Iterator<? extends T> iterator)

Returns a list that contains all the entries of the given iterator in the same order.

Parameters:

iterator - the iterator. May not be null.

Returns:

a list with the same entries as the given iterator. Never null.

toSet

public static <T> java.util.Set<T> toSet(java.util.Iterator<? extends T> iterator)

Returns a set that contains all the unique entries of the given iterator in the order of their appearance. The result set is a copy of the iterator with stable order.

Parameters:

iterator - the iterator. May not be null.

Returns:

a set with the unique entries of the given iterator. Never null.

toInvertedMap

public static <K,V> java.util.Map<K,V> toInvertedMap(java.util.Iterator<? extends K> keys,
                                                     Functions.Function1<? super K,V> computeValues)

Returns a map for which the Map.values() are computed by the given function, and each key is an element in the given keys. If the iterator contains equal keys more than once, the last one will be contained in the map. The map is computed eagerly. That is, subsequent changes in the keys are not reflected by the map. The key iterator is left exhausted.

Parameters:

keys - the keys to use when constructing the Map. May not be null.

computeValues - the function used to produce the values for each key. May not be null.

Returns:

a map mapping each entry in the given iterator to the corresponding result when evaluating the function computeValues.

toMap

public static <K,V> java.util.Map<K,V> toMap(java.util.Iterator<? extends V> values,
                                             Functions.Function1<? super V,K> computeKeys)

Returns a map for which the Map.values() are the given elements in the given order, and each key is the product of invoking a supplied function computeKeys on its corresponding value. If the function produces the same key for different values, the last one will be contained in the map. The value iterator is left exhausted.

Parameters:

values - the values to use when constructing the Map. May not be null.

computeKeys - the function used to produce the key for each value. May not be null.

Returns:

a map mapping the result of evaluating the function keyFunction on each value in the input iterator to that value

toMap

public static <T,K,V> java.util.Map<K,V> toMap(java.util.Iterator<? extends T> inputs,
                                               Functions.Function1<? super T,K> computeKeys,
                                               Functions.Function1<? super T,V> computeValues)

Returns a map for which the Map.values() are the product of invoking supplied function computeValues on input iterable elements, and each key is the product of invoking a supplied function computeKeys on same elements. If the function produces the same key for different values, the last one will be contained in the map. The input iterator is left exhausted.

Parameters:

inputs - the elements to use when constructing the Map. May not be null.

computeKeys - the function used to produce the key for each value. May not be null.

computeValues - the function used to produce the values for each key. May not be null.

Returns:

a map mapping the result of evaluating the functions keyFunction and computeValues on each value in the input iterator to that value

groupBy

public static <K,V> java.util.Map<K,java.util.List<V>> groupBy(java.util.Iterator<? extends V> values,
                                                               Functions.Function1<? super V,? extends K> computeKeys)

Returns a map for which the Map.values() is a collection of lists, where the elements in the list will appear in the order as they appeared in the iterator. Each key is the product of invoking the supplied function computeKeys on its corresponding value. So a key of that map groups a list of values for which the function produced exactly that key. The value iterator is left exhausted.

Parameters:

values - the values to use when constructing the Map. May not be null.

computeKeys - the function used to produce the key for each value. May not be null.

Returns:

a map mapping the result of evaluating the function keyFunction on each value in the input iterator to that value. As there can be more than one value mapped by a key, the mapping result is is a list of values.

Since:

2.7

takeWhile

public static <T> java.util.Iterator<T> takeWhile(java.util.Iterator<? extends T> iterator,
                                                  Functions.Function1<? super T,java.lang.Boolean> predicate)

Returns an Iterator containing all elements starting from the head of the source up to and excluding the first element that violates the predicate. The resulting Iterator is a lazily computed view, so any modifications to the underlying Iterators will be reflected on iteration. The result does not support Iterator.remove()

Parameters:

iterator - the elements from which to take. May not be null.

predicate - the predicate which decides whether to keep taking elements. May not be null.

Returns:

the taken elements

Since:

2.7

dropWhile

public static <T> java.util.Iterator<T> dropWhile(java.util.Iterator<? extends T> iterator,
                                                  Functions.Function1<? super T,java.lang.Boolean> predicate)

Returns an Iterator containing all elements starting from the first element for which the drop-predicate returned false. The resulting Iterator is a lazily computed view, so any modifications to the underlying Iterators will be reflected on iteration. The result does not support Iterator.remove()

Parameters:

iterator - the elements from which to drop. May not be null.

predicate - the predicate which decides whether to keep dropping elements. May not be null.

Returns:

the remaining elements after dropping

Since:

2.7

indexed

public static <A> java.util.Iterator<Pair<java.lang.Integer,A>> indexed(java.util.Iterator<? extends A> iterator)

Returns an Iterator of Pairs where the nth pair is created by taking the nth element of the source as the value and its 0-based index as the key. E.g. zipWitIndex(#["a", "b", "c"]) == #[(0, "a"), (1, "b"), (2, "c")] If the index would overflow, Integer.MAX_VALUE is returned for all subsequent elements. The resulting Iterator is a lazily computed view, so any modifications to the underlying Iterator will be reflected on iteration. The result does not support Iterator.remove()

Parameters:

iterator - the elements. May not be null.

Returns:

the zipped result

Since:

2.7

min

public static <T extends java.lang.Comparable<? super T>> T min(java.util.Iterator<T> iterator)

Finds the minimum of the given elements according to their natural ordering. If there are several mimina, the first one will be returned.

Parameters:

iterator - the mutually comparable elements. May not be null.

Returns:

the minimum

Throws:

java.util.NoSuchElementException - if the iterator is empty

Since:

2.7

minBy

public static <T,C extends java.lang.Comparable<? super C>> T minBy(java.util.Iterator<T> iterator,
                                                                    Functions.Function1<? super T,C> compareBy)

Finds the element that yields the minimum value when passed to compareBy. If there are several maxima, the first one will be returned.

Parameters:

iterator - the elements to find the minimum of. May not be null.

compareBy - a function that returns a comparable characteristic to compare the elements by. May not be null.

Returns:

the minimum

Throws:

java.util.NoSuchElementException - if the iterator is empty

Since:

2.7

min

public static <T> T min(java.util.Iterator<T> iterator,
                        java.util.Comparator<? super T> comparator)

Finds the mininmum element according to comparator. If there are several minima, the first one will be returned.

Parameters:

iterator - the elements to find the minimum of. May not be null.

comparator - the comparison function. May not be null.

Returns:

the minimum

Throws:

java.util.NoSuchElementException - if the iterator is empty

Since:

2.7

max

public static <T extends java.lang.Comparable<? super T>> T max(java.util.Iterator<T> iterator)

Finds the maximum of the elements according to their natural ordering. If there are several maxima, the first one will be returned.

Parameters:

iterator - the mutually comparable elements. May not be null.

Returns:

the maximum

Throws:

java.util.NoSuchElementException - if the iterator is empty

Since:

2.7

maxBy

public static <T,C extends java.lang.Comparable<? super C>> T maxBy(java.util.Iterator<T> iterator,
                                                                    Functions.Function1<? super T,C> compareBy)

Finds the element that yields the maximum value when passed to compareBy If there are several maxima, the first one will be returned.

Parameters:

iterator - the elements to find the maximum of. May not be null.

compareBy - a function that returns a comparable characteristic to compare the elements by. May not be null.

Returns:

the maximum

Throws:

java.util.NoSuchElementException - if the iterator is empty

Since:

2.7

max

public static <T> T max(java.util.Iterator<T> iterator,
                        java.util.Comparator<? super T> comparator)

Finds the maximum element according to comparator. If there are several maxima, the first one will be returned.

Parameters:

iterator - the elements to find the maximum of. May not be null.

comparator - the comparison function. May not be null.

Returns:

the maximum

Throws:

java.util.NoSuchElementException - if the iterator is empty

Since:

2.7