routine push
Documentation for routine push
assembled from the following types:
class Nil
From Nil
(Nil) method push
method push(*@)
Warns the user that they tried to push onto a Nil
.
role Buf
From Buf
(Buf) method push
method push( )
Adds elements at the end of the buffer
my = 1,1, * + * … ∞;my = Buf.new( [^5] );.push( [5] );say .perl; # OUTPUT: «Buf.new(1,1,2,3,5,8)»
class Array
From Array
(Array) routine push
Defined as:
multi sub push(Array, ** --> Array)multi method push(Array: ** --> Array)
Adds the @values
to the end of the array, and returns the modified array. Throws for lazy arrays.
Example:
my = <a b c>;.push: 'd';say ; # 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 b c>;my = <d e f>;.push: ;say .elems; # OUTPUT: «4»say [3].join; # OUTPUT: «def»
Only if you supply multiple values as separate arguments to push
are multiple values added to the array:
my = '1';my = <a b>;my = <E F>;.push: , ;say .elems; # OUTPUT: «3»
See method append for when you want to append multiple values that are stored in a single array.
class Any
From Any
(Any) method push
Defined as:
method push(|values --> Positional)
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 ;say <a>; # OUTPUT: «(Any)» <-- Undefined<a>.push(1); # .push on Anysay ; # OUTPUT: «{a => [1]}» <-- Note the Array
class Hash
From Hash
(Hash) method push
Defined as:
multi method push(Hash: *)
Adds the @new
elements to the hash with the same semantics as hash assignment, but with three exceptions:
The hash isn't emptied first, i.e. old pairs are not deleted.
If a key already exists in the hash, and the corresponding value is an Array, the new value is pushed onto the array (instead of replacing it).
If a key already exists in the hash, and the corresponding value is not an Array, old and new value are both placed into an array in the place of the old value.
Example:
my = a => 1;.push: (a => 1); # a => [1,1].push: (a => 1) xx 3 ; # a => [1,1,1,1,1].push: (b => 3); # a => [1,1,1,1,1], b => 3.push('c' => 4); # a => [1,1,1,1,1], b => 3, c => 4push , 'd' => 5; # a => [1,1,1,1,1], b => 3, c => 4, d => 5
Please note that Pair
s 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 .= push(e => 6);push , f => 7;say .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 = 'hash' => 323, 'pair' => 322, 'pipe' => 323;(my ).push: .invert;say ; # OUTPUT: «{322 => pair, 323 => [pipe hash]}»
Note that such an initialization could also be written as
my = 'hash' => 323, 'pair' => 322, 'pipe' => 323;my .= push: .invert;
Note: Compared to append
, push
will add the given value as is, whereas append
will slip
it in:
my = :a[42, ]; .push: "a" => <a b c a>;say ; # OUTPUT: «{a => [42 (a b c a)]}»my = :a[42, ]; .append: "a" => <a b c a>;say ; # OUTPUT: «{a => [42 a b c a]}»