TITLE

SUBTITLE

role Sequence does PositionalBindFailover { }


This role implements a series of methods for converting sequences and
accessing their elements. These methods should work on all sequences:
serial L<C<Seq>|/type/Seq>, ordered parallel L<C<HyperSeq>|/type/HyperSeq>,
and unordered parallel L<C<RaceSeq>|/type/RaceSeq>.


These methods have in common that they all access the underlying
iterator if the sequence has not been
L<cached|/type/PositionalBindFailover#method_cache> yet. Therefore they
will throw an error of type L<C<X::Seq::Consumed>|/type/X::Seq::Consumed>
if called on a L<C<Seq>|/type/Seq> that was already consumed.


head

L<Stringifies|/type/List#method_Str> the
L<cached|/type/PositionalBindFailover#method_cache> sequence.


Calls C<.Stringy> on the
L<cached|/type/PositionalBindFailover#method_cache> sequence.


Returns the number of elements in the
L<cached|/type/PositionalBindFailover#method_cache> sequence.


multi method AT-POS(::?CLASS:D: Int:D $idx)
multi method AT-POS(::?CLASS:D: int $idx)


Returns the element at position C<$idx> in the
L<cached|/type/PositionalBindFailover#method_cache> sequence.


multi method EXISTS-POS(::?CLASS:D: Int:D $idx)
multi method EXISTS-POS(::?CLASS:D: int $idx)


Returns a L<C<Bool>|/type/Bool> indicating whether there is an element at position
C<$idx> in the L<cached|/type/PositionalBindFailover#method_cache>
sequence.


Returns an eagerly evaluated L<C<List>|/type/List> based on the invocant
sequence, and marks it as consumed.
If called on an already consumed L<C<Seq>|/type/Seq>, throws an error of type
L<C<X::Seq::Consumed>|/type/X::Seq::Consumed>.


say $s.is-lazy; # OUTPUT: «True␤»
say $s.eager;   # OUTPUT: «(1 2 3 4 5)␤»


say $s.eager;
CATCH {
    when X::Seq::Consumed {
        say 'Throws exception if already consumed';
    }
}
# OUTPUT: «Throws exception if already consumed␤»


method fmt($format = '%s', $separator = ' ' --> Str:D)


L<Formats|/type/List#method_fmt> the
L<cached|/type/PositionalBindFailover#method_cache> sequence.


Returns the L<gist|/type/List#method_gist> of the
L<cached|/type/PositionalBindFailover#method_cache> sequence.


root

Object that supports looking up values by key


role Associative


Collection of distinct weighted objects


role Baggy


Immutable buffer for binary data ('Binary Large OBject')


role Blob


Mutable buffer for binary data


role Buf


Interface for container objects that can be iterated over


role Iterable


Generic API for producing a sequence of values


role Iterator


Collection of distinct objects with Real weights


role Mixy


Object that supports looking up values by index


role Positional


Failover for binding to a Positional


role PositionalBindFailover


Object hashes with a limitation on the type of values


role QuantHash


Collection of distinct objects


role Setty


Common methods of sequences


para

L<Examples| file:../examples/index.podlite>


L<Download |file:../download/index.podlite>


React

=begin React :component<HeaderCol> :id<menu> 
=para L<Documentation|/doc/introduction>
=para L<Modules| /mods>
=para L<Examples| file:../examples/index.podlite>
=para L<Download |file:../download/index.podlite>
=para L<About|file:../about/index.podlite>
=para 🔍 K<⌘K>/K<ctrl-K>
=end React


HEADER

FOOTER

role Sequence


Immutable collection of distinct objects


A C<Set> is an immutable set, meaning a collection of distinct elements in no
particular order. (For I<mutable> sets, see L<C<SetHash>|/type/SetHash> instead.)


Objects/values of any type are allowed as set elements. Within a C<Set>, every
element is guaranteed to be unique (in the sense that no two elements would
compare positively with the L<===|/routine/===> operator):


code

=begin code
my $fruits = set <peach apple orange apple apple>;

say $fruits.elems;      # OUTPUT: «3␤»
say $fruits.keys.sort;  # OUTPUT: «apple orange peach␤»
=end code


C<Set>s can be treated as object hashes using the C<{ }> postcircumfix operator,
which returns the value C<True> for keys that are elements of the set, and
C<False> for keys that aren't:


my $fruits = set <peach apple orange apple apple>;
say $fruits<apple>;  # OUTPUT: «True␤»
say $fruits<kiwi>;   # OUTPUT: «False␤»


C<Set>s can be composed using the L<set|#sub set> subroutine (or C<Set.new>, for
which it is a shorthand). Any positional parameters, regardless of their type,
become elements of the set:


my $n = set "zero" => 0, "one" => 1, "two" => 2;
say $n.keys.raku;        # OUTPUT: «(:two(2), :zero(0), :one(1)).Seq␤»
say $n.keys.map(&WHAT);  # OUTPUT: «((Pair) (Pair) (Pair))␤»


Alternatively, the C<.Set> coercer (or its functional form, C<Set()>) can be
called on an existing object to coerce it to a C<Set>. Its semantics depend on
the type and contents of the object. In general it evaluates the object in list
context and creates a set with the resulting items as elements, although for
Hash-like objects or Pair items, only the keys become elements of the set - and
keys mapped to values which boolify to C<False> are skipped:


my $n = ("zero" => 0, "one" => 1, "two" => 2).Set;
say $n.keys.raku;        # OUTPUT: «("one", "two").Seq␤»
say $n.keys.map(&WHAT);  # OUTPUT: «((Str) (Str))␤»


Furthermore, you can get a C<Set> by using set operators (see next section) on
objects of other types such as L<C<List>|/type/List>, which will act like they
internally call C<.Set> on them before performing the operation. Be aware of
the tight precedence of those operators though, which may require you to use
parentheses around arguments:


say (1..5) (^) 4;  # OUTPUT: «Set(1 2 3 5)␤»


You can also create a C<Set> with the C<.new> method.


my $fruits = Set.new( <peach apple orange apple apple> );


Since 6.d (2019.03 and later) you can also use this syntax for parameterization
of the C<Set>, to specify which type of values are acceptable:


# only allow strings (Str) in the Set
my $fruits = Set[Str].new( <peach apple orange apple apple> );


# only allow whole numbers (Int) in the Set
my $fruits = Set[Int].new( <peach apple orange apple apple> );
# Type check failed in binding; expected Int but got Str ("peach")


Finally, you can create C<Set> masquerading as a hash (actually, declare a
variable L<C<Associative>|/type/Associative> by using the corresponding sigil) by using the C<is>
trait:


my %s is Set = <a b c>;
say %s<a>;  # OUTPUT: «True␤»
say %s<d>;  # OUTPUT: «False␤»


Since 6.d (2019.03 and later), this syntax also allows you to specify the
type of values you would like to allow:


# limit to strings
my %s is Set[Str] = <a b c>;
say %s<a>;  # OUTPUT: «True␤»
say %s<d>;  # OUTPUT: «False␤»


# limit to whole numbers
my %s is Set[Int] = <a b c>;
# Type check failed in binding; expected Int but got Str ("a")


See L<Operators with set
semantics|/language/setbagmix#Operators_with_set_semantics> for a complete
list of "set operators" applicable to, among other types, C<Set>.


=begin code
my ($a, $b) = set(1, 2, 3), set(2, 4);

say $a (<) $b;  # OUTPUT: «False␤»
say $a (&) $b;  # OUTPUT: «Set(2)␤»
say $a (^) $b;  # OUTPUT: «Set(1 3 4)␤»

# Unicode versions:
say $a ⊂ $b;  # OUTPUT: «False␤»
say $a ∩ $b;  # OUTPUT: «Set(2)␤»
say $a ⊖ $b;  # OUTPUT: «Set(1 3 4)␤»
=end code


Creates a C<Set> from the given C<@args>


L<Sets, Bags, and Mixes|/language/setbagmix>


Sequence of itemized values


class Array


Immutable collection of distinct objects with integer weights


class Bag


Mutable collection of distinct objects with integer weights


class BagHash


Argument list suitable for passing to a Signature


class Capture


Mapping from strings to itemized values


class Hash


Low level storage of positional values


class IterationBuffer


Sequence of values


class List


Immutable mapping from strings to values


class Map


Immutable collection of distinct objects with Real weights


class Mix


Mutable collection of distinct objects with Real weights


class MixHash


Codepoint string in Normal Form C (composed)


class NFC


Codepoint string in Normal Form D (decomposed)


class NFD


Codepoint string in Normal Form KC (compatibility composed)


class NFKC


Codepoint string in Normal Form KD (compatibility decomposed)


class NFKD


Key/value pair


class Pair


Stash type for pseudo-packages


class PseudoStash


Interval of ordered values


class Range


An iterable, potentially lazy sequence of values


class Seq


Mutable collection of distinct objects


class SetHash


A kind of List that automatically flattens into an outer container


class Slip


Table for "our"-scoped symbols


class Stash


A string of Unicode codepoints


class Uni


Mutable uint8 buffer for utf8 binary data


class utf8


class Set


class Seq is Cool does Iterable does Sequence { }


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


A high-level construct to generate a C<Seq> is L«C<gather/take>|/syntax/gather%20take»,
as well as many built-in methods like L«C<map>|/routine/map» and
L«C<grep>|/routine/grep», low-level constructors to create a
C<Seq> from an iterator or from looping constructs are available too.


A C<Seq> can also be constructed with the
L«sequence operator C<...>|/language/operators#infix_...» 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 C<Seq> to an array consumes a C<Seq> that is
not lazy. Use the C<lazy> statement prefix to avoid a C<Seq> from being
iterated during the assignment:


=begin code
# 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␤»
=end code


A typical use case is L<method C<lines> in C<IO::Handle>|/type/IO::Handle#routine_lines>,
which could use a lot of memory if it stored all the lines read from the
file. So


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


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


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


my @a = 1, 2, 3;
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)»


B<Caution:> No program should ever assume a C<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 C<Seq> may become cached by many operations,
including calling C<.raku> (C<.perl> before version 2019.11) on the C<Seq> (if
called prior to a non-cached iteration). From version 6.d, C<.raku> (again,
C<.perl> before version 2019.11) can be called on consumed C<Seq>. If a program
assumes a C<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 C<Seq>, the cached list is used when C<&infix:<eqv>>, C<.Slip>,
C<.join>, C<.List>, C<.list>, C<.eager>, C<.Array> and C<.is-lazy> are called.


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


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


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


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


If the C<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 L<C<X::Seq::Consumed>|/type/X::Seq::Consumed>.


Otherwise returns an iterator over the cached list.


Returns C<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 L<C<X::Seq::Consumed>|/type/X::Seq::Consumed>.


Coerces the object to a L<C<List>|/type/List>, which is in turn coerced into a L<C<Capture>|/type/Capture>.


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


Because an infinite sequence cannot be evaluated till the end, such a
sequence I<should> be declared lazy. Calling C<.elems> on a lazy C<Seq>
L<fail|/routine/fail>s with L<C<X::Cannot::Lazy>|/type/X::Cannot::Lazy>.


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 C<Seq>-based callbacks.


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


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


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


Calls L<C<sink-all>|/routine/sink-all> if it is an L<C<Iterator>|/type/Iterator>, C<sink> if the Sequence is a list.


The Raku Knowledge Base


=begin React :component<HeaderCol> :id<footer>  
=begin nested :!nested
=item1 B<Language>
    =item2 L<Get started|file:../getting-started/getting-started.podlite>
    =item2 L<Why Raku?|/doc/language/faq#Why-should-I-learn-Raku-What's-so-great-about-it>
    =item2 L<Try Raku|https://glot.io/new/raku>
    =item2 L<Raku cheat sheet|https://github.com/Raku/mu/blob/master/docs/Perl6/Cheatsheet/cheatsheet.txt>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<Raku on Exercism|https://exercism.org/tracks/raku>
    =item2 L<Wikipedia|https://en.wikipedia.org/wiki/Raku_(programming_language)>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>

=end nested
=begin nested :!nested

=item1 B<L<Documentation|/doc>>
    =item2 L<Getting started, Migration guides from other languages, & Tutorials | file:../doc/introduction.podlite>
    =item2 L<Language References|file:../doc/reference.podlite>
    =item2 L<Type Reference| file:../doc/types.podlite>
    =item2 L<Miscellaneous| file:../doc/miscellaneous.podlite>
    =item2 L<FAQs (Frequently Asked Questions)|/doc/language/faq>
    =item2 L<Community|/doc/language/community>
    =item2 L<The list of all documents|file:../doc/index.podlite>

=item1 B<Resources>
    =item2 L<The Raku Guide|https://raku.guide/>
    =item2 L<Books |https://perl6book.com/>
    =item2 L<Rosetta Code | https://www.raku.org/community/rosettacode>

=end nested
=begin nested :!nested

=item1 B<Resoures>
    =item2 L<Download | file:../download/index.podlite>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>

=item1 B<Learning>
    =item2 L<The Raku Guide|https://raku.guide/>
    =item2 L<Wikibook |https://en.wikibooks.org/wiki/Raku_Programming>
    =item2 L<Books |https://perl6book.com/>
    =item2 L<Rosetta Code | https://www.raku.org/community/rosettacode>
    =item2 L<Learn Raku in Y minutes|https://learnxinyminutes.com/docs/raku/>
    =item2 L<Golfing |https://github.com/AlexDaniel/raku-golf-cheatsheet>
=end nested
=begin nested :!nested

=item1 B<Explore>
    =item2 L<Raku Blog Aggregator|https://planet.raku.org/>
    =item2 L<Rakudo Weekly|https://rakudoweekly.blog/>
    =item2 L<The Weekly Challenge |https://perlweeklychallenge.org/>
    =item2 L<Raku Advent Calendar|https://raku-advent.blog/>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>

=end nested
=end React


=begin React :component<CookieConsent> :id<CookieConsent> :buttonCaption("Got it!")
=para
This website uses cookies for analytics.
=end React


role Sequence

Methods

method Str

method Stringy

method Numeric

method AT-POS

method EXISTS-POS

method eager

method fmt

method gist

See Also