T M
class Seq
Error ReportCollection examples

An iterable, potentially lazy sequence of values

class Seq is Cool does Iterable does Sequence { }

A Seq represents anything that can produce a sequence of values. A Seq is born in a state where iterating it will consume the values. Calling .cache on a Seq will make it store the generated values for later access.

A high-level construct to generate a Seq is gather/take, as well as many built-in methods like map and grep, low-level constructors to create a Seq from an iterator or from looping constructs are available too.

A Seq can also be constructed with the sequence operator ... or one of its variants.

my $s = (1...5);
say $s;              # OUTPUT: «(1 2 3 4 5)␤» 
say $s.^name;        # OUTPUT: «Seq␤»

Assigning the values of a Seq to an array consumes a Seq that is not lazy. Use the lazy statement prefix to avoid a Seq from being iterated during the assignment:

# The Seq created by gather ... take is consumed on the spot here. 
my @a = gather do { say 'consuming...'take 'one' };  # OUTPUT: «consuming...␤» 
 
# The Seq here is only consumed as we iterate over @a later. 
my @a = lazy gather do { say 'consuming...'take 'one' };  # outputs nothing. 
.say for @a;  # OUTPUT: «consuming...␤one␤» 

A typical use case is method lines in IO::Handle, which could use a lot of memory if it stored all the lines read from the file. So

for open('README.md').lines -> $line {
    say $line;
}

won't keep all lines from the file in memory.

This implies that you cannot iterate the same Seq object twice (otherwise it couldn't throw away old values), so this dies:

my @a = 123;
my @b = <a b c>;
my \c = @a Z=> @b;
.say for c;
.say for c# fails 
CATCH { default { put .^name''.Str } };
# OUTPUT: «X::Seq::Consumed: This Seq has already been iterated, and its values consumed 
# (you might solve this by adding .cache on usages of the Seq, or 
# by assigning the Seq into an array)»

Caution: No program should ever assume a Seq may only be iterated once even if not cached by the program. Caching is a volatile state exposed to the developer as an optimization. The Seq may become cached by many operations, including calling .raku (.perl before version 2019.11) on the Seq (if called prior to a non-cached iteration). From version 6.d, .raku (again, .perl before version 2019.11) can be called on consumed Seq. If a program assumes a Seq can only iterate once, but then is later changed to call one of these operations during the loop, that assumption will fail.

On a cached Seq, the cached list is used when &infix:<eqv>, .Slip, .join, .List, .list, .eager, .Array and .is-lazy are called.

You can smartmatch a regex with Seq, even if it's infinite

my @fib = 1,1*+* ... *;
say @fib[^1000~~ /^9999/# OUTPUT: «Nil␤»

However, infinite or lazy Seq will be vivified when doing the match, leading to possibly infinite loops, so be sure to limit search somehow.

Methods

method new

proto method new(Seq: |{*}
multi method new(Seq: Iterator:D $iter)
multi method new(Seq:)

Creates a new Seq object from the supplied iterator passed as the single argument. Creates an empty Seq if called with no argument.

method iterator

method iterator(Seq:D:)

If the Seq is not cached, returns the underlying iterator and marks the invocant as consumed. If called on an already consumed sequence, throws an error of type X::Seq::Consumed.

Otherwise returns an iterator over the cached list.

method is-lazy

method is-lazy(Seq:D:)

Returns True if and only if the underlying iterator or cached list considers itself lazy. If called on an already consumed sequence, throws an error of type X::Seq::Consumed.

method Seq

Defined as

multi method Seq(Seq:D:)

Clones the object.

method Capture

Defined as

method Capture()

Coerces the object to a List, which is in turn coerced into a Capture

method elems

method elems(Seq:D:)

Returns the number of values in the sequence. If this number cannot be predicted, the Seq is cached and evaluated till the end.

Because an infinite sequence cannot be evaluated till the end, such a sequence should be declared lazy. Calling .elems on a lazy Seq fails with X::Cannot::Lazy.

method from-loop

multi method from-loop(&body:$label)
multi method from-loop(&body&cond:$repeat!:$label)
multi method from-loop(&body&cond:$label)
multi method from-loop(&body&cond&afterwards:$label)

These methods create new Seq-based callbacks.

In general, it produces an infinite Seq by calling &body each time a new element is requested, using the return value from &body as the item. This emulates (or implements) a loop { body } construct.

When the multi includes &cond, it's invoked before each call to &body, and terminates the sequence if &cond returns a false value. If $repeat is set to a true value, the first call to &cond is omitted, and &body called right away. This emulates (or implements) while cond { body } and repeat { body } while cond loops.

If present, &afterward will be called after each call to &body.

method sink

Defined as:

method sink(--> Nil)

Calls sink-all if it is an Iterator, sink if the Sequence is a list.

say (1 ... 1000).sink# OUTPUT: «Nil␤»

This is something you might want to do for the side effects of producing those values.

method skip

Defined as:

multi method skip(Int() $n = 1 --> Seq)

Returns a Seq containing whatever is left of the invocant after throwing away $n of the next available values. Negative values of $n count as 0. Also can take a WhateverCode to indicate how many values to skip from the end. Will block on lazy Seqs until the requested number of values have been discarded.

say (1..5).map({$_}).skip;      # OUTPUT: «(2,3,4,5)␤» 
say (1..5).map({$_}).skip(3);   # OUTPUT: «(4,5)␤» 
say (1..5).map({$_}).skip(5);   # OUTPUT: «()␤» 
say (1..5).map({$_}).skip(-1);  # OUTPUT: «(1,2,3,4,5)␤» 
say (1..5).map({$_}).skip(*-3); # OUTPUT: «(3,4,5)␤»