Array Reference

Sequence of itemized values

What it is #

Routines #

Signatures are reproduced from the documentation, including their declared return types. A routine listed here is part of the type's published interface; whether Raku++ implements it is a separate question, answered by the examples below.

method gist #

Exactly the same as List.gist, except using square brackets for surrounding delimiters.

method pop #

method pop(Array:D:) is nodal

Removes and returns the last item from the array. Fails if the array is empty. Like many Array methods, method pop may be called via the corresponding subroutine. For example:

method push #

multi method push(Array:D: **@values is raw --> Array:D)
multi method push(Array:D: \value --> Array:D)
multi method push(Array:D: Slip \values --> Array:D)

Returns Array:D.

Adds the provided value or values to the end of the array, and returns the modified array. If any argument is a Slip, method push will add the values produced by the argument's iterator. It throws if the invocant array or a Slip is lazy. Example: Note that push does not attempt to flatten its argument list. If you pass

method append #

multi method append(Array:D: **@values is raw --> Array:D)
multi method append(Array:D: \arg --> Array:D)

Returns Array:D.

Adds the provided values to the end of the array and returns the modified array, or throws if the invocant array or an argument that requires flattening is lazy. In contrast with method push, method append adheres to the single argument rule and is probably best thought of as: This means that if you pass a single argument that is a

method elems #

method elems(Array:D: --> Int:D)

Returns Int:D.

Returns the number of elements in the invocant. Throws X::Cannot::Lazy exception if the invocant is lazy. For shaped arrays, returns the outer dimension; see shape if you need information for all dimensions.

method clone #

method clone(Array:D: --> Array:D)

Returns Array:D.

Clones the original Array. Modifications of elements in the clone are not propagated to the original and vice-versa: However, note that the reifier is shared between the two Arrays, so both Arrays will have the same elements even when each is randomly-generated on reification and each element will be reified just once, regardless of whether the reification was done by the clone or the original Array.

method flat #

multi method flat(Array:U:)
multi method flat(Array:D:)

This method will return the type object itself if it's applied to a type object; when applied to an object, it will return a Seq created from the Array underlying iterator.

method shift #

method shift(Array:D:) is nodal

Removes and returns the first item from the array. Fails if the array is empty. Example:

routine unshift #

multi        unshift(Array:D, **@values --> Array:D)
multi method unshift(Array:D: **@values --> Array:D)

Returns Array:D.

Adds the @values to the start of the array, and returns the modified array. Fails if @values is a lazy list. Example: The notes in the documentation for method push apply, regarding how many elements are added to the array. The routine prepend is the equivalent for adding multiple elements from one list or array.

routine prepend #

sub prepend(\array, |values)
multi method prepend(Array:D: \values)
multi method prepend(Array:D: **@values is raw)

Adds the elements from values to the front of the array, modifying it in-place. Example: The difference from method unshift is that if you prepend a single array or list argument, prepend will flatten that array / list, whereas unshift prepends the list / array as just a single element.

routine splice #

multi        splice(@list,   $start = 0, $elems?, *@replacement --> Array)
multi method splice(Array:D: $start = 0, $elems?, *@replacement --> Array)

Returns Array.

Deletes $elems elements starting from index $start from the Array, returns them and replaces them by @replacement. If $elems is omitted or is larger than the number of elements starting from $start, all the elements starting from index $start are deleted. If both $start and $elems are omitted, all elements are deleted from the Array and returned. Each of $start and $elems can be specified as a

method shape #

method shape() { (*,) }

Returns the shape of the array as a list. Example:

method default #

method default

Returns the default value of the invocant, i.e. the value which is returned when trying to access an element in the Array which has not been previously initialized or when accessing an element which has explicitly been set to Nil. Unless the Array is declared as having a default value by using the is default trait the method returns the type object for

method of #

method of()

Returns the type constraint for the values of the invocant. By default, i.e. if no type constraint is given during declaration, the method returns (Mu).

method dynamic #

method dynamic(Array:D: --> Bool:D)

Returns Bool:D.

Returns True if the invocant has been declared with the is dynamic trait, that is, if it's a dynamic variable that can be accessed from the inner lexical scope without having been declared there. If you declare a variable with the * twigil is dynamic is implied. Please note that the dynamic trait is a property of the variable, not the content. If a Scalar dynamic variable contains an array, rules for this

method List #

multi method List(Array:D:)

Converts the array to a List. The holes will show up as Nil.

method Slip #

multi method Slip(Array:D: --> Slip:D)

Returns Slip:D.

Converts the array to a Slip, filling the holes with the type value the Array has been defined with.

Examples, run three ways #

Every example below comes from the official documentation, together with the output that documentation asserts. Each was then executed by Rakudo and by Raku++ when this page was built. Where the three agree, one result is shown; where they do not, all three are — because which of them is wrong is exactly the information worth having.

2 all-differ · 4 no-output · 1 not-runnable · 19 ok · 3 rakupp-differs

class Array is List {}

my @foo of Int = 33,44;        # [33 44]
my @bar is Array[Int] = 33,44; # [33 44]

my @foo = <a b>; # a b
@foo.pop;        # b
pop @foo;        # a
pop @foo;
CATCH { default { put .^name, ': ', .Str } };
# OUTPUT: «X::Cannot::Empty: Cannot pop from an empty Array␤»

X::Cannot::Empty: Cannot pop from an empty Array

X::Cannot::Empty: Cannot pop from an empty Array

my @foo = <a b c>;
@foo.push: 'd';
say @foo;                   # OUTPUT: «[a b c d]␤»

[a b c d]

my @a = <a b c>;
my @b = <d e f>;
@a.push: @b;
say @a.elems;               # OUTPUT: «4␤»
say @a[3].join;             # OUTPUT: «def␤»

4
def

multi method append(Array:D: +values --> Array:D)

my @a = <a b c>;
my @b = <d e f>;
@a.append: @b;
say @a.elems;               # OUTPUT: «6␤»
say @a;                     # OUTPUT: «[a b c d e f]␤»

6
[a b c d e f]

say [<foo bar ber>] .elems; # OUTPUT: «3␤»
say (my @a[42;3;70]).elems; # OUTPUT: «42␤»

3
42

try [-∞...∞].elems;
say $!.^name;               # OUTPUT: «X::Cannot::Lazy␤»

X::Cannot::Lazy

X::Cannot::Lazy

my @a = <a b c>; my @b = @a.clone;
@b[1] = 42; @a.push: 72;
say @b; # OUTPUT: «[a 42 c]␤»
say @a; # OUTPUT: «[a b c 72]␤»

[a 42 c]
[a b c 72]

my @a = 1, {rand} … ∞; my @b = @a.clone;
say @b[^3]; # OUTPUT: «(1 0.0216426755282736 0.567660896142156)␤»
say @a[^3]; # OUTPUT: «(1 0.0216426755282736 0.567660896142156)␤»

(1 0.0216426755282736 0.567660896142156)
(1 0.0216426755282736 0.567660896142156)

(1 0.8613723171000599 0.5910719388876747)
(1 0.8613723171000599 0.5910719388876747)

(1 0.11280538944745189 0.23726505139606857)
(1 0.8139357399235791 0.7853491656748979)

my @a = <a 2 c>;
say @a.flat.^name; # OUTPUT: «Seq␤»

Seq

my @foo = <a b>;
say @foo.shift;             # OUTPUT: «a␤»
say @foo.shift;             # OUTPUT: «b␤»
say @foo.shift;
CATCH { default { put .^name, ': ', .Str } };
# OUTPUT: «X::Cannot::Empty: Cannot shift from an empty Array␤»

a
b
X::Cannot::Empty: Cannot shift from an empty Array

my @foo = <a b c>;
@foo.unshift: 1, 3 ... 11;
say @foo;                   # OUTPUT: «[(1 3 5 7 9 11) a b c]␤»

[(1 3 5 7 9 11) a b c]

my @foo = <a b c>;
@foo.prepend: 1, 3 ... 11;
say @foo;                   # OUTPUT: «[1 3 5 7 9 11 a b c]␤»

[1 3 5 7 9 11 a b c]

my @foo = <a b c d e f g>;
say @foo.splice(2, 3, <M N O P>);        # OUTPUT: «[c d e]␤»
say @foo;                                # OUTPUT: «[a b M N O P f g]␤»

[c d e]
[a b M N O P f g]

my @foo = <a b c d e f g>;
say @foo.splice(6, 4, <M N O P>);       # OUTPUT: «[g]␤»
say @foo;                               # OUTPUT: «[a b c d e f M N O P]␤»

[g]
[a b c d e f M N O P]

@a.push($x, $y)      @a.splice: *  , *, $x, $y
@a.pop               @a.splice: *-1,
@a.shift             @a.splice: 0  , 1,
@a.unshift($x, $y)   @a.splice: 0  , 0, $x, $y
@a[$i] = $y          @a.splice: $i , 1, $y,

my @foo = <a b c d e f g>;
say @foo.splice: *-2, *-1;           # OUTPUT: «[f]␤»
say @foo;                            # OUTPUT: «[a b c d e g]␤»

[f]
[a b c d e g]

my &start     = -> $n { $n - 2 };
my &elems-num = -> $m { $m - 1 };
say @foo.splice: &start, &elems-num; # OUTPUT: «[e]␤»
say @foo;                            # OUTPUT: «[a b c d g]␤»

my @foo[2;3] = ( < 1 2 3 >, < 4 5 6 > ); # Array with fixed dimensions
say @foo.shape;                          # OUTPUT: «(2 3)␤»
my @bar = ( < 1 2 3 >, < 4 5 6 > );      # Normal array (of arrays)
say @bar.shape;                          # OUTPUT: «(*)␤»

(2 3)
(*)

my @a1 = 1, "two", 2.718;
say @a1.default;                               # OUTPUT: «(Any)␤»
say @a1[4];                                    # OUTPUT: «(Any)␤»

my @a2 is default(17) = 1, "two", 3;
say @a2.default;                               # OUTPUT: «17␤»
say @a2[4];                                    # OUTPUT: «17␤»
@a2[1] = Nil;                                  # (resets element to its default)
say @a2[1];                                    # OUTPUT: «17␤»

(Any)
(Any)
17
17
17

my @a1 = 1, 'two', 3.14159;              # (no type constraint specified)
say @a1.of;                              # OUTPUT: «(Mu)␤»

(Mu)

my Int @a2 = 1, 2, 3;                    # (values must be of type Int)
say @a2.of;                              # OUTPUT: «(Int)␤»
@a2.push: 'd';
CATCH { default { put .^name, ': ', .Str } };
# OUTPUT: «X::TypeCheck::Assignment: Type check failed in assignment to @a2; expected Int but got Str ("d")␤»

(Int)
X::TypeCheck::Assignment: Type check failed in assignment to @a2; expected Int but got Str ("d")

(Int)
X::TypeCheck::Assignment: Type check failed for an element of @a2; expected Int but got Str ("d")

(Int)

my @a;
say @a.dynamic;                          # OUTPUT: «False␤»

False

my @b is dynamic;
say @b.dynamic;                          # OUTPUT: «True␤»

True

my @*b;
say @*b.dynamic;                         # OUTPUT: «True␤»

True

my @array= [1];
@array[3]=3;
say @array.List;       # OUTPUT: «(1 Nil Nil 3)␤»

(1 Nil Nil 3)

(1 Nil Nil 3)

(1 (Any) (Any) 3)

my Int @array= [0];
@array[3]=3;
say @array.Slip; # OUTPUT: «(0 (Int) (Int) 3)␤»

(0 (Int) (Int) 3)