Documentation for routine push assembled from the following pages:

Class: Any §

From Any

(Any) method push §

Defined as:

multi method push(Any:U \SELF: |values --> Positional:D)

The method push is defined for undefined invocants and allows for autovivifying undefined to an empty Array, unless the undefined value implements Positional already. The argument provided will then be pushed into the newly created Array.

my %h;
say %h<a>;     # OUTPUT: «(Any)␤»      <-- Undefined 
%h<a>.push(1); # .push on Any 
say %h;        # OUTPUT: «{a => [1]}␤» <-- Note the Array

Class: Nil §

From Nil

(Nil) method push §

method push(*@)

Warns the user that they tried to push onto a Nil or derived type object.

Role: Buf §

From Buf

(Buf) method push §

method push( $elems )

Adds elements at the end of the buffer

my @φ =  1,1, * + * … ∞;
my $bú = Buf.new( @φ[^5] );
$bú.push( @φ[5] );
say $bú.raku; # OUTPUT: «Buf.new(1,1,2,3,5,8)»

Class: Hash §

From Hash

(Hash) method push §

Defined as:

method push(Hash:D: +new)

Adds the new elements to the hash with the same semantics as hash assignment, but with three exceptions:

Example:

my %h  = a => 1;
%h.push: (a => 1);              # a => [1,1] 
%h.push: (a => 1) xx 3 ;        # a => [1,1,1,1,1] 
%h.push: (b => 3);              # a => [1,1,1,1,1], b => 3 
%h.push('c' => 4);              # a => [1,1,1,1,1], b => 3, c => 4 
push %h, 'd' => 5;              # a => [1,1,1,1,1], b => 3, c => 4, d => 5

Please note that literal pairs in the argument list may be interpreted as named arguments and as such won't end up in the Hash:

my %h .= push(e => 6);
say %h.raku; # OUTPUT: «{}␤»

Use the corresponding subroutine to catch this kind of mistake:

push my %h, f => 7;
CATCH { default { put .message } };
# OUTPUT: «Unexpected named argument 'f' passed␤»

Also note that push can be used as a replacement for assignment during hash initialization very useful ways. Take for instance the case of an inverted index:

my %wc = 'hash' => 323, 'pair' => 322, 'pipe' => 323;
(my %inv).push: %wc.invert;
say %inv;                     # OUTPUT: «{322 => pair, 323 => [pipe hash]}␤»

Note that such an initialization could also be written as

my %wc = 'hash' => 323, 'pair' => 322, 'pipe' => 323;
my %inv .= push: %wc.invert;

Note: Compared to append, push will add the given value as is, whereas append will slip it in:

my %ha = :a[42, ]; %ha.push: "a" => <a b c a>;
say %ha; # OUTPUT: «{a => [42 (a b c a)]}␤» 
 
my %hb = :a[42, ]; %hb.append: "a" => <a b c a>;
say %hb; # OUTPUT: «{a => [42 a b c a]}␤»

Language documentation: Independent routines §

From Independent routines

(Independent routines) sub push §

Defined as:

multi sub push(\a, **@b is raw)
multi sub push(\a, \b)

Calls method push on the first argument, passing the remaining arguments. Method push is supposed to add the provided values to the end of the collection or parts thereof. See the documentation of the Hash method for an example where indirection via this subroutine can be helpful.

The push method is supposed to flatten all arguments of type Slip. Therefore, if you want to implement a conforming method for a new collection type, it should behave as if its signature was just:

multi method push(::?CLASS:D: **@values is raw --> ::?CLASS:D)

Autovivification to an instance of the new type is provided by the default base class if the new type implements the Positional role. If the new type is not Positional, autovivification can be supported by an adding a multi method with a signature like

multi method push(::?CLASS:U: **@values is raw --> ::?CLASS:D)

Class: Array §

From Array

(Array) method push §

Defined as:

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)

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:

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

Note that push does not attempt to flatten its argument list. If you pass an array or list as the thing to push, it becomes one additional element:

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

Multiple values are added to the array only if you supply them as separate arguments or in a slip:

my @a = '1';
say @a.push: 'a', 'b';       # OUTPUT: «[1 a b]␤» 
my @c = <E F>;
say @a.push: @c.Slip;        # OUTPUT: «[1 a b E F]␤»

See method append if you want to append multiple values that are produced by a single non-slipping Iterable.