A sequence of elements, supporting sequential and parallel operations.
Seq pipelines
There are two kinds of operations in seq; intermediate and terminal operations. A seq pipeline consists of zero or more
intermediate operations and a terminal operation.
Intermediate operations
Intermediate operations are always lazy. It means that traversal of the source does not begin until a terminal operation is
executed. They return a new seq that will perform the operation, and the operation will be performed just before a terminal operation is
executed. The previous seq, that has called the intermediate operation method, of the new one is closed and can no longer be used.
Intermediate operations are further divided into stateless and stateful operations. Stateless operations retain no state
from previously seen element when processing a new element. Therefore, each element can be processed independently on other elements.
Stateful operations may incorporate state from previously seen elements when processing new elements, and may need to process the entire
input before producing a result. Consequently, seq pipelines containing stateful intermediate operations may require multiple passes or
may need to buffer significant data. On the contrary, seq pipelines containing only stateless intermediate (and terminal) operations can
be processed in a single pass.
Terminal operations
Terminal operations may traverse the source to produce a result or a side-effect. Almost all of terminal operations are eager.
They complete their traversal of the input and processing of the pipeline before the future completed. The only exceptions are
Seq.iterator and Seq.spliterator. They
are provided for client-controlled traversals. After a terminal operation is performed, the seq is closed and can no longer be used.
Short-circuiting
Some operations are regarded as short-circuiting operations. A short-circuiting intermediate operation may produce a finite seq as
a result when infinite input given. A short-circuiting terminal operation may terminate in finite time when infinite input given. For
processing a seq of infinite source to terminate normally in finite time, it is necessary that the pipeline contains a short-circuiting
operation.
Parallelism
When the terminal operation is started, the seq pipeline is executed sequentially or in parallel depending on the mode of the seq on
which it is invoked. The mode is sequential in an initial seq, and can be changed by
Seq.sequential and Seq.parallel intermediate operations.
All operations respect encounter order in sequential execution. In parallel execution, however, all stateful intermediate and terminal
operations may not respect the encounter order, except for operations identified as explicitly ordered such as
Seq.find_first.
Non-interference
If a data source, such as list, is used to create a seq, the data source must not be interfered until the execution of the seq
pipeline is completed. It means ensuring that the data source is not modified until the execution of the seq pipeline is completed. Except
for the non-eager operations iterator() and spliterator(), execution is performed when the terminal operation is invoked. In case of the
non-eager operations, the data source must not be modified while the iterator/spliterator is used.
Stateless
The result of seq pipeline may be nondeterministic or incorrect if the behaviors to the seq operations are stateful -- its result
depends on any state that might change during the execution of the seq pipeline.
Associativity
An associative operator or function '~' follows: (a ~ b) ~ c == a ~ (b ~ c)
Numeric addition, numeric multiplication, min, max, and string concatenation are examples of associative operations.
Notes
With nullable primitive types, operations using GLib.CompareDataFunc function, such as order_by(), produce
an undesirable result if the compare function is not specified. You should provide specified compare function to get a proper result.
Some operation might not work properly with unowned types. The best approach is never to use unowned types for seq.
If an operation method is tried after the seq has been closed, the try is (assertion) failed.
A result future of a sequential pipeline is already completed when returned from the terminal operation method, and therefore you do not
have to wait the future for getting the value.
- public Future<void*> @foreach (owned Func<G> f)
Applies the given function to each element of this seq.
- public Future<bool?> all_match (Predicate<G> pred)
Returns whether or not all elements of this seq match the given
predicate. If the seq is empty, the result is true.
- public Future<bool?> any_match (Predicate<G> pred)
Returns whether or not any elements of this seq match the given
predicate. If the seq is empty, the result is false.
- public Seq<G> chop (int64 offset, int64 length = -1)
Returns a seq which contains the remaining elements of this seq after
discarding the first n elements, truncated to be no longer than n in length.
- public Seq<G> chop_ordered (int64 offset, int64 length = -1)
Returns a seq which contains the remaining elements of this seq after
discarding the first n elements, truncated to be no longer than n in length.
- public void close ()
Closes this seq.
- public Future<R> collect<R,A> (Collector<R,A,G> collector)
Performs a mutable reduction operation on the elements of this seq.
- public Future<R> collect_ordered<R,A> (Collector<R,A,G> collector)
Performs a mutable reduction operation on the elements of this seq.
- public Future<int64?> count ()
Returns the count of elements in this seq.
- public Seq<G> distinct (owned HashDataFunc<G>? hash = null, owned EqualDataFunc<G>? equal = null)
Returns a seq which contains the distinct elements of this seq, based
on the given functions.
- public Seq<G> filter (owned Predicate<G> pred)
Returns a seq which contains the elements of this seq that match the
given predicate.
- public Future<Optional<G>> find_any (Predicate<G> pred)
Returns an optional describing the any element that matches the given
predicate, or an empty optional if not found.
- public Future<Optional<G>> find_first (Predicate<G> pred)
Returns an optional describing the first element that matches the
given predicate, or an empty optional if not found.
- public Seq<A> flat_map<A> (owned FlatMapFunc<A,G> mapper)
Returns a seq which contains the elements of the results of applying
the given mapper function to the elements of this seq.
- public Future<A> fold<A> (FoldFunc<A,G> accumulator, CombineFunc<A> combiner, A identity)
Performs a reduction operation on the elements of this seq. This is
equivalent to:
- public Future<Map<K,List<G>>> group_by<K> (owned MapFunc<K,G> classifier)
Groups the elements based on the classifier function and
returns the results in a map.
- public Iterator<G> iterator ()
Returns an iterator for the elements of this seq.
- public Seq<G> limit (int64 n)
Returns a seq which contains the remaining elements of this seq,
truncated to be no longer than n in length.
- public Seq<G> limit_ordered (int64 n)
Returns a seq which contains the remaining elements of this seq,
truncated to be no longer than n in length.
- public Seq<A> map<A> (owned MapFunc<A,G> mapper)
Returns a seq which contains the results of applying the given mapper
function to the elements of this seq.
- public Future<Optional<G>> max (owned CompareDataFunc<G>? compare = null)
Returns the maximum element of this seq, based on the given compare
function.
- public Future<Optional<G>> min (owned CompareDataFunc<G>? compare = null)
Returns the minimum element of this seq, based on the given compare
function.
- public Future<bool?> none_match (Predicate<G> pred)
Returns whether or not no elements of this seq match the given
predicate. If the seq is empty, the result is true.
- public Seq<G> order_by (owned CompareDataFunc<G>? compare = null)
Returns a seq which contains the elements of this seq, sorted based on
the given compare function. The sort is stable.
- public Seq<G> parallel ()
Returns a new equivalent seq that is parallel.
- public Future<Map<bool,List<G>>> partition (owned Predicate<G> pred)
Partitions the elements based on the pred function and returns
the results in a map.
- public Future<Optional<G>> reduce (CombineFunc<G> accumulator)
Performs a reduction operation on the elements of this seq. This is
equivalent to:
- public Seq<G> reverse_order_by (owned CompareDataFunc<G>? compare = null)
Returns a seq which contains the elements of this seq, sorted based on
the given compare function, but in descending order. The sort is stable.
- public Seq<G> sequential ()
Returns a new equivalent seq that is sequential.
- public Seq<G> skip (int64 n)
Returns a seq which contains the remaining elements of this seq after
discarding the first n elements.
- public Seq<G> skip_ordered (int64 n)
Returns a seq which contains the remaining elements of this seq after
discarding the first n elements.
- public Spliterator<G> spliterator ()
Returns a spliterator for the elements of this seq.
- public Future<GenericArray<G>> to_generic_array ()
Accumulates the elements into a new generic array, in encounter order.
- public Future<List<G>> to_list ()
Accumulates the elements into a new list, in encounter order.
- public Future<Map<K,V>> to_map<K,V> (owned MapFunc<K,G> key_mapper, owned MapFunc<V,G> val_mapper, owned CombineFunc<V>? merger = null, owned HashDataFunc<K>? key_hash = null, owned EqualDataFunc<K>? key_equal = null, owned EqualDataFunc<V>? value_equal = null)
Accumulates the elements into a new map.
- public Future<Set<G>> to_set (owned HashDataFunc<G>? hash = null, owned EqualDataFunc<G>? equal = null)
Accumulates the elements into a new set.