Lists, Sequences, and Arrays

Positional data constructs

Lists have been a central part of computing since before there were computers, during which time many devils have taken up residence in their details. They were actually one of the hardest parts of Perl 6 to design, but through persistence and patience, Perl 6 has arrived with an elegant system for handling them.

Literal Lists

Literal Lists are created with commas and semicolons not with parentheses, so:

12;        # This is two-element list 
(12);      # This is also a List, in parentheses 
(12);      # same List (see below) 
(1);         # This is not a List, just a 1 in parentheses 
(1,);        # This is a one-element List 

There is one exception, empty lists are created with just parenthesis:

    ();          # This is an empty List 
    (,);         # This is a syntax error 

Note that hanging commas are just fine as long as the beginning and end of a list are clear, so feel free to use them for easy code editing.

Parentheses can be used to mark the beginning and end of a List, so:

(12), (12); # This is a list of two lists. 

Lists of Lists can also be created by combining comma and semicolon. This is also called multi-dimensional syntax, because it is most often used to index multidimensional arrays.

say so (1,23,4eqv ((1,2), (3,4));
# OUTPUT: «True␤» 
say so (1,23,4;) eqv ((1,2), (3,4));
# OUTPUT: «True␤» 
say so ("foo";) eqv ("foo"eqv (("foo")); # not a list 
# OUTPUT: «True␤» 

Unlike a comma, a hanging semicolon does not create a multidimensional list in a literal. However, be aware that this behavior changes in most argument lists, where the exact behavior depends on the function... but will usually be:

say('foo';);   # a list with one element and the empty list 
# OUTPUT: «(foo)()␤» 
say(('foo';)); # no list, just the string "foo" 
# OUTPUT: «foo␤» 

Because the semicolon doubles as a statement terminator it will end a literal list when used at the top level, instead creating a statement list. If you want to create a statement list inside parenthesis, use a sigil before the parenthesis:

say so (42eqv $(my $a = 42$a;);
# OUTPUT: «True␤» 
say so (42,42eqv (my $a = 42$a;);
# OUTPUT: «True␤» 

Individual elements can be pulled out of a list using a subscript. The first element of a list is at index number zero:

say (12)[0];  # says 1 
say (12)[1];  # says 2 
say (12)[2];  # says Nil 
say (12)[-1]; # Error 
say ((<a b>,<c d>),(<e f>,<g h>))[1;0;1]; # says "f" 

The @ sigil

Variables in Perl 6 whose names bear the @ sigil are expected to contain some sort of list-like object. Of course, other variables may also contain these objects, but @-sigiled variables always do, and are expected to act the part.

By default, when you assign a List to an @-sigiled variable, you create an Array. Those are described below. If, instead you want to put an actual List into an @-sigiled variable, you can use binding with := instead.

my @a := 123;

One of the ways @-sigiled variables act like lists is by always supporting positional subscripting. Anything bound to a @-sigiled value must support the Positional role which guarantees this:

my @a := 1# Type check failed in binding; expected Positional but got Int 

Reset a List Container

To remove all elements from a Positional container assign Empty, the empty list () or a Slip of the empty list to the container.

my @a = 123;
@a = ();
@a = Empty;
@a = |();

Iteration

All lists may be iterated, which means taking each element from the list in order and stopping after the last element:

for 123 { .say }  # OUTPUT: «1␤2␤3␤» 

Testing for Elements

To test for elements convert the List or Array to a Set or use a Set operator.

my @a = <foo bar buzz>;
say @a.Set<bar buzz># OUTPUT: «(True True)␤» 
say so 'bar'  @a;    # OUTPUT: «True␤» 

Sequences

Not all lists are born full of elements. Some only create as many elements as they are asked for. These are called sequences, which are of type Seq. As it so happens, loops return Seqs.

(loop { 42.say })[2]  # OUTPUT: «42␤42␤42␤» 

So, it is fine to have infinite lists in Perl 6, just so long as you never ask them for all their elements. In some cases, you may want to avoid asking them how long they are too – Perl 6 will try to return Inf if it knows a sequence is infinite, but it cannot always know.

Although the Seq class does provide some positional subscripting, it does not provide the full interface of Positional, so an @-sigiled variable may not be bound to a Seq.

my @s := Seq.new(<a b c>); CATCH { default { say .^name' '.Str } }
# OUTPUT«Type check failed in binding to $iter; expected Iterator but got List ($("a", "b", "c"))␤  in block <unit> at <tmp> line 1␤␤» 

This is because the Seq does not keep values around after you have used them. This is useful behavior if you have a very long sequence, as you may want to throw values away after using them, so that your program does not fill up memory. For example, when processing a file of a million lines:

for 'filename'.IO.lines -> $line {
    do-something-with($line);
}

You can be confident that the entire content of the file will not stay around in memory, unless you are explicitly storing the lines somewhere.

On the other hand, you may want to keep old values around in some cases. It is possible to hide a Seq inside a List, which will still be lazy, but will remember old values. This is done by calling the .list method. Since this List fully supports Positional, you may bind it directly to an @-sigiled variable.

my @s := (loop { 42.say }).list;
@s[2]; # says 42 three times 
@s[1]; # does not say anything 
@s[4]; # says 42 two more times 

You may also use the .cache method instead of .list, depending on how you want the references handled. See the page on Seq for details.

Slips

Sometimes you want to insert the elements of a list into another list. This can be done with a special type of list called a Slip.

say (1, (23), 4eqv (1234);         # OUTPUT: «False␤» 
say (1Slip.new(23), 4eqv (1234); # OUTPUT: «True␤» 
say (1slip(23), 4eqv (1234);     # OUTPUT: «True␤» 

Another way to make a Slip is with the | prefix operator. Note that this has a tighter precedence than the comma, so it only affects a single value, but unlike the above options, it will break Scalars.

say (1|(23), 4eqv (1234);        # OUTPUT: «True␤» 
say (1|$(23), 4eqv (1234);       # OUTPUT: «True␤» 
say (1slip($(23)), 4eqv (1234);  # OUTPUT: «False␤» 

Lazy Lists

Lists can be lazy, what means that their values are computed on demand and stored for later use. To create a lazy list use gather/take or the sequence operator. You can also write a class that implements the role Iterable and returns True on a call to is-lazy. Please note that some methods like elems may cause the entire list to be computed what will fail if the list is also infinite.

my @l = 1,2,4,8...Inf;
say @l[0..16];
# OUTPUT: «(1 2 4 8 16 32 64 128 256 512 1024 2048 4096 8192 16384 32768 65536)␤» 

Immutability

The lists we have talked about so far (List, Seq and Slip) are all immutable. This means you cannot remove elements from them, or re-bind existing elements:

(123)[0]:delete# Error Can not remove elements from a List 
(123)[0:= 0;   # Error Cannot use bind operator with this left-hand side 
(123)[0= 0;    # Error Cannot modify an immutable Int 

However, if any of the elements is wrapped in a Scalar you can still change the value which that Scalar points to:

my $a = 2;
(1$a3)[1= 42;
$a.say;            # OUTPUT: «42␤» 

...that is, it is only the list structure itself – how many elements there are and each element's identity – that is immutable. The immutability is not contagious past the identity of the element.

List Contexts

So far we have mostly dealt with lists in neutral contexts. Lists are actually very context sensitive on a syntactical level.

List Assignment Context

When a list appears on the right hand side of an assignment into a @-sigiled variable, it is "eagerly" evaluated. This means that a Seq will be iterated until it can produce no more elements. This is one of the places you do not want to put an infinite list, lest your program hang and, eventually, run out of memory:

my $i = 3;
my @a = (loop { $i.saylast unless --$i }); # OUTPUT: «3␤2␤1␤» 
say "take off!";

Flattening "Context"

When you have a list that contains sub-lists, but you only want one flat list, you may flatten the list to produce a sequence of values as if all parentheses were removed. This works no matter how many levels deep the parentheses are nested.

say (1, (2, (34)), 5).flat eqv (12345# OUTPUT: «True␤» 

This is not really a syntactical "context" as much as it is a process of iteration, but it has the appearance of a context.

Note that Scalars around a list will make it immune to flattening:

for (1, (2$(34)), 5).flat { .say } # OUTPUT: «1␤2␤(3 4)␤5␤» 

...but an @-sigiled variable will spill its elements.

my @l := 2, (34);
for (1@l5).flat { .say };      # OUTPUT: «1␤2␤3␤4␤5␤» 
my @a = 2, (34);                 # Arrays are special, see below 
for (1@a5).flat { .say };      # OUTPUT: «1␤2␤(3 4)␤5␤» 

Argument List (Capture) Context

When a list appears as arguments to a function or method call, special syntax rules are at play: the list is immediately converted into a Capture. A Capture itself has a List (.list) and a Hash (.hash). Any Pair literals whose keys are not quoted, or which are not parenthesized, never make it into .list. Instead, they are considered to be named arguments and squashed into .hash. See the page on Capture for the details of this processing.

Consider the following ways to make a new Array from a List. These ways place the List in an argument list context and because of that, the Array only contains 1 and 2 but not the Pair :c(3), which is ignored.

Array.new(12:c(3));
Array.new: 12:c(3);
new Array: 12:c(3);

In contrast, these ways do not place the List in argument list context, so all the elements, even the Pair :c(3), are placed in the Array.

Array.new((12:c(3)));
(12:c(3)).Array;
my @a = 12:c(3); Array.new(@a);
my @a = 12:c(3); Array.new: @a;
my @a = 12:c(3); new Array: @a;

In argument list context the | prefix operator applied to a Positional will always slip list elements as positional arguments to the Capture, while a | prefix operator applied to an Associative will slip pairs in as named parameters:

my @a := 2"c" => 3;
Array.new(1|@a4);    # Array contains 1, 2, :c(3), 4 
my %a = "c" => 3;
Array.new(1|%a4);    # Array contains 1, 4 

Slice Indexing Context

From the perspective of the List inside a slice subscript, is only remarkable in that it is unremarkable: because adverbs to a slice are attached after the ], the inside of a slice is not an argument list, and no special processing of pair forms happens.

Most Positional types will enforce an integer coercion on each element of a slice index, so pairs appearing there will generate an error, anyway:

(123)[12:c(3)] # OUTPUT: «Method 'Int' not found for invocant of class 'Pair'␤» 

...however this is entirely up to the type – if it defines an order for pairs, it could consider :c(3) a valid index.

Indices inside a slice are usually not automatically flattened, but neither are sublists usually coerced to Int. Instead, the list structure is kept intact, causing a nested slice operation that replicates the structure in the result:

say ("a""b""c")[(12), (01)] eqv (("b""c"), ("a""b")) # OUTPUT: «True␤» 

Range as Slice

A Range is a container for a lower and a upper boundary. Generating a slice with a Range will include any index between those bounds, including the bounds. For infinite upper boundaries we agree with mathematicians that Inf equals Inf-1.

my @a = 1..5;
say @a[0..2];     # OUTPUT: «(1 2 3)␤» 
say @a[0..^2];    # OUTPUT: «(1 2)␤» 
say @a[0..*];     # OUTPUT: «(1 2 3 4 5)␤» 
say @a[0..^*];    # OUTPUT: «(1 2 3 4 5)␤» 
say @a[0..Inf-1]; # OUTPUT: «(1 2 3 4 5)␤» 

Array Constructor Context

Inside an Array Literal, the list of initialization values is not in capture context and is just a normal list. It is, however, eagerly evaluated just as in assignment.

12:c(3) ] eqv Array.new((12:c(3))); # OUTPUT: «True␤» 
[while $++ < 2 { 42.say43 }].map: *.say;    # OUTPUT: «42␤42␤43␤43␤» 
(while $++ < 2 { 42.say43 }).map: *.say;    # OUTPUT: «42␤43␤42␤43␤» 

Which brings us to Arrays...

Arrays

Arrays differ from lists in three major ways: Their elements may be typed, they automatically itemize their elements, and they are mutable. Otherwise they are Lists and are accepted wherever lists are.

say Array ~~ List     # OUTPUT: «True␤» 

A fourth, more subtle, way they differ is that when working with Arrays, it can sometimes be harder to maintain laziness or work with infinite sequences.

Typing

Arrays may be typed such that their slots perform a typecheck whenever they are assigned to. An Array that only allows Int values to be assigned is of type Array[Int] and one can create one with Array[Int].new. If you intend to use an @-sigiled variable only for this purpose, you may change its type by specifying the type of the elements when declaring it:

my Int @a = 123;              # An Array that contains only Ints 
my @b := Array[Int].new(123); # Same thing, but the variable is not typed 
say @b eqv @a;                    # says True. 
my @c = 123;                  # An Array that can contain anything 
say @b eqv @c;                    # says False because types do not match 
say @c eqv (123);             # says False because one is a List 
say @b eq @c;                     # says True, because eq only checks values 
say @b eq (123);              # says True, because eq only checks values 
 
@a[0= 42;                       # fine 
@a[0= "foo";                    # error: Type check failed in assignment 

In the above example we bound a typed Array object to a @-sigil variable for which no type had been specified. The other way around does not work – you may not bind an Array that has the wrong type to a typed @-sigiled variable:

my @a := Array[Int].new(123);     # fine 
@a := Array[Str].new("a""b");       # fine, can be re-bound 
my Int @b := Array[Int].new(123); # fine 
@b := Array.new(123);             # error: Type check failed in binding 

When working with typed arrays, it is important to remember that they are nominally typed. This means the declared type of an array is what matters. Given the following sub declaration:

sub mean(Int @a{
    @a.sum / @a.elems
}

Calls that pass an Array[Int] will be successful:

my Int @b = 135;
say mean(@b);                       # @b is Array[Int] 
say mean(Array[Int].new(135));  # Anonymous Array[Int] 
say mean(my Int @ = 135);       # Another anonymous Array[Int] 

However, the following calls will all fail, due to passing an untyped array, even if the array just happens to contain Int values at the point it is passed:

my @c = 135;
say mean(@c);                       # Fails, passing untyped Array 
say mean([135]);                # Same 
say mean(Array.new(135));       # Same again 

Note that in any given compiler, there may be fancy, under-the-hood, ways to bypass the type check on arrays, so when handling untrusted input, it can be good practice to perform additional type checks, where it matters:

for @a -> Int $i { $_++.say };

However, as long as you stick to normal assignment operations inside a trusted area of code, this will not be a problem, and typecheck errors will happen promptly during assignment to the array, if they cannot be caught at compile time. None of the core functions provided in Perl 6 for operating on lists should ever produce a wonky typed Array.

Nonexistent elements (when indexed), or elements to which Nil has been assigned, will assume a default value. This default may be adjusted on a variable-by-variable basis with the is default trait. Note that an untyped @-sigiled variable has an element type of Mu, however its default value is an undefined Any:

my @a;
@a.of.perl.say;                 # OUTPUT: «Mu␤» 
@a.default.perl.say;            # OUTPUT: «Any␤» 
@a[0].say;                      # OUTPUT: «(Any)␤» 
my Numeric @n is default(Real);
@n.of.perl.say;                 # OUTPUT: «Numeric␤» 
@n.default.perl.say;            # OUTPUT: «Real␤» 
@n[0].say;                      # OUTPUT: «(Real)␤» 

Fixed Size Arrays

To limit the dimensions of an Array provide the dimensions separated by , or ; in brackets after the name of the array container. The values of such an Arrays will default to Any. The shape can be accessed at runtime via the shape method.

my @a[2,2];
dd @a;
# OUTPUT: «Array.new(:shape(2, 2), [Any, Any], [Any, Any])␤» 
say @a.shape;
# OUTPUT: «(2 2)␤» 

Assignment to a fixed size Array will promote a List of Lists to an Array of Arrays.

my @a[2;2= (1,23,4);
@a[1;1= 42;
dd @a;
# OUTPUT: «Array.new(:shape(2, 2), [1, 2], [3, 42])␤» 

Itemization

For most uses, Arrays consist of a number of slots each containing a Scalar of the correct type. Each such Scalar, in turn, contains a value of that type. Perl 6 will automatically type-check values and create Scalars to contain them when Arrays are initialized, assigned to, or constructed.

This is actually one of the trickiest parts of Perl 6 list handling to get a firm understanding of.

First, be aware that because itemization in Arrays is assumed, it essentially means that $(…)s are being put around everything that you assign to an array, if you do not put them there yourself. On the other side, Array.perl does not put $ to explicitly show scalars, unlike List.perl:

((12), $(34)).perl.say# says "((1, 2), $(3, 4))" 
[(12), $(34)].perl.say# says "[(1, 2), (3, 4)]" 
                            # ...but actually means: "[$(1, 2), $(3, 4)]" 

It was decided all those extra dollar signs and parentheses were more of an eye sore than a benefit to the user. Basically, when you see a square bracket, remember the invisible dollar signs.

Second, remember that these invisible dollar signs also protect against flattening, so you cannot really flatten the elements inside of an Array with a normal call to flat or .flat.

((12), $(34)).flat.perl.say# OUTPUT: «(1, 2, $(3, 4)).Seq␤» 
[(12), $(34)].flat.perl.say# OUTPUT: «($(1, 2), $(3, 4)).Seq␤» 

Since the square brackets do not themselves protect against flattening, you can still spill the elements out of an Array into a surrounding list using flat.

(0, [(12), $(34)], 5).flat.perl.say# OUTPUT: «(0, $(1, 2), $(3, 4), 5).Seq␤» 

...the elements themselves, however, stay in one piece.

This can irk users of data you provide if you have deeply nested Arrays where they want flat data. Currently they have to deeply map the structure by hand to undo the nesting:

say gather [0, [(12), [34]], $(56)].deepmap: *.take# OUTPUT: «(1 2 3 4 5 6)␤» 

...future versions of Perl 6 might find a way to make this easier. However, not returning Arrays or itemized lists from functions, when non-itemized lists are sufficient, is something that one should consider as a courtesy to their users:

The fact that all elements of an array are itemized (in Scalar containers) is more a gentleman's agreement than a universally enforced rule, and it is less well enforced that typechecks in typed arrays. See the section below on binding to Array slots.

Literal Arrays

Literal Arrays are constructed with a List inside square brackets. The List is eagerly iterated (at compile time if possible) and values in the list are each type-checked and itemized. The square brackets themselves will spill elements into surrounding lists when flattened, but the elements themselves will not spill due to the itemization.

Mutability

Unlike lists, Arrays are mutable. Elements may deleted, added, or changed.

my @a = "a""b""c";
@a.say;                  # OUTPUT: «[a b c]␤» 
@a.pop.say;              # OUTPUT: «c␤» 
@a.say;                  # OUTPUT: «[a b]␤» 
@a.push("d");
@a.say;                  # OUTPUT: «[a b d]␤» 
@a[13= "c""c";
@a.say;                  # OUTPUT: «[a c d c]␤» 

Assigning

Assignment of a list to an Array is eager. The list will be entirely evaluated, and should not be infinite or the program may hang. Assignment to a slice of an Array is, likewise, eager, but only up to the requested number of elements, which may be finite:

my @a;
@a[012= (loop { 42 });
@a.say;                     # OUTPUT: «[42 42 42]␤» 

During assignment, each value will be typechecked to ensure it is a permitted type for the Array. Any Scalar will be stripped from each value and a new Scalar will be wrapped around it.

Binding

Individual Array slots may be bound the same way $-sigiled variables are:

my $b = "foo";
my @a = 123;
@a[2:= $b;
@a.say;          # OUTPUT: «[1 2 "foo"]␤» 
$b = "bar";
@a.say;          # OUTPUT: «[1 2 "bar"]␤» 

...but binding Array slots directly to values is strongly discouraged. If you do, expect surprises with built-in functions. The only time this would be done is if a mutable container that knows the difference between values and Scalar-wrapped values is needed, or for very large Arrays where a native-typed array cannot be used. Such a creature should never be passed back to unsuspecting users.