Package com.singularsys.extensions.stream

package com.singularsys.extensions.stream

Package to allow use of Stream in Jep. Either in a chained function notation

[1..10] . map(x=>x^2) . fold([x,y] =>x+y) -> total

which is syntactically the same as the chained package. Or in a traditions notations

total = fold([x,y]=>x+y, map(x=>x^2, [1..10]))

The individual PFMCs either return a Stream, take a Stream as argument or both.

Using streams allows for indefinite sequences

iterate(2, n=>n+2) . limit(20)

values will only be calculated as needed by down-stream functions.

There are three main types of function in this package:

• Generators: return a stream
• Intermediate functions: take a stream as input perform some operation on it and return another stream
• Terminal Functions: take a stream as input and return some other data type, often a number or a list.

The StreamFunctionSet contains a number of standard stream functions including the generator iterate, the intermediate functions map, filter and sort and the terminal function fold.

The StreamOperatorTable defines the operators used with streams: the chaining operator ., the lambda function definition operator =>, the range operator .., and the right-hand assignment operator ->. It also redfines the left hand assingment operator = and optionally the ternary conditional operator ? : .

These are implements using a number of classes, which can also be user to add new functions.

Generators:

• StreamRange produces a finite sequence of numbers, [1..10]
• StreamIterate produces either a finite or infinite sequence iterate(2, n=>n+2, n=>n<20) or iterate(2, n=>n+2)
• StreamSourcePfmc uses an external stream as source, say reading from a file or database
• FieldStreamRange produces a finite sequence of numbers using a FieldI to calculate the next value and determine when to end the stream.

Intermediate functions:

• StreamMap performs an operation on each element of the stream, {[1..10] . map(x => x^2)
• StreamExternalMap uses an external function which implements Function<Object, Object> or a UnaryFunction like SquareRoot {[1..10] . sqrt()
• StreamFilter filters elements of a stream using a lambda function [1..10] . filter(x=>x%2 ==0)
• StreamExternalFilter filters elements of a stream using a function which implements Predicate<Object> or a UnaryFunction which returns a Boolean. [1..10] . even()
• StreamSort sorts elements of a stream using a lambda function stream([3,2,7,6,8]). sort([x,y]=>x-y).
• StreamExternalSort sorts elements of a stream using a function which implements Comparator<Object> or a BinaryFunction which returns a Integer.
• StreamLimit return only the first n elements from a stream,
• StreamSkip skips the first n elements from a stream,
• StreamWhile return elements from a stream while a predicate is true,
• StreamAppend concatenates two streams together,
• StreamMerge merge two streams together pairwise using a lambda function
• StreamLoop loops a stream indefinitely.

Terminal Functions:

• StreamFold reduces elements of a stream using a lambda function [3,2,7,6,8] . fold([x,y]=>x+y). By default throws an exception if the stream is empty.
• StreamFoldOr reduces elements of a stream using a lambda function, returning a default value if the stream is empty [3,2,7,6,8] . foldOr([x,y]=>x+y, -1). Returns -1 if the stream is empty.
• StreamReduce reduces elements of a stream using a lambda function and an initial value [3,2,7,6,8] . reduce(1, [x,y]=>x*y). Returns 1 if the stream is empty.
• StreamFirst returns the first element of a stream
• StreamFirstOr returns the first element of a stream or a default value if the stream is empty.
• StreamLast returns the last element of a stream.
• StreamCount counts the number of elements in a stream.
• StreamMinMax finds the minimum or maximum numeric value of a stream.
• StreamTerminalFunction uses a Jep function to perform a terminal operation on a stream,
• StreamTerminalNaryBinaryFunction uses a Jep Nary-Binary function to perform a terminal operation on a stream.
• {link StreamCollector} uses a Java Collector to perform a terminal operation on a stream.

Functions for operators:

• StreamAssign an left hand assignment operator, = that converts streams to lists. v = [1..10]. map(x=>x^2)
• StreamSendTo an right hand assignment operator -> that converts streams to lists. [1..10]. map(x=>x^2) -> v
• StreamRange used in the range syntax [1..10], returns a stream of values between the endpoints.
• FieldStreamRange used in the range syntax [1..10], returns a stream of values calculated using a FieldI.

Two other classes are used to implement the stream processing functions.

• StreamEvaluator. An evaluator which converts final stream result to a List. This decorates an other evaluator.
• StreamListProcessor. Helper functions to convert arguments to and from streams and lists.

Typically the stream processing functions will used adapters in the chained package to build functions that can be used in a chain

[1..10] . map(x=>x^2) . foldOr([x,y] =>x+y,-1)

Here the map and fold functions are defined with

jep.addFunction("map",new ChainableBinaryFunction(new StreamMap()));
jep.addFunction("foldOr",
    new ChainableGeneralFunction(
        new ChainedNaryFunction(new StreamFoldOr()),
        new StreamFoldOr(),
        n -> n.jjtGetNumChildren() == 2));

Most functions mirror those in the lambda package but are written to use methods in the Stream class.

The terminal functions StreamFirst, StreamFold, StreamLast, StreamMinMax and StreamTerminalNaryBinaryFunction all, by default, throw an exception if the stream is empty. These all implement ZeroLengthBehaviourI so can be configured to return a default value instead.

Simple setup

The StreamOperatorTable creates a set of operators for lambda functions, and the range operator. The ConfigurableParserWithRange adds support for parsing the range operator syntax [1..10]. The StreamFunctionSet adds the various stream enabled higher order functions the StreamListProcessor converts resutls to and from streams and lists, and the StreamEvaluator converts stream results to lists.

var cot = new StreamOperatorTable("=>", "..", "->", true);
var cp = new ConfigurableParserWithRange("..");
FunctionSet lfs = new StreamFunctionSet();
lp = new StreamListProcessor();
StreamEvaluator se = new StreamEvaluator(new FastEvaluator());
jep = new Jep(cot, cp, lp, se, lfs);

Since:

Jep 4.1, extension 2.2

See Also:

• Chained function documentation
• Lambda function documentation

Related Packages

Package	Description
com.singularsys.extensions	Extensions to the main Jep package.
com.singularsys.extensions.stream.dictionary	Provides a set of components for using dictionaries compatible with the com.singularsys.extensions.stream package.

Classes

Class	Description
FieldStreamRange	A function which returns an increasing sequence using a FieldI.
StreamAccumulate	Accumulate values in a sequence returning a sequence of intermediate values.
StreamAnyMatch	Tests a predicate against sequence.
StreamAppend	Concatenates two streams into a single stream.
StreamApply	Apply a lambda function, converting stream arguments to lists and passing them as a single argument.
StreamAssign	An assignment operator that converts rhs streams values to Vector<Object> using the List.
StreamCar	Extract the first element from a stream.
StreamCdr	Extract a stream with the first element removed.
StreamClone	Create a new stream with the same elements as the original stream.
StreamCollector	Collects the elements of a stream into a list using a provided Collector.
StreamCount	Counts the number of elements in a stream and returns it as a Number.
StreamDistinct	Return only distinct elements of a stream.
StreamEvaluator	An evaluator that works with stream converting the final result of StreamEvaluator.evaluate(Node) to a list.
StreamExternalFilter	Filters elements of a stream based on a externally defined predicate.
StreamExternalMap	Applies an externally defined mapping function to each element of a stream.
StreamExternalSort	Sorts elements of a stream based on a comparator.
StreamFilter	Filter a list using a lambda function returning only those elements which meet a criteria.
StreamFirst	Returns the first element from a stream.
StreamFirstMatchOr	Finds the first element that matches a predicate or return a default value.
StreamFirstOr	Returns the first element from a stream or a default value if the stream is empty.
StreamFold	Fold a list using a lambda function to reduce the list down to a single argument.
StreamFoldOr	Fold or reduce a list using a lambda function and an defualt value returned when the stream is empty.
StreamFunctionSet	Adds stream processing functions.
StreamIterate	Generate an infinite sequence using iteration using an initial value and a lambda function to calculate the next value and optionally a lambda function to determine when to end the stream.
StreamLast	Returns the last element from a stream.
StreamLimit	Return only the first n elements of a stream.
StreamListProcessor	A ListProcessor implementation that can process lists, vectors and streams.
StreamLoop	Takes a stream and returns a stream that loops over the same elements indefinitely.
StreamMap	Apply a lambda function to a list of arguments returning a list.
StreamMatrixListProcessor	A ListProcessor implementation that can convert MatrixI, VectorI to and from streams.
StreamMerge	Joins two sequences together, element by element.
StreamMinMax	Returns the minimum or maximum element from a stream.
StreamOperatorTable	An OperatorTable for stream package.
StreamRange	A function which returns an increasing sequence of double values all the items between the end points inclusive.
StreamReduce	Reduce a list to a single value using a lambda function and an initial identity value.
StreamSendTo	An assignment operator so we can do 3+4 -> x This function implements the CallbackEvaluationI interface so that it handles setting the value of a variable.
StreamSendToStream	An assignment operator allowing unclosed steams to be saved to a variable.
StreamSkip	Skip the first n elements of a stream.
StreamSort	Use a lambda functions to sort items in a stream.
StreamSourcePfmc	A PostfixMathCommandI which returns a stream specified in the constructor.
StreamTerminalFunction	A terminal function that takes a Stream as its single argument, takes all elements from the stream and passes them as arguments to the inner functions.
StreamTerminalNaryBinaryFunction	Terminal function that reduces a stream to a single value using an NaryBinaryFunction.
StreamToList	Convert the Stream to a list using the ListProcessor.
StreamWhile	Filter a stream so only the elements from the start of the stream that match a criteria are returned.