txt: ## append.md
  append
  
  Combined from primary sources listed below.
  
  # [In Independent routines](#___top "go to top of document")[§](#(Independent_routines)_sub_append "direct link")
  
  See primary documentation
  [in context](/type/independent-routines#sub_append)
  for **sub append**.
  
  ```raku
  multi append(\a, **@b is raw)
  multi append(\a, \b)
  ```
  
  Calls method `append` on the first argument, passing the remaining arguments. Method `append` is supposed to add the provided values to the end of the collection or parts thereof. Unlike method `push`, method `append` should follow the [single argument rule](/language/functions#Slurpy_conventions). So if you want to implement a conforming method `append` for a new collection type, it should behave as if its signature was just:
  
  ```raku
  multi method append(::?CLASS:D: +values --> ::?CLASS:D)
  ```
  
  Similar to [routine `push`](/routine/push#(Independent_routines)_sub_push), you may need to add a multi method if you want to support autovivification:
  
  ```raku
  multi method append(::?CLASS:U: +values --> ::?CLASS:D)
  ```
  
  The subroutine form of `append` can be helpful when appending to the values of a [`Hash`](/type/Hash). Whereas [method `append`](/routine/append#(Hash)_method_append) will silently ignore literal pairs that are interpreted as named arguments, the subroutine will throw:
  
  ```raku
  my %h = i => 0;
  append %h, i => (1, 42);
  CATCH { default { put .message } };
  # OUTPUT: «Unexpected named argument 'i' passed␤»
  ```
  
  # [In Any](#___top "go to top of document")[§](#(Any)_method_append "direct link")
  
  See primary documentation
  [in context](/type/Any#method_append)
  for **method append**.
  
  ```raku
  multi method append(Any:U \SELF: |values)
  ```
  
  In the case the instance is not a positional-thing, it instantiates it as a new [`Array`](/type/Array), otherwise clone the current instance. After that, it appends the values passed as arguments to the array obtained calling [`Array.append`](/type/Array#method_append) on it.
  
  ```raku
  my $a;
  say $a.append; # OUTPUT: «[]␤»
  my $b;
  say $b.append((1,2,3)); # OUTPUT: «[1 2 3]␤»
  ```
  
  # [In Array](#___top "go to top of document")[§](#(Array)_method_append "direct link")
  
  See primary documentation
  [in context](/type/Array#method_append)
  for **method append**.
  
  ```raku
  multi method append(Array:D: **@values is raw --> Array:D)
  multi method append(Array:D: \arg --> Array:D)
  ```
  
  Adds the provided values to the end of the array and returns the modified array, or throws if the invocant array or an argument that requires flattening [is lazy](/routine/is-lazy).
  
  In contrast with [method push](/type/Array#method_push), method `append` adheres to the [single argument rule](/language/functions#Slurpy_conventions) and is probably best thought of as:
  
  ```raku
  multi method append(Array:D: +values --> Array:D)
  ```
  
  This means that if you pass a **single** argument that is a non-[itemized](/language/mop#VAR) [`Iterable`](/type/Iterable), `append` will try to flatten it.
  
  For example:
  
  ```raku
  my @a = <a b c>;
  my @b = <d e f>;
  @a.append: @b;
  say @a.elems;               # OUTPUT: «6␤»
  say @a;                     # OUTPUT: «[a b c d e f]␤»
  ```
  
  # [In role Buf](#___top "go to top of document")[§](#(role_Buf)_method_append "direct link")
  
  See primary documentation
  [in context](/type/Buf#method_append)
  for **method append**.
  
  ```raku
  method append( $elems )
  ```
  
  Appends to the end of the buffer.
  
  ```raku
  my $bú = Buf.new( 1, 1, 2, 3, 5 );
  $bú.append(9, 8, 7, 6);
  say $bú.raku; # OUTPUT: «Buf.new(1,1,2,3,5,9,8,7,6)␤»
  ```
  
  # [In Hash](#___top "go to top of document")[§](#(Hash)_method_append "direct link")
  
  See primary documentation
  [in context](/type/Hash#method_append)
  for **method append**.
  
  ```raku
  method append(+@values)
  ```
  
  Append the provided Pairs or even sized list to the Hash. If a key already exists, turn the existing value into an [`Array`](/type/Array) and push new value onto that [`Array`](/type/Array). Please note that you can't mix even sized lists and lists of Pairs. Also, bare [`Pair`](/type/Pair)s or colon pairs will be treated as [named arguments](/language/signatures#Positional_vs._named_arguments) to `.append`.
  
  ```raku
  my %h = a => 1;
  %h.append('b', 2, 'c', 3);
  %h.append( %(d => 4) );
  say %h;
  # OUTPUT: «{a => 1, b => 2, c => 3, d => 4}␤»
  %h.append('a', 2);
  # OUTPUT: «{a => [1 2], b => 2, c => 3, d => 4}␤»
  ```
  
  **Note:** Compared to [`push`](/routine/push), `append` will [`slip`](/routine/slip) in the given value, whereas `push` will add it as is:
  
  ```raku
  my %hb = :a[42, ]; %hb.append: "a" => <a b c a>;
  say %hb; # OUTPUT: «{a => [42 a b c a]}␤»
  
  my %ha = :a[42, ]; %ha.push: "a" => <a b c a>;
  say %ha; # OUTPUT: «{a => [42 (a b c a)]}␤»
  ```
  
  # [In IterationBuffer](#___top "go to top of document")[§](#(IterationBuffer)_method_append "direct link")
  
  See primary documentation
  [in context](/type/IterationBuffer#method_append)
  for **method append**.
  
  ```raku
  method append(IterationBuffer:D: IterationBuffer:D $other --> IterationBuffer:D)
  ```
  
  Adds the contents of the other `IterationBuffer` at the end of the `IterationBuffer`, and returns the updated invocant.
  
  # [In Nil](#___top "go to top of document")[§](#(Nil)_method_append "direct link")
  
  See primary documentation
  [in context](/type/Nil#method_append)
  for **method append**.
  
  ```raku
  method append(*@)
  ```
  
  Warns the user that they tried to append onto a `Nil` (or derived type object).
  