From type/Buf

See Original text in context

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

From type/independent-routines

See Original text in context

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)

From type/Nil

See Original text in context

method push(*@)

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

From type/Any

See Original text in context

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

From type/Array

See Original text in context

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.

From type/Hash

See Original text in context

method push(Hash:D: +new)

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