Documentation for routine push

Documentation for routine push, assembled from the following types:

class Any

From Any

(Any) method push

Defined as:

method push(|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;
dd %h<a>;      # Any (and therefore undefined) 
%h<a>.push(1); # .push on Any 
dd %h;         # «Hash %h = {:a($[1])}␤» # please note the Array 

class Array

From Array

(Array) routine push

Defined as:

multi sub    push(Array:D**@values --> Array:D)
multi method push(Array:D: **@values --> Array:D)

Adds the @values to the end of the array, and returns the modified list. Throws for lazy arrays.

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␤» 

Only if you supply multiple values as separate arguments to push are multiple values added to the array:

my @a = '1';
my @b = <a b>;
my @c = <E F>;
@a.push: @b@c;
say @a.elems;                # OUTPUT: «3␤» 

See method append for when you want to append multiple values that are stored in a single array.

class Hash

From Hash

(Hash) method push

Defined as:

multi 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  = => 1;
%h.push: (=> 1);                  # a => [1,1] 
%h.push: (=> 1xx 3 ;            # a => [1,1,1,1,1] 
%h.push: (=> 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 Pairs or colon pairs as arguments to push will be treated as extra named arguments and as such wont end up the Hash. The same applies to the sub push.

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

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.unique;
say %inv;                           # OUTPUT: «{322 => pair, 323 => [pipe hash]}␤» 

Note that such a initialization could also be written as

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

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]}␤» 

class Nil

From Nil

(Nil) method push

method push(*@)

Warns the user that they tried to push onto a Nil.