txt: ## push.md
  push
  
  Combined from primary sources listed below.
  
  # [In role Buf](#___top "go to top of document")[§](#(role_Buf)_method_push "direct link")
  
  See primary documentation
  [in context](/type/Buf#method_push)
  for **method push**.
  
  ```raku
  method push( $elems )
  ```
  
  Adds elements at the end of the buffer.
  
  ```raku
  my $bú = Buf.new( 1, 1, 2, 3, 5 );
  $bú.push( 8 );
  say $bú.raku; # OUTPUT: «Buf.new(1,1,2,3,5,8)␤»
  ```
  
  # [In IterationBuffer](#___top "go to top of document")[§](#(IterationBuffer)_method_push "direct link")
  
  See primary documentation
  [in context](/type/IterationBuffer#method_push)
  for **method push**.
  
  ```raku
  method push(IterationBuffer:D: Mu \value)
  ```
  
  Adds the given value at the end of the `IterationBuffer` and returns the given value.
  
  # [In Array](#___top "go to top of document")[§](#(Array)_method_push "direct link")
  
  See primary documentation
  [in context](/type/Array#method_push)
  for **method push**.
  
  ```raku
  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`](/type/Slip), method `push` will add the values produced by the argument's [iterator](/routine/iterator). It throws if the invocant array or a [`Slip`](/type/Slip) [is lazy](/routine/is-lazy).
  
  Example:
  
  ```raku
  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:
  
  ```raku
  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`](/type/Slip):
  
  ```raku
  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](/type/Array#method_append) if you want to append multiple values that are produced by a single non-slipping [`Iterable`](/type/Iterable).
  
  # [In Any](#___top "go to top of document")[§](#(Any)_method_push "direct link")
  
  See primary documentation
  [in context](/type/Any#method_push)
  for **method push**.
  
  ```raku
  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`](/type/Array), unless the undefined value implements [`Positional`](/type/Positional) already. The argument provided will then be pushed into the newly created Array.
  
  ```raku
  my %h;
  say %h<a>;     # OUTPUT: «(Any)␤»      <-- Undefined
  %h<a>.push(1); # .push on Any
  say %h;        # OUTPUT: «{a => [1]}␤» <-- Note the Array
  ```
  
  # [In Nil](#___top "go to top of document")[§](#(Nil)_method_push "direct link")
  
  See primary documentation
  [in context](/type/Nil#method_push)
  for **method push**.
  
  ```raku
  method push(*@)
  ```
  
  Warns the user that they tried to push onto a `Nil` or derived type object.
  
  # [In Hash](#___top "go to top of document")[§](#(Hash)_method_push "direct link")
  
  See primary documentation
  [in context](/type/Hash#method_push)
  for **method push**.
  
  ```raku
  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`](/type/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`](/type/Array), old and new value are both placed into an array in the place of the old value.
  
  Example:
  
  ```raku
  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](/type/Capture) and as such won't end up in the `Hash`:
  
  ```raku
  my %h .= push(e => 6);
  say %h.raku; # OUTPUT: «{}␤»
  ```
  
  Use the corresponding [subroutine](/type/independent-routines#sub_push) to catch this kind of mistake:
  
  ```raku
  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:
  
  ```raku
  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
  
  ```raku
  my %wc = 'hash' => 323, 'pair' => 322, 'pipe' => 323;
  my %inv .= push: %wc.invert;
  ```
  
  **Note:** Compared to [`append`](/routine/append), `push` will add the given value as is, whereas `append` will [`slip`](/routine/slip) it in:
  
  ```raku
  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]}␤»
  ```
  
  # [In Independent routines](#___top "go to top of document")[§](#(Independent_routines)_sub_push "direct link")
  
  See primary documentation
  [in context](/type/independent-routines#sub_push)
  for **sub push**.
  
  ```raku
  multi push(\a, **@b is raw)
  multi 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](/routine/push#(Hash)_method_push) for an example where indirection via this subroutine can be helpful.
  
  The `push` method is supposed to flatten all arguments of type [`Slip`](/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:
  
  ```raku
  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](/routine/append#(Any)_method_append) if the new type implements the [`Positional`](/type/Positional) role. If the new type is not [`Positional`](/type/Positional), autovivification can be supported by adding a multi method with a signature like
  
  ```raku
  multi method push(::?CLASS:U: **@values is raw --> ::?CLASS:D)
  ```
  