txt: ## splice.md
  splice
  
  Combined from primary sources listed below.
  
  # [In Array](#___top "go to top of document")[§](#(Array)_routine_splice "direct link")
  
  See primary documentation
  [in context](/type/Array#routine_splice)
  for **routine splice**.
  
  ```raku
  multi        splice(@list,   $start = 0, $elems?, *@replacement --> Array)
  multi method splice(Array:D: $start = 0, $elems?, *@replacement --> Array)
  ```
  
  Deletes `$elems` elements starting from index `$start` from the `Array`, returns them and replaces them by `@replacement`. If `$elems` is omitted or is larger than the number of elements starting from `$start`, all the elements starting from index `$start` are deleted. If both `$start` and `$elems` are omitted, all elements are deleted from the `Array` and returned.
  
  Each of `$start` and `$elems` can be specified as a [`Whatever`](/type/Whatever) or as a [`Callable`](/type/Callable) that returns an [`Int`](/type/Int)-compatible value: this returned value is then used as the corresponding argument to the `splice` routine.
  
  A [`Whatever`](/type/Whatever) `$start` uses the number of elements of `@list` (or invocant). A [`Callable`](/type/Callable) `$start` is called with one argument—the number of elements in `@list` (or `self`).
  
  A [`Whatever`](/type/Whatever) `$elems` deletes from `$start` to end of `@list` (or `self`) (same as no `$elems`). A [`Callable`](/type/Callable) `$elems` is called with one argument—the number of elements in `@list` (or `self`) minus the value of `$start`.
  
  Example:
  
  ```raku
  my @foo = <a b c d e f g>;
  say @foo.splice(2, 3, <M N O P>);        # OUTPUT: «[c d e]␤»
  say @foo;                                # OUTPUT: «[a b M N O P f g]␤»
  ```
  
  It can be used to extend an array by simply splicing in more elements than the current size (since version 6.d)
  
  ```raku
  my @foo = <a b c d e f g>;
  say @foo.splice(6, 4, <M N O P>);       # OUTPUT: «[g]␤»
  say @foo;                               # OUTPUT: «[a b c d e f M N O P]␤»
  
  ```
  
  The following equivalences hold (assuming that `@a.elems ≥ $i`):
  
  ｢text｣ without highlighting
  
  ```
  
  
  ```
  
  @a.push($x, $y)      @a.splice: *  , *, $x, $y
  @a.pop               @a.splice: *-1,
  @a.shift             @a.splice: 0  , 1,
  @a.unshift($x, $y)   @a.splice: 0  , 0, $x, $y
  @a[$i] = $y          @a.splice: $i , 1, $y,
  
  
  ```
  
  
  ```
  
  As mentioned above, a [`Whatever`](/type/Whatever) or [`Callable`](/type/Callable) object can be provided for both the `$start` and `$elems` parameters. For example, we could use either of them to remove the second to last element from an array provided it's large enough to have one:
  
  ```raku
  my @foo = <a b c d e f g>;
  say @foo.splice: *-2, *-1;           # OUTPUT: «[f]␤»
  say @foo;                            # OUTPUT: «[a b c d e g]␤»
  
  my &start     = -> $n { $n - 2 };
  my &elems-num = -> $m { $m - 1 };
  say @foo.splice: &start, &elems-num; # OUTPUT: «[e]␤»
  say @foo;                            # OUTPUT: «[a b c d g]␤»
  ```
  
  # [In role Buf](#___top "go to top of document")[§](#(role_Buf)_method_splice "direct link")
  
  See primary documentation
  [in context](/type/Buf#method_splice)
  for **method splice**.
  
  ```raku
  method splice( Buf:D: $start = 0, $elems?, *@replacement --> Buf)
  ```
  
  Substitutes elements of the buffer by other elements, returning a buffer with the removed elements.
  
  ```raku
  my $bú = Buf.new( 1, 1, 2, 3, 5 );
  say $bú.splice:  0, 3, <3 2 1>;  # OUTPUT: «Buf:0x<01 01 02>␤»
  say $bú.raku;                    # OUTPUT: «Buf.new(3,2,1,3,5)␤»
  ```
  