txt: ## iterationbuffer.md
  class IterationBuffer
  
  Low level storage of positional values
  
  ```raku
  my class IterationBuffer { }
  
  ```
  
  An `IterationBuffer` is used when the implementation of an [`Iterator`](/type/Iterator) class needs a lightweight way to store/transmit values. It doesn't make [`Scalar`](/type/Scalar) containers, and only supports mutation through the `BIND-POS` method, only supports adding values with the `push` and `unshift` methods, supports merging of two `IterationBuffer` objects with the `append` and `prepend` methods, and supports resetting with the `clear` method.
  
  It can be coerced into a [`List`](/type/List), [`Slip`](/type/Slip), or [`Seq`](/type/Seq).
  
  Values will be stored "as is", which means that [Junctions](/type/Junction) will be stored as such and will **not** [autothread](/language/glossary#Autothreading).
  
  As of release 2021.12 of the Rakudo compiler, the `new` method also accepts an [`Iterable`](/type/Iterable) as an optional argument which will be used to fill the `IterationBuffer`.
  
  # [Methods](#class_IterationBuffer "go to top of document")[§](#Methods "direct link")
  
  ## [method push](#class_IterationBuffer "go to top of document")[§](#method_push "direct link")
  
  ```raku
  method push(IterationBuffer:D: Mu \value)
  ```
  
  Adds the given value at the end of the `IterationBuffer` and returns the given value.
  
  ## [method unshift](#class_IterationBuffer "go to top of document")[§](#method_unshift "direct link")
  
  ```raku
  method unshift(IterationBuffer:D: Mu \value)
  ```
  
  Adds the given value at the beginning of the `IterationBuffer` and returns the given value. Available as of the 2021.12 release of the Rakudo compiler.
  
  ## [method append](#class_IterationBuffer "go to top of document")[§](#method_append "direct link")
  
  ```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.
  
  ## [method prepend](#class_IterationBuffer "go to top of document")[§](#method_prepend "direct link")
  
  ```raku
  method prepend(IterationBuffer:D: IterationBuffer:D $other --> IterationBuffer:D)
  ```
  
  Adds the contents of the other `IterationBuffer` at the beginning of the `IterationBuffer`, and returns the updated invocant. Available as of the 2021.12 release of the Rakudo compiler.
  
  ## [method clear](#class_IterationBuffer "go to top of document")[§](#method_clear "direct link")
  
  ```raku
  method clear(IterationBuffer:D: --> Nil)
  ```
  
  Resets the number of elements in the `IterationBuffer` to zero, effectively removing all data from it, and returns [`Nil`](/type/Nil).
  
  ## [method elems](#class_IterationBuffer "go to top of document")[§](#method_elems "direct link")
  
  ```raku
  method elems(IterationBuffer:D: --> Int:D)
  ```
  
  Returns the number of elements in the `IterationBuffer`.
  
  ## [method AT-POS](#class_IterationBuffer "go to top of document")[§](#method_AT-POS "direct link")
  
  ```raku
  multi method AT-POS(IterationBuffer:D: int   $pos)
  multi method AT-POS(IterationBuffer:D: Int:D $pos)
  ```
  
  Returns the value at the given element position, or [`Mu`](/type/Mu) if the element position is beyond the length of the `IterationBuffer`, or an error will be thrown indicating the index is out of bounds (for negative position values).
  
  ## [method BIND-POS](#class_IterationBuffer "go to top of document")[§](#method_BIND-POS "direct link")
  
  ```raku
  multi method BIND-POS(IterationBuffer:D: int   $pos, Mu \value)
  multi method BIND-POS(IterationBuffer:D: Int:D $pos, Mu \value)
  ```
  
  Binds the given value at the given element position and returns it. The `IterationBuffer` is automatically lengthened if the given element position is beyond the length of the `IterationBuffer`. An error indicating the index is out of bounds will be thrown for negative position values.
  
  ## [method Slip](#class_IterationBuffer "go to top of document")[§](#method_Slip "direct link")
  
  ```raku
  method Slip(IterationBuffer:D: --> Slip:D)
  ```
  
  Coerces the `IterationBuffer` to a [`Slip`](/type/Slip).
  
  ## [method List](#class_IterationBuffer "go to top of document")[§](#method_List "direct link")
  
  ```raku
  method List(IterationBuffer:D: --> List:D)
  ```
  
  Coerces the `IterationBuffer` to a [`List`](/type/List).
  
  ## [method Seq](#class_IterationBuffer "go to top of document")[§](#method_Seq "direct link")
  
  ```raku
  method Seq(IterationBuffer:D: --> Seq:D)
  ```
  
  Coerces the `IterationBuffer` to a [`Seq`](/type/Seq).
  
  ## [method raku](#class_IterationBuffer "go to top of document")[§](#method_raku "direct link")
  
  ```raku
  method raku(IterationBuffer:D: --> Str)
  ```
  
  Produces a representation of the `IterationBuffer` as a [`List`](/type/List) postfixed with ".IterationBuffer" to make it different from an ordinary list. Does **not** roundtrip. Intended for debugging uses only, specifically for use with [dd](/programs/01-debugging#Dumper_function_(dd)).
  