Sequence

Sequence is an abstraction of the order defined on a collection of elements of some type. The only operation that is allowed on a sequence is iterating its elements from first to last. A sequence is immutable. All operations defined in the following subsections and declared to return a sequence, always return a new instance of a sequence or the original sequence.

Although it is possible to create a sequence that produces infinite number of elements, it is not recommended. Some operations may require one or two full traversals of the sequence in order to compute, and invoking such an operation on an infinite sequence would never yield result.

Sequence type

sequence< Type >

Subtypes	Supertypes	Comparable types
list< Type > set< Type >	none	java.lang.Iterable<Type>

Creation

new sequence

Parameter type	Result type
{ => sequence< Type >}	sequence< Type >

Sequence can be created with initializer.

sequence<Type> seq = new sequence<Type>({=> /* code with yield keywords */ })

closure invocation

Result type
sequence< Type >

A sequence may be returned from a closure (see Closures ).

sequence<Type> seq = {=> /* code with yield keywords producing a sequence */
            }.invoke;
        

array as a sequence

Operand type	Parameter type	Result type
Type[]	none	sequence< Type >

An array can be used as a sequence.

T[] arrayOfT;
            sequence<T> seq = T.asSequence;
        

A list, a set and a map are sequences, too. All operations defined on a sequence are also available on an instance of any of these types.

Sequence type is assignable to a variable of type java.lang.Iterable. The opposite is also true.

Operations on sequence

Iteration and querying

foreach statement

Loop statement

foreach foo in bar {
                    ...
                    }
                

is equivalent to

for (Type foo: bar) {
                    ...
                    }
                

forEach

Operand type	Parameter type	Result type
sequence< Type >	{ Type => void}	void

The code passed as a parameter (as a closure literal or by reference) is executed once for each element.

seq.forEach({=> /* arbitrary code*/});

size

Operand type	Parameter type	Result type
sequence< Type >	none	int

Gives number of elements in a sequence.

isEmpty

Operand type	Parameter type	Result type
sequence< Type >	none	boolean

Test whether a sequence is empty, that is its size is 0.

isNotEmpty

Operand type	Parameter type	Result type
sequence< Type >	none	boolean

Test whether a sequence contains any elements.

indexOf

Operand type	Parameter type	Result type
sequence< Type >	Type	int

Gives the index of a first occurrence in a sequence of an element that is passed to it as a parameter.

int idx = seq.indexOf(elm)

contains

Operand type	Parameter type	Result type
sequence< Type >	Type	boolean

Produces boolean value, indicating whether or not a sequence contains the specified element.

if (seq.contains(elm)) {
                    ...
                    }
                

any / all

Operand type	Parameter type	Result type
sequence< Type >	{ Type => boolean}	boolean

Produces boolean value that indicates whether any (in case of any operation) or all (in case of all) of the elements in the input sequence match the condition specified by the closure.

if (seq.any({~it=> /* condition */ })) {
                    ...
                    }
                

iterator

Operand type	Parameter type	Result type
sequence< Type >	none	iterator< Type >

Produces an #iterator.

enumerator

Operand type	Parameter type	Result type
sequence< Type >	none	enumerator< Type >

Produces an #enumerator.

Selection and filtering

first

Operand type	Parameter type	Result type
sequence< Type >	none	Type

Yields the first element.

last

Operand type	Parameter type	Result type
sequence< Type >	none	Type

Yields the last element.

take

Operand type	Parameter type	Result type
sequence< Type >	int	sequence< Type >

Produces a sequence that is sub-sequence of the original one, starting from first element and of size count.

seq.take (count)

skip

Operand type	Parameter type	Result type
sequence< Type >	int	sequence< Type >

Produces a sequence that is sub-sequence of the original one, containing all elements starting with the element at index count.

seq.skip (count)

cut

Operand type	Parameter type	Result type
sequence< Type >	int	sequence< Type >

Produces a sequence that is a sub-sequence of the original one, containing all elements starting with first and up to (but not including) the element at index size minus count. In other words, this operation returns a sequence with all elements from the original one except the last count elements.

seq.cut (count)

tail

Operand type	Parameter type	Result type
sequence< Type >	int	sequence< Type >

Produces a sequence that is a sub-sequence of the original one, containing all elements starting with the element at index size minus count. In other words, this operations returns a sequence with count elements from the end of the original sequence, in the original order.

seq.tail (count)

page

Operand type	Parameter type	Result type
sequence< Type >	int int	sequence< Type >

Results in a sequence that is a sub-sequence of the original one, containing all elements starting with the element at index start and up to (but not including) the element at index end. It is a requirement that start is no greater than end.

seq.page (start, end)

This is equivalent to

seq.skip (skip).take (count)

Where skip = start, count = end - start .

where

Operand type	Parameter type	Result type
sequence< Type >	{ Type => boolean}	sequence< Type >

Produces a sequence that is a sub-sequence of the original one, with all elements for which the code passed as a parameter returns true.

seq.where ({ => ... })

ofType

Operand type	Parameter type	Result type
sequence< Type >	OtherType	sequence< OtherType >

Filters the sequence by the type of the elements. Returns a sub-sequence of the original one, with all elements which match the provided type. The collection is cast to the new element type.

seq.ofType<Integer>

findFirst

Operand type	Parameter type	Result type
sequence< Type >	{ Type => boolean}	Type

Results in the first element that matches the parameter closure.

seq.findFirst ({ => ... })

findLast

Operand type	Parameter type	Result type
sequence< Type >	{ Type => boolean}	Type

Results in the last element that matches the parameter closure.

seq.findLast ({ => ... })

Transformation and sorting

select

Operand type	Parameter type	Result type
sequence< Type >	{ Type => Type2 }	sequence< Type2 >

Results in a sequence consisting of elements, each of which is the result of applying the parameter function to each element of the original sequence in turn.

seq.select ({ Type element => /* code returning single element of same or some other
                type */ })
            

selectMany

Operand type	Parameter type	Result type
sequence< Type >	{ Type => sequence< Type2 >}	sequence< Type2 >

Produces a sequence that is a concatenation of all sequences, which are all the results of applying the parameter closure to each element of the original sequence in turn. The statements skip and stop are available within the parameter closure.

seq.selectMany ({ <Type> element => /* code returning a sequence. May utilize
                yield keyword.*/ })
            

distinct

Operand type	Parameter type	Result type
sequence< Type >	none	sequence< Type >

Produces a sequence, which contains all elements from the original sequence in the original order, with all the elements having cardinality exactly 1. Of all occurrences of an element in the original sequence only the first occurrence is included in the resulting sequence.

sortBy

Operand type	Parameter type	Result type
sequence< Type >	{ Type => Type2 } boolean	sequence< Type >

Produces a sequence with all elements from the original one in the order, which corresponds to an order induced by an imaginary sequence produced by applying the selector function to each element in the original sequence in turn. The selector function can be thought of as returning a key, which is used to sort elements in a sequence. The ascending parameter controls the sort order.

seq.sortBy ({ => /* code returning a sorting key */ }, ascending)

alsoSortBy

Operand type	Parameter type	Result type
sequence< Type >	{ Type => Type2 } boolean	sequence< Type >

Equivalent to sortBy, unless used as a chain operation immediately following sortBy or another alsoSortBy. The result is a sequence sorted with a compound key, with the first component taken from previous sortBy or alsoSortBy (which is also a compound key), and the last component taken from this operation.

seq.sortBy ({ => /* code returning a sorting key */ }, ascending).alsoSortBy ({ =>
                /* code returning another key */ }, descending)
            

sort

Operand type	Parameter type	Result type
sequence< Type >	{ Type, Type => int} boolean sequence< Type >

Produces a sequence containing all elements from the original one in the order produced by applying the comparator function (passed as a closure literal or by reference) to a list with elements from the original sequence. The ascending parameter controls the sort order (order is reversed if the value is false).

seq.sort ({ <Type> a, <Type> b => /* code returning -1, 0 or 1 according
                to java.util.Comparator */}, ascending)
            

Binary operations

All operations in this section have the semantics of operations on multisets. This means that the elements of both the operand and the parameter sequences are taken with their respective cardinalities (that is, how many times an element appears in the sequence), and then the cardinality of matched elements in the output is the result of an arithmetic operation on these values. These operations keep the order of elements (first operand's, then the parameter's).

intersect

Operand type	Parameter type	Result type
sequence< Type >	sequence< Type >	sequence< Type >

Produces a sequence containing elements contained both by the original sequence and the parameter sequence. More precisely, the cardinality in the output of an element appearing in both the operand and the parameter sequences, is the minimum of its cardinalities in the input.

seq.intersect (anotherSeq)

except

Operand type	Parameter type	Result type
sequence< Type >	sequence< Type >	sequence< Type >

Produces a sequence containing all elements from the original sequence that are not also members of the parameter sequence. More precisely, the cardinality in the output of an element appearing in both the operand and the parameter sequences, is the maximum of 0 and the result of subtracting the parameter's cardinality from the operand's cardinality.

seq.except (anotherSeq)

union

Operand type	Parameter type	Result type
sequence< Type >	sequence< Type >	sequence< Type >

Produces a sequence containing elements either from the original sequence or the one passed as a parameter. More precisely, the cardinality in the output of an element appearing in both the operand and the parameter sequences, is the maximum of its cardinalities in the input.

seq.union (anotherSeq)

disjunction

Operand type	Parameter type	Result type
sequence< Type >	sequence< Type >	sequence< Type >

Produces exclusive disjunction (symmetric difference) of the original sequence and the one passed as a parameter. This operation equivalent to:

(operand.except(param)).concat(parameter.except(operand))

seq.disjunction (anotherSeq)

concat

Operand type	Parameter type	Result type
sequence< Type >	sequence< Type >}	sequence< Type >

Produces a sequence, which is a concatenation of the original one with the sequence passed as a parameter.

seq.concat (otherSeq)

Conversion

reduceLeft / reduceRight

Operand type	Parameter type	Result type
sequence< Type >	{ Type, Type => Type }	Type

Operation reduceLeft/reduceRight applies the combinator function passed as a parameter to all elements of the sequence in turn. One of the function parameters is a sequence element, and another is the result of previous application of the function. Operation reduceLeft takes first two sequence elements and applies the function to them, then takes the result of the first application and the third sequence element, etc. Operation reduceRight does the same, but moving from the sequence's tail backwards.

sequence<int> int = ...
                int sum = in.reduceLeft({~a,~b => a + b; });
            

reduceLeft

{Type,Type => Type} f = ... // represented as *
                sequence<Type> seq = new sequence<Type>{A,B,C,D,E,F}; A B C D E F
                seq.reduceLeft(f) == f(f(f(f(f(A,B),C),D),E),F); \ | | | | |
                \| | | | |
                *\ | | | |
                \| | | |
                *\ | | |
                \| | |
                *\ | |
                \| |
                *\ |
                \|
                result of reduceLeft operation --> *
            

reduceRight

{Type,Type => Type} f = ... // represented as *
                sequence<Type> seq = new sequence<Type>{A,B,C,D,E,F} A B C D E F
                seq.reduceRight(f) == f(A,f(B,f(C,f(D,f(E,F)))))); | | | | | /
                | | | | |/
                | | | | /*
                | | | |/
                | | | /*
                | | |/
                | | /*
                | |/
                | /*
                |/
                result of reduceRight operation --> *
            

foldLeft / foldRight

Operand type	Parameter type	Result type	Applicable for
seed sequence< Type >	{ Z, Type => Z }	Z	foldLeft
seed sequence< Type >	{ Type, Z => Z }	Z	foldRight

Operation foldLeft/foldRight behaves similarly to reduceLeft/reduceRight, with the difference that it also accepts a seed value. Also the combinator function is asymmetric (it takes a Type and a Z parameters and returns a Z value). The result of the operation is of type Z.

sequence<int> int = ...
                string concat = in.foldLeft("",{string s,~it => "" + s + it; });
            

foldLeft

{Z,Type => Z} f = ... // represented as *
                Z z = ... // the "seed" value
                sequence<Type> seq = new sequence<Type>{A,B,C,D,E,F}; z A B C D E F
                seq.reduceLeft(f) == f(f(f(f(f(f(z,A),B),C),D),E),F); \ | | | | | |
                \| | | | | |
                *\ | | | | |
                \| | | | |
                *\ | | | |
                \| | | |
                *\ | | |
                \| | |
                *\ | |
                \| |
                *\ |
                \|
                result of foldLeft operation --> *
            

foldRight

{Type,Z => Z} f = ... // represented as *
                Z z = ... // the "seed" value
                sequence<Type> seq = new sequence<Type>{A,B,C,D,E,F} A B C D E F z
                seq.foldRight(f) == f(A,f(B,f(C,f(D,f(E,f(F,z))))))); | | | | | | /
                | | | | | |/
                | | | | | /*
                | | | | |/
                | | | | /*
                | | | |/
                | | | /*
                | | |/
                | | /*
                | |/
                | /*
                |/
                result of foldRight operation --> *
            

join

Operand type	Parameter type	Result type
sequence< ? extends string >	string (optional)	string

This operation is only available on a sequence of strings. The result is a string that is produced by concatenating all elements with the optional separator. The default separator is " " (single space).

seq.join ("; ");

toList

Operand type	Parameter type	Result type
sequence< Type >	none	list< Type >

Returns new list containing all the elements from the original sequence.

seq.toList

toArray

Operand type	Parameter type	Result type
sequence< Type >	none	Type[]

Returns new array containing all the elements from the original sequence.

seq.toArray

Last modified: 23 March 2021