edu.stanford.nlp.util

Class Iterables

java.lang.Object

edu.stanford.nlp.util.Iterables

public class Iterables
extends java.lang.Object

Utilities for helping out with Iterables as Collections is to Collection. NB: Some Iterables returned by methods in this class return Iterators that assume a call to hasNext will precede each call to next. While this usage is not up to the Java Iterator spec, it should work fine with e.g. the Java enhanced for-loop. Methods in Iterators are merged.

Author:

dramage, dlwh flatMap(Iterable, Function), Huy Nguyen (htnguyen@cs.stanford.edu)

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	Iterables.IncrementComparator<V1,V2> A comparator used by the merge functions to determine which of two iterators to increment by one of the merge functions.

Method Summary

Modifier and Type	Method and Description
static <T> java.util.Collection<T>	addAll(java.util.Iterator<? extends T> iter, java.util.Collection<T> c) Adds all of the Objects returned by the given Iterator into the given Collection.
static <T> java.util.ArrayList<T>	asArrayList(java.util.Iterator<? extends T> iter) Creates an ArrayList containing all of the Objects returned by the given Iterator.
static <E> java.util.Collection<E>	asCollection(java.util.Iterator<? extends E> iter, CollectionFactory<E> cf) Creates a new Collection from the given CollectionFactory, and adds all of the Objects returned by the given Iterator.
static <T> java.util.HashSet<T>	asHashSet(java.util.Iterator<? extends T> iter) Creates a HashSet containing all of the Objects returned by the given Iterator.
static <T> java.lang.Iterable<T>	cast(java.lang.Iterable<?> iterable, java.lang.Class<? extends T> type) Casts all values in the given Iterable to the given type.
static <T> java.lang.Iterable<T>	chain(java.lang.Iterable<? extends java.lang.Iterable<T>> iterables) Chains together a set of Iterables of compatible types.
static <T> java.lang.Iterable<T>	chain(java.lang.Iterable<T>... iterables) Chains together all Iterables of type T as given in an array or varargs parameter.
static <T> java.lang.Iterable<T>	chain(T[]... arrays) Chains together all arrays of type T[] as given in an array or varargs parameter.
static <T> java.lang.Iterable<T>	drop(java.lang.Iterable<T> iterable, int toDrop) Returns a view of the given data, ignoring the first toDrop elements.
static <T> java.lang.Iterable<T>	drop(T[] array, int toDrop) Returns a view of the given data, ignoring the first toDrop elements.
static <T> java.lang.Iterable<T>	filter(java.lang.Iterable<T> iterable, java.util.function.Predicate<T> accept) Filtered view of the given iterable.
static <T,U> java.lang.Iterable<U>	flatMap(java.lang.Iterable<? extends java.lang.Iterable<T>> iterables, java.util.function.Function<? super T,U> trans) Chains together an Iterable of Iterables after transforming each one.
static <V> java.lang.Iterable<java.lang.Iterable<V>>	group(java.lang.Iterable<V> iterable, java.util.Comparator<V> comparator) Groups consecutive elements from the given iterable based on the value in the given comparator.
static void	main(java.lang.String[] args) For internal debugging purposes only.
static <V> java.lang.Iterable<Pair<V,V>>	merge(java.lang.Iterable<V> iter1, java.lang.Iterable<V> iter2, java.util.Comparator<V> comparator) Same as merge(Iterable, Iterable, IncrementComparator) but using the given (symmetric) comparator.
static <V> java.lang.Iterable<Triple<V,V,V>>	merge(java.lang.Iterable<V> iter1, java.lang.Iterable<V> iter2, java.lang.Iterable<V> iter3, java.util.Comparator<V> comparator) Same as merge(Iterable, Iterable, Iterable, IncrementComparator, IncrementComparator) but using the given (symmetric) comparator.
static <V1,V2,V3> java.lang.Iterable<Triple<V1,V2,V3>>	merge(java.lang.Iterable<V1> iter1, java.lang.Iterable<V2> iter2, java.lang.Iterable<V3> iter3, Iterables.IncrementComparator<V1,V2> comparatorA, Iterables.IncrementComparator<V1,V3> comparatorB) Iterates over triples of objects from three (sorted) iterators such that for every returned triple a (from iter1), b (from iter2), c (from iter3) satisfies the constraint that comparator.compare(a,b) == comparator.compare(a,c) == 0.
static <V1,V2> java.lang.Iterable<Pair<V1,V2>>	merge(java.lang.Iterable<V1> iter1, java.lang.Iterable<V2> iter2, Iterables.IncrementComparator<V1,V2> comparator) Iterates over pairs of objects from two (sorted) iterators such that each pair a \in iter1, b \in iter2 returned has comparator.compare(a,b)==0.
static <T> java.lang.Iterable<T>	sample(java.lang.Iterable<T> items, int n, int k, java.util.Random random) Sample k items uniformly from an Iterable of size n (without replacement).
static <T> java.lang.Iterable<T>	take(java.lang.Iterable<T> iterable, int max) Returns a shortened view of an iterator.
static <T> java.lang.Iterable<T>	take(T[] array, int max) Returns a shortened view of an iterator.
static <E> java.lang.String	toString(java.lang.Iterable<E> iter, java.lang.String glue) Returns a string representation of the contents of calling toString on each element of the given iterable, joining the elements together with the given glue.
static <K,V> java.lang.Iterable<V>	transform(java.lang.Iterable<K> iterable, java.util.function.Function<? super K,? extends V> function) Transformed view of the given iterable.
static <T1,T2> java.lang.Iterable<Pair<T1,T2>>	zip(java.lang.Iterable<T1> iter1, java.lang.Iterable<T2> iter2) Zips two iterables into one iterable over Pairs of corresponding elements in the two underlying iterables.
static <T1,T2> java.lang.Iterable<Pair<T1,T2>>	zip(java.lang.Iterable<T1> iter, T2[] array) Zips two iterables into one iterable over Pairs of corresponding elements in the two underlying iterables.
static <T1,T2> java.util.Iterator<Pair<T1,T2>>	zip(java.util.Iterator<T1> iter1, java.util.Iterator<T2> iter2) Zips up two iterators into one iterator over Pairs of corresponding elements.
static <T1,T2> java.lang.Iterable<Pair<T1,T2>>	zip(T1[] array, java.lang.Iterable<T2> iter) Zips two iterables into one iterable over Pairs of corresponding elements in the two underlying iterables.
static <T1,T2> java.lang.Iterable<Pair<T1,T2>>	zip(T1[] array1, T2[] array2) Zips two iterables into one iterable over Pairs of corresponding elements in the two underlying iterables.

Methods inherited from class java.lang.Object

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

Method Detail

transform

public static <K,V> java.lang.Iterable<V> transform(java.lang.Iterable<K> iterable,
                                                    java.util.function.Function<? super K,? extends V> function)

Transformed view of the given iterable. Returns the output of the given function when applied to each element of the iterable.

filter

public static <T> java.lang.Iterable<T> filter(java.lang.Iterable<T> iterable,
                                               java.util.function.Predicate<T> accept)

Filtered view of the given iterable. Returns only those elements from the iterable for which the given Function returns true.

cast

public static <T> java.lang.Iterable<T> cast(java.lang.Iterable<?> iterable,
                                             java.lang.Class<? extends T> type)

Casts all values in the given Iterable to the given type.

take

public static <T> java.lang.Iterable<T> take(T[] array,
                                             int max)

Returns a shortened view of an iterator. Returns at most max elements.

take

public static <T> java.lang.Iterable<T> take(java.lang.Iterable<T> iterable,
                                             int max)

Returns a shortened view of an iterator. Returns at most max elements.

drop

public static <T> java.lang.Iterable<T> drop(T[] array,
                                             int toDrop)

Returns a view of the given data, ignoring the first toDrop elements.

drop

public static <T> java.lang.Iterable<T> drop(java.lang.Iterable<T> iterable,
                                             int toDrop)

Returns a view of the given data, ignoring the first toDrop elements.

flatMap

public static <T,U> java.lang.Iterable<U> flatMap(java.lang.Iterable<? extends java.lang.Iterable<T>> iterables,
                                                  java.util.function.Function<? super T,U> trans)

Chains together an Iterable of Iterables after transforming each one. Equivalent to Iterables.transform(Iterables.chain(iterables),trans);

chain

public static <T> java.lang.Iterable<T> chain(java.lang.Iterable<? extends java.lang.Iterable<T>> iterables)

Chains together a set of Iterables of compatible types. Returns all elements of the first iterable, then all of the second, then the third, etc.

chain

public static <T> java.lang.Iterable<T> chain(java.lang.Iterable<T>... iterables)

Chains together all Iterables of type T as given in an array or varargs parameter.

chain

public static <T> java.lang.Iterable<T> chain(T[]... arrays)

Chains together all arrays of type T[] as given in an array or varargs parameter.

zip

public static <T1,T2> java.lang.Iterable<Pair<T1,T2>> zip(java.lang.Iterable<T1> iter1,
                                                          java.lang.Iterable<T2> iter2)

Zips two iterables into one iterable over Pairs of corresponding elements in the two underlying iterables. Ends when the shorter iterable ends.

zip

public static <T1,T2> java.lang.Iterable<Pair<T1,T2>> zip(java.lang.Iterable<T1> iter,
                                                          T2[] array)

Zips two iterables into one iterable over Pairs of corresponding elements in the two underlying iterables. Ends when the shorter iterable ends.

zip

public static <T1,T2> java.lang.Iterable<Pair<T1,T2>> zip(T1[] array,
                                                          java.lang.Iterable<T2> iter)

Zips two iterables into one iterable over Pairs of corresponding elements in the two underlying iterables. Ends when the shorter iterable ends.

zip

public static <T1,T2> java.lang.Iterable<Pair<T1,T2>> zip(T1[] array1,
                                                          T2[] array2)

Zips two iterables into one iterable over Pairs of corresponding elements in the two underlying iterables. Ends when the shorter iterable ends.

zip

public static <T1,T2> java.util.Iterator<Pair<T1,T2>> zip(java.util.Iterator<T1> iter1,
                                                          java.util.Iterator<T2> iter2)

Zips up two iterators into one iterator over Pairs of corresponding elements. Ends when the shorter iterator ends.

merge

public static <V1,V2> java.lang.Iterable<Pair<V1,V2>> merge(java.lang.Iterable<V1> iter1,
                                                            java.lang.Iterable<V2> iter2,
                                                            Iterables.IncrementComparator<V1,V2> comparator)

Iterates over pairs of objects from two (sorted) iterators such that each pair a \in iter1, b \in iter2 returned has comparator.compare(a,b)==0. If the comparator says that a and b are not equal, we increment the iterator of the smaller value. If the comparator says that a and b are equal, we return that pair and increment both iterators. This is used, e.g. to return lines from two input files that have the same "key" as determined by the given comparator. The comparator will always be passed elements from the first iter as the first argument.

merge

public static <V> java.lang.Iterable<Pair<V,V>> merge(java.lang.Iterable<V> iter1,
                                                      java.lang.Iterable<V> iter2,
                                                      java.util.Comparator<V> comparator)

Same as merge(Iterable, Iterable, IncrementComparator) but using the given (symmetric) comparator.

merge

public static <V1,V2,V3> java.lang.Iterable<Triple<V1,V2,V3>> merge(java.lang.Iterable<V1> iter1,
                                                                    java.lang.Iterable<V2> iter2,
                                                                    java.lang.Iterable<V3> iter3,
                                                                    Iterables.IncrementComparator<V1,V2> comparatorA,
                                                                    Iterables.IncrementComparator<V1,V3> comparatorB)

Iterates over triples of objects from three (sorted) iterators such that for every returned triple a (from iter1), b (from iter2), c (from iter3) satisfies the constraint that comparator.compare(a,b) == comparator.compare(a,c) == 0. Internally, this function first calls merge(iter1,iter2,comparatorA), and then merges that iterator with the iter3 by comparing based on the value returned by iter1. This is used, e.g. to return lines from three input files that have the same "key" as determined by the given comparator.

merge

public static <V> java.lang.Iterable<Triple<V,V,V>> merge(java.lang.Iterable<V> iter1,
                                                          java.lang.Iterable<V> iter2,
                                                          java.lang.Iterable<V> iter3,
                                                          java.util.Comparator<V> comparator)

Same as merge(Iterable, Iterable, Iterable, IncrementComparator, IncrementComparator) but using the given (symmetric) comparator.

group

public static <V> java.lang.Iterable<java.lang.Iterable<V>> group(java.lang.Iterable<V> iterable,
                                                                  java.util.Comparator<V> comparator)

Groups consecutive elements from the given iterable based on the value in the given comparator. Each inner iterable will iterate over consecutive items from the input until the comparator says that the next item is not equal to the previous.

toString

public static <E> java.lang.String toString(java.lang.Iterable<E> iter,
                                            java.lang.String glue)

Returns a string representation of the contents of calling toString on each element of the given iterable, joining the elements together with the given glue.

sample

public static <T> java.lang.Iterable<T> sample(java.lang.Iterable<T> items,
                                               int n,
                                               int k,
                                               java.util.Random random)

Sample k items uniformly from an Iterable of size n (without replacement).

Parameters:

items - The items from which to sample.

n - The total number of items in the Iterable.

k - The number of items to sample.

random - The random number generator.

Returns:

An Iterable of k items, chosen randomly from the original n items.

asArrayList

public static <T> java.util.ArrayList<T> asArrayList(java.util.Iterator<? extends T> iter)

Creates an ArrayList containing all of the Objects returned by the given Iterator.

asHashSet

public static <T> java.util.HashSet<T> asHashSet(java.util.Iterator<? extends T> iter)

Creates a HashSet containing all of the Objects returned by the given Iterator.

asCollection

public static <E> java.util.Collection<E> asCollection(java.util.Iterator<? extends E> iter,
                                                       CollectionFactory<E> cf)

Creates a new Collection from the given CollectionFactory, and adds all of the Objects returned by the given Iterator.

addAll

public static <T> java.util.Collection<T> addAll(java.util.Iterator<? extends T> iter,
                                                 java.util.Collection<T> c)

Adds all of the Objects returned by the given Iterator into the given Collection.

Returns:

the given Collection

main

public static void main(java.lang.String[] args)

For internal debugging purposes only.