fj.data.Stream Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of functionaljava Show documentation
Show all versions of functionaljava Show documentation
Functional Java is an open source library that supports closures for the Java programming language
package fj.data;
import fj.Equal;
import fj.F0;
import fj.F3;
import fj.Hash;
import fj.Show;
import fj.F;
import fj.F2;
import fj.Function;
import fj.Monoid;
import fj.Ord;
import fj.P;
import fj.P1;
import fj.P2;
import fj.Unit;
import fj.control.parallel.Promise;
import fj.control.parallel.Strategy;
import fj.Ordering;
import fj.function.Effect1;
import java.util.*;
import static fj.Bottom.error;
import static fj.Function.*;
import static fj.P.p;
import static fj.P.p2;
import static fj.Unit.unit;
import static fj.control.parallel.Promise.promise;
import static fj.data.Array.mkArray;
import static fj.data.Option.none;
import static fj.data.Option.some;
import static fj.function.Booleans.not;
import static fj.Ordering.EQ;
import static fj.Ordering.GT;
import static fj.Ordering.LT;
/**
* A lazy (not yet evaluated), immutable, singly linked list.
*
* @version %build.number%
*/
public abstract class Stream implements Iterable {
private Stream() {
}
/**
* Returns an iterator for this stream. This method exists to permit the use in a for-each loop.
*
* @return A iterator for this stream.
*/
public final Iterator iterator() {
return toCollection().iterator();
}
/**
* The first element of the stream or fails for the empty stream.
*
* @return The first element of the stream or fails for the empty stream.
*/
public abstract A head();
/**
* The stream without the first element or fails for the empty stream.
*
* @return The stream without the first element or fails for the empty stream.
*/
public abstract P1> tail();
/**
* Returns true if this stream is empty, false otherwise.
*
* @return true if this stream is empty, false otherwise.
*/
public final boolean isEmpty() {
return this instanceof Nil;
}
/**
* Returns false if this stream is empty, true otherwise.
*
* @return false if this stream is empty, true otherwise.
*/
public final boolean isNotEmpty() {
return this instanceof Cons;
}
/**
* Performs a reduction on this stream using the given arguments. Equivalent to {@link #uncons}.
*
* @deprecated As of release 4.5, use {@link #uncons}
*
* @param nil The value to return if this stream is empty.
* @param cons The function to apply to the head and tail of this stream if it is not empty.
* @return A reduction on this stream.
*/
@Deprecated
public final B stream(final B nil, final F>, B>> cons) {
return uncons(nil, cons);
}
/**
* Performs a reduction on this stream using the given arguments.
*
* @param nil The value to return if this stream is empty.
* @param cons The function to apply to the head and tail of this stream if it is not empty.
* @return A reduction on this stream.
*/
public final B uncons(final B nil, final F>, B>> cons) {
return isEmpty() ? nil : cons.f(head()).f(tail());
}
/**
* Performs a right-fold reduction across this stream. This function uses O(length) stack space.
*
* @param f The function to apply on each element of the stream.
* @param b The beginning value to start the application from.
* @return The final result after the right-fold reduction.
*/
public final B foldRight(final F, B>> f, final B b) {
return isEmpty() ? b : f.f(head()).f(P.lazy(() -> tail()._1().foldRight(f, b)));
}
/**
* Performs a right-fold reduction across this stream. This function uses O(length) stack space.
*
* @param f The function to apply on each element of the stream.
* @param b The beginning value to start the application from.
* @return The final result after the right-fold reduction.
*/
public final B foldRight(final F2, B> f, final B b) {
return foldRight(curry(f), b);
}
/**
* Performs a right-fold reduction across this stream. This function uses O(length) stack space.
*
* @param f The function to apply on each element of the stream.
* @param b The beginning value to start the application from.
* @return The final result after the right-fold reduction.
*/
public final B foldRight1(final F> f, final B b) {
return foldRight(compose(Function., B, B>andThen().f(P1.__1()), f), b);
}
/**
* Performs a right-fold reduction across this stream. This function uses O(length) stack space.
*
* @param f The function to apply on each element of the stream.
* @param b The beginning value to start the application from.
* @return The final result after the right-fold reduction.
*/
public final B foldRight1(final F2 f, final B b) {
return foldRight1(curry(f), b);
}
/**
* Performs a left-fold reduction across this stream. This function runs in constant space.
*
* @param f The function to apply on each element of the stream.
* @param b The beginning value to start the application from.
* @return The final result after the left-fold reduction.
*/
public final B foldLeft(final F> f, final B b) {
return foldLeft(uncurryF2(f), b);
}
/**
* Performs a left-fold reduction across this stream. This function runs in constant space.
*
* @param f The function to apply on each element of the stream.
* @param b The beginning value to start the application from.
* @return The final result after the left-fold reduction.
*/
public final B foldLeft(final F2 f, final B b) {
B x = b;
for (Stream xs = this; !xs.isEmpty(); xs = xs.tail()._1())
x = f.f(x, xs.head());
return x;
}
/**
* Takes the first 2 elements of the stream and applies the function to them,
* then applies the function to the result and the third element and so on.
*
* @param f The function to apply on each element of the stream.
* @return The final result after the left-fold reduction.
*/
public final A foldLeft1(final F2 f) {
if (isEmpty())
throw error("Undefined: foldLeft1 on empty list");
return tail()._1().foldLeft(f, head());
}
/**
* Takes the first 2 elements of the stream and applies the function to them,
* then applies the function to the result and the third element and so on.
*
* @param f The function to apply on each element of the stream.
* @return The final result after the left-fold reduction.
*/
public final A foldLeft1(final F> f) {
return foldLeft1(uncurryF2(f));
}
/**
* Returns the head of this stream if there is one or the given argument if this stream is empty.
*
* @param a The argument to return if this stream is empty.
* @return The head of this stream if there is one or the given argument if this stream is empty.
*/
public final A orHead(final F0 a) {
return isEmpty() ? a.f() : head();
}
/**
* Returns the tail of this stream if there is one or the given argument if this stream is empty.
*
* @param as The argument to return if this stream is empty.
* @return The tail of this stream if there is one or the given argument if this stream is empty.
*/
public final P1> orTail(final F0> as) {
return isEmpty() ? P.lazy(as) : tail();
}
/**
* Intersperses the given value between each two elements of the stream.
*
* @param a The value to intersperse between values of the stream.
* @return A new stream with the given value between each two elements of the stream.
*/
public final Stream intersperse(final A a) {
return isEmpty() ? this : cons(head(), new P1>() {
public Stream _1() {
return prefix(a, tail()._1());
}
public Stream prefix(final A x, final Stream xs) {
return xs.isEmpty() ? xs : cons(x, p(cons(xs.head(), () -> prefix(a, xs.tail()._1()))));
}
});
}
/**
* Maps the given function across this stream.
*
* @param f The function to map across this stream.
* @return A new stream after the given function has been applied to each element.
*/
public final Stream map(final F f) {
return isEmpty() ? Stream.nil() : cons(f.f(head()), () -> tail()._1().map(f));
}
/**
* Provides a first-class version of the map function.
*
* @return A function that maps a given function across a given stream.
*/
public static F, F, Stream>> map_() {
return f -> as -> as.map(f);
}
/**
* Performs a side-effect for each element of this stream.
*
* @param f The side-effect to perform for the given element.
* @return The unit value.
*/
public final Unit foreach(final F f) {
for (Stream xs = this; xs.isNotEmpty(); xs = xs.tail()._1())
f.f(xs.head());
return unit();
}
/**
* Performs a side-effect for each element of this stream.
*
* @param f The side-effect to perform for the given element.
*/
public final void foreachDoEffect(final Effect1 f) {
for (Stream xs = this; xs.isNotEmpty(); xs = xs.tail()._1())
f.f(xs.head());
}
/**
* Filters elements from this stream by returning only elements which produce true
* when the given function is applied to them.
*
* @param f The predicate function to filter on.
* @return A new stream whose elements all match the given predicate.
*/
public final Stream filter(final F f) {
final Stream as = dropWhile(not(f));
return as.isNotEmpty() ? cons(as.head(), () -> as.tail()._1().filter(f)) : as;
}
/**
* Appends the given stream to this stream.
*
* @param as The stream to append to this one.
* @return A new stream that has appended the given stream.
*/
public final Stream append(final Stream as) {
return isEmpty() ? as : cons(head(), () -> tail()._1().append(as));
}
/**
* Appends the given stream to this stream.
*
* @param as The stream to append to this one.
* @return A new stream that has appended the given stream.
*/
public final Stream append(final F0> as) {
return isEmpty() ? as.f() : cons(head(), () -> tail()._1().append(as));
}
/**
* Returns a new stream of all the items in this stream that do not appear in the given stream.
*
* @param eq an equality for the items of the streams.
* @param xs a list to subtract from this stream.
* @return a stream of all the items in this stream that do not appear in the given stream.
*/
public final Stream minus(final Equal eq, final Stream xs) {
return removeAll(compose(Monoid.disjunctionMonoid.sumLeftS(), xs.mapM(curry(eq.eq()))));
}
/**
* Filters elements from this stream by returning only elements which produce false when
* the given function is applied to them.
*
* @param f The predicate function to filter on.
* @return A new stream whose elements do not match the given predicate.
*/
public final Stream removeAll(final F f) {
return filter(compose(not, f));
}
/**
* Turn a stream of functions into a function returning a stream.
*
* @param fs The stream of functions to sequence into a single function that returns a stream.
* @return A function that, when given an argument, applies all the functions in the given stream to it
* and returns a stream of the results.
*/
public static F> sequence_(final Stream> fs) {
return fs.foldRight((baf, p1) -> Function.bind(baf, p1._1(), curry((a, stream) -> cons(a, p(stream)))), Function
.constant(Stream.nil()));
}
/**
* Maps the given function of arity-2 across this stream and returns a function that applies all the resulting
* functions to a given argument.
*
* @param f A function of arity-2
* @return A function that, when given an argument, applies the given function to that argument and every element
* in this list.
*/
public final F> mapM(final F> f) {
return sequence_(map(f));
}
/**
* Binds the given function across each element of this stream with a final join.
*
* @param f The function to apply to each element of this stream.
* @return A new stream after performing the map, then final join.
*/
public final Stream bind(final F> f) {
return foldRight(h -> t -> f.f(h).append(t), nil());
}
/**
* Binds the given function across each element of this stream and the given stream with a final
* join.
*
* @param sb A given stream to bind the given function with.
* @param f The function to apply to each element of this stream and the given stream.
* @return A new stream after performing the map, then final join.
*/
public final Stream bind(final Stream sb, final F> f) {
return sb.apply(map(f));
}
/**
* Binds the given function across each element of this stream and the given stream with a final
* join.
*
* @param sb A given stream to bind the given function with.
* @param f The function to apply to each element of this stream and the given stream.
* @return A new stream after performing the map, then final join.
*/
public final Stream bind(final Stream sb, final F2 f) {
return bind(sb, curry(f));
}
/**
* Binds the given function across each element of this stream and the given streams with a final
* join.
*
* @param sb A given stream to bind the given function with.
* @param sc A given stream to bind the given function with.
* @param f The function to apply to each element of this stream and the given streams.
* @return A new stream after performing the map, then final join.
*/
public final Stream bind(final Stream sb, final Stream sc, final F>> f) {
return sc.apply(bind(sb, f));
}
/**
* Binds the given function across each element of this stream and the given streams with a final
* join.
*
* @param sb A given stream to bind the given function with.
* @param sc A given stream to bind the given function with.
* @param sd A given stream to bind the given function with.
* @param f The function to apply to each element of this stream and the given streams.
* @return A new stream after performing the map, then final join.
*/
public final Stream bind(final Stream sb, final Stream sc, final Stream sd,
final F>>> f) {
return sd.apply(bind(sb, sc, f));
}
/**
* Binds the given function across each element of this stream and the given streams with a final
* join.
*
* @param sb A given stream to bind the given function with.
* @param sc A given stream to bind the given function with.
* @param sd A given stream to bind the given function with.
* @param se A given stream to bind the given function with.
* @param f The function to apply to each element of this stream and the given streams.
* @return A new stream after performing the map, then final join.
*/
public final Stream bind(final Stream sb, final Stream sc, final Stream sd,
final Stream se, final F>>>> f) {
return se.apply(bind(sb, sc, sd, f));
}
/**
* Binds the given function across each element of this stream and the given streams with a final
* join.
*
* @param sb A given stream to bind the given function with.
* @param sc A given stream to bind the given function with.
* @param sd A given stream to bind the given function with.
* @param se A given stream to bind the given function with.
* @param sf A given stream to bind the given function with.
* @param f The function to apply to each element of this stream and the given streams.
* @return A new stream after performing the map, then final join.
*/
public final Stream bind(final Stream sb, final Stream sc, final Stream sd,
final Stream se, final Stream sf,
final F>>>>> f) {
return sf.apply(bind(sb, sc, sd, se, f));
}
/**
* Binds the given function across each element of this stream and the given streams with a final
* join.
*
* @param sb A given stream to bind the given function with.
* @param sc A given stream to bind the given function with.
* @param sd A given stream to bind the given function with.
* @param se A given stream to bind the given function with.
* @param sf A given stream to bind the given function with.
* @param sg A given stream to bind the given function with.
* @param f The function to apply to each element of this stream and the given streams.
* @return A new stream after performing the map, then final join.
*/
public final Stream bind(final Stream sb, final Stream sc, final Stream sd,
final Stream se, final Stream sf, final Stream sg,
final F>>>>>> f) {
return sg.apply(bind(sb, sc, sd, se, sf, f));
}
/**
* Binds the given function across each element of this stream and the given streams with a final
* join.
*
* @param sb A given stream to bind the given function with.
* @param sc A given stream to bind the given function with.
* @param sd A given stream to bind the given function with.
* @param se A given stream to bind the given function with.
* @param sf A given stream to bind the given function with.
* @param sg A given stream to bind the given function with.
* @param sh A given stream to bind the given function with.
* @param f The function to apply to each element of this stream and the given streams.
* @return A new stream after performing the map, then final join.
*/
public final Stream bind(final Stream sb, final Stream sc, final Stream sd,
final Stream se, final Stream sf, final Stream sg,
final Stream sh,
final F>>>>>>> f) {
return sh.apply(bind(sb, sc, sd, se, sf, sg, f));
}
/**
* Performs a bind across each stream element, but ignores the element value each time.
*
* @param bs The stream to apply in the final join.
* @return A new stream after the final join.
*/
public final Stream sequence(final Stream bs) {
final F> c = constant(bs);
return bind(c);
}
/**
* Sequence through the Stream monad.
*
* @param io The IO stream to sequence.
* @return The stream of IOs after sequencing.
*/
public static Stream> sequence(final IO> io) {
return IOFunctions.runSafe(io).map(IOFunctions::unit);
}
/**
* Sequence through the Stream monad.
*
* @param p The lazy stream to sequence.
* @return The stream of (pre-calculated) lazy values after sequencing.
*/
public static Stream> sequence(final F0> p) {
return p.f().map(P::p);
}
/**
* Sequence through the Stream monad.
*
* @param o The optional stream to sequence.
* @return The stream of options after sequencing.
*/
public static Stream> sequence(final Option> o) {
return o.isNone() ? nil() : o.some().map(Option::some);
}
/**
* Performs function application within a stream (applicative functor pattern).
*
* @param sf The stream of functions to apply.
* @return A new stream after applying the given stream of functions through this stream.
*/
public final Stream apply(final Stream> sf) {
return sf.bind(this::map);
}
/**
* Interleaves the given stream with this stream to produce a new stream.
*
* @param as The stream to interleave this stream with.
* @return A new stream with elements interleaved from this stream and the given stream.
*/
public final Stream interleave(final Stream as) {
return isEmpty() ? as : as.isEmpty() ? this : cons(head(), () -> as.interleave(tail()._1()));
}
public static Stream enumerationStream(Enumeration e) {
if (e.hasMoreElements()) {
return cons(e.nextElement(), () -> enumerationStream(e));
} else {
return nil();
}
}
/**
* Sort this stream according to the given ordering.
*
* @param o An ordering for the elements of this stream.
* @return A new stream with the elements of this stream sorted according to the given ordering.
*/
public final Stream sort(final Ord o) {
return mergesort(o, map(flip(Stream.cons()).f(p(Stream.nil()))));
}
// Merges a stream of individually sorted streams into a single sorted stream.
private static Stream mergesort(final Ord o, final Stream> s) {
if (s.isEmpty())
return nil();
Stream> xss = s;
while (xss.tail()._1().isNotEmpty())
xss = mergePairs(o, xss);
return xss.head();
}
// Merges individually sorted streams two at a time.
private static Stream> mergePairs(final Ord o, final Stream> s) {
if (s.isEmpty() || s.tail()._1().isEmpty())
return s;
final Stream> t = s.tail()._1();
return cons(merge(o, s.head(), t.head()), () -> mergePairs(o, t.tail()._1()));
}
// Merges two individually sorted streams.
private static Stream merge(final Ord o, final Stream xs, final Stream ys) {
if (xs.isEmpty())
return ys;
if (ys.isEmpty())
return xs;
final A x = xs.head();
final A y = ys.head();
if (o.isGreaterThan(x, y))
return cons(y, () -> merge(o, xs, ys.tail()._1()));
return cons(x, () -> merge(o, xs.tail()._1(), ys));
}
/**
* Sort this stream according to the given ordering, using a parallel Quick Sort algorithm that uses the given
* parallelisation strategy.
*
* @param o An ordering for the elements of this stream.
* @param s A strategy for parallelising the algorithm.
* @return A new stream with the elements of this stream sorted according to the given ordering.
*/
public final Stream sort(final Ord o, final Strategy s) {
return qs(o, s).claim();
}
private Promise> qs(final Ord o, final Strategy s) {
if (isEmpty())
return promise(s, p(this));
else {
final F id = identity();
final A x = head();
final P1> xs = tail();
final Promise> left = Promise.join(s, xs.map(flt(o, s, x, id)));
final Promise> right = xs.map(flt(o, s, x, not))._1();
final Monoid> m = Monoid.streamMonoid();
return right.fmap(m.sum(single(x))).apply(left.fmap(m.sum()));
}
}
private static F, Promise>> qs_(final Ord o, final Strategy s) {
return xs -> xs.qs(o, s);
}
private static F, Promise>> flt(final Ord o,
final Strategy s,
final A x,
final F f) {
final F, F, Stream>> filter = filter();
final F lt = o.isLessThan(x);
return compose(qs_(o, s), filter.f(compose(f, lt)));
}
/**
* Projects an immutable collection of this stream.
*
* @return An immutable collection of this stream.
*/
public final Collection toCollection() {
return new AbstractCollection() {
public Iterator iterator() {
return new Iterator() {
private Stream xs = Stream.this;
public boolean hasNext() {
return xs.isNotEmpty();
}
public A next() {
if (xs.isEmpty())
throw new NoSuchElementException();
else {
final A a = xs.head();
xs = xs.tail()._1();
return a;
}
}
public void remove() {
throw new UnsupportedOperationException();
}
};
}
public int size() {
return length();
}
};
}
/**
* Returns a stream of integers from the given from value (inclusive) to the given
* to value (exclusive).
*
* @param from The minimum value for the stream (inclusive).
* @param to The maximum value for the stream (exclusive).
* @return A stream of integers from the given from value (inclusive) to the given
* to value (exclusive).
*/
public static Stream range(final int from, final long to) {
return from >= to ? Stream.nil() : cons(from, () -> range(from + 1, to));
}
/**
* Constructs a stream with the given elements.
*
* @param as The elements which which to construct a stream.
* @return a new stream with the given elements.
*/
@SafeVarargs public static Stream stream(final A... as) {
return arrayStream(as);
}
/**
* Constructs a stream with the given elements in the Iterable. Equivalent to {@link #iterableStream(Iterable)} .
*
* @deprecated As of release 4.5, use {@link #iterableStream(Iterable)}
*/
@Deprecated
public static Stream stream(Iterable it) {
return iterableStream(it);
}
/**
* Constructs a stream with the given elements in the Iterator. Equivalent to {@link #iteratorStream(Iterator)} .
*
* @deprecated As of release 4.5, use {@link #iteratorStream(Iterator)}
*/
@Deprecated
public static Stream stream(final Iterator it) {
return iteratorStream(it);
}
/**
* Constructs a stream with the given elements in the Iterator.
*/
public static Stream iteratorStream(final Iterator it) {
if (it.hasNext()) {
final A a = it.next();
return cons(a, () -> iteratorStream(it));
} else
return nil();
}
/**
* Returns a stream that is either infinite or bounded up to the maximum value of the given iterator starting at the
* given value and stepping at increments of 1.
*
* @param e The enumerator to compute successors from.
* @param from The value to begin computing successors from.
* @return A stream that is either infinite or bounded up to the maximum value of the given iterator starting at the
* given value and stepping at increments of 1.
*/
public static Stream forever(final Enumerator e, final A from) {
return forever(e, from, 1L);
}
/**
* Returns a stream that is either infinite or bounded up to the maximum value of the given iterator starting at the
* given value and stepping at the given increment.
*
* @param e The enumerator to compute successors from.
* @param from The value to begin computing successors from.
* @param step The increment to step.
* @return A stream that is either infinite or bounded up to the maximum value of the given iterator starting at the
* given value and stepping at the given increment.
*/
public static Stream forever(final Enumerator e, final A from, final long step) {
return cons(from, () -> e.plus(from, step).map(a -> forever(e, a, step)).orSome(Stream.nil()));
}
/**
* Returns a stream using the given enumerator from the given value to the other given value stepping at increments of
* 1.
*
* @param e The enumerator to compute successors from.
* @param from The value to begin computing successors from.
* @param to The value to stop computing successors from.
* @return A stream using the given enumerator from the given value to the other given value stepping at increments of
* 1.
*/
public static Stream range(final Enumerator e, final A from, final A to) {
return range(e, from, to, 1L);
}
/**
* Returns a stream using the given enumerator from the given value to the other given value stepping at the given
* increment.
*
* @param e The enumerator to compute successors from.
* @param from The value to begin computing successors from.
* @param to The value to stop computing successors from.
* @param step The increment to step.
* @return A stream using the given enumerator from the given value to the other given value stepping at the given
* increment.
*/
public static Stream range(final Enumerator e, final A from, final A to, final long step) {
final Ordering o = e.order().compare(from, to);
return o == EQ || step > 0L && o == GT || step < 0L && o == LT ? single(from) : cons(from, () -> join(e.plus(from, step).filter(a -> !(o == LT
? e.order().isLessThan(to, a)
: e.order().isGreaterThan(to, a))).map(a1 -> range(e, a1, to, step)).toStream()));
}
/**
* Returns an infinite stream of integers from the given from value (inclusive).
*
* @param from The minimum value for the stream (inclusive).
* @return A stream of integers from the given from value (inclusive).
*/
public static Stream range(final int from) {
return cons(from, () -> range(from + 1));
}
/**
* Returns a first-class version of the filter function.
*
* @return a function that filters a given stream using a given predicate.
*/
public static F, F, Stream>> filter() {
return curry((f, as) -> as.filter(f));
}
/**
* Zips this stream with the given stream of functions, applying each function in turn to the
* corresponding element in this stream to produce a new stream. If this stream and the given stream
* have different lengths, then the longer stream is normalised so this function never fails.
*
* @param fs The stream of functions to apply to this stream.
* @return A new stream with a length the same as the shortest of this stream and the given stream.
*/
public final Stream zapp(final Stream> fs) {
return fs.isEmpty() || isEmpty() ? Stream.nil() :
cons(fs.head().f(head()), () -> tail()._1().zapp(fs.tail()._1()));
}
/**
* Zips this stream with the given stream using the given function to produce a new stream. If
* this stream and the given stream have different lengths, then the longer stream is normalised
* so this function never fails.
*
* @param bs The stream to zip this stream with.
* @param f The function to zip this stream and the given stream with.
* @return A new stream with a length the same as the shortest of this stream and the given
* stream.
*/
public final Stream zipWith(final Stream bs, final F> f) {
return bs.zapp(zapp(repeat(f)));
}
/**
* Zips this stream with the given stream using the given function to produce a new stream. If
* this stream and the given stream have different lengths, then the longer stream is normalised
* so this function never fails.
*
* @param bs The stream to zip this stream with.
* @param f The function to zip this stream and the given stream with.
* @return A new stream with a length the same as the shortest of this stream and the given
* stream.
*/
public final Stream zipWith(final Stream bs, final F2 f) {
return zipWith(bs, curry(f));
}
/**
* Partially-applied version of zipWith.
* Returns a function that zips a given stream with this stream using the given function.
*
* @param f The function to zip this stream and a given stream with.
* @return A function that zips a given stream with this stream using the given function.
*/
public final F, Stream> zipWith(final F> f) {
return stream -> zipWith(stream, f);
}
/**
* Zips this stream with the given stream to produce a stream of pairs. If this stream and the
* given stream have different lengths, then the longer stream is normalised so this function
* never fails.
*
* @param bs The stream to zip this stream with.
* @return A new stream with a length the same as the shortest of this stream and the given
* stream.
*/
public final Stream> zip(final Stream bs) {
final F>> __2 = p2();
return zipWith(bs, __2);
}
/**
* Zips this stream with the index of its element as a pair.
*
* @return A new stream with the same length as this stream.
*/
public final Stream> zipIndex() {
return zipWith(range(0), (F2>) P::p);
}
/**
* Returns an either projection of this stream; the given argument in Left if empty,
* or the first element in Right.
*
* @param x The value to return in left if this stream is empty.
* @return An either projection of this stream.
*/
public final Either toEither(final F0 x) {
return isEmpty() ? Either.left(x.f()) : Either.right(head());
}
/**
* Returns an option projection of this stream; None if empty, or the first element
* in Some.
*
* @return An option projection of this stream.
*/
public final Option toOption() {
return isEmpty() ? Option.none() : some(head());
}
/**
* To be removed in future release:
* affectation of the result of this method to a non generic array
* will result in runtime error (ClassCastException).
*
* @deprecated As of release 4.6, use {@link #array(Class)}.
*/
@Deprecated
public final A[] toJavaArray() {
@SuppressWarnings("unchecked")
final A[] array = (A[]) new Object[length()];
int i = 0;
for (A a: this) {
array[i] = a;
i++;
}
return array;
}
/**
* Returns a list projection of this stream.
*
* @return A list projection of this stream.
*/
public final List toList() {
List.Buffer buf = List.Buffer.empty();
foreachDoEffect(buf::snoc);
return buf.toList();
}
/**
* Returns a java.util.List projection of this stream.
*/
public final java.util.List toJavaList() {
return new java.util.LinkedList<>(toCollection());
}
/**
* Returns a array projection of this stream.
*
* @return A array projection of this stream.
*/
@SuppressWarnings("unchecked")
public final Array toArray() {
final int l = length();
final Object[] a = new Object[l];
Stream x = this;
for (int i = 0; i < l; i++) {
a[i] = x.head();
x = x.tail()._1();
}
return mkArray(a);
}
/**
* Returns a array projection of this stream.
*
* @param c The class type of the array to return.
* @return A array projection of this stream.
*/
@SuppressWarnings({"unchecked", "UnnecessaryFullyQualifiedName"})
public final Array toArray(final Class c) {
final A[] a = (A[]) java.lang.reflect.Array.newInstance(c.getComponentType(), length());
int i = 0;
for (final A x : this) {
a[i] = x;
i++;
}
return Array.array(a);
}
/**
* Returns an array from this stream.
*
* @param c The class type of the array to return.
* @return An array from this stream.
*/
public final A[] array(final Class c) {
return toArray(c).array(c);
}
/**
* Prepends (cons) the given element to this stream to product a new stream.
*
* @param a The element to prepend.
* @return A new stream with the given element at the head.
*/
public final Stream cons(final A a) {
return new Cons<>(a, () -> Stream.this);
}
/**
* Returns a string from the given stream of characters. The inverse of this function is {@link
* #fromString(String)}.
*
* @param cs The stream of characters to produce the string from.
* @return A string from the given stream of characters.
*/
public static String asString(final Stream cs) {
StringBuilder sb = new StringBuilder();
cs.foreachDoEffect(sb::append);
return sb.toString();
}
/**
* Returns a stream of characters from the given string. The inverse of this function is {@link
* #asString(Stream)}.
*
* @param s The string to produce the stream of characters from.
* @return A stream of characters from the given string.
*/
public static Stream fromString(final String s) {
return LazyString.str(s).toStream();
}
/**
* Append the given element to this stream to product a new stream.
*
* @param a The element to append.
* @return A new stream with the given element at the end.
*/
public final Stream snoc(final A a) {
return snoc(p(a));
}
/**
* Append the given element to this stream to produce a new stream.
*
* @param a The element to append.
* @return A new stream with the given element at the end.
*/
public final Stream snoc(final F0 a) {
return append(() -> single(a.f()));
}
/**
* Returns the first n elements from the head of this stream.
*
* @param n The number of elements to take from this stream.
* @return The first n elements from the head of this stream.
*/
public final Stream take(final int n) {
return n <= 0 || isEmpty() ?
Stream.nil() :
cons(head(), () -> n <= 1 ? Stream.nil() : tail()._1().take(n - 1));
}
/**
* Drops the given number of elements from the head of this stream if they are available.
*
* @param i The number of elements to drop from the head of this stream.
* @return A stream with a length the same, or less than, this stream.
*/
public final Stream drop(final int i) {
Stream xs = this;
for (int c = 0; xs.isNotEmpty() && c < i; xs = xs.tail()._1())
c++;
return xs;
}
/**
* Returns the first elements of the head of this stream that match the given predicate function.
*
* @param f The predicate function to apply on this stream until it finds an element that does not
* hold, or the stream is exhausted.
* @return The first elements of the head of this stream that match the given predicate function.
*/
public final Stream takeWhile(final F f) {
return isEmpty() ?
this :
f.f(head()) ?
cons(head(), () -> tail()._1().takeWhile(f)) :
Stream.nil();
}
/**
* Traversable instance of Stream for IO.
*
* @return traversed value
*/
public final IO> traverseIO(F> f) {
return this.foldRight1((a, acc) ->
IOFunctions.bind(acc, (Stream bs) ->
IOFunctions.map(f.f(a), bs::cons)), IOFunctions.unit(Stream.nil()));
}
/**
* Traversable instance of Stream for Option.
*
* @return traversed value
*/
public final Option> traverseOption(F> f) {
return this.foldRight1((a, acc) -> acc.bind(bs -> f.f(a).map(bs::cons)), some(Stream.nil()));
}
/**
* Removes elements from the head of this stream that do not match the given predicate function
* until an element is found that does match or the stream is exhausted.
*
* @param f The predicate function to apply through this stream.
* @return The stream whose first element does not match the given predicate function.
*/
public final Stream dropWhile(final F f) {
Stream as;
//noinspection StatementWithEmptyBody
for (as = this; !as.isEmpty() && f.f(as.head()); as = as.tail()._1()) ;
return as;
}
/**
* Returns a tuple where the first element is the longest prefix of this stream that satisfies
* the given predicate and the second element is the remainder of the stream.
*
* @param p A predicate to be satisfied by a prefix of this stream.
* @return A tuple where the first element is the longest prefix of this stream that satisfies
* the given predicate and the second element is the remainder of the stream.
*/
public final P2, Stream> span(final F p) {
if (isEmpty())
return p(this, this);
else if (p.f(head())) {
final P1, Stream>> yszs = P.lazy(() -> tail()._1().span(p));
return P.lazy(
() -> cons(head(), yszs.map(P2.__1())),
() -> yszs._1()._2()
);
} else
return p(Stream.nil(), this);
}
/**
* Returns a new stream resulting from replacing all elements that match the given predicate with the given element.
*
* @param p The predicate to match replaced elements.
* @param a The element with which to replace elements.
* @return A new stream resulting from replacing all elements that match the given predicate with the given element.
*/
public final Stream replace(final F p, final A a) {
if (isEmpty())
return nil();
else {
final P2, Stream> s = span(p);
return s._1().append(cons(a, () -> s._2().tail()._1().replace(p, a)));
}
}
/**
* Returns a tuple where the first element is the longest prefix of this stream that does not satisfy
* the given predicate and the second element is the remainder of the stream.
*
* @param p A predicate not to be satisfied by a prefix of this stream.
* @return A tuple where the first element is the longest prefix of this stream that does not satisfy
* the given predicate and the second element is the remainder of the stream.
*/
public final P2, Stream> split(final F p) {
return span(compose(not, p));
}
/**
* Reverse this stream in constant stack space.
*
* @return A new stream that is the reverse of this one.
*/
public final Stream reverse() {
return foldLeft((as, a) -> cons(a, () -> as), Stream.nil());
}
/**
* Get the last element of this stream. Undefined for infinite streams.
*
* @return The last element in this stream, if there is one.
*/
public final A last() {
return reverse().head();
}
/**
* The length of this stream. This function will not terminate for an infinite stream.
*
* @return The length of this stream.
*/
public final int length() {
// we're using an iterative approach here as the previous implementation (toList().length()) took
// very long even for some 10000 elements.
Stream xs = this;
int i = 0;
while (!xs.isEmpty()) {
xs = xs.tail()._1();
i += 1;
}
return i;
}
/**
* Returns the element at the given index if it exists, fails otherwise.
*
* @param i The index at which to get the element to return.
* @return The element at the given index if it exists, fails otherwise.
*/
public final A index(final int i) {
if (i < 0)
throw error("index " + i + " out of range on stream");
else {
Stream xs = this;
for (int c = 0; c < i; c++) {
if (xs.isEmpty())
throw error("index " + i + " out of range on stream");
xs = xs.tail()._1();
}
if (xs.isEmpty())
throw error("index " + i + " out of range on stream");
return xs.head();
}
}
/**
* Returns true if the predicate holds for all of the elements of this stream,
* false otherwise (true for the empty stream).
*
* @param f the predicate function to test on each element of this stream.
* @return true if the predicate holds for all of the elements of this stream,
* false otherwise.
*/
public final boolean forall(final F f) {
for (final A a : this) {
if (!f.f(a)) return false;
}
return true;
}
@Override
public final boolean equals(Object other) {
return Equal.equals0(Stream.class, this, other, () -> Equal.streamEqual(Equal.anyEqual()));
}
@Override
public final int hashCode() {
return Hash.streamHash(Hash.anyHash()).hash(this);
}
@Override
public final String toString() {
return toStringLazy();
}
public final String toStringLazy() {
return isEmpty() ? "Nil()" : "Cons(" + Show.anyShow().showS(head()) + ", ?)";
}
public final String toStringEager() {
return Show.streamShow(Show.anyShow()).showS(this);
}
/**
* Returns true if the predicate holds for at least one of the elements of this
* stream, false otherwise (false for the empty stream).
*
* @param f The predicate function to test on the elements of this stream.
* @return true if the predicate holds for at least one of the elements of this
* stream.
*/
public final boolean exists(final F f) {
return dropWhile(not(f)).isNotEmpty();
}
/**
* Finds the first occurrence of an element that matches the given predicate or no value if no
* elements match.
*
* @param f The predicate function to test on elements of this stream.
* @return The first occurrence of an element that matches the given predicate or no value if no
* elements match.
*/
public final Option find(final F f) {
for (Stream as = this; as.isNotEmpty(); as = as.tail()._1()) {
if (f.f(as.head()))
return some(as.head());
}
return none();
}
/**
* Binds the given function across the stream of substreams of this stream.
*
* @param k A function to bind across this stream and its substreams.
* @return a new stream of the results of applying the given function to this stream and its substreams.
*/
public final Stream cobind(final F, B> k) {
return substreams().map(k);
}
/**
* Returns a stream of the suffixes of this stream. A stream is considered to be a suffix of itself in this context.
*
* @return a stream of the suffixes of this stream, starting with the stream itself.
*/
public final Stream> tails() {
return isEmpty() ? Stream.nil() : cons(this, () -> tail()._1().tails());
}
/**
* Returns a stream of all prefixes of this stream. A stream is considered a prefix of itself in tnis context.
*
* @return a stream of the prefixes of this stream, starting with the stream itself.
*/
public final Stream> inits() {
final Stream> nil = cons(Stream.nil(), Stream::nil);
return isEmpty() ? nil : nil.append(() -> tail()._1().inits().map(Stream.cons_().f(head())));
}
/**
* Returns a stream of all infixes of this stream. A stream is considered to contain itself.
*
* @return a stream of the infixes of this stream.
*/
public final Stream> substreams() {
return tails().bind(Stream::inits);
}
/**
* Returns the position of the first element matching the given predicate, if any.
*
* @param p A predicate to match.
* @return the position of the first element matching the given predicate, if any.
*/
public final Option indexOf(final F p) {
return zipIndex().find(p2 -> p.f(p2._1())).map(P2.__2());
}
/**
* Applies a stream of comonadic functions to this stream, returning a stream of values.
*
* @param fs A stream of comonadic functions to apply to this stream.
* @return A new stream of the results of applying the stream of functions to this stream.
*/
public final Stream sequenceW(final Stream, B>> fs) {
return fs.isEmpty()
? Stream.nil()
: cons(fs.head().f(this), () -> sequenceW(fs.tail()._1()));
}
/**
* Converts this stream to a function of natural numbers.
*
* @return A function from natural numbers to values with the corresponding position in this stream.
*/
public final F toFunction() {
return this::index;
}
/**
* Converts a function of natural numbers to a stream.
*
* @param f The function to convert to a stream.
* @return A new stream of the results of the given function applied to the natural numbers, starting at 0.
*/
public static Stream fromFunction(final F f) {
return fromFunction(Enumerator.naturalEnumerator, f, Natural.ZERO);
}
/**
* Converts a function of an enumerable type to a stream of the results of that function,
* starting at the given index.
*
* @param e An enumerator for the domain of the function.
* @param f The function to convert to a stream.
* @param i The index into the function at which to begin the stream.
* @return A new stream of the results of the given function applied to the values of the given enumerator,
* starting at the given value.
*/
public static Stream fromFunction(final Enumerator e, final F f, final B i) {
return cons(f.f(i), () -> {
final Option s = e.successor(i);
return s.isSome()
? fromFunction(e, f, s.some())
: Stream.nil();
});
}
/**
* Transforms a stream of pairs into a stream of first components and a stream of second components.
*
* @param xs The stream of pairs to transform.
* @return A stream of first components and a stream of second components.
*/
public static P2, Stream> unzip(final Stream> xs) {
return xs.foldRight((p, ps) -> {
final P2, Stream> pp = ps._1();
return p(cons(p._1(), p(pp._1())), cons(p._2(), p(pp._2())));
}, p(Stream.nil(), Stream.nil()));
}
/**
* A first-class version of the zipWith function.
*
* @return a function that zips two given streams with a given function.
*/
public static F, F